blume 1.5.2 → 1.6.0

package/src/core/heading-markers.ts

@@ -0,0 +1,96 @@
+/**
+ * Trailing heading markers, matching Fumadocs' syntax so migrated content works
+ * verbatim: `## Heading [#custom-id]` pins the anchor id, `## Heading [!toc]`
+ * keeps the heading on the page but out of the table of contents, and
+ * `## Heading [toc]` shows it only in the table of contents. Markers chain in
+ * any order (`## Heading [toc] [#id]`). The `{#id}` pin of Pandoc, kramdown,
+ * and Markdown-based specification toolchains is accepted as an equivalent of
+ * `[#id]` — in `.md` verbatim, in `.mdx` only as the escape `\{#id\}` (a bare
+ * `{…}` there is a JSX expression; the scan-time scanner reports one as
+ * `BLUME_MDX_CURLY_ANCHOR`). Both pipelines resolve escapes before parsing
+ * markers, so the escaped and bare spellings reach this parser identically.
+ *
+ * Both heading pipelines share this parser — the render-time hast plugin
+ * (`markdown/heading-anchors.ts`) and the scan-time source scanner
+ * (`core/sources/normalize.ts`) — so the rendered `id`, the TOC entry, and the
+ * anchor index `blume validate` checks against always agree.
+ */
+
+import type GithubSlugger from "github-slugger";
+
+/**
+ * Frontmatter key carrying the slugs of `[!toc]` headings out of a render. The
+ * hast plugin pushes onto it and the generated page template reads it back via
+ * `remarkPluginFrontmatter` to filter the TOC.
+ */
+export const TOC_HIDDEN_KEY = "__blumeTocHidden";
+
+/**
+ * Register a pinned `[#id]` with the document slugger, the way
+ * `GithubSlugger#slug` registers the slugs it returns — so a later heading
+ * whose auto-slug collides disambiguates (`setup` → `setup-1`) instead of
+ * silently duplicating the anchor id. An id that is already taken is left
+ * untouched (the pin still uses it verbatim; duplicate pins are the author's
+ * explicit choice).
+ */
+export const occupySlug = (slugger: GithubSlugger, id: string): void => {
+  slugger.occurrences[id] ??= 0;
+};
+
+/** One trailing marker: `[#id]`, `{#id}`, `[toc]`, or `[!toc]`. */
+const MARKER =
+  /\s*(?:\{#(?<curlyId>[^\s}]+)\}|\[(?:#(?<id>[^\s\]]+)|(?<hide>!)?toc)\])\s*$/u;
+
+export interface HeadingMarkers {
+  /** Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never re-slugged). */
+  id?: string;
+  /** The heading text with every trailing marker stripped. */
+  text: string;
+  /** `[!toc]` hides the heading from the TOC; `[toc]` shows it only there. */
+  toc?: "hide" | "only";
+}
+
+/**
+ * Split trailing markers off a heading's text. Only markers at the very end of
+ * the heading count (mid-text brackets are ordinary prose); when a marker kind
+ * repeats, the last one written wins.
+ *
+ * `isRefDefined` reports whether a link-reference definition exists for a
+ * bracket's label (`toc`, `!toc`, `#id`): a defined bracket is a CommonMark
+ * shortcut link, not a marker — the renderer sees a resolved `<a>` element
+ * there and strips nothing at or before it, so the parse stops the same way.
+ * The render-time hast plugin never passes it (resolved links are already
+ * elements by the time it runs); the raw-source scanner does.
+ */
+export const parseHeadingMarkers = (
+  text: string,
+  isRefDefined?: (label: string) => boolean
+): HeadingMarkers => {
+  let remaining = text;
+  let id: string | undefined;
+  let toc: HeadingMarkers["toc"];
+  for (
+    let match = MARKER.exec(remaining);
+    match?.groups;
+    match = MARKER.exec(remaining)
+  ) {
+    const explicitId = match.groups.curlyId ?? match.groups.id;
+    const label =
+      explicitId === undefined
+        ? `${match.groups.hide ?? ""}toc`
+        : `#${explicitId}`;
+    // A `{#id}` is never a shortcut link, whatever the definitions say.
+    if (match.groups.curlyId === undefined && isRefDefined?.(label)) {
+      break;
+    }
+    remaining = remaining.slice(0, match.index);
+    if (explicitId === undefined) {
+      // Stripping runs right-to-left, so keeping the first capture of each
+      // kind makes the rightmost occurrence win.
+      toc ??= match.groups.hide === undefined ? "only" : "hide";
+    } else {
+      id ??= explicitId;
+    }
+  }
+  return { id, text: remaining, toc };
+};

package/src/core/i18n-ui.ts

@@ -31,6 +31,11 @@ const uiStringsObject = z.object({
       // `{name}` is replaced with the provider's brand name at render time.
       openIn: z.string().default("Open in {name}"),
       openInChat: z.string().default("Open in chat"),
+      // The prompt handed to the chat provider; `{url}` is replaced with the
+      // page's raw-Markdown URL at load time.
+      openInChatPrompt: z
+        .string()
+        .default("Read {url} so I can ask you questions about this page."),
       scrollToTop: z.string().default("Scroll to top"),
     })
     .prefault({}),
@@ -107,6 +112,12 @@ const uiStringsObject = z.object({
         .string()
         .default("We couldn't find the page you're looking for."),
       home: z.string().default("Back to home"),
+      /** Label of the llms.txt link on the 404 page. */
+      llms: z.string().default("Docs index for AI agents (llms.txt)"),
+      /** Label of the sitemap link on the 404 page. */
+      sitemap: z.string().default("Sitemap"),
+      /** Heading over the recovery links (sections, sitemap, llms.txt). */
+      suggestions: z.string().default("Where to look next"),
       title: z.string().default("Page not found"),
     })
     .prefault({}),