living-documentation 7.0.0

package/dist/src/frontend/misc.js

@@ -0,0 +1,25 @@
+// ── Misc viewer helpers ─────────────────────────────────────────────────────
+
+function toggleFullWidth() {
+  const article = document.getElementById("doc-view");
+  const btn = document.getElementById("full-width-btn");
+  const isWide = article.classList.toggle("max-w-none");
+  article.classList.toggle("max-w-4xl", !isWide);
+  article.classList.toggle("mx-auto", !isWide);
+  btn.textContent = isWide ? window.t('doc.full_width_narrow_btn') : window.t('doc.full_width_btn');
+}
+
+function copyLink() {
+  navigator.clipboard.writeText(location.href).then(() => {
+    const btn = document.getElementById("copy-link-btn");
+    const orig = btn.innerHTML;
+    btn.textContent = window.t('doc.copied');
+    setTimeout(() => {
+      btn.innerHTML = orig;
+    }, 1800);
+  });
+}
+
+function exportPDF() {
+  window.print();
+}

package/dist/src/frontend/new-doc-modal.js

@@ -0,0 +1,260 @@
+// ── New Document modal ──────────────────────────────────────────────────────
+// Depends on globals from state.js (currentDocId, allDocs), documents.js
+// (loadDocuments, openDocument) and utils.js (esc).
+
+let _newDocBrowseCurrent = null;
+let _newDocBrowseParent = null;
+let _newDocSelectedFolder = "";
+let _newDocDocsFolder = "";
+let _newDocPattern = "YYYY_MM_DD_HH_mm_[Category]_title";
+
+async function openNewDocModal() {
+  try {
+    const cfg = await fetch("/api/config").then((r) => r.json());
+    _newDocDocsFolder = cfg.docsFolder || "";
+    _newDocPattern =
+      cfg.filenamePattern || "YYYY_MM_DD_HH_mm_[Category]_title";
+  } catch {
+    _newDocDocsFolder = "";
+    _newDocPattern = "YYYY_MM_DD_HH_mm_[Category]_title";
+  }
+  // Pre-fill from currently open document if any
+  const currentDoc =
+    currentDocId && allDocs.find((d) => d.id === currentDocId);
+  const prefillCategory =
+    (currentDoc && currentDoc.category) || "General";
+  // Derive folder from currentDocId (encoded relative path, e.g. "1_tutorial%2Fsome_file")
+  // For extra files (absolute paths), skip.
+  let prefillFolder = "";
+  if (currentDocId) {
+    const decodedId = decodeURIComponent(currentDocId);
+    if (!decodedId.startsWith("/")) {
+      const segments = decodedId.split("/");
+      if (segments.length > 1) {
+        prefillFolder = segments.slice(0, -1).join("/");
+      }
+    }
+  }
+  const prefillFolderAbs = prefillFolder
+    ? _newDocDocsFolder + "/" + prefillFolder
+    : "";
+
+  _newDocSelectedFolder = prefillFolder;
+  _newDocBrowseCurrent = prefillFolderAbs || null;
+  _newDocBrowseParent = null;
+  document.getElementById("new-doc-title").value = "";
+  document.getElementById("new-doc-category").value = prefillCategory;
+  document.getElementById("new-doc-folder-display").textContent =
+    prefillFolder ? "/" + prefillFolder : "/ (root)";
+  document.getElementById("new-doc-browser").classList.add("hidden");
+  document.getElementById("new-doc-new-folder-name").value = "";
+  document.getElementById("new-doc-error").classList.add("hidden");
+  const createBtn = document.getElementById("new-doc-create-btn");
+  createBtn.disabled = false;
+  createBtn.textContent = window.t('common.create');
+  newDocUpdatePreview();
+  document.getElementById("new-doc-modal").classList.remove("hidden");
+  setTimeout(() => document.getElementById("new-doc-title").focus(), 50);
+}
+
+function closeNewDocModal() {
+  document.getElementById("new-doc-modal").classList.add("hidden");
+}
+
+function newDocToggleBrowser() {
+  const browser = document.getElementById("new-doc-browser");
+  const isHidden = browser.classList.toggle("hidden");
+  if (!isHidden)
+    newDocLoadBrowse(_newDocBrowseCurrent || _newDocDocsFolder);
+}
+
+async function newDocLoadBrowse(dirPath) {
+  const list = document.getElementById("new-doc-browse-list");
+  list.innerHTML =
+    `<p class="px-3 py-4 text-xs text-gray-400 text-center">${window.t('common.loading')}</p>`;
+  try {
+    const data = await fetch(
+      "/api/browse?path=" + encodeURIComponent(dirPath),
+    ).then((r) => r.json());
+    _newDocBrowseCurrent = data.current;
+    _newDocBrowseParent = data.parent;
+    document.getElementById("new-doc-browse-path").textContent =
+      data.current;
+    const atRoot = data.current === _newDocDocsFolder;
+    document.getElementById("new-doc-browse-up").disabled = atRoot;
+
+    const rows = data.dirs.map(
+      (dir) =>
+        `<div class="flex items-center hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
+          <button data-path="${esc(dir.path)}" onclick="newDocLoadBrowse(this.dataset.path)"
+            class="flex-1 flex items-center gap-2 px-3 py-2 text-sm text-left">
+            <span class="text-gray-400 shrink-0">&#128193;</span>
+            <span class="text-gray-700 dark:text-gray-300 truncate">${esc(dir.name)}</span>
+          </button>
+          <button data-path="${esc(dir.path)}" onclick="newDocSelectFolder(this.dataset.path)"
+            title="${window.t('modal.new_doc.use_folder_btn')}"
+            class="shrink-0 text-blue-400 hover:text-blue-600 px-3 py-2 text-sm transition-colors">&#10003;</button>
+        </div>`,
+    );
+
+    const selectBtn = `<button onclick="newDocSelectCurrentFolder()"
+      class="w-full px-3 py-2 text-xs text-blue-600 dark:text-blue-400 hover:bg-blue-50 dark:hover:bg-blue-950/30 text-left font-medium border-t border-gray-100 dark:border-gray-800">
+      ${window.t('modal.new_doc.use_folder_btn')}
+    </button>`;
+
+    list.innerHTML =
+      (rows.length
+        ? rows.join("")
+        : `<p class="px-3 py-3 text-xs text-gray-400 text-center">${window.t('modal.new_doc.no_subfolders')}</p>`) +
+      selectBtn;
+  } catch {
+    list.innerHTML =
+      `<p class="px-3 py-4 text-xs text-red-400 text-center">${window.t('common.cannot_read_dir')}</p>`;
+  }
+}
+
+function newDocBrowseUp() {
+  if (_newDocBrowseCurrent !== _newDocDocsFolder && _newDocBrowseParent) {
+    newDocLoadBrowse(_newDocBrowseParent);
+  }
+}
+
+function _newDocAbsToRel(absPath) {
+  const base = _newDocDocsFolder;
+  if (absPath === base) return "";
+  if (absPath.startsWith(base + "/"))
+    return absPath.slice(base.length + 1);
+  return absPath;
+}
+
+function newDocSelectFolder(absPath) {
+  _newDocSelectedFolder = _newDocAbsToRel(absPath);
+  _newDocBrowseCurrent = absPath;
+  document.getElementById("new-doc-folder-display").textContent =
+    _newDocSelectedFolder ? "/" + _newDocSelectedFolder : "/ (root)";
+  document.getElementById("new-doc-browser").classList.add("hidden");
+  newDocUpdatePreview();
+}
+
+function newDocSelectCurrentFolder() {
+  newDocSelectFolder(_newDocBrowseCurrent || _newDocDocsFolder);
+}
+
+function newDocCreateFolder() {
+  const name = document
+    .getElementById("new-doc-new-folder-name")
+    .value.trim();
+  if (!name) return;
+  const parent = _newDocBrowseCurrent || _newDocDocsFolder;
+  const newRelPath =
+    (_newDocAbsToRel(parent) ? _newDocAbsToRel(parent) + "/" : "") + name;
+  _newDocSelectedFolder = newRelPath;
+  document.getElementById("new-doc-folder-display").textContent =
+    "/" + newRelPath;
+  document.getElementById("new-doc-new-folder-name").value = "";
+  document.getElementById("new-doc-browser").classList.add("hidden");
+  newDocUpdatePreview();
+}
+
+function newDocUpdatePreview() {
+  const title = document.getElementById("new-doc-title").value.trim();
+  const category =
+    document.getElementById("new-doc-category").value.trim() || "General";
+  const previewEl = document.getElementById("new-doc-filename-preview");
+
+  if (!title) {
+    previewEl.textContent = window.t('modal.new_doc.title_placeholder');
+    return;
+  }
+
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  const hours = String(now.getHours()).padStart(2, "0");
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const titleSlug =
+    title
+      .toLowerCase()
+      .replace(/\s+/g, "_")
+      .replace(/[^a-z0-9_]/g, "")
+      .replace(/_+/g, "_")
+      .replace(/^_|_$/g, "") || "document";
+
+  const filename =
+    _newDocPattern
+      .replace("YYYY", year)
+      .replace("MM", month)
+      .replace("DD", day)
+      .replace("HH", hours)
+      .replace("mm", minutes)
+      .replace(/\[Category\]/i, `[${category}]`)
+      .replace(
+        /(?<![a-z0-9])(?:title_words|title)(?![a-z0-9])/i,
+        titleSlug,
+      ) + ".md";
+
+  previewEl.textContent = _newDocSelectedFolder
+    ? _newDocSelectedFolder + "/" + filename
+    : filename;
+}
+
+async function createNewDocument() {
+  const title = document.getElementById("new-doc-title").value.trim();
+  const category =
+    document.getElementById("new-doc-category").value.trim() || "General";
+  const errorEl = document.getElementById("new-doc-error");
+  const btn = document.getElementById("new-doc-create-btn");
+
+  if (!title) {
+    errorEl.textContent = window.t('modal.new_doc.error_empty_title');
+    errorEl.classList.remove("hidden");
+    return;
+  }
+
+  errorEl.classList.add("hidden");
+  btn.disabled = true;
+  btn.textContent = window.t('modal.new_folder.creating_btn');
+
+  try {
+    const res = await fetch("/api/documents", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        title,
+        category,
+        folder: _newDocSelectedFolder,
+      }),
+    });
+
+    if (!res.ok) {
+      const data = await res.json();
+      throw new Error(data.error || "Creation failed");
+    }
+
+    const doc = await res.json();
+    closeNewDocModal();
+    await loadDocuments();
+    openDocument(doc.id);
+  } catch (err) {
+    errorEl.textContent = window.t('common.error_prefix') + err.message;
+    errorEl.classList.remove("hidden");
+    btn.disabled = false;
+    btn.textContent = window.t('common.create');
+  }
+}
+
+// Allow Enter key in title/category to submit
+document.addEventListener("DOMContentLoaded", () => {
+  ["new-doc-title", "new-doc-category"].forEach((id) => {
+    document.getElementById(id)?.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") createNewDocument();
+      if (e.key === "Escape") closeNewDocModal();
+    });
+  });
+  document
+    .getElementById("new-doc-new-folder-name")
+    ?.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") newDocCreateFolder();
+    });
+});

package/dist/src/frontend/new-folder-modal.js

@@ -0,0 +1,174 @@
+// ── New Folder modal ────────────────────────────────────────────────────────
+// Depends on globals from state.js (currentDocId) and documents.js
+// (loadDocuments).
+
+let _newFolderDocsFolder = "";
+let _newFolderBrowseCurrent = null;
+let _newFolderBrowseParent = null;
+let _newFolderSelectedPath = "";
+
+async function openNewFolderModal() {
+  try {
+    const cfg = await fetch("/api/config").then((r) => r.json());
+    _newFolderDocsFolder = cfg.docsFolder || "";
+  } catch {
+    _newFolderDocsFolder = "";
+  }
+
+  // Pre-fill location from currently open document
+  let prefillFolder = "";
+  if (currentDocId) {
+    const decodedId = decodeURIComponent(currentDocId);
+    if (!decodedId.startsWith("/")) {
+      const segments = decodedId.split("/");
+      if (segments.length > 1)
+        prefillFolder = segments.slice(0, -1).join("/");
+    }
+  }
+
+  _newFolderSelectedPath = prefillFolder
+    ? _newFolderDocsFolder + "/" + prefillFolder
+    : _newFolderDocsFolder;
+  _newFolderBrowseCurrent = _newFolderSelectedPath;
+  _newFolderBrowseParent = null;
+
+  document.getElementById("new-folder-name").value = "";
+  document.getElementById("new-folder-location-display").textContent =
+    prefillFolder ? "/" + prefillFolder : "/ (root)";
+  document.getElementById("new-folder-browser").classList.add("hidden");
+  document.getElementById("new-folder-error").classList.add("hidden");
+  const btn = document.getElementById("new-folder-create-btn");
+  btn.disabled = false;
+  btn.textContent = window.t('modal.new_folder.create_btn');
+  newFolderUpdatePreview();
+  document.getElementById("new-folder-modal").classList.remove("hidden");
+  setTimeout(
+    () => document.getElementById("new-folder-name").focus(),
+    50,
+  );
+}
+
+function closeNewFolderModal() {
+  document.getElementById("new-folder-modal").classList.add("hidden");
+}
+
+function newFolderToggleBrowser() {
+  const browser = document.getElementById("new-folder-browser");
+  const isHidden = browser.classList.toggle("hidden");
+  if (!isHidden)
+    newFolderLoadBrowse(_newFolderBrowseCurrent || _newFolderDocsFolder);
+}
+
+async function newFolderLoadBrowse(dirPath) {
+  const list = document.getElementById("new-folder-browse-list");
+  list.innerHTML =
+    `<p class="px-3 py-4 text-xs text-gray-400 text-center">${window.t('common.loading')}</p>`;
+  try {
+    const data = await fetch(
+      "/api/browse?path=" + encodeURIComponent(dirPath),
+    ).then((r) => r.json());
+    _newFolderBrowseCurrent = data.current;
+    _newFolderBrowseParent = data.parent;
+    document.getElementById("new-folder-browse-path").textContent =
+      data.current;
+    const atRoot = data.current === _newFolderDocsFolder;
+    document.getElementById("new-folder-browse-up").disabled = atRoot;
+
+    list.innerHTML = data.dirs.length
+      ? data.dirs
+          .map(
+            (dir) => `
+          <div class="flex items-center hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
+            <button data-path="${esc(dir.path)}" onclick="newFolderLoadBrowse(this.dataset.path)"
+              class="flex-1 flex items-center gap-2 px-3 py-2 text-sm text-left">
+              <span class="text-gray-400 shrink-0">&#128193;</span>
+              <span class="truncate text-gray-700 dark:text-gray-300">${esc(dir.name)}</span>
+            </button>
+            <button data-path="${esc(dir.path)}" onclick="newFolderSelectFolder(this.dataset.path)"
+              class="px-3 py-2 text-xs text-blue-600 dark:text-blue-400 hover:underline shrink-0">${window.t('modal.new_folder.browse_select_btn')}</button>
+          </div>`,
+          )
+          .join("")
+      : `<p class="px-3 py-3 text-xs text-gray-400 text-center">${window.t('modal.new_folder.no_subfolders')}</p>`;
+  } catch {
+    list.innerHTML =
+      `<p class="px-3 py-3 text-xs text-red-400 text-center">${window.t('modal.new_folder.error_loading')}</p>`;
+  }
+}
+
+function newFolderBrowseUp() {
+  if (_newFolderBrowseParent) newFolderLoadBrowse(_newFolderBrowseParent);
+}
+
+function newFolderSelectCurrentLocation() {
+  newFolderSelectFolder(_newFolderBrowseCurrent || _newFolderDocsFolder);
+}
+
+function newFolderSelectFolder(absPath) {
+  _newFolderSelectedPath = absPath;
+  _newFolderBrowseCurrent = absPath;
+  const rel = absPath.startsWith(_newFolderDocsFolder + "/")
+    ? absPath.slice(_newFolderDocsFolder.length)
+    : absPath === _newFolderDocsFolder
+      ? ""
+      : absPath;
+  document.getElementById("new-folder-location-display").textContent = rel
+    ? rel
+    : "/ (root)";
+  document.getElementById("new-folder-browser").classList.add("hidden");
+  newFolderUpdatePreview();
+}
+
+function newFolderUpdatePreview() {
+  const name = document.getElementById("new-folder-name").value.trim();
+  const previewEl = document.getElementById("new-folder-preview");
+  if (!name) {
+    previewEl.textContent = window.t('modal.new_folder.enter_name');
+    return;
+  }
+  const base = _newFolderSelectedPath || _newFolderDocsFolder;
+  const rel = base.startsWith(_newFolderDocsFolder)
+    ? base.slice(_newFolderDocsFolder.length).replace(/^\//, "")
+    : "";
+  previewEl.textContent = (rel ? rel + "/" : "") + name;
+}
+
+async function createNewFolder() {
+  const name = document.getElementById("new-folder-name").value.trim();
+  const errEl = document.getElementById("new-folder-error");
+  errEl.classList.add("hidden");
+
+  if (!name) {
+    errEl.textContent = window.t('modal.new_folder.error_empty');
+    errEl.classList.remove("hidden");
+    return;
+  }
+  if (!/^[a-zA-Z0-9_\-. ]+$/.test(name)) {
+    errEl.textContent = window.t('modal.new_folder.error_invalid_chars');
+    errEl.classList.remove("hidden");
+    return;
+  }
+
+  const base = _newFolderSelectedPath || _newFolderDocsFolder;
+  const fullPath = base.endsWith("/") ? base + name : base + "/" + name;
+
+  const btn = document.getElementById("new-folder-create-btn");
+  btn.disabled = true;
+  btn.textContent = window.t('modal.new_folder.creating_btn');
+
+  try {
+    const res = await fetch("/api/browse/mkdir", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: fullPath }),
+    });
+    if (!res.ok) throw new Error(await res.text());
+    closeNewFolderModal();
+    await loadDocuments();
+  } catch (err) {
+    btn.disabled = false;
+    btn.textContent = window.t('modal.new_folder.create_btn');
+    errEl.textContent = window.t('common.error_prefix') + err.message;
+    errEl.classList.remove("hidden");
+  }
+}

package/dist/src/frontend/search.js

@@ -0,0 +1,157 @@
+// ── Search + result highlighting ─────────────────────────────────────────────
+
+let searchTimer = null;
+
+function setupSearch() {
+  ["header-search", "sidebar-search"].forEach((id) => {
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.addEventListener("input", (e) => {
+      const q = e.target.value.trim();
+      // Sync the other input
+      ["header-search", "sidebar-search"].forEach((oid) => {
+        if (oid !== id) {
+          const other = document.getElementById(oid);
+          if (other) other.value = q;
+        }
+      });
+      clearTimeout(searchTimer);
+      if (!q) {
+        searchQuery = "";
+        searchResults = null;
+        renderSidebar(allDocs);
+        return;
+      }
+      searchQuery = q;
+      // Immediate client-side filter for snappy UX
+      const local = allDocs.filter(
+        (d) =>
+          d.title.toLowerCase().includes(q.toLowerCase()) ||
+          d.category.toLowerCase().includes(q.toLowerCase()),
+      );
+      searchResults = local;
+      renderSidebar(local);
+      // Then full-text search from server
+      searchTimer = setTimeout(() => doSearch(q), 350);
+    });
+  });
+}
+
+async function doSearch(q) {
+  try {
+    const results = await fetch(
+      "/api/documents/search?q=" + encodeURIComponent(q),
+    ).then((r) => r.json());
+    if (q !== searchQuery) return;
+    searchResults = results;
+    renderSidebar(results);
+  } catch {
+    /* ignore */
+  }
+}
+
+function highlightMatches(el, q) {
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  const nodes = [];
+  while (walker.nextNode()) nodes.push(walker.currentNode);
+  const re = new RegExp(
+    `(${q.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})`,
+    "gi",
+  );
+  let idx = 0;
+  nodes.forEach((node) => {
+    if (!node.textContent.toLowerCase().includes(q.toLowerCase())) return;
+    const span = document.createElement("span");
+    span.innerHTML = node.textContent.replace(
+      re,
+      (m) => `<mark id="match-${idx++}">${m}</mark>`,
+    );
+    node.parentNode.replaceChild(span, node);
+  });
+  // Build snippet list from inserted marks
+  const matches = [];
+  el.querySelectorAll("mark[id^='match-']").forEach((mark) => {
+    const block =
+      mark.closest("p, li, td, h1, h2, h3, h4, h5, h6, pre") ||
+      mark.parentElement;
+    const full = block.textContent.trim();
+    const pos = full.toLowerCase().indexOf(q.toLowerCase());
+    const start = Math.max(0, pos - 40);
+    const end = Math.min(full.length, pos + q.length + 40);
+    const snippet =
+      (start > 0 ? "…" : "") +
+      full.slice(start, end) +
+      (end < full.length ? "…" : "");
+    matches.push({ id: mark.id, snippet });
+  });
+  return matches;
+}
+
+function buildSearchNotice(matches, q) {
+  document.getElementById("search-notice-title").textContent =
+    window.t(matches.length === 1 ? 'search.notice_singular' : 'search.notice_plural')
+    .replace('{count}', matches.length).replace('{query}', q);
+  const list = document.getElementById("search-notice-list");
+  list.innerHTML = matches
+    .map(
+      (m, i) =>
+        `<li>
+      <button onclick="scrollToMatch('${m.id}')" data-match-id="${m.id}"
+        class="w-full text-left px-3 py-1.5 hover:bg-yellow-100 dark:hover:bg-yellow-900/30 transition-colors">
+        <span class="text-yellow-600 dark:text-yellow-500 font-mono text-xs mr-2">${i + 1}.</span
+        ><span class="text-xs">${esc(m.snippet)}</span>
+      </button>
+    </li>`,
+    )
+    .join("");
+}
+
+function scrollToAnchor(anchorId) {
+  const container = document.getElementById("content-area");
+  const target = document.getElementById(anchorId);
+  if (!container || !target) return;
+  const stickyHeader = document.querySelector("#doc-view header");
+  const headerHeight = stickyHeader
+    ? stickyHeader.getBoundingClientRect().height
+    : 0;
+  const targetTop = target.getBoundingClientRect().top;
+  const containerTop = container.getBoundingClientRect().top;
+  container.scrollTop += targetTop - containerTop - headerHeight - 8;
+}
+
+function scrollToMatch(id) {
+  const mark = document.getElementById(id);
+  const container = document.getElementById("content-area");
+  if (!mark || !container) return;
+
+  // Open any collapsed <details> ancestors so the match is visible
+  let ancestor = mark.parentElement;
+  while (ancestor && ancestor !== container) {
+    if (ancestor.tagName === "DETAILS" && !ancestor.open) {
+      ancestor.open = true;
+    }
+    ancestor = ancestor.parentElement;
+  }
+
+  // Orange on the active mark, yellow on the rest
+  document
+    .querySelectorAll("mark.match-active")
+    .forEach((m) => m.classList.remove("match-active"));
+  mark.classList.add("match-active");
+
+  // Highlight active list item
+  document.querySelectorAll("#search-notice-list button").forEach((b) => {
+    b.classList.toggle("bg-orange-100", b.dataset.matchId === id);
+    b.classList.toggle("dark:bg-orange-900/30", b.dataset.matchId === id);
+  });
+
+  const stickyHeader = document.querySelector("#doc-view header");
+  const headerHeight = stickyHeader
+    ? stickyHeader.getBoundingClientRect().height
+    : 0;
+  const markTop = mark.getBoundingClientRect().top;
+  const containerTop = container.getBoundingClientRect().top;
+  const targetOffset =
+    headerHeight + (container.clientHeight - headerHeight) / 3;
+  container.scrollTop += markTop - containerTop - targetOffset;
+}

package/dist/src/frontend/sidebar-helpers.js

@@ -0,0 +1,58 @@
+// ── Sidebar helpers — tree traversal + annotation badges ─────────────────────
+// Loaded as a classic script; all symbols are global.
+// Depends on globals defined elsewhere: `annotationCounts` (index.html),
+// `esc` (utils.js), `window.t` (i18n.js).
+
+function countTreeDocs(node) {
+  let n = Object.values(node.categories).reduce(
+    (s, arr) => s + arr.length,
+    0,
+  );
+  for (const child of Object.values(node.children))
+    n += countTreeDocs(child);
+  return n;
+}
+
+function countTreeAnnotations(node) {
+  let n = 0;
+  for (const arr of Object.values(node.categories)) {
+    for (const doc of arr) n += annotationCounts[doc.id] || 0;
+  }
+  for (const child of Object.values(node.children))
+    n += countTreeAnnotations(child);
+  return n;
+}
+
+function countTreeAnnotatedDocs(node) {
+  let n = 0;
+  for (const arr of Object.values(node.categories)) {
+    for (const doc of arr) if (annotationCounts[doc.id] > 0) n += 1;
+  }
+  for (const child of Object.values(node.children))
+    n += countTreeAnnotatedDocs(child);
+  return n;
+}
+
+function annotationBadge(count) {
+  if (!count) return "";
+  const label = window.t
+    ? window.t("sidebar.annotation_badge")
+    : "annotation";
+  return `<span title="${count} ${esc(label)}${count > 1 ? "s" : ""}"
+                 class="inline-flex items-center justify-center min-w-[1.25rem] h-5 px-1.5
+                        rounded-full bg-yellow-300 dark:bg-yellow-400
+                        text-[10px] font-bold text-yellow-900
+                        border border-yellow-500 shadow-sm">${count}</span>`;
+}
+
+function annotatedDocsBadge(count) {
+  if (!count) return "";
+  const label = window.t
+    ? window.t("sidebar.annotated_docs_badge")
+    : "document with annotations";
+  return `<span title="${count} ${esc(label)}${count > 1 ? "s" : ""}"
+                 class="inline-flex items-center justify-center min-w-[1.25rem] h-5 px-1.5
+                        rounded-full bg-orange-400 dark:bg-orange-500
+                        text-[10px] font-bold text-white
+                        border border-orange-600 shadow-sm">${count}</span>`;
+}