@solutiondesk/help 1.0.0-a1101b8 → 1.0.0-a6af2d6

package/README.md

@@ -29,7 +29,7 @@ const { page } = await help.page("guides/login"); // one page with its text
 
 | Method | API | Returns |
 | --- | --- | --- |
-| `site({ lang })` | `GET …/site` | The site (`name`, `languages`, `websiteUrl`, its own building `blocks`) and its navigation tree: pages, folders (with index page, `root` tab, `group`, `defaultOpen`, `collapsible`), separators and links. Empty folders are left out. |
+| `site({ lang })` | `GET …/site` | The site (`name`, `languages`, `websiteUrl`, its own building `blocks`) and its navigation tree: pages, folders (with index page, `listIndex`, `root` tab, `description`, `group`, `defaultOpen`, `collapsible`), separators and links. Empty folders are left out. |
 | `pages({ lang })` | `GET …/pages` | Every visible page without its text, in reading order (for builds and sitemaps). |
 | `page(path, { lang, redirect })` | `GET …/page?path=` | One page: `markdown`, `html`, `headings`, `blocks`, `customBlocks`, `breadcrumbs`, `previous`/`next`. The home page has the path `""`. |
 | `pageMarkdown(path, { lang })` | `GET …/page.md?path=` | One page as plain Markdown. |
@@ -37,7 +37,7 @@ const { page } = await help.page("guides/login"); // one page with its text
 | `preview(token, { lang })` | `GET …/preview?token=` | A page in any state (drafts too) for your preview route. |
 | `llmsTxt({ lang })` / `llmsFullTxt({ lang })` | `GET …/llms.txt`, `…/llms-full.txt` | The site for language models: the index, or every page as Markdown. |
 
-`html` is safe to insert as it is: raw HTML in the Markdown is shown as text, links only go to web addresses, `mailto:`, paths and anchors, images only come from your help center. Headings carry the `id`s listed in `headings`.
+`html` is safe to insert as it is: raw HTML in the Markdown is shown as text, links only go to web addresses, `mailto:`, paths and anchors, images only come from your help center. Headings carry the `id`s listed in `headings`, made the way GitHub and Fumadocs make them (umlauts kept, `-1` for a repeat), so a site moved from Fumadocs keeps its `#links`; a step's title is a heading too.
 
 ### Moved pages
 
@@ -104,7 +104,7 @@ The navigation becomes the files Fumadocs knows from a content folder:
 | --- | --- |
 | page `guides/login` | `guides/login.mdx` (`slugs: ["guides", "login"]`) |
 | home page | `index.mdx` at the top, or `(core)/index.mdx` when it is a top-level group's own page |
-| folder `guides` | `guides/meta.json` with `title`, `icon`, `root`, `defaultOpen`, `collapsible`, `pages` |
+| folder `guides` | `guides/meta.json` with `title`, `description` (shown under a tab's name), `pagesIndex` — or, with `listIndex`, `"index"` first in `pages` (after a leading separator), so the page is an entry and the name only opens the folder —, `icon`, `root`, `defaultOpen`, `collapsible`, `pages` |
 | group folder `core` (adds no address part) | `(core)/` — a Fumadocs folder group, so `(core)/sign-up/index.mdx` is still `sign-up` |
 | folder's own page | `guides/index.mdx` (`pagesIndex: "index"`, so it also works for `root` tabs) |
 | any other page with the slug `index` | `guides/index_.mdx` (`slugs: ["guides", "index"]`), so it never collides with the folder's own page |
@@ -286,7 +286,7 @@ document.querySelector("article")!.innerHTML = page.html;
 | Block | HTML |
 | --- | --- |
 | callout | `<div class="sd-callout" data-type="info\|warn\|error\|success\|idea" role="note">` with `<p class="sd-callout-title">` and `<div class="sd-callout-body">` |
-| steps | `<ol class="sd-steps">` of `<li class="sd-step">` with `<p class="sd-step-title">` and `<div class="sd-step-body">` |
+| steps | `<ol class="sd-steps">` of `<li class="sd-step">` with `<h3 class="sd-step-title" id="…">` and `<div class="sd-step-body">` |
 | tabs | `<div class="sd-tabs">` of `<section class="sd-tab" data-title="…">` (build the tab buttons from `data-title`; `page.blocks` says when a page has tabs) |
 | cards | `<div class="sd-cards">` of `<a class="sd-card" href="…" data-icon="Rocket">` (or `<div class="sd-card">`) with `<p class="sd-card-title">` and `<div class="sd-card-body">` |
 | titled code | `<figure class="sd-code"><figcaption>client.ts</figcaption><pre><code class="language-ts">` |

package/dist/fumadocs.d.ts

@@ -81,6 +81,8 @@ interface HelpPublicTreeFolder {
     /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
     path: string;
     title: string;
+    /** A short line under a tab's name in the tab menu (Fumadocs `description`); null without one. */
+    description: string | null;
     icon: string | null;
     /** A tab (top level only; Fumadocs `root`). */
     root: boolean;
@@ -93,6 +95,11 @@ interface HelpPublicTreeFolder {
     collapsible: boolean;
     /** The folder's own page, shown at the folder's path; null without one. */
     index: HelpPublicTreePage | null;
+    /**
+     * List `index` as the folder's first entry (after a section title it starts
+     * with); the folder's name then only opens it (Fumadocs: `index` in `pages`).
+     */
+    listIndex: boolean;
     children: HelpPublicTreeNode[];
 }
 /** A labelled divider between entries (Fumadocs `---Title---`). */
@@ -318,6 +325,8 @@ interface HelpStepsProps {
 }
 interface HelpStepProps {
     title?: string;
+    /** The title's anchor id (a step's title is a heading of the page, level 3). */
+    id?: string;
     children: ReactNode;
 }
 interface HelpTabsProps {
@@ -664,6 +673,8 @@ interface HelpPageData extends PageData {
 /** What every folder's `meta.json` of a help source carries. */
 interface HelpMetaData extends MetaData {
     title?: string;
+    /** Shown under a tab's name in Fumadocs' tab menu. */
+    description?: string;
     icon?: string;
     root?: boolean;
     defaultOpen?: boolean;

package/dist/fumadocs.js

@@ -112,28 +112,25 @@ function codeInfo(lang, meta) {
   const title = (match ? match[1] ?? match[2] ?? match[3] : void 0)?.trim() || void 0;
   return { language, title };
 }
-var TRANSLITERATIONS = {
-  \u00E4: "ae",
-  \u00F6: "oe",
-  \u00FC: "ue",
-  \u00DF: "ss",
-  \u00E6: "ae",
-  \u0153: "oe",
-  \u00F8: "o",
-  \u00E5: "a",
-  \u0111: "d",
-  \u00F0: "d",
-  \u00FE: "th",
-  \u0142: "l",
-  \u0131: "i"
-};
-function headingSlug(text) {
-  return text.normalize("NFC").toLowerCase().replace(/[äöüßæœøåđðþłı]/g, (ch) => TRANSLITERATIONS[ch] ?? ch).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 96).replace(/-+$/, "");
+var GITHUB_SLUG_DROP = /[^\p{L}\p{M}\p{N}\p{Pc} -]/gu;
+function headingId(text, used) {
+  const base = text.toLowerCase().replace(GITHUB_SLUG_DROP, "").replace(/ /g, "-") || "section";
+  let id = base;
+  while (used.has(id)) {
+    const count = (used.get(base) ?? 0) + 1;
+    used.set(base, count);
+    id = `${base}-${count}`;
+  }
+  used.set(id, 0);
+  return id;
+}
+function isTitledStep(node) {
+  return node.type === "containerDirective" && node.name === "step" && !!directiveTitle(node);
 }
 function collectHeadings(root) {
   const out = [];
   const walk = (node) => {
-    if (node.type === "heading") out.push(node);
+    if (node.type === "heading" || isTitledStep(node)) out.push(node);
     if ("children" in node) for (const child of node.children) walk(child);
   };
   walk(root);
@@ -149,12 +146,14 @@ function headingIds(root, known, override) {
     return ids;
   }
   const used = /* @__PURE__ */ new Map();
+  const withoutBlocks = override ? (node) => {
+    if (override(node) === void 0) return void 0;
+    if (node.type !== "textDirective") return "";
+    return node.children.map((child) => plainText(child)).join("").trim();
+  } : void 0;
   for (const heading of headings) {
-    const text = plainText(heading, override).replace(/\s+/g, " ").trim();
-    const base = headingSlug(text) || "section";
-    const seen = used.get(base) ?? 0;
-    used.set(base, seen + 1);
-    ids.set(heading, seen === 0 ? base : `${base}-${seen + 1}`);
+    const text = heading.type === "heading" ? plainText(heading, withoutBlocks) : (directiveTitle(heading) ?? "").replace(/\s+/g, " ").trim();
+    ids.set(heading, headingId(text, used));
   }
   return ids;
 }
@@ -379,8 +378,8 @@ var PLAIN_CODE_COLORS = {
 var helpBodyComponents = {
   Callout: ({ type, title, children }) => /* @__PURE__ */ jsx(Callout, { type, title, children }),
   Steps: ({ children }) => /* @__PURE__ */ jsx(Steps, { children }),
-  Step: ({ title, children }) => /* @__PURE__ */ jsxs(Step, { children: [
-    title ? /* @__PURE__ */ jsx("h3", { children: title }) : null,
+  Step: ({ title, id, children }) => /* @__PURE__ */ jsxs(Step, { children: [
+    title ? /* @__PURE__ */ jsx(Heading, { as: "h3", id, children: title }) : null,
     children
   ] }),
   Tabs: ({ items, children }) => /* @__PURE__ */ jsx(Tabs, { items, children }),
@@ -555,7 +554,7 @@ function renderDirective(node, ctx) {
       return /* @__PURE__ */ jsx(c.Steps, { children: content.map(
         (child, i) => isDirective(child, "step") ? (
           // biome-ignore lint/suspicious/noArrayIndexKey: static content, never reordered.
-          /* @__PURE__ */ jsx(c.Step, { title: directiveTitle(child), children: renderAll(contentOf(child), ctx) }, i)
+          /* @__PURE__ */ jsx(c.Step, { title: directiveTitle(child), id: ctx.ids.get(child), children: renderAll(contentOf(child), ctx) }, i)
         ) : (
           // A loose block between steps becomes a step of its own.
           // biome-ignore lint/suspicious/noArrayIndexKey: static content, never reordered.
@@ -563,7 +562,7 @@ function renderDirective(node, ctx) {
         )
       ) });
     case "step":
-      return /* @__PURE__ */ jsx(c.Steps, { children: /* @__PURE__ */ jsx(c.Step, { title, children: renderAll(content, ctx) }) });
+      return /* @__PURE__ */ jsx(c.Steps, { children: /* @__PURE__ */ jsx(c.Step, { title, id: ctx.ids.get(node), children: renderAll(content, ctx) }) });
     case "tabs":
       return renderTabs(content, ctx);
     case "tab":
@@ -792,6 +791,13 @@ function helpStructuredData(markdown, headings, blocks) {
       if (current && content) out.headings.push({ id: current, content });
       return;
     }
+    if (isTitledStep(node)) {
+      current = ids.get(node);
+      const content = directiveTitle(node) ?? "";
+      if (current) out.headings.push({ id: current, content });
+      for (const child of contentOf(node)) walk(child);
+      return;
+    }
     const use = matcher.use(node);
     if (use) {
       add(use.text);
@@ -864,16 +870,23 @@ function helpTreeToFiles(payload, options) {
     };
     files.push({ type: "page", path: file, slugs: slugsOf(page.path), data });
   };
+  const folderPages = (folder) => {
+    const pages = folder.children.map(helpMetaEntry);
+    if (!folder.index || !folder.listIndex) return pages;
+    const at = folder.children[0]?.type === "separator" ? 1 : 0;
+    return [...pages.slice(0, at), "index", ...pages.slice(at)];
+  };
   const addFolder = (folder, dir) => {
     if (folder.index) addPage(folder.index, join(dir, ext("index", "mdx")));
     const data = {
       title: folder.title,
+      ...folder.description ? { description: folder.description } : {},
       ...folder.icon ? { icon: folder.icon } : {},
       ...folder.root ? { root: true } : {},
       defaultOpen: folder.defaultOpen,
       collapsible: folder.collapsible,
-      ...folder.index ? { pagesIndex: "index" } : {},
-      pages: folder.children.map(helpMetaEntry)
+      ...folder.index && !folder.listIndex ? { pagesIndex: "index" } : {},
+      pages: folderPages(folder)
     };
     files.push({ type: "meta", path: join(dir, ext("meta", "json")), data });
     addChildren(folder.children, dir);

package/dist/index.d.cts

@@ -208,6 +208,8 @@ interface HelpPublicTreeFolder {
     /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
     path: string;
     title: string;
+    /** A short line under a tab's name in the tab menu (Fumadocs `description`); null without one. */
+    description: string | null;
     icon: string | null;
     /** A tab (top level only; Fumadocs `root`). */
     root: boolean;
@@ -220,6 +222,11 @@ interface HelpPublicTreeFolder {
     collapsible: boolean;
     /** The folder's own page, shown at the folder's path; null without one. */
     index: HelpPublicTreePage | null;
+    /**
+     * List `index` as the folder's first entry (after a section title it starts
+     * with); the folder's name then only opens it (Fumadocs: `index` in `pages`).
+     */
+    listIndex: boolean;
     children: HelpPublicTreeNode[];
 }
 /** A labelled divider between entries (Fumadocs `---Title---`). */

package/dist/index.d.ts

@@ -208,6 +208,8 @@ interface HelpPublicTreeFolder {
     /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
     path: string;
     title: string;
+    /** A short line under a tab's name in the tab menu (Fumadocs `description`); null without one. */
+    description: string | null;
     icon: string | null;
     /** A tab (top level only; Fumadocs `root`). */
     root: boolean;
@@ -220,6 +222,11 @@ interface HelpPublicTreeFolder {
     collapsible: boolean;
     /** The folder's own page, shown at the folder's path; null without one. */
     index: HelpPublicTreePage | null;
+    /**
+     * List `index` as the folder's first entry (after a section title it starts
+     * with); the folder's name then only opens it (Fumadocs: `index` in `pages`).
+     */
+    listIndex: boolean;
     children: HelpPublicTreeNode[];
 }
 /** A labelled divider between entries (Fumadocs `---Title---`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solutiondesk/help",
-  "version": "1.0.0-a1101b8",
+  "version": "1.0.0-a6af2d6",
   "description": "Typed, zero-dependency client for the SolutionDesk public help center API, plus a Fumadocs adapter: navigation, pages, search, previews, llms.txt and webhook verification.",
   "keywords": [
     "solutiondesk",