living-documentation 7.2.0 → 7.3.0

package/dist/src/frontend/boot.js

@@ -87,5 +87,10 @@ document
 window.addEventListener("popstate", (e) => {
   const id =
     e.state?.docId || new URLSearchParams(location.search).get("doc");
-  if (id) openDocument(id, true);
+  const anchor =
+    e.state?.anchor ||
+    (location.hash && location.hash.length > 1
+      ? location.hash.slice(1)
+      : null);
+  if (id) openDocument(id, true, false, anchor);
 });

package/dist/src/frontend/documents.js

@@ -43,17 +43,23 @@ async function refreshAnnotationCounts() {
   }
 }
 
-async function openDocument(id, skipHistory = false, fromLink = false) {
+async function openDocument(id, skipHistory = false, fromLink = false, anchor = null) {
   // Track navigation history for breadcrumb trail
   // fromLink===true  : forward navigation via in-doc link → push current to stack
+  //                   (unless target is already in the stack → rewind instead of loop)
   // fromLink==="restore" : back navigation via history breadcrumb → stack already trimmed, don't touch
   // fromLink===false : sidebar/direct navigation → reset stack
   if (fromLink === true && currentDocId && currentDocId !== id) {
-    const prev = allDocs && allDocs.find((d) => d.id === currentDocId);
-    navHistory.push({
-      id: currentDocId,
-      title: prev ? prev.title : currentDocId,
-    });
+    const existingIdx = navHistory.findIndex((e) => e.id === id);
+    if (existingIdx !== -1) {
+      navHistory = navHistory.slice(0, existingIdx);
+    } else {
+      const prev = allDocs && allDocs.find((d) => d.id === currentDocId);
+      navHistory.push({
+        id: currentDocId,
+        title: prev ? prev.title : currentDocId,
+      });
+    }
   } else if (!fromLink) {
     navHistory = [];
   }
@@ -105,7 +111,8 @@ async function openDocument(id, skipHistory = false, fromLink = false) {
   if (!skipHistory) {
     const url = new URL(location.href);
     url.searchParams.set("doc", id);
-    history.pushState({ docId: id }, "", url);
+    url.hash = anchor ? `#${anchor}` : "";
+    history.pushState({ docId: id, anchor: anchor || null }, "", url);
   }
 
   document.getElementById("welcome").classList.add("hidden");
@@ -158,14 +165,16 @@ async function openDocument(id, skipHistory = false, fromLink = false) {
       hljs.highlightElement(block);
     });
 
-    // Intercept inter-doc links (?doc=X) to stay in SPA and track origin
+    // Intercept inter-doc links (?doc=X[#anchor]) to stay in SPA and track origin
     contentEl.querySelectorAll("a[href]").forEach((a) => {
       const href = a.getAttribute("href");
       const m = href && href.match(/[?&]doc=([^&#]+)/);
       if (!m) return;
+      const hashIdx = href.indexOf("#");
+      const anchor = hashIdx !== -1 ? href.slice(hashIdx + 1) : null;
       a.addEventListener("click", (e) => {
         e.preventDefault();
-        openDocument(decodeURIComponent(m[1]), false, true);
+        openDocument(decodeURIComponent(m[1]), false, true, anchor);
       });
     });
 
@@ -199,10 +208,11 @@ async function openDocument(id, skipHistory = false, fromLink = false) {
 
     document.title = doc.title;
 
-    // Scroll to anchor if present in URL
-    const hash = window.location.hash;
-    if (hash && hash.length > 1) {
-      scrollToAnchor(hash.slice(1));
+    // Scroll to anchor if present (explicit param wins over URL hash)
+    const targetAnchor =
+      anchor || (window.location.hash ? window.location.hash.slice(1) : "");
+    if (targetAnchor) {
+      scrollToAnchor(targetAnchor);
     } else {
       document.getElementById("content-area").scrollTop = 0;
     }
@@ -331,9 +341,11 @@ async function saveDocument() {
       const href = a.getAttribute("href");
       const m = href && href.match(/[?&]doc=([^&#]+)/);
       if (!m) return;
+      const hashIdx = href.indexOf("#");
+      const anchor = hashIdx !== -1 ? href.slice(hashIdx + 1) : null;
       a.addEventListener("click", (e) => {
         e.preventDefault();
-        openDocument(decodeURIComponent(m[1]), false, true);
+        openDocument(decodeURIComponent(m[1]), false, true, anchor);
       });
     });
 

package/dist/src/frontend/i18n/en.json

@@ -152,6 +152,8 @@
   "snippet.link_anchor_label": "Anchor",
   "snippet.link_anchor_placeholder": "my-heading",
   "snippet.link_anchor_hint": "(without #, e.g. my-heading)",
+  "snippet.link_anchor_select_hint": "(pick a heading from the document)",
+  "snippet.link_anchor_no_headings": "No headings detected in this document",
   "snippet.link_target_doc_label": "Target document",
   "snippet.code_lang_label": "Language",
   "snippet.code_lang_hint": "(e.g. javascript, python, bash…)",

package/dist/src/frontend/i18n/fr.json

@@ -152,6 +152,8 @@
   "snippet.link_anchor_label": "Ancre",
   "snippet.link_anchor_placeholder": "mon-titre",
   "snippet.link_anchor_hint": "(sans #, ex : mon-titre)",
+  "snippet.link_anchor_select_hint": "(choisissez un titre du document)",
+  "snippet.link_anchor_no_headings": "Aucun titre détecté dans ce document",
   "snippet.link_target_doc_label": "Document cible",
   "snippet.code_lang_label": "Langage",
   "snippet.code_lang_hint": "(ex : javascript, python, bash…)",

package/dist/src/frontend/index.html

@@ -1227,18 +1227,15 @@
             <label
               class="block text-xs font-medium text-gray-500 dark:text-gray-400"
               ><span data-i18n="snippet.link_anchor_label">Anchor</span>
-              <span data-i18n="snippet.link_anchor_hint" class="font-normal text-gray-400"
-                >(without #, e.g. my-heading)</span
+              <span data-i18n="snippet.link_anchor_select_hint" class="font-normal text-gray-400"
+                >(pick a heading from the document)</span
               ></label
             >
-            <input
+            <select
               id="snip-anchor-id"
-              type="text"
-              data-i18n-placeholder="snippet.link_anchor_placeholder"
-              placeholder="my-heading"
-              oninput="snippetUpdatePreview()"
+              onchange="snippetUpdatePreview()"
               class="w-full px-3 py-2 text-sm rounded-lg border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
-            />
+            ></select>
           </div>
         </div>
 
@@ -1252,7 +1249,7 @@
             >
             <select
               id="snip-anchor-doc-select"
-              onchange="snippetUpdatePreview()"
+              onchange="snippetAnchorDocChanged()"
               class="w-full px-3 py-2 text-sm rounded-lg border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
             ></select>
           </div>
@@ -1275,18 +1272,15 @@
             <label
               class="block text-xs font-medium text-gray-500 dark:text-gray-400"
               ><span data-i18n="snippet.link_anchor_label">Anchor</span>
-              <span data-i18n="snippet.link_anchor_hint" class="font-normal text-gray-400"
-                >(without #, e.g. my-heading)</span
+              <span data-i18n="snippet.link_anchor_select_hint" class="font-normal text-gray-400"
+                >(pick a heading from the document)</span
               ></label
             >
-            <input
+            <select
               id="snip-anchor-doc-id"
-              type="text"
-              data-i18n-placeholder="snippet.link_anchor_placeholder"
-              placeholder="my-heading"
-              oninput="snippetUpdatePreview()"
+              onchange="snippetUpdatePreview()"
               class="w-full px-3 py-2 text-sm rounded-lg border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
-            />
+            ></select>
           </div>
         </div>
 

package/dist/src/frontend/snippets.js

@@ -58,6 +58,96 @@ function colorTextPickSwatch(btn) {
   snippetUpdatePreview();
 }
 
+function _stripMdInline(s) {
+  return s
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/__([^_]+)__/g, "$1")
+    .replace(/(^|[^*])\*([^*]+)\*(?!\*)/g, "$1$2")
+    .replace(/(^|[^_])_([^_]+)_(?!_)/g, "$1$2")
+    .trim();
+}
+
+function _slugifyHeading(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+function _extractHeadingsFromMarkdown(content) {
+  const out = [];
+  const lines = (content || "").split("\n");
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (!m) continue;
+    const text = _stripMdInline(m[2]);
+    const slug = _slugifyHeading(text);
+    if (slug) out.push({ level: m[1].length, text, slug });
+  }
+  return out;
+}
+
+function _collectEditorHeadings() {
+  const editor = document.getElementById("doc-editor");
+  return _extractHeadingsFromMarkdown(editor ? editor.value : "");
+}
+
+function _renderAnchorOptions(sel, headings, emptyKey) {
+  if (!sel) return;
+  if (headings.length === 0) {
+    sel.innerHTML = `<option value="" disabled selected>${window.t(emptyKey)}</option>`;
+    return;
+  }
+  sel.innerHTML = headings
+    .map((h) => {
+      const indent = "· ".repeat(Math.max(0, h.level - 1));
+      return `<option value="${esc(h.slug)}">${esc(indent + h.text)}</option>`;
+    })
+    .join("");
+}
+
+function _populateAnchorSelect() {
+  _renderAnchorOptions(
+    document.getElementById("snip-anchor-id"),
+    _collectEditorHeadings(),
+    'snippet.link_anchor_no_headings',
+  );
+}
+
+async function snippetAnchorDocChanged() {
+  const docSel = document.getElementById("snip-anchor-doc-select");
+  const anchorSel = document.getElementById("snip-anchor-doc-id");
+  if (!docSel || !anchorSel) return;
+  const docId = docSel.value;
+  if (!docId) {
+    _renderAnchorOptions(anchorSel, [], 'snippet.link_anchor_no_headings');
+    snippetUpdatePreview();
+    return;
+  }
+  anchorSel.innerHTML = `<option value="" disabled selected>${window.t('common.loading')}</option>`;
+  try {
+    const doc = await fetch("/api/documents/" + encodeURIComponent(docId))
+      .then((r) => {
+        if (!r.ok) throw new Error(r.statusText);
+        return r.json();
+      });
+    const headings = _extractHeadingsFromMarkdown(doc.content || "");
+    _renderAnchorOptions(anchorSel, headings, 'snippet.link_anchor_no_headings');
+  } catch {
+    _renderAnchorOptions(anchorSel, [], 'snippet.link_anchor_no_headings');
+  }
+  snippetUpdatePreview();
+}
+
 function openSnippetsModal() {
   const editor = document.getElementById("doc-editor");
   _snippetSelStart = editor.selectionStart;
@@ -68,6 +158,8 @@ function openSnippetsModal() {
     .join("");
   document.getElementById("snip-doc-select").innerHTML = docOpts;
   document.getElementById("snip-anchor-doc-select").innerHTML = docOpts;
+  _populateAnchorSelect();
+  snippetAnchorDocChanged();
 
   const msgEl = document.getElementById("snippet-detect-msg");
   const selectedText = editor.value.slice(
@@ -443,7 +535,18 @@ function parseAndFillSnippet(text, type) {
       const m = t.match(/^\[([\s\S]*?)\]\(#([\s\S]*?)\)$/);
       if (m) {
         document.getElementById("snip-anchor-text").value = m[1];
-        document.getElementById("snip-anchor-id").value = m[2];
+        const sel = document.getElementById("snip-anchor-id");
+        const wanted = m[2];
+        const hasOpt = Array.from(sel.options).some(
+          (o) => o.value === wanted,
+        );
+        if (!hasOpt) {
+          const opt = document.createElement("option");
+          opt.value = wanted;
+          opt.textContent = wanted;
+          sel.insertBefore(opt, sel.firstChild);
+        }
+        sel.value = wanted;
       }
       break;
     }
@@ -460,7 +563,22 @@ function parseAndFillSnippet(text, type) {
           }
         }
         document.getElementById("snip-anchor-doc-text").value = m[1];
-        document.getElementById("snip-anchor-doc-id").value = m[3];
+        const wanted = m[3];
+        snippetAnchorDocChanged().then(() => {
+          const anchorSel = document.getElementById("snip-anchor-doc-id");
+          if (!anchorSel) return;
+          const hasOpt = Array.from(anchorSel.options).some(
+            (o) => o.value === wanted,
+          );
+          if (!hasOpt) {
+            const opt = document.createElement("option");
+            opt.value = wanted;
+            opt.textContent = wanted;
+            anchorSel.insertBefore(opt, anchorSel.firstChild);
+          }
+          anchorSel.value = wanted;
+          snippetUpdatePreview();
+        });
       }
       break;
     }

package/dist/starting-doc/2026_04_21_19_47_[General]_tata.md

@@ -0,0 +1,6 @@
+# tata
+[vers tutu](?doc=2026_04_21_19_47_%255BGeneral%255D_tutu#tutu)
+
+<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
+
+# tata-anchored

package/dist/starting-doc/2026_04_21_19_47_[General]_tutu.md

@@ -0,0 +1,11 @@
+# tutu
+
+[Vers Titi](?doc=2026_04_21_19_52_%255BGeneral%255D_titi#titi)
+
+[Vers Tata](?doc=2026_04_21_19_47_%255BGeneral%255D_tata#tata)
+
+[Vers tata anchored](?doc=2026_04_21_19_47_%255BGeneral%255D_tata#tata-anchored)
+
+<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
+
+# tutu-anchored

package/dist/starting-doc/2026_04_21_19_52_[General]_titi.md

@@ -0,0 +1,5 @@
+# Titi
+
+[Tata](?doc=2026_04_21_19_47_%255BGeneral%255D_tata)
+
+[Tata anchored](?doc=2026_04_21_19_47_%255BGeneral%255D_tata#tata-anchored)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "living-documentation",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "A CLI tool that serves a local Markdown documentation viewer",
   "main": "dist/src/server.js",
   "bin": {