Skip to content
CodeAtlas UI sketchbook
On this page Markup

Docs kit

Release lists

The markup contract for changelog and release-notes pages inside .ca-prose, and how the heading anchors and the version index are linked.

.ca-prose styles a changelog page with no custom CSS, as long as the markup follows the contract below. The package ships only the CSS: it never generates the ids, the anchors or the version index. Your app (its markdown pipeline or its template) renders them. The changelog page of this site is the reference: site/functions/_lib/page.ts builds exactly this markup.

Markup

<div class="ca-prose">
  <nav class="ca-release-jump" aria-label="Versions">
    <ul>
      <li><a href="#v3-0-0">3.0.0</a></li>
      <li><a href="#v2-4-0-beta-1">2.4.0-beta.1</a></li>
    </ul>
  </nav>

  <section class="ca-release" id="v3-0-0" aria-labelledby="v3-0-0-h">
    <h2 id="v3-0-0-h">
      <a href="#v3-0-0">3.0.0</a>
      <span class="ca-chip ca-chip--sm ca-chip--brand"><span class="ca-chip__label">latest</span></span>
    </h2>
    <p class="ca-release__meta">
      <time datetime="2026-10-15">October 15, 2026</time>
      <a href="https://www.npmjs.com/package/@codeatlasdev/ui/v/3.0.0">npm</a>
      <a href="https://github.com/codeatlasdev/ui/releases/tag/%40codeatlasdev%2Fui%403.0.0">GitHub release</a>
    </p>
    <h3 id="v3-0-0-minor-changes">Minor Changes</h3>
    <ul><li>The rendered notes.</li></ul>
  </section>

  <footer class="ca-release-thanks">
    <h2 id="special-thanks">Special thanks</h2>
    <p>To our supporters.</p>
  </footer>
</div>
Class Element Role
ca-release <section> One per version, newest first. Draws the rule between versions and sets scroll-margin-top so a jump lands clear of the sticky header (--ca-docs-header-h).
ca-release-jump <nav> The version index as a wrapping row of pills. Holds a <ul> of links; each pill is a 44px touch target.
ca-release__meta <p> Row under the heading: a <time>, then links (npm, GitHub release). Wraps on small screens; links are 44px tall.
ca-release-thanks <footer> Closes the page, set apart from the last release by a rule.

The channel badge in the heading is a regular Chip (ca-chip--sm). The package only styles h2 > a inside a release (inherits the heading color, underline on hover); the chip, the date and the links are yours.

Anchors

Two kinds of anchors exist on a release page, and both are generated by the app:

  • Version id. The id of each ca-release section, the href of its heading link and the href of its pill in ca-release-jump must be the same string. The convention used by this site: v plus the version with every run of non-alphanumeric characters replaced by -, so 3.0.0 is #v3-0-0 and 2.4.0-beta.1 is #v2-4-0-beta-1. If your versions are dates (2026-10-14 (1.1.0)), pick your own slug and use the same function for the pill and the section. Nothing in the package computes it.
  • Heading ids inside the notes. Slugify the heading text (lowercase, non-alphanumerics to -, trim dashes) and prefix it with the version id, so two ### Patch Changes in different versions never collide: v3-0-0-patch-changes. Repeat headings inside one version get -2, -3.

Give the section aria-labelledby pointing at its heading id (<version id>-h) so the landmark has an accessible name. Do not give the heading the same id as the section: ids must be unique per page.

.ca-prose styles an optional <a class="ca-prose-anchor" href="#id">#</a> placed first inside an h2, h3 or h4. It sits in the left margin, appears on heading hover and on focus, and stays visible on touch screens (hover: none), where there is no hover to reveal it. You inject it, the package does not.