Add permalink anchors to every example

[Copilot]

Each numbered example on principle pages lacked a stable URL fragment, making it impossible to link directly to a specific example.

Changes

• examples/NN-*.md (all 12 files) — the numbered list of examples has been moved from the Markdown body into a structured examples: YAML front matter array. Each entry has a title and body key. The Markdown body retains only the # Principle N heading, blockquote, and ## 20 Practical Examples subheading.
• _layouts/principle.html — iterates over page.examples using a Liquid {% for %} loop, generating id="example-N" on each <li> and appending a link-icon anchor at Jekyll build time. Enables deep links such as:

  /examples/01-make-the-right-thing-the-easy-thing/#example-5
  

• assets/css/style.css — adds .example-anchor styles: hidden by default, revealed on li:hover / :focus, aligned to the far right of the flex row via margin-left: auto, using existing colour tokens.

[landro]

Why are we using js? Jekyll must surely know how to iterate

[landro]

Why are we using js? Jekyll must surely know how to iterate

[Copilot]

Why are we using js? Jekyll must surely know how to iterate

Good call. Replaced the JavaScript with proper Jekyll/Liquid iteration (db0288b). The 20 examples in each of the 12 principle files are now stored as a structured examples: array in YAML front matter. The principle.html layout iterates over page.examples with {% for %}, generating id="example-N" and the anchor link at build time — no runtime JS needed.

[landro]

I need a screenshot of these changes @copilot

[Copilot]

I need a screenshot of these changes @copilot

Here's the rendered result:

Normal state — examples render as numbered cards with the anchor hidden:

Hover state — the link icon appears top-right of the card on hover, linking directly to e.g. #example-1:

All IDs (example-1 … example-20) and anchors are generated at build time by Jekyll — no JavaScript involved.

[landro]

This is not ok. The formatting of the example commands breaks everything. @copilot

[Copilot]

This is not ok. The formatting of the example commands breaks everything.

Fixed in 14b5c91. The <li> uses display: flex, so inline <code> elements inside the body text were each becoming their own flex item. Wrapping the body in a <span> keeps the title, em-dash, text, and inline code as a single flex child.

Normal state:

Hover state (anchor icon visible):

[landro]

@copilot Could you add a diff for the generated page? I want to make sure the actual html/css stays more or less the same as before

[landro]

@copilot Could you add a diff for the generated page? I want to make sure the actual html/css stays more or less the same as before

[Copilot]

@copilot Could you add a diff for the generated page? I want to make sure the actual html/css stays more or less the same as before

Here's the structural diff for one example item. The content is identical — the only additions are the id attribute on <li>, a <span> wrapper (to fix the flex layout), and the hidden anchor <a>:

Before — each <li> was a plain Markdown-generated <p>:

<ol>
  <li>
    <p><strong>Scaffold with security baked in</strong> — Provide a <code>create-service</code> CLI command …</p>
  </li>
  …
</ol>

After — each <li> gets an id, the text is in a <span>, plus a hidden anchor link:

<ol>
  <li id="example-1">
    <span><strong>Scaffold with security baked in</strong> &mdash; Provide a <code>create-service</code> CLI command …</span>
    <a href="#example-1" class="example-anchor" aria-label="Permalink to example 1">
      <svg …/>
    </a>
  </li>
  …
</ol>

The CSS adds .example-anchor (hidden by default, visible on li:hover/:focus) — no existing selectors were changed. All 20 items per page follow the same pattern.