@solutiondesk/help 1.0.0-69d9f69 → 1.0.0-8141b92

package/README.md

@@ -29,15 +29,15 @@ const { page } = await help.page("guides/login"); // one page with its text
 
 | Method | API | Returns |
 | --- | --- | --- |
-| `site({ lang })` | `GET …/site` | The site (`name`, `languages`, `websiteUrl`) and its navigation tree: pages, folders (with index page, `root` tab, `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`, `breadcrumbs`, `previous`/`next`. The home page has the path `""`. |
+| `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. |
 | `search(query, { lang, limit })` | `GET …/search?q=` | Up to 20 hits: title hits before heading hits before text hits, with an `excerpt` and the best `heading`. |
 | `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
 
@@ -103,15 +103,16 @@ The navigation becomes the files Fumadocs knows from a content folder:
 | SolutionDesk | Fumadocs |
 | --- | --- |
 | page `guides/login` | `guides/login.mdx` (`slugs: ["guides", "login"]`) |
-| home page | `index.mdx` (always at the top) |
-| folder `guides` | `guides/meta.json` with `title`, `icon`, `root`, `defaultOpen`, `collapsible`, `pages` |
+| 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`, `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 |
 | order of the top level | `meta.json` (`title` = site name) |
 | separator | `"---[Icon]Title---"` (a separator without a title is `"---"`) |
 | link | `"[Icon][Title](url)"`, `"external:[Icon][Title](url)"` |
 
-Every page's `data` holds `title`, `description`, `icon`, `path`, `lang`, `load()` (the page with its text, or `null` when the page was taken offline after the source was built — answer with a 404) and `structuredData()` (for Fumadocs search; empty for such a page, so it never breaks the search index).
+Every page's `data` holds `title`, `description`, `icon`, `path`, `lang`, `blocks` (the site's own building blocks, for `HelpBody`), `load()` (the page with its text, or `null` when the page was taken offline after the source was built — answer with a 404) and `structuredData()` (for Fumadocs search; empty for such a page, so it never breaks the search index).
 
 **Lazy or eager.** The page list has no texts, so by default (`pages: "lazy"`) building the source costs one request per language, and `page.data.load()` fetches a page's text when it is rendered. Cache that with your framework (the tags above). With `pages: "eager"` every page is fetched while building (`concurrency`, default 6) and kept in `page.data.page`: slower to build, nothing fetched later, best for a fully static export.
 
@@ -152,7 +153,7 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
       <DocsTitle>{page.title}</DocsTitle>
       <DocsDescription>{page.description}</DocsDescription>
       <DocsBody>
-        <HelpBody markdown={page.markdown} headings={page.headings} icon={icon} />
+        <HelpBody page={page} blocks={entry.data.blocks} icon={icon} />
       </DocsBody>
     </DocsPage>
   );
@@ -163,20 +164,67 @@ export async function generateStaticParams() {
 }
 ```
 
-`HelpBody` renders the Markdown with Fumadocs UI: `:::callout` → `Callout`, `::::steps`/`:::step` → `Steps`/`Step`, `::::tabs`/`:::tab` → `Tabs`/`Tab`, `::::cards`/`:::card` → `Cards`/`Card`, a code fence with `title="…"` → `CodeBlock`. Pass `headings` so the anchors match `getHelpToc`. Replace any part with `components`, for example syntax highlighting:
+`page` gives `HelpBody` the page's `markdown`, `headings` and `locale`; you can also pass `markdown`, `headings` and `lang` yourself. `HelpBody` renders the Markdown with Fumadocs UI: `:::callout` → `Callout`, `::::steps`/`:::step` → `Steps`/`Step`, `::::tabs`/`:::tab` → `Tabs`/`Tab`, `::::cards`/`:::card` → `Cards`/`Card`, a code fence with `title="…"` → `CodeBlock`. Pass `headings` (or `page`) so the anchors match `getHelpToc`. Replace any part with `components`, for example syntax highlighting:
 
 ```tsx
 import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock";
 
 <HelpBody
-  markdown={page.markdown}
-  headings={page.headings}
+  page={page}
   components={{ Code: ({ code, lang, title }) => <DynamicCodeBlock lang={lang ?? "text"} code={code} codeblock={{ title }} /> }}
 />;
 ```
 
 The same safety rules as the API's `html` apply: raw HTML is shown as text, links only go to `http(s)`, `mailto:`, `/paths` and `#anchors`, images only come from `http(s)` or `/paths` — never to another host through `//`, `/\`, `\\` or control characters hidden in the address. A directive SolutionDesk doesn't know stays the text it was written as.
 
+### Your own building blocks
+
+In SolutionDesk, a doc site can define its own building blocks: what a block is called, whether it sits in a sentence, on its own line or around content, and which fields it has. How it looks is up to your website. Map each block's name to one of your components:
+
+```tsx
+import { type HelpBlockProps, HelpBody } from "@solutiondesk/help/fumadocs";
+import { icons } from "lucide-react";
+
+// :app-button{icon="Palette" label="Your team"} — in a sentence
+function AppButton({ icon, label }: HelpBlockProps<{ icon: string; label: string }>) {
+  const Icon = icon ? icons[icon as keyof typeof icons] : undefined;
+  return <kbd className="app-button">{Icon ? <Icon /> : null}{label}</kbd>;
+}
+
+// ::paid-addon{name="Events"} — on its own line
+function PaidAddon({ name, lang }: HelpBlockProps<{ name: string }>) {
+  return <aside className="paid-addon">{lang === "de" ? "Kostenpflichtig" : "Paid add-on"}: {name}</aside>;
+}
+
+// :::download-buttons{title="UXP installer" versionsHref="#versions"} … ::: — around content
+function DownloadButtons({ title, versionsHref, children }: HelpBlockProps<{ title: string; versionsHref: string }>) {
+  return (
+    <section className="downloads">
+      <h4>{title}</h4>
+      {children}
+      {versionsHref ? <a href={versionsHref}>Older versions</a> : null}
+    </section>
+  );
+}
+
+<HelpBody
+  page={page}
+  blocks={entry.data.blocks} // or `site.blocks` from `help.site()`
+  components={{ "app-button": AppButton, "paid-addon": PaidAddon, "download-buttons": DownloadButtons }}
+/>;
+```
+
+A component gets:
+
+- the block's **fields**, already checked the way SolutionDesk checks them: text fields as strings, on/off fields as `true`/`false`. A value that isn't valid (an unsafe address such as `javascript:`, a picture or video address that isn't allowed, an icon name that isn't one, an option that isn't offered) is left out, so every field may be missing — `HelpBlockProps<Fields>` types them as optional.
+- `lang`: the page's language (`page.locale`, or the `lang` you pass) — no need to store it in the block.
+- `block`: the block's name.
+- `children`: for a block in a sentence or on its own line, its text in `[brackets]` (`:app-button[Share]{icon="Share2"}`); for a block around content, that content, rendered like the rest of the page (built-in and own blocks inside included).
+
+`block`, `lang` and `children` always mean the above; SolutionDesk doesn't allow fields with these names. A block the site defines but you have no component for shows its **text version** (set in SolutionDesk, e.g. `Paid add-on: Events`) in a neutral `<span class="sd-block" data-block="…" data-props="…">` (in a sentence) or `<div class="sd-block">` (on its own line; around content with `<p class="sd-block-text">` and `<div class="sd-block-body">`) — the same as the API's `html`. A name the site doesn't define, or a block written in the wrong form, stays the text it was written as. Without `blocks`, every one of them stays text. Search data (`structuredData()`) and heading anchors use the text version as well, like the API's search.
+
+`helpBlockValues(definition, attributes)` and `helpBlockText(definition, values, label?)` expose the same rules if you render blocks yourself.
+
 ### Refresh when something changes
 
 In SolutionDesk set the site's webhook to a route on your website and copy the signing secret. The handler checks the `X-SolutionDesk-Signature` header and answers `401` when it doesn't match (or is older than 5 minutes) and `400` for a signed body that isn't a help webhook:
@@ -238,10 +286,11 @@ 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">` |
+| the site's own block | `<span class="sd-block" data-block="app-button" data-props="{…}">` in a sentence, `<div class="sd-block">` on its own line or around content (`<p class="sd-block-text">`, `<div class="sd-block-body">`); the text is the block's text version, `data-props` its checked values as JSON — hydrate your own component from it |
 
 Build the table of contents from `page.headings` (`#id`), the breadcrumb from `page.breadcrumbs` and the footer links from `page.previous`/`page.next`.
 

package/dist/fumadocs.d.ts

@@ -1,4 +1,4 @@
-import { ComponentType, ReactNode } from 'react';
+import { JSXElementConstructor, ReactNode, ComponentType } from 'react';
 import { MetaData, PageData, StaticSource, VirtualFile, DynamicSource } from 'fumadocs-core/source';
 import { TOCItemType } from 'fumadocs-core/toc';
 
@@ -12,7 +12,8 @@ import { TOCItemType } from 'fumadocs-core/toc';
  * preview token names. Absent values are `null`, never a missing key.
  *
  * Paths: a page's path is its folder slugs plus its slug, without leading or
- * trailing slash (`guides/login`); the site's home page has the path `""`.
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
  */
 /** The doc site itself. */
 interface HelpPublicSite {
@@ -25,6 +26,40 @@ interface HelpPublicSite {
     languages: string[];
     /** The docs website's base address (`https://help.acme.com/docs`), if set. */
     websiteUrl: string | null;
+    /** The site's own building blocks pages may use (empty when it defines none). */
+    blocks: HelpPublicBlockDefinition[];
+}
+/** What a field of a site's own block holds (see {@link HelpPublicBlockField}). */
+type HelpPublicBlockFieldType = "text" | "longText" | "icon" | "url" | "choice" | "image" | "video" | "boolean";
+/**
+ * One field of a site's own block: an attribute of its directive
+ * (`key="value"`). `boolean` fields are on when written bare (`key`) or as
+ * `key="true"`; every other value is a string. `options` lists a `choice`
+ * field's values (null for other types).
+ */
+interface HelpPublicBlockField {
+    key: string;
+    label: string;
+    type: HelpPublicBlockFieldType;
+    required: boolean;
+    options: string[] | null;
+}
+/**
+ * A building block the site defines itself — WHAT it is; how it looks is the
+ * website's own component. Written in Markdown as `:name[label]{…}` in running
+ * text (`inline`), `::name[label]{…}` alone on a line (`block`) or
+ * `:::name{…}` … `:::` around Markdown content (`container`). `text` is the
+ * template of its text version (`{key}` = a field's value, a `boolean` field's
+ * label when on; `{{`/`}}` = a brace) — what to show without a component.
+ */
+interface HelpPublicBlockDefinition {
+    /** The directive name (`app-button`). */
+    name: string;
+    /** Display name. */
+    label: string;
+    kind: "inline" | "block" | "container";
+    fields: HelpPublicBlockField[];
+    text: string;
 }
 /** A page in the navigation. */
 interface HelpPublicTreePage {
@@ -43,16 +78,28 @@ interface HelpPublicTreeFolder {
     /** Stable node id. */
     id: string;
     slug: string;
-    /** The folder's path (its index page, if any, lives here). */
+    /** 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;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
     defaultOpen: boolean;
     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---`). */
@@ -129,12 +176,17 @@ interface HelpPublicPageLink {
 }
 /** One page with its text. */
 interface HelpPublicPage extends HelpPublicPageSummary {
-    /** The page's Markdown with directives (`:::callout`, `::::steps`, …). */
+    /**
+     * The page's Markdown with directives (`:::callout`, `::::steps`, …, and the
+     * site's own blocks as written — see `site.blocks`).
+     */
     markdown: string;
     /** Safe server-rendered HTML of `markdown` (stable `sd-*` classes for the directives). */
     html: string;
     headings: HelpPublicHeading[];
     blocks: HelpPublicBlock[];
+    /** The site's own building blocks the page uses, by name (in the site's order). */
+    customBlocks: string[];
     breadcrumbs: HelpPublicBreadcrumb[];
     previous: HelpPublicPageLink | null;
     next: HelpPublicPageLink | null;
@@ -209,8 +261,8 @@ interface HelpWebhookBody {
  * Parsing the help center's Markdown the way the API renders it
  * (`packages/db/src/help-markdown.ts`): GFM plus container directives in the
  * generic syntax of `remark-directive`. Only the directive names below mean
- * something; every other directive — and every leaf (`::x`) or text (`:x`)
- * directive — is printed back as the text it was written as.
+ * something, plus the site's own blocks (`blocks.ts`); every other directive
+ * is printed back as the text it was written as.
  */
 /** The directive names the help center knows. */
 declare const HELP_BLOCKS: readonly ["callout", "steps", "step", "tabs", "tab", "cards", "card"];
@@ -230,6 +282,38 @@ type HelpCalloutType = (typeof HELP_CALLOUT_TYPES)[number];
  */
 declare function safeHelpHref(raw: string | null | undefined): string | null;
 
+/**
+ * A doc site's own building blocks (`site.blocks`) in the page Markdown — the
+ * same rules as the API (`packages/db/src/help-blocks.ts`, `help-markdown.ts`,
+ * contract in `docs/help/06-eigene-bausteine.md`), copied so the package has no
+ * dependency on the API's code; `test/blocks.test.tsx` holds both in step.
+ *
+ * The Markdown parser (micromark's directive extension) finds the directives;
+ * a use only counts when its name is defined, it is written in its kind's form
+ * (`:name` inline, `::name` alone on a line, `:::name` around content) and its
+ * source re-reads under the API's stricter syntax (label and attributes on one
+ * line, the basic character references) — otherwise it stays literal text.
+ */
+/** A field's checked value: `boolean` fields are true/false, every other type a string. */
+type HelpBlockValue = string | boolean;
+/** A block's checked field values, in the definition's field order. */
+type HelpBlockValues = Record<string, HelpBlockValue>;
+/**
+ * A block's attributes as checked field values, by the API's rules: only
+ * defined fields; an absent `boolean` is `false`; an empty value counts as
+ * absent; invalid values (a `javascript:` link, a malformed icon, a choice
+ * not offered) and attributes without a field are left out.
+ */
+declare function helpBlockValues(block: Pick<HelpPublicBlockDefinition, "fields">, attributes: Readonly<Record<string, string>>): HelpBlockValues;
+/**
+ * A block's text version: its template with every `{key}` replaced by the
+ * field's value (a `boolean` by its label when on, else nothing; a missing
+ * value by nothing), `{{`/`}}` as braces, then `label` after a space;
+ * whitespace collapsed. What `HelpBody` shows without a component, and what
+ * search and the outline read.
+ */
+declare function helpBlockText(block: Pick<HelpPublicBlockDefinition, "fields" | "text">, values: Readonly<HelpBlockValues>, label?: string): string;
+
 interface HelpCalloutProps {
     /** `info`, `warn`, `error`, `success` or `idea` (an unknown type arrives as `info`). */
     type: HelpCalloutType;
@@ -241,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 {
@@ -288,6 +374,40 @@ interface HelpImageProps {
     alt: string;
     title?: string;
 }
+/** A field value of a site's own block, as its component receives it. */
+type HelpBlockFieldValue = string | boolean | undefined;
+/**
+ * The props of a component for one of the site's own blocks
+ * (`docs/help/06`). `Fields` names the block's fields: a `boolean` field is
+ * always there (`true`/`false`); any other field is a string, or absent when
+ * the page leaves it out or its value isn't valid (a `javascript:` link, an
+ * icon name that isn't one, a choice not offered) — even a required one, so
+ * every field is optional here.
+ *
+ * @example
+ * type AppButtonProps = HelpBlockProps<{ icon: string; label: string }>;
+ * function AppButton({ icon, label, children, lang }: AppButtonProps) { … }
+ */
+type HelpBlockProps<Fields extends {
+    [K in keyof Fields]: HelpBlockFieldValue;
+} = Record<never, never>> = {
+    [K in Exclude<keyof Fields, "block" | "lang" | "children">]?: Fields[K];
+} & {
+    /** The block's name (`app-button`). */
+    block: string;
+    /** The page's language (`page.locale`, or `HelpBody`'s `lang`). */
+    lang: string;
+    /**
+     * `inline`/`block`: the `[label]` (rendered Markdown), if written;
+     * `container`: the rendered content — built-in and own blocks included.
+     */
+    children?: ReactNode;
+};
+/**
+ * A component for a site's own block. Typed loosely so any component fits;
+ * type yours with {@link HelpBlockProps}.
+ */
+type HelpBlockComponent = JSXElementConstructor<never>;
 /** Everything `HelpBody` renders through a component — replace any of them. */
 interface HelpBodyComponents {
     Callout: ComponentType<HelpCalloutProps>;
@@ -305,17 +425,47 @@ interface HelpBodyComponents {
 }
 /** The Fumadocs UI defaults. */
 declare const helpBodyComponents: HelpBodyComponents;
+/**
+ * `HelpBody`'s components: any of the built-in ones by their (capitalised)
+ * name, and a component per site block by the block's name (`app-button`).
+ */
+interface HelpBodyComponentMap extends Partial<HelpBodyComponents> {
+    [block: string]: HelpBlockComponent | undefined;
+}
 interface HelpBodyProps {
-    /** The page's Markdown with directives (`page.markdown` from the API). */
-    markdown: string;
+    /**
+     * The page from the API (`page.data.load()`, `help.page()`, `help.preview()`):
+     * its `markdown`, `headings` and `locale` (passed to block components as
+     * `lang`). Or pass `markdown` (and `headings`, `lang`) yourself.
+     */
+    page?: {
+        markdown: string;
+        headings?: readonly HelpPublicHeading[];
+        locale?: string;
+    };
+    /** The page's Markdown with directives (`page.markdown` from the API); wins over `page`. */
+    markdown?: string;
     /**
      * The page's `headings` from the API: their ids become the headings' anchors,
      * so they always match `getHelpToc(page.headings)`. Without them the ids are
      * computed the API's way.
      */
     headings?: readonly HelpPublicHeading[];
-    /** Replace any of the default Fumadocs UI components. */
-    components?: Partial<HelpBodyComponents>;
+    /** The page's language for block components (default `page.locale`, else `""`). */
+    lang?: string;
+    /**
+     * The site's own blocks (`page.data.blocks` of a help source, or
+     * `site.blocks` from `help.site()`). Without them every such directive stays
+     * the text it was written as.
+     */
+    blocks?: readonly HelpPublicBlockDefinition[];
+    /**
+     * Replace any of the default Fumadocs UI components (`Callout`, `Code`, …),
+     * and render the site's own blocks with your components, keyed by the
+     * block's name: `{ "app-button": AppButton }`. A defined block without a
+     * component shows its text version.
+     */
+    components?: HelpBodyComponentMap;
     /**
      * Turn a card's Lucide icon name (`Rocket`) into an element, e.g. with
      * `lucide-react`: `(name) => { const Icon = icons[name as keyof typeof icons]; return Icon ? <Icon /> : null; }`.
@@ -326,15 +476,20 @@ interface HelpBodyProps {
 /**
  * A help page's Markdown with its blocks (callout, steps, tabs, cards, titled
  * code fences) as Fumadocs UI components — a React Server Component, also fine
- * on the client. The API's safety rules apply: raw HTML is shown as text,
- * links only to http(s), mailto, `/paths` and `#anchors`, images only from
- * http(s) or `/paths`; unknown directives stay the text they were written as.
+ * on the client. The site's own blocks (`blocks`) render with your
+ * `components`, or as their text version. The API's safety rules apply: raw
+ * HTML is shown as text, links only to http(s), mailto, `/paths` and
+ * `#anchors`, images only from http(s) or `/paths`; unknown directives stay
+ * the text they were written as.
  *
  * @example
- * const page = await source.getPage(slugs)?.data.load();
- * <DocsBody><HelpBody markdown={page.markdown} headings={page.headings} /></DocsBody>
+ * const entry = source.getPage(slugs);
+ * const page = await entry.data.load();
+ * <DocsBody>
+ *   <HelpBody page={page} blocks={entry.data.blocks} components={{ "app-button": AppButton }} />
+ * </DocsBody>
  */
-declare function HelpBody({ markdown, headings, components, icon }: HelpBodyProps): ReactNode;
+declare function HelpBody(props: HelpBodyProps): ReactNode;
 
 /** Per-call options. */
 interface RequestOptions {
@@ -477,9 +632,11 @@ interface HelpStructuredData {
 /**
  * A page's search data for Fumadocs (`createFromSource`): every heading with
  * its anchor, and every paragraph, quote and table cell under the heading it
- * belongs to — code is left out, as in Fumadocs' own `remark-structure`.
+ * belongs to — code is left out, as in Fumadocs' own `remark-structure`. The
+ * site's own `blocks` count as their text version (like the API's search): a
+ * container's text version is an entry of its own, followed by its content.
  */
-declare function helpStructuredData(markdown: string, headings?: readonly HelpPublicHeading[]): HelpStructuredData;
+declare function helpStructuredData(markdown: string, headings?: readonly HelpPublicHeading[], blocks?: readonly HelpPublicBlockDefinition[]): HelpStructuredData;
 
 /** What every page of a help source carries in `page.data`. */
 interface HelpPageData extends PageData {
@@ -491,6 +648,11 @@ interface HelpPageData extends PageData {
     path: string;
     /** The language this file was built for (the `lang` asked for; the API falls back per page). */
     lang: string;
+    /**
+     * The site's own building blocks (`site.blocks`) — pass them to `HelpBody`
+     * (`blocks={page.data.blocks}`) so pages render them with your components.
+     */
+    blocks: HelpPublicBlockDefinition[];
     /**
      * The page with its text (`markdown`, `html`, `headings`, `breadcrumbs`,
      * `previous`/`next`). Fetched when called — or right away with
@@ -511,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;
@@ -570,8 +734,10 @@ interface HelpFilesOptions {
 /**
  * The Fumadocs virtual files for one language of the site: a `.mdx` page file
  * per page (a folder's own page as `<folder>/index.mdx`, the home page as
- * `index.mdx` at the top, any other page named `index` as `index_.mdx`) and a
- * `meta.json` per folder plus one at the top that fixes the order. Every file
+ * `index.mdx` at the top or in a top-level group, any other page named `index`
+ * as `index_.mdx`) and a `meta.json` per folder plus one at the top that fixes
+ * the order. A group folder is a `(slug)/` directory, so Fumadocs gives its
+ * pages the same addresses as the tree (no segment for the group). Every file
  * path is unique. Exported for custom setups; `createHelpSource` uses it.
  */
 declare function helpTreeToFiles(payload: HelpPublicSitePayload, options: HelpFilesOptions): HelpVirtualFile[];
@@ -611,4 +777,4 @@ declare function getHelpToc(headings: readonly HelpPublicHeading[] | {
     headings: readonly HelpPublicHeading[];
 }, options?: HelpTocOptions): TOCItemType[];
 
-export { HELP_BLOCKS, HELP_CALLOUT_TYPES, type HelpBlockName, HelpBody, type HelpBodyComponents, type HelpBodyProps, type HelpCalloutProps, type HelpCalloutType, type HelpCardProps, type HelpCardsProps, type HelpCodeProps, type HelpFilesOptions, type HelpHeadingProps, type HelpImageProps, type HelpLinkProps, type HelpMetaData, type HelpPageData, type HelpRevalidateOptions, type HelpSource, type HelpSourceConfig, type HelpSourceOptions, type HelpStepProps, type HelpStepsProps, type HelpStructuredData, type HelpTabProps, type HelpTabsProps, type HelpTocOptions, type HelpVirtualFile, type HelpWebhookRequest, createHelpRevalidateHandler, createHelpSource, getHelpToc, helpBodyComponents, helpDynamicSource, helpMetaEntry, helpStructuredData, helpTreePaths, helpTreeToFiles, safeHelpHref };
+export { HELP_BLOCKS, HELP_CALLOUT_TYPES, type HelpBlockComponent, type HelpBlockFieldValue, type HelpBlockName, type HelpBlockProps, type HelpBlockValue, type HelpBlockValues, HelpBody, type HelpBodyComponentMap, type HelpBodyComponents, type HelpBodyProps, type HelpCalloutProps, type HelpCalloutType, type HelpCardProps, type HelpCardsProps, type HelpCodeProps, type HelpFilesOptions, type HelpHeadingProps, type HelpImageProps, type HelpLinkProps, type HelpMetaData, type HelpPageData, type HelpRevalidateOptions, type HelpSource, type HelpSourceConfig, type HelpSourceOptions, type HelpStepProps, type HelpStepsProps, type HelpStructuredData, type HelpTabProps, type HelpTabsProps, type HelpTocOptions, type HelpVirtualFile, type HelpWebhookRequest, createHelpRevalidateHandler, createHelpSource, getHelpToc, helpBlockText, helpBlockValues, helpBodyComponents, helpDynamicSource, helpMetaEntry, helpStructuredData, helpTreePaths, helpTreeToFiles, safeHelpHref };

package/dist/fumadocs.js

@@ -1,26 +1,57 @@
+import { directiveFromMarkdown } from 'mdast-util-directive';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { gfmFromMarkdown } from 'mdast-util-gfm';
+import { directive } from 'micromark-extension-directive';
+import { gfm } from 'micromark-extension-gfm';
 import { Callout } from 'fumadocs-ui/components/callout';
 import { Card, Cards } from 'fumadocs-ui/components/card';
 import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';
 import { Heading } from 'fumadocs-ui/components/heading';
 import { Step, Steps } from 'fumadocs-ui/components/steps';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import { Fragment as Fragment$1 } from 'react';
-import { directiveFromMarkdown } from 'mdast-util-directive';
-import { fromMarkdown } from 'mdast-util-from-markdown';
-import { gfmFromMarkdown } from 'mdast-util-gfm';
-import { directive } from 'micromark-extension-directive';
-import { gfm } from 'micromark-extension-gfm';
+import { Fragment as Fragment$1, createElement } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
-// src/fumadocs/body.tsx
+// src/fumadocs/markdown.ts
 var HELP_BLOCKS = ["callout", "steps", "step", "tabs", "tab", "cards", "card"];
 var HELP_CALLOUT_TYPES = ["info", "warn", "error", "success", "idea"];
 var isHelpBlock = (name) => HELP_BLOCKS.includes(name);
+var CODE_FENCE = /^[ \t]*(`{3,}|~{3,})(.*)$/;
+var CLOSING_FENCE = /^([ \t]*):(:{2,}[ \t]*)$/;
+var MASK = "\uE000";
+function maskCodeFences(markdown) {
+  if (markdown.includes(MASK)) return markdown;
+  let open = null;
+  return markdown.split("\n").map((line) => {
+    const fence = CODE_FENCE.exec(line);
+    if (open) {
+      if (fence?.[1]?.[0] === open.char && fence[1].length >= open.length && !fence[2]?.trim()) {
+        open = null;
+        return line;
+      }
+      return line.replace(CLOSING_FENCE, `$1${MASK}$2`);
+    }
+    if (fence?.[1] && !(fence[1][0] === "`" && fence[2]?.includes("`"))) {
+      open = { char: fence[1][0] ?? "`", length: fence[1].length };
+    }
+    return line;
+  }).join("\n");
+}
+function unmask(node) {
+  if ("value" in node && typeof node.value === "string" && node.value.includes(MASK)) {
+    node.value = node.value.replaceAll(MASK, ":");
+  }
+  if ("children" in node) for (const child of node.children) unmask(child);
+}
 function parseHelpMarkdown(markdown) {
-  return fromMarkdown(markdown ?? "", {
+  const source = markdown ?? "";
+  const masked = maskCodeFences(source);
+  const root = fromMarkdown(masked, {
     extensions: [gfm(), directive()],
     mdastExtensions: [gfmFromMarkdown(), directiveFromMarkdown()]
   });
+  if (masked !== source) unmask(root);
+  return root;
 }
 var CONTROL = /[\u0000-\u001f\u007f]/;
 var PROTOCOL_RELATIVE = /^[\\/]{2}/;
@@ -40,10 +71,14 @@ function safeHelpImageSrc(raw) {
   if (/^\/[^\s]*$/.test(src)) return src;
   return null;
 }
-function plainText(node) {
+function plainText(node, override) {
+  const own = override?.(node);
+  if (own !== void 0) return own;
   if ("value" in node && typeof node.value === "string") return node.value;
   if (node.type === "image") return node.alt ?? "";
-  if ("children" in node) return node.children.map(plainText).join("");
+  if ("children" in node) {
+    return node.children.map((child) => plainText(child, override)).join("");
+  }
   return "";
 }
 function sourceOf(node, markdown) {
@@ -77,34 +112,31 @@ 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);
   return out;
 }
-function headingIds(root, known) {
+function headingIds(root, known, override) {
   const headings = collectHeadings(root);
   const ids = /* @__PURE__ */ new Map();
   if (known && known.length === headings.length) {
@@ -114,15 +146,231 @@ function headingIds(root, known) {
     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).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;
 }
+
+// src/fumadocs/blocks.ts
+var TEXT_VALUE_MAX = 300;
+var LONG_VALUE_MAX = 2e3;
+var ICON = /^[A-Za-z][A-Za-z0-9]{0,47}$/;
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0"
+};
+function decodeEntities(value) {
+  return value.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]+);/gi, (match, ref) => {
+    if (ref[0] === "#") {
+      const code = ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : Number(ref.slice(1));
+      return Number.isFinite(code) && code > 0 && code <= 1114111 ? String.fromCodePoint(code) : match;
+    }
+    return NAMED_ENTITIES[ref.toLowerCase()] ?? match;
+  });
+}
+var ATTRIBUTE = /^(?:#([^\s"'<>=`}#.]+)|\.([^\s"'<>=`}#.]+)|([A-Za-z_:][A-Za-z0-9_.:-]*)(?:[ \t]*=[ \t]*(?:"([^"\n]*)"|'([^'\n]*)'|([^\s"'<>=`}]+)))?)/;
+function parseAttributes(src) {
+  const attributes = {};
+  let pos = 1;
+  for (; ; ) {
+    while (src[pos] === " " || src[pos] === "	") pos++;
+    if (src[pos] === "}") return { attributes, length: pos + 1 };
+    const match = ATTRIBUTE.exec(src.slice(pos));
+    if (!match) return null;
+    const [whole, id, cls, key, dq, sq, bare] = match;
+    if (id !== void 0) attributes.id = decodeEntities(id);
+    else if (cls !== void 0)
+      attributes.class = attributes.class ? `${attributes.class} ${cls}` : cls;
+    else if (key !== void 0) attributes[key] = decodeEntities(dq ?? sq ?? bare ?? "");
+    pos += whole.length;
+    if (src[pos] !== " " && src[pos] !== "	" && src[pos] !== "}") return null;
+  }
+}
+function parseLabel(src) {
+  let depth = 0;
+  for (let pos = 0; pos < src.length; pos++) {
+    const char = src[pos];
+    if (char === "\n") return null;
+    if (char === "\\") {
+      pos++;
+      continue;
+    }
+    if (char === "[") depth++;
+    else if (char === "]") {
+      depth--;
+      if (depth === 0) return { label: src.slice(1, pos), length: pos + 1 };
+    }
+  }
+  return null;
+}
+function parseDirectiveTail(src) {
+  let rest = src;
+  let label;
+  let attributes = {};
+  if (rest.startsWith("[")) {
+    const parsed = parseLabel(rest);
+    if (!parsed) return null;
+    label = parsed.label;
+    rest = rest.slice(parsed.length);
+  }
+  if (rest.startsWith("{")) {
+    const parsed = parseAttributes(rest);
+    if (!parsed) return null;
+    attributes = parsed.attributes;
+    rest = rest.slice(parsed.length);
+  }
+  return { ...label !== void 0 ? { label } : {}, attributes, rest };
+}
+function plainLabel(label) {
+  if (label === void 0) return void 0;
+  const text = label.replace(/\\(.)/g, "$1").replace(/[*_`~]/g, "").trim();
+  return text || void 0;
+}
+var isVideoAddress = (value) => safeHelpHref(value) === value && (/^https:\/\//i.test(value) || value.startsWith("/"));
+function fieldValue(field, raw) {
+  if (field.type === "boolean") {
+    const flag = raw.trim().toLowerCase();
+    if (flag === "" || flag === "true") return true;
+    if (flag === "false") return false;
+    return void 0;
+  }
+  const value = raw.trim();
+  switch (field.type) {
+    case "text":
+      return !/[\r\n]/.test(value) && value.length <= TEXT_VALUE_MAX ? value : void 0;
+    case "longText":
+      return value.length <= LONG_VALUE_MAX ? value : void 0;
+    case "icon":
+      return ICON.test(value) ? value : void 0;
+    case "url":
+      return value.length <= LONG_VALUE_MAX && safeHelpHref(value) === value ? value : void 0;
+    case "choice":
+      return field.options?.includes(value) ? value : void 0;
+    case "image":
+      return value.length <= LONG_VALUE_MAX && safeHelpImageSrc(value) === value ? value : void 0;
+    case "video":
+      return value.length <= LONG_VALUE_MAX && isVideoAddress(value) ? value : void 0;
+    default:
+      return void 0;
+  }
+}
+function helpBlockValues(block, attributes) {
+  const values = {};
+  for (const field of block.fields) {
+    const raw = Object.hasOwn(attributes, field.key) ? attributes[field.key] : void 0;
+    if (field.type === "boolean") {
+      if (raw === void 0) {
+        values[field.key] = false;
+        continue;
+      }
+    } else if (raw === void 0 || raw.trim() === "") {
+      continue;
+    }
+    const value = fieldValue(field, raw);
+    if (value !== void 0) values[field.key] = value;
+  }
+  return values;
+}
+function isTemplate(template) {
+  for (let i = 0; i < template.length; i++) {
+    const char = template[i];
+    if ((char === "{" || char === "}") && template[i + 1] === char) {
+      i++;
+      continue;
+    }
+    if (char === "}") return false;
+    if (char !== "{") continue;
+    const end = template.indexOf("}", i + 1);
+    if (end === -1) return false;
+    const key = template.slice(i + 1, end).trim();
+    if (!key || key.includes("{")) return false;
+    i = end;
+  }
+  return true;
+}
+function helpBlockText(block, values, label) {
+  const template = block.text ?? "";
+  const fields = new Map(block.fields.map((f) => [f.key, f]));
+  let text = "";
+  if (isTemplate(template)) {
+    for (let i = 0; i < template.length; i++) {
+      const char = template[i] ?? "";
+      if ((char === "{" || char === "}") && template[i + 1] === char) {
+        text += char;
+        i++;
+        continue;
+      }
+      if (char !== "{") {
+        text += char;
+        continue;
+      }
+      const end = template.indexOf("}", i + 1);
+      const key = template.slice(i + 1, end).trim();
+      const value = values[key];
+      if (value === true) text += fields.get(key)?.label ?? "";
+      else if (typeof value === "string") text += value;
+      i = end;
+    }
+  }
+  return `${text} ${label ?? ""}`.replace(/\s+/g, " ").trim();
+}
+var FORMS = {
+  textDirective: "inline",
+  leafDirective: "block",
+  containerDirective: "container"
+};
+function helpBlockMatcher(blocks, markdown) {
+  const defined = new Map((blocks ?? []).map((block) => [block.name, block]));
+  const cache = /* @__PURE__ */ new Map();
+  const find = (node) => {
+    if (defined.size === 0) return null;
+    if (node.type !== "textDirective" && node.type !== "leafDirective" && node.type !== "containerDirective") {
+      return null;
+    }
+    const block = defined.get(node.name);
+    if (!block || block.kind !== FORMS[node.type]) return null;
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    if (start === void 0 || end === void 0) return null;
+    const lineEnd = markdown.indexOf("\n", start);
+    const line = markdown.slice(start, lineEnd === -1 ? void 0 : lineEnd);
+    const head = /^(:+)([A-Za-z][A-Za-z0-9_-]*)/.exec(line);
+    const colons = head?.[1]?.length ?? 0;
+    const form = colons === 1 ? "textDirective" : colons === 2 ? "leafDirective" : "containerDirective";
+    if (!head || form !== node.type || head[2] !== node.name) return null;
+    const tail = parseDirectiveTail(line.slice(head[0].length));
+    if (!tail) return null;
+    if (node.type === "textDirective") {
+      if (line.length - tail.rest.length !== end - start) return null;
+    } else if (tail.rest.trim() !== "") return null;
+    const values = helpBlockValues(block, tail.attributes);
+    const label = node.type === "containerDirective" ? void 0 : plainLabel(tail.label);
+    return { block, node, values, text: helpBlockText(block, values, label) };
+  };
+  const use = (node) => {
+    if (!cache.has(node)) cache.set(node, find(node));
+    return cache.get(node) ?? null;
+  };
+  const text = (node) => {
+    const found = use(node);
+    if (!found) return void 0;
+    if (found.node.type !== "containerDirective") return found.text;
+    const inner = contentOf(found.node).map((child) => plainText(child, text)).join(" ");
+    return `${found.text} ${inner}`.trim();
+  };
+  return { use, text };
+}
 var PLAIN_CODE_COLORS = {
   "--shiki-light": "var(--color-fd-foreground)",
   "--shiki-dark": "var(--color-fd-foreground)"
@@ -130,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 }),
@@ -152,6 +400,15 @@ var helpBodyComponents = {
   Link: ({ href, title, children }) => /* @__PURE__ */ jsx("a", { href, title, children }),
   Image: ({ src, alt, title }) => /* @__PURE__ */ jsx("img", { src, alt, title, loading: "lazy" })
 };
+var BUILT_IN_KEYS = Object.keys(helpBodyComponents);
+function pickBuiltIns(components) {
+  const out = {};
+  for (const key of BUILT_IN_KEYS) {
+    const component = components[key];
+    if (component) out[key] = component;
+  }
+  return out;
+}
 var normalizeId = (id) => id.trim().replace(/\s+/g, " ").toLowerCase();
 function collectDefinitions(root) {
   const out = /* @__PURE__ */ new Map();
@@ -254,8 +511,30 @@ function renderTabs(children, ctx) {
     );
   }) });
 }
+function renderCustomBlock(use, ctx) {
+  const { block, node, values, text } = use;
+  const isContainer = node.type === "containerDirective";
+  const children = node.type === "containerDirective" ? renderAll(contentOf(node), { ...ctx, tight: false }) : node.children.length ? renderAll(node.children, { ...ctx, inline: true }) : void 0;
+  const Component = Object.hasOwn(ctx.custom, block.name) ? ctx.custom[block.name] : void 0;
+  if (Component) {
+    return createElement(Component, { ...values, block: block.name, lang: ctx.lang }, children);
+  }
+  const attributes = {
+    className: "sd-block",
+    "data-block": block.name,
+    "data-props": JSON.stringify(values)
+  };
+  if (block.kind === "inline") return /* @__PURE__ */ jsx("span", { ...attributes, children: text });
+  if (!isContainer) return /* @__PURE__ */ jsx("div", { ...attributes, children: text });
+  return /* @__PURE__ */ jsxs("div", { ...attributes, children: [
+    text ? /* @__PURE__ */ jsx("p", { className: "sd-block-text", children: text }) : null,
+    /* @__PURE__ */ jsx("div", { className: "sd-block-body", children })
+  ] });
+}
 function renderDirective(node, ctx) {
   const { c } = ctx;
+  const custom = ctx.blocks.use(node);
+  if (custom) return renderCustomBlock(custom, ctx);
   if (!isHelpBlock(node.name)) {
     const source = sourceOf(node, ctx.markdown);
     const lines = source.split("\n");
@@ -275,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.
@@ -283,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":
@@ -358,24 +637,34 @@ function renderNode(node, ctx) {
       return null;
     case "containerDirective":
       return renderDirective(node, { ...ctx, tight: false });
-    // Not ours: printed back as written.
     case "leafDirective":
+    case "textDirective": {
+      const custom = ctx.blocks.use(node);
+      if (custom) return renderCustomBlock(custom, ctx);
+      return node.type === "leafDirective" ? literalBlock(sourceOf(node, ctx.markdown)) : sourceOf(node, ctx.markdown);
+    }
+    // Not ours: printed back as written.
     case "footnoteDefinition":
       return literalBlock(sourceOf(node, ctx.markdown));
-    case "textDirective":
     case "footnoteReference":
       return sourceOf(node, ctx.markdown);
     default:
       return "children" in node ? renderAll(node.children, ctx) : "value" in node ? String(node.value) : plainText(node);
   }
 }
-function HelpBody({ markdown, headings, components, icon }) {
-  const source = markdown ?? "";
+function HelpBody(props) {
+  const { page, components = {}, icon } = props;
+  const source = props.markdown ?? page?.markdown ?? "";
+  const headings = props.headings ?? page?.headings;
   const root = parseHelpMarkdown(source);
+  const blocks = helpBlockMatcher(props.blocks, source);
   const ctx = {
     markdown: source,
-    ids: headingIds(root, headings),
-    c: { ...helpBodyComponents, ...components },
+    blocks,
+    custom: components,
+    lang: props.lang ?? page?.locale ?? "",
+    ids: headingIds(root, headings, blocks.text),
+    c: { ...helpBodyComponents, ...pickBuiltIns(components) },
     icon,
     definitions: collectDefinitions(root),
     linkless: false,
@@ -484,12 +773,17 @@ function parseBody(raw) {
 }
 
 // src/fumadocs/structured.ts
-function helpStructuredData(markdown, headings) {
-  const root = parseHelpMarkdown(markdown);
-  const ids = headingIds(root, headings);
+function helpStructuredData(markdown, headings, blocks) {
+  const source = markdown ?? "";
+  const root = parseHelpMarkdown(source);
+  const matcher = helpBlockMatcher(blocks, source);
+  const ids = headingIds(root, headings, matcher.text);
   const out = { headings: [], contents: [] };
   let current;
-  const text = (node) => plainText(node).replace(/\s+/g, " ").trim();
+  const text = (node) => plainText(node, matcher.text).replace(/\s+/g, " ").trim();
+  const add = (content) => {
+    if (content) out.contents.push({ heading: current, content });
+  };
   const walk = (node) => {
     if (node.type === "heading") {
       current = ids.get(node);
@@ -497,9 +791,22 @@ function helpStructuredData(markdown, headings) {
       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);
+      if (use.node.type === "containerDirective")
+        for (const child of contentOf(use.node)) walk(child);
+      return;
+    }
     if (node.type === "paragraph" || node.type === "tableCell") {
-      const content = text(node);
-      if (content) out.contents.push({ heading: current, content });
+      add(text(node));
       return;
     }
     if (node.type === "code" || node.type === "html" || node.type === "definition") return;
@@ -519,12 +826,13 @@ var pageFileName = (page) => {
   const name = lastSegment(page.path);
   return name === "index" ? "index_" : name;
 };
+var folderDirName = (folder) => folder.group ? `(${folder.slug})` : folder.slug;
 function helpMetaEntry(node) {
   switch (node.type) {
     case "page":
       return pageFileName(node);
     case "folder":
-      return node.slug;
+      return folderDirName(node);
     case "separator": {
       const title = node.title?.replace(/---/g, "\u2013").trim();
       if (!title) return "---";
@@ -539,6 +847,7 @@ function helpTreeToFiles(payload, options) {
   const ext = (name, extension) => `${name}${options.suffix ? `.${options.suffix}` : ""}.${extension}`;
   const join = (dir, name) => dir ? `${dir}/${name}` : name;
   const seen = /* @__PURE__ */ new Set();
+  const blocks = payload.site.blocks ?? [];
   const addPage = (page, file) => {
     if (seen.has(file)) return;
     seen.add(file);
@@ -551,25 +860,33 @@ function helpTreeToFiles(payload, options) {
       ...page.icon ? { icon: page.icon } : {},
       path: page.path,
       lang: options.lang,
+      blocks,
       load,
       structuredData: async () => {
         const full = await load();
-        return full ? helpStructuredData(full.markdown, full.headings) : { headings: [], contents: [] };
+        return full ? helpStructuredData(full.markdown, full.headings, blocks) : { headings: [], contents: [] };
       },
       ...prefetched ? { page: prefetched } : {}
     };
     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);
@@ -577,9 +894,9 @@ function helpTreeToFiles(payload, options) {
   const addChildren = (nodes, dir) => {
     for (const node of nodes) {
       if (node.type === "page") {
-        addPage(node, node.path ? join(dir, ext(pageFileName(node), "mdx")) : ext("index", "mdx"));
+        addPage(node, join(dir, ext(pageFileName(node), "mdx")));
       } else if (node.type === "folder") {
-        addFolder(node, join(dir, node.slug));
+        addFolder(node, join(dir, folderDirName(node)));
       }
     }
   };
@@ -661,4 +978,4 @@ function getHelpToc(headings, options = {}) {
   return list.filter((heading) => heading.level >= min && heading.level <= max && heading.id).map((heading) => ({ title: heading.text, url: `#${heading.id}`, depth: heading.level }));
 }
 
-export { HELP_BLOCKS, HELP_CALLOUT_TYPES, HelpBody, createHelpRevalidateHandler, createHelpSource, getHelpToc, helpBodyComponents, helpDynamicSource, helpMetaEntry, helpStructuredData, helpTreePaths, helpTreeToFiles, safeHelpHref };
+export { HELP_BLOCKS, HELP_CALLOUT_TYPES, HelpBody, createHelpRevalidateHandler, createHelpSource, getHelpToc, helpBlockText, helpBlockValues, helpBodyComponents, helpDynamicSource, helpMetaEntry, helpStructuredData, helpTreePaths, helpTreeToFiles, safeHelpHref };

package/dist/index.d.cts

@@ -139,7 +139,8 @@ declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, he
  * preview token names. Absent values are `null`, never a missing key.
  *
  * Paths: a page's path is its folder slugs plus its slug, without leading or
- * trailing slash (`guides/login`); the site's home page has the path `""`.
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
  */
 /** The doc site itself. */
 interface HelpPublicSite {
@@ -152,6 +153,40 @@ interface HelpPublicSite {
     languages: string[];
     /** The docs website's base address (`https://help.acme.com/docs`), if set. */
     websiteUrl: string | null;
+    /** The site's own building blocks pages may use (empty when it defines none). */
+    blocks: HelpPublicBlockDefinition[];
+}
+/** What a field of a site's own block holds (see {@link HelpPublicBlockField}). */
+type HelpPublicBlockFieldType = "text" | "longText" | "icon" | "url" | "choice" | "image" | "video" | "boolean";
+/**
+ * One field of a site's own block: an attribute of its directive
+ * (`key="value"`). `boolean` fields are on when written bare (`key`) or as
+ * `key="true"`; every other value is a string. `options` lists a `choice`
+ * field's values (null for other types).
+ */
+interface HelpPublicBlockField {
+    key: string;
+    label: string;
+    type: HelpPublicBlockFieldType;
+    required: boolean;
+    options: string[] | null;
+}
+/**
+ * A building block the site defines itself — WHAT it is; how it looks is the
+ * website's own component. Written in Markdown as `:name[label]{…}` in running
+ * text (`inline`), `::name[label]{…}` alone on a line (`block`) or
+ * `:::name{…}` … `:::` around Markdown content (`container`). `text` is the
+ * template of its text version (`{key}` = a field's value, a `boolean` field's
+ * label when on; `{{`/`}}` = a brace) — what to show without a component.
+ */
+interface HelpPublicBlockDefinition {
+    /** The directive name (`app-button`). */
+    name: string;
+    /** Display name. */
+    label: string;
+    kind: "inline" | "block" | "container";
+    fields: HelpPublicBlockField[];
+    text: string;
 }
 /** A page in the navigation. */
 interface HelpPublicTreePage {
@@ -170,16 +205,28 @@ interface HelpPublicTreeFolder {
     /** Stable node id. */
     id: string;
     slug: string;
-    /** The folder's path (its index page, if any, lives here). */
+    /** 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;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
     defaultOpen: boolean;
     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---`). */
@@ -256,12 +303,17 @@ interface HelpPublicPageLink {
 }
 /** One page with its text. */
 interface HelpPublicPage extends HelpPublicPageSummary {
-    /** The page's Markdown with directives (`:::callout`, `::::steps`, …). */
+    /**
+     * The page's Markdown with directives (`:::callout`, `::::steps`, …, and the
+     * site's own blocks as written — see `site.blocks`).
+     */
     markdown: string;
     /** Safe server-rendered HTML of `markdown` (stable `sd-*` classes for the directives). */
     html: string;
     headings: HelpPublicHeading[];
     blocks: HelpPublicBlock[];
+    /** The site's own building blocks the page uses, by name (in the site's order). */
+    customBlocks: string[];
     breadcrumbs: HelpPublicBreadcrumb[];
     previous: HelpPublicPageLink | null;
     next: HelpPublicPageLink | null;
@@ -424,4 +476,4 @@ declare function createHelpClient(options: HelpClientOptions): HelpClient;
  */
 declare function verifyHelpWebhook(secret: string, rawBody: WebhookBody, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): Promise<HelpWebhookBody | null>;
 
-export { type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type GetPageParams, type HelpClient, type HelpClientOptions, type HelpPageResult, type HelpPublicBlock, type HelpPublicBreadcrumb, type HelpPublicHeading, type HelpPublicPage, type HelpPublicPageLink, type HelpPublicPagePayload, type HelpPublicPageSummary, type HelpPublicPagesPayload, type HelpPublicPreviewPage, type HelpPublicPreviewPayload, type HelpPublicRedirect, type HelpPublicSearchHit, type HelpPublicSearchPayload, type HelpPublicSite, type HelpPublicSitePayload, type HelpPublicTreeFolder, type HelpPublicTreeLink, type HelpPublicTreeNode, type HelpPublicTreePage, type HelpPublicTreeSeparator, type HelpWebhookBody, type HelpWebhookEvent, type LangParams, type RequestOptions, SIGNATURE_HEADER, type SearchParams, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createHelpClient, createMemoryEtagCache, normalizeHelpPath, verifyHelpWebhook, verifyWebhookSignature };
+export { type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type GetPageParams, type HelpClient, type HelpClientOptions, type HelpPageResult, type HelpPublicBlock, type HelpPublicBlockDefinition, type HelpPublicBlockField, type HelpPublicBlockFieldType, type HelpPublicBreadcrumb, type HelpPublicHeading, type HelpPublicPage, type HelpPublicPageLink, type HelpPublicPagePayload, type HelpPublicPageSummary, type HelpPublicPagesPayload, type HelpPublicPreviewPage, type HelpPublicPreviewPayload, type HelpPublicRedirect, type HelpPublicSearchHit, type HelpPublicSearchPayload, type HelpPublicSite, type HelpPublicSitePayload, type HelpPublicTreeFolder, type HelpPublicTreeLink, type HelpPublicTreeNode, type HelpPublicTreePage, type HelpPublicTreeSeparator, type HelpWebhookBody, type HelpWebhookEvent, type LangParams, type RequestOptions, SIGNATURE_HEADER, type SearchParams, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createHelpClient, createMemoryEtagCache, normalizeHelpPath, verifyHelpWebhook, verifyWebhookSignature };

package/dist/index.d.ts

@@ -139,7 +139,8 @@ declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, he
  * preview token names. Absent values are `null`, never a missing key.
  *
  * Paths: a page's path is its folder slugs plus its slug, without leading or
- * trailing slash (`guides/login`); the site's home page has the path `""`.
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
  */
 /** The doc site itself. */
 interface HelpPublicSite {
@@ -152,6 +153,40 @@ interface HelpPublicSite {
     languages: string[];
     /** The docs website's base address (`https://help.acme.com/docs`), if set. */
     websiteUrl: string | null;
+    /** The site's own building blocks pages may use (empty when it defines none). */
+    blocks: HelpPublicBlockDefinition[];
+}
+/** What a field of a site's own block holds (see {@link HelpPublicBlockField}). */
+type HelpPublicBlockFieldType = "text" | "longText" | "icon" | "url" | "choice" | "image" | "video" | "boolean";
+/**
+ * One field of a site's own block: an attribute of its directive
+ * (`key="value"`). `boolean` fields are on when written bare (`key`) or as
+ * `key="true"`; every other value is a string. `options` lists a `choice`
+ * field's values (null for other types).
+ */
+interface HelpPublicBlockField {
+    key: string;
+    label: string;
+    type: HelpPublicBlockFieldType;
+    required: boolean;
+    options: string[] | null;
+}
+/**
+ * A building block the site defines itself — WHAT it is; how it looks is the
+ * website's own component. Written in Markdown as `:name[label]{…}` in running
+ * text (`inline`), `::name[label]{…}` alone on a line (`block`) or
+ * `:::name{…}` … `:::` around Markdown content (`container`). `text` is the
+ * template of its text version (`{key}` = a field's value, a `boolean` field's
+ * label when on; `{{`/`}}` = a brace) — what to show without a component.
+ */
+interface HelpPublicBlockDefinition {
+    /** The directive name (`app-button`). */
+    name: string;
+    /** Display name. */
+    label: string;
+    kind: "inline" | "block" | "container";
+    fields: HelpPublicBlockField[];
+    text: string;
 }
 /** A page in the navigation. */
 interface HelpPublicTreePage {
@@ -170,16 +205,28 @@ interface HelpPublicTreeFolder {
     /** Stable node id. */
     id: string;
     slug: string;
-    /** The folder's path (its index page, if any, lives here). */
+    /** 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;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
     defaultOpen: boolean;
     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---`). */
@@ -256,12 +303,17 @@ interface HelpPublicPageLink {
 }
 /** One page with its text. */
 interface HelpPublicPage extends HelpPublicPageSummary {
-    /** The page's Markdown with directives (`:::callout`, `::::steps`, …). */
+    /**
+     * The page's Markdown with directives (`:::callout`, `::::steps`, …, and the
+     * site's own blocks as written — see `site.blocks`).
+     */
     markdown: string;
     /** Safe server-rendered HTML of `markdown` (stable `sd-*` classes for the directives). */
     html: string;
     headings: HelpPublicHeading[];
     blocks: HelpPublicBlock[];
+    /** The site's own building blocks the page uses, by name (in the site's order). */
+    customBlocks: string[];
     breadcrumbs: HelpPublicBreadcrumb[];
     previous: HelpPublicPageLink | null;
     next: HelpPublicPageLink | null;
@@ -424,4 +476,4 @@ declare function createHelpClient(options: HelpClientOptions): HelpClient;
  */
 declare function verifyHelpWebhook(secret: string, rawBody: WebhookBody, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): Promise<HelpWebhookBody | null>;
 
-export { type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type GetPageParams, type HelpClient, type HelpClientOptions, type HelpPageResult, type HelpPublicBlock, type HelpPublicBreadcrumb, type HelpPublicHeading, type HelpPublicPage, type HelpPublicPageLink, type HelpPublicPagePayload, type HelpPublicPageSummary, type HelpPublicPagesPayload, type HelpPublicPreviewPage, type HelpPublicPreviewPayload, type HelpPublicRedirect, type HelpPublicSearchHit, type HelpPublicSearchPayload, type HelpPublicSite, type HelpPublicSitePayload, type HelpPublicTreeFolder, type HelpPublicTreeLink, type HelpPublicTreeNode, type HelpPublicTreePage, type HelpPublicTreeSeparator, type HelpWebhookBody, type HelpWebhookEvent, type LangParams, type RequestOptions, SIGNATURE_HEADER, type SearchParams, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createHelpClient, createMemoryEtagCache, normalizeHelpPath, verifyHelpWebhook, verifyWebhookSignature };
+export { type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type GetPageParams, type HelpClient, type HelpClientOptions, type HelpPageResult, type HelpPublicBlock, type HelpPublicBlockDefinition, type HelpPublicBlockField, type HelpPublicBlockFieldType, type HelpPublicBreadcrumb, type HelpPublicHeading, type HelpPublicPage, type HelpPublicPageLink, type HelpPublicPagePayload, type HelpPublicPageSummary, type HelpPublicPagesPayload, type HelpPublicPreviewPage, type HelpPublicPreviewPayload, type HelpPublicRedirect, type HelpPublicSearchHit, type HelpPublicSearchPayload, type HelpPublicSite, type HelpPublicSitePayload, type HelpPublicTreeFolder, type HelpPublicTreeLink, type HelpPublicTreeNode, type HelpPublicTreePage, type HelpPublicTreeSeparator, type HelpWebhookBody, type HelpWebhookEvent, type LangParams, type RequestOptions, SIGNATURE_HEADER, type SearchParams, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createHelpClient, createMemoryEtagCache, normalizeHelpPath, verifyHelpWebhook, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solutiondesk/help",
-  "version": "1.0.0-69d9f69",
+  "version": "1.0.0-8141b92",
   "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",