feat(docs): add deep-link anchors to prerequisites and steps

ELSPrerequisites and ELSSteps are Vue component templates, so VuePress's
markdown anchor system (which only slugs h2-h5 headings) never gave them
ids - there was nothing to deep-link to. This adds hover-revealed anchors:

- Each step gets a stable id slugified from its title text (e.g.
  #download-the-install-script), deduped page-wide so multiple steps and
  multiple ELSSteps blocks never collide.
- Each Prerequisites section gets a single #prerequisites section anchor.
- A '#' link (styled like the site's h2 header-anchors) reveals on hover and
  sits to the left of the wording; clicking it - or the step's number badge -
  updates the URL and scrolls below the fixed navbar.
- The step number badge changes color on hover.
- Step body content and the prerequisites list are indented to line up with
  the title/heading wording; anchors are vertically aligned with the text.
- A shared slugify helper (utils/slugify.ts) strips punctuation/signs from
  anchor urls; markdown heading anchors (config.ts) now use it too, so the
  no-signs rule applies site-wide.

Author: claude

docs/.vuepress/components/ELSPrerequisites.vue

@@ -1,21 +1,54 @@
 <template>
-  <div class="prereqs">
+  <div ref="rootRef" class="prereqs">
     <div class="prereqs-header">
-      <h4><slot name="title">Prerequisites</slot></h4>
+      <h4 ref="headingRef"><slot name="title">Prerequisites</slot></h4>
     </div>
     <div class="prereqs-body">
       <slot />
     </div>
   </div>
 </template>
 
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { slugify, uniqueId, collectUsedIds } from '../utils/slugify';
+
+const rootRef = ref<HTMLElement | null>(null);
+const headingRef = ref<HTMLElement | null>(null);
+
+function anchorPrerequisites() {
+  const heading = headingRef.value;
+  if (!heading || heading.id) return;
+
+  const used = collectUsedIds();
+  const id = uniqueId(slugify(heading.textContent ?? '') || 'prerequisites', used);
+  heading.id = id;
+
+  const anchor = document.createElement('a');
+  anchor.className = 'header-anchor prereq-anchor';
+  anchor.setAttribute('href', `#${id}`);
+  anchor.setAttribute('aria-hidden', 'true');
+  anchor.setAttribute('tabindex', '-1');
+  anchor.textContent = '#';
+  // On the left of the heading wording, vertically aligned with it.
+  heading.insertBefore(anchor, heading.firstChild);
+}
+
+onMounted(() => {
+  // Run after VuePress has assigned heading ids.
+  setTimeout(anchorPrerequisites, 0);
+});
+</script>
+
 <style scoped>
 .prereqs {
   border-radius: 10px;
   border: 1px solid #D9EDFF;
   background: linear-gradient(135deg, #f8fbff 0%, #f0f7ff 100%);
   padding: 1.25rem 1.5rem;
   margin: 1.5rem 0;
+  /* Land below the fixed navbar when navigated to via the section anchor. */
+  scroll-margin-top: 6rem;
 }
 
 .prereqs-header h4 {
@@ -25,6 +58,36 @@
   color: #1b1f27;
 }
 
+/* The anchor floats left at its natural position with a fixed width and a
+   minimal gap; the body list below is indented to match (see .prereqs-body).
+   font-size in rem (not em) keeps it identical to the ELSSteps anchor. */
+.prereqs-header h4 :deep(a.prereq-anchor) {
+  opacity: 0;
+  font-size: 1rem;
+  width: 0.7rem;
+  padding-right: 0;
+  margin-left: 0;
+  /* Match the heading's line-height and nudge down so the floated # starts at
+     the same level as the wording instead of riding above it. */
+  line-height: inherit;
+  margin-top: 0.1rem;
+  transition: opacity 0.15s ease;
+}
+
+.prereqs-header h4:hover {
+  cursor: pointer;
+}
+
+.prereqs-header h4:hover :deep(a.prereq-anchor) {
+  opacity: 1;
+}
+
+/* Indent the body by the anchor's reserved width so the list aligns with the
+   "Prerequisites" wording, which the floated anchor pushes right. */
+.prereqs-body {
+  padding-left: 0.7rem;
+}
+
 .prereqs-body :deep(ul) {
   list-style: none;
   padding: 0;

docs/.vuepress/components/ELSSteps.vue

@@ -1,11 +1,61 @@
 <template>
   <div class="els-steps">
-    <div class="els-steps-body">
+    <div ref="bodyRef" class="els-steps-body">
       <slot />
     </div>
   </div>
 </template>
 
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { slugify, uniqueId, collectUsedIds } from '../utils/slugify';
+
+const bodyRef = ref<HTMLElement | null>(null);
+
+function anchorSteps() {
+  const body = bodyRef.value;
+  if (!body) return;
+
+  // Seed from ids already on the page so step anchors never collide with
+  // heading anchors or other <ELSSteps> blocks on the same page.
+  const used = collectUsedIds();
+
+  // Top-level steps only — leave nested sub-steps (ol ol > li) un-anchored.
+  body.querySelectorAll<HTMLLIElement>(':scope > ol > li').forEach((li) => {
+    if (li.id) return; // already processed
+
+    const titleEl = li.querySelector('p');
+    const title = titleEl?.textContent ?? li.textContent ?? '';
+    const id = uniqueId(slugify(title) || 'step', used);
+    li.id = id;
+
+    const anchor = document.createElement('a');
+    anchor.className = 'header-anchor els-step-anchor';
+    anchor.setAttribute('href', `#${id}`);
+    anchor.setAttribute('aria-hidden', 'true');
+    anchor.setAttribute('tabindex', '-1');
+    anchor.textContent = '#';
+    // On the left of the step title (prepended), vertically aligned with it.
+    const target = titleEl ?? li;
+    target.insertBefore(anchor, target.firstChild);
+
+    // Transparent overlay over the number badge so clicking the number also
+    // navigates to the step's anchor and updates the URL.
+    const numberLink = document.createElement('a');
+    numberLink.className = 'els-step-number';
+    numberLink.setAttribute('href', `#${id}`);
+    numberLink.setAttribute('aria-hidden', 'true');
+    numberLink.setAttribute('tabindex', '-1');
+    li.appendChild(numberLink);
+  });
+}
+
+onMounted(() => {
+  // Run after VuePress has assigned heading ids.
+  setTimeout(anchorSteps, 0);
+});
+</script>
+
 <style scoped>
 .els-steps {
   margin: 1.5rem 0;
@@ -22,11 +72,52 @@
 .els-steps-body :deep(ol > li) {
   counter-increment: step-counter;
   position: relative;
-  padding-left: 1.5rem;
+  padding-left: 1.2rem;
   padding-bottom: 1.25rem;
   margin-bottom: 0;
   border-left: 2px solid #e0e3e8;
   margin-left: 0.9rem;
+  /* Land below the fixed navbar when navigated to via a step anchor. */
+  scroll-margin-top: 6rem;
+}
+
+/* The anchor floats left at its natural position (no negative margin, so it
+   never overlaps the number badge), with a fixed width and a minimal gap.
+   font-size in rem (not em) keeps it identical to the prerequisites anchor. */
+.els-steps-body :deep(ol > li > p:first-child > a.els-step-anchor) {
+  opacity: 0;
+  font-size: 1rem;
+  width: 0.7rem;
+  padding-right: 0;
+  margin-left: 0;
+  /* Inherit the title's 2rem line-height so the floated # centers at the same
+     level as the (vertically centered) wording. No extra margin-top needed. */
+  line-height: inherit;
+  margin-top: 0;
+  transition: opacity 0.15s ease;
+}
+
+.els-steps-body :deep(ol > li:hover > p:first-child > a.els-step-anchor) {
+  opacity: 1;
+}
+
+/* Indent the step's body content (everything below the title) by the anchor's
+   reserved width so it aligns with the title wording. margin-left (not padding)
+   so code blocks move as a whole and their background aligns too. Exclude the
+   absolutely positioned number-overlay link. */
+.els-steps-body :deep(ol > li > *:not(:first-child):not(a)) {
+  margin-left: 0.7rem;
+}
+
+/* Transparent overlay over the number badge — makes the number clickable. */
+.els-steps-body :deep(ol > li > a.els-step-number) {
+  position: absolute;
+  left: -1rem;
+  top: 0;
+  width: 2rem;
+  height: 2rem;
+  border-radius: 50%;
+  cursor: pointer;
 }
 
 .els-steps-body :deep(ol > li:last-child) {
@@ -50,12 +141,22 @@
   align-items: center;
   justify-content: center;
   line-height: 1;
+  transition: background 0.15s ease;
+}
+
+/* Hover hint on the step: the number badge changes color. */
+.els-steps-body :deep(ol > li:hover::before) {
+  background: #0B5CAD;
 }
 
 .els-steps-body :deep(ol > li > p:first-child) {
   font-weight: 600;
   color: #0d1a26;
   margin-top: 0;
+  /* Match the number badge height so the wording sits at the badge's vertical
+     middle (where the number is) instead of at its top. */
+  min-height: 2rem;
+  line-height: 2rem;
 }
 
 .els-steps-body :deep(ol > li > p) {
@@ -83,7 +184,10 @@
 
 .els-steps-body :deep(div[class*="language-"]),
 .els-steps-body :deep(.code-with-copy) {
-  margin: 0.5rem 0;
+  /* top/bottom only — left indent comes from the body-content rule above so
+     the code block aligns with the step wording. */
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
 }
 
 .els-steps-body :deep(:not(pre) > code) {

docs/.vuepress/config.ts

@@ -2,17 +2,14 @@ import { defineUserConfig, viteBundler } from "vuepress";
 import theme from "./theme";
 import plugins from "./config-user/plugins";
 import headFunctions from "./headFunctions";
+import { slugify } from "./utils/slugify";
 
 export default defineUserConfig({
   theme,
   markdown: {
     anchor: {
-    slugify: str =>
-      str
-        .replace(/®/g, '')
-        .replace(/™/g, '')
-        .toLowerCase()
-        .replace(/\s+/g, '-')
+      // Shared rule: strip punctuation/signs (, . ? ! ' etc.) from anchor urls.
+      slugify,
     },
     headers: {
       level: [2, 3, 4, 5],

docs/.vuepress/utils/slugify.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared slug helper for anchor ids.
+ *
+ * Mirrors the rule used by VuePress markdown anchors in `config.ts`
+ * (strip ® / ™, lowercase, spaces -> "-") so component-generated anchors
+ * (steps, prerequisites) behave exactly like heading anchors. Additionally
+ * strips characters that aren't url/id-safe and collapses repeated hyphens.
+ */
+export function slugify(str: string): string {
+  return str
+    .replace(/®/g, '')
+    .replace(/™/g, '')
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '') // drop non url-safe chars
+    .replace(/\s+/g, '-')         // spaces -> hyphens
+    .replace(/-+/g, '-')          // collapse repeats
+    .replace(/^-+|-+$/g, '');     // trim leading/trailing hyphens
+}
+
+/**
+ * Returns `base` if unused, otherwise appends -1, -2, ... until unique.
+ * Records the chosen id in `used` (mutates the set). Same dedupe behavior
+ * as markdown-it-anchor so step/prereq ids never collide with each other
+ * or with heading anchors already present on the page.
+ */
+export function uniqueId(base: string, used: Set<string>): string {
+  const safeBase = base || 'section';
+  let id = safeBase;
+  let i = 0;
+  while (used.has(id)) {
+    i += 1;
+    id = `${safeBase}-${i}`;
+  }
+  used.add(id);
+  return id;
+}
+
+/**
+ * Seeds a "used ids" set from every element already carrying an id within
+ * the given root (defaults to the whole document). Lets runtime-generated
+ * anchors avoid colliding with VuePress heading anchors and other blocks.
+ */
+export function collectUsedIds(root: ParentNode = document): Set<string> {
+  const used = new Set<string>();
+  root.querySelectorAll('[id]').forEach((el) => {
+    const id = el.getAttribute('id');
+    if (id) used.add(id);
+  });
+  return used;
+}