blume 2.1.3 → 2.2.0

package/src/markdown/index.ts

@@ -1,22 +1,31 @@
+import { fileURLToPath } from "node:url";
+
 import { satteri } from "@astrojs/markdown-satteri";
 import {
   transformerMetaHighlight,
   transformerNotationDiff,
+  transformerNotationErrorLevel,
   transformerNotationFocus,
   transformerNotationHighlight,
   transformerNotationWordHighlight,
 } from "@shikijs/transformers";
 import { escape as escapeHtml } from "html-escaper";
+import { resolve } from "pathe";
 import { codeToHtml } from "shiki";
 
-import { hasVariables } from "../core/variables.ts";
+import { withIncludedDefinitions } from "../core/includes.ts";
+import { escapePinnedIds } from "../core/pinned-ids.ts";
+import { hasVariables, substituteVariables } from "../core/variables.ts";
 import type { ContentVariables } from "../core/variables.ts";
 import { apiRailPlugin } from "./api-rail.ts";
 import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
+import { contentAssetsPlugin } from "./content-assets.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
 import { externalLinksPlugin } from "./external-links.ts";
 import { MARKDOWN_BODY_FEATURES, MDX_BODY_FEATURES } from "./features.ts";
+import { fenceLanguagePlugin } from "./fence-language.ts";
+import { githubAlertsPlugin } from "./github-alerts.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
 import { includePlugin } from "./include.ts";
 import { inlineCodeHighlightPlugin } from "./inline-code.ts";
@@ -24,10 +33,13 @@ import { languageIconTransformer } from "./language-icon.ts";
 import { mathPlugin } from "./math.ts";
 import { mermaidPlugin } from "./mermaid.ts";
 import { packageInstallPlugin } from "./package-install.ts";
+import { promptTextPlugin } from "./prompt-text.ts";
 import { relativeLinksPlugin } from "./relative-links.ts";
+import { svgFallbackPlugin } from "./svg-fallback.ts";
 import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
+import { titleHeadingPlugin } from "./title-heading.ts";
 import { ts2jsPlugin } from "./ts2js.ts";
 import { variablesPlugin } from "./variables.ts";
 import { viewsPlugin } from "./views.ts";
@@ -94,29 +106,33 @@ const asShikiTransformer = (transformer: { name: string }): ShikiTransformer =>
  * (`[#custom-id]`, `[!toc]`, `[toc]`), which must parse regardless of config —
  * while `markdown.headingAnchors: false` only turns off the self-linking
  * anchor wrap on `<h2>`–`<h6>`. Inline code runs first so the anchor wrap
- * re-refs already-highlighted code. The external-link plugin is added only
- * when `markdown.externalLinks` is on, so off stays today's exact output.
+ * re-refs already-highlighted code. The title-heading plugin runs after the
+ * heading plugin has slugged every heading, so dropping an untitled page's
+ * title `<h1>` moves no other heading's id. The external-link plugin is added
+ * only when `markdown.externalLinks` is on, so off stays today's exact output.
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => [
   asHastPlugin(inlineCodeHighlightPlugin(options.codeThemes)),
   asHastPlugin(tableWrapPlugin()),
   asHastPlugin(headingAnchorPlugin({ wrap: options.headingAnchors !== false })),
+  asHastPlugin(titleHeadingPlugin()),
   ...(options.externalLinks ? [asHastPlugin(externalLinksPlugin())] : []),
 ];
 
 /**
- * Shiki transformers enabled by default for every code block. The four upstream
+ * Shiki transformers enabled by default for every code block. The upstream
  * notation transformers read GitHub-style comments and strip them from the
  * output: `// [!code highlight]`, `// [!code ++]` / `// [!code --]`,
- * `// [!code word:x]`, and `// [!code focus]`. The v3 match algorithm scopes a
+ * `// [!code word:x]`, `// [!code focus]`, and `// [!code error]` /
+ * `// [!code warning]`. The v3 match algorithm scopes a
  * notation to the line it sits on (or the next, for a trailing comment).
  * `transformerMetaHighlight` adds numeric range highlighting from the fence meta
  * (` ```ts {1,3-5} `), reusing the same `highlighted` class. Blume's own
  * {@link languageIconTransformer} prepends a brand icon, and
  * {@link codeTitleTransformer} runs last to promote fence-meta (title / line
  * numbers) to `<pre>` attributes. The theme styles the classes these emit
- * (`highlighted`, `diff add/remove`, `highlighted-word`, `focused`,
- * `blume-lang-icon`).
+ * (`highlighted`, `highlighted error/warning`, `diff add/remove`,
+ * `highlighted-word`, `focused`, `blume-lang-icon`).
  */
 export interface BlumeShikiOptions {
   /** Prepend a brand language icon to the header (`markdown.code.icons`). */
@@ -131,6 +147,15 @@ export const blumeShikiTransformers = (
     transformerNotationDiff({ matchAlgorithm: "v3" }),
     transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
     transformerNotationFocus({ matchAlgorithm: "v3" }),
+    // Only the two levels the theme styles: upstream also maps `[!code info]`,
+    // which would otherwise strip the comment and leave a plain highlight.
+    transformerNotationErrorLevel({
+      classMap: {
+        error: ["highlighted", "error"],
+        warning: ["highlighted", "warning"],
+      },
+      matchAlgorithm: "v3",
+    }),
     transformerMetaHighlight(),
   ];
   if (options.icons !== false) {
@@ -305,14 +330,17 @@ export interface BlumeMarkdownOptions {
 }
 
 /**
- * MDAST plugins that apply to both `.md` and `.mdx`: relative page links
- * rewritten to the served URL of the route they mean, then the base-path link
- * rewrite for root-relative links (added only when a `basePath` or
- * `deployBase` is configured).
+ * MDAST plugins that apply to both `.md` and `.mdx`: an SVG Astro can't
+ * measure pointed at its served original, relative page links rewritten to
+ * the served URL of the route they mean, references to other files beside the
+ * page to their served copies, then the base-path link rewrite for
+ * root-relative links (added only when a `basePath` or `deployBase` is
+ * configured).
  */
 const blumeSharedMdastPlugins = (
   options: BlumeMarkdownOptions
 ): MdastPlugin[] => [
+  asMdastPlugin(svgFallbackPlugin()),
   asMdastPlugin(
     relativeLinksPlugin({
       contentRoot: options.contentRoot,
@@ -320,6 +348,12 @@ const blumeSharedMdastPlugins = (
       deployBase: options.deployBase,
     })
   ),
+  asMdastPlugin(
+    contentAssetsPlugin({
+      dataFile: options.dataFile,
+      deployBase: options.deployBase,
+    })
+  ),
   ...(options.basePath || options.deployBase
     ? [
         asMdastPlugin(
@@ -344,29 +378,94 @@ const blumeIncludePlugin = (options: BlumeMarkdownOptions): MdastPlugin =>
     })
   );
 
+/** A Sätteri processor, as `satteri()` builds one. */
+type SatteriProcessor = ReturnType<typeof satteri>;
+
+/**
+ * `processor`, rendering each page from the source its parse needs: with the
+ * link-reference definitions its includes write appended (see
+ * `withIncludedDefinitions`) — the include splice runs after the page is
+ * parsed, too late for the parse to resolve a reference in the page against
+ * a partial's definition — and with the punctuation in its pinned heading
+ * ids escaped (see `escapePinnedIds`), so smart punctuation leaves a
+ * `[#a--b]` pin as written. Pages with neither render their source as given.
+ */
+const withRenderSource = (
+  processor: SatteriProcessor,
+  options: BlumeMarkdownOptions
+): SatteriProcessor => {
+  const contentRoot = options.contentRoot
+    ? resolve(options.contentRoot)
+    : undefined;
+  const source = async (content: string, sourcePath: string) =>
+    substituteVariables(
+      await withIncludedDefinitions(content, { contentRoot, sourcePath }),
+      options.variables
+    );
+  const { createMdxRenderer, createRenderer } = processor;
+  const wrapped: SatteriProcessor = {
+    ...processor,
+    createRenderer: async (shared) => {
+      const renderer = await createRenderer(shared);
+      return {
+        render: async (content, renderOptions) =>
+          renderer.render(
+            escapePinnedIds(
+              renderOptions?.fileURL
+                ? await source(content, fileURLToPath(renderOptions.fileURL))
+                : content,
+              "markdown"
+            ),
+            renderOptions
+          ),
+      };
+    },
+  };
+  if (createMdxRenderer) {
+    wrapped.createMdxRenderer = async (shared, mdx) => {
+      const renderer = await createMdxRenderer(shared, mdx);
+      return {
+        process: async (content, filePath, frontmatter) =>
+          renderer.process(
+            escapePinnedIds(await source(content, filePath), "mdx"),
+            filePath,
+            frontmatter
+          ),
+      };
+    };
+  }
+  return wrapped;
+};
+
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
 export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
-  satteri({
-    features: { ...MARKDOWN_BODY_FEATURES },
-    hastPlugins: blumeHastPlugins(options),
-    mdastPlugins: [
-      blumeIncludePlugin(options),
-      ...(hasVariables(options.variables)
-        ? [asMdastPlugin(variablesPlugin(options.variables))]
-        : []),
-      ...blumeSharedMdastPlugins(options),
-    ],
-  });
+  withRenderSource(
+    satteri({
+      features: { ...MARKDOWN_BODY_FEATURES },
+      hastPlugins: blumeHastPlugins(options),
+      mdastPlugins: [
+        blumeIncludePlugin(options),
+        asMdastPlugin(fenceLanguagePlugin()),
+        ...(hasVariables(options.variables)
+          ? [asMdastPlugin(variablesPlugin(options.variables))]
+          : []),
+        ...blumeSharedMdastPlugins(options),
+      ],
+    }),
+    options
+  );
 
 export type BlumeMdxOptions = BlumeMarkdownOptions;
 
 /**
  * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
  * components — `package-install` → package-manager tabs, ` ```ts ts2js ` →
- * TypeScript/JavaScript tabs, `:::note` → `<Callout>`, ` ```mermaid ` → a
+ * TypeScript/JavaScript tabs, `:::note` and GitHub's `> [!NOTE]` alerts →
+ * `<Callout>`, ` ```mermaid ` → a
  * `<blume-mermaid>` element, block math
- * (`$$…$$`) → the `<Math>` component, and top-level `<RequestExample>` and
- * `<ResponseExample>` → the page's `<ApiRail>`. Used as the `processor` for
+ * (`$$…$$`) → the `<Math>` component, top-level `<RequestExample>` and
+ * `<ResponseExample>` → the page's `<ApiRail>`, and a `<Prompt>` body's text
+ * back to the punctuation its author typed. Used as the `processor` for
  * `@astrojs/mdx` so these apply to `.mdx` only (plain `.md` uses
  * {@link blumeMarkdownProcessor}).
  *
@@ -380,18 +479,24 @@ export type BlumeMdxOptions = BlumeMarkdownOptions;
  * Satteri's full `MdastPlugin` type at this single boundary.
  */
 export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
-  satteri({
-    features: { ...MDX_BODY_FEATURES },
-    hastPlugins: blumeHastPlugins(options),
-    mdastPlugins: [
-      blumeIncludePlugin(options),
-      asMdastPlugin(packageInstallPlugin()),
-      asMdastPlugin(ts2jsPlugin()),
-      asMdastPlugin(directiveToCalloutPlugin()),
-      asMdastPlugin(mermaidPlugin()),
-      asMdastPlugin(mathPlugin()),
-      ...blumeSharedMdastPlugins(options),
-      asMdastPlugin(apiRailPlugin()),
-      asMdastPlugin(viewsPlugin()),
-    ],
-  });
+  withRenderSource(
+    satteri({
+      features: { ...MDX_BODY_FEATURES },
+      hastPlugins: blumeHastPlugins(options),
+      mdastPlugins: [
+        blumeIncludePlugin(options),
+        asMdastPlugin(fenceLanguagePlugin()),
+        asMdastPlugin(packageInstallPlugin()),
+        asMdastPlugin(ts2jsPlugin()),
+        asMdastPlugin(directiveToCalloutPlugin()),
+        asMdastPlugin(githubAlertsPlugin()),
+        asMdastPlugin(mermaidPlugin()),
+        asMdastPlugin(mathPlugin()),
+        ...blumeSharedMdastPlugins(options),
+        asMdastPlugin(apiRailPlugin()),
+        asMdastPlugin(viewsPlugin()),
+        asMdastPlugin(promptTextPlugin()),
+      ],
+    }),
+    options
+  );

package/src/markdown/prompt-text.ts

@@ -0,0 +1,95 @@
+/**
+ * Smart punctuation (Astro's `smartypants`, on by default) curls quotes and
+ * turns `--`, `---`, and `...` into dashes and an ellipsis as a page parses.
+ * That suits prose, but a `<Prompt>`'s body is never shown: it's copied into
+ * an AI tool as Markdown, where `lang=“ts”` and `–force` are broken code. This
+ * plugin puts back the punctuation the author typed in the body's text.
+ *
+ * Each text node is compared with its own source: a typographic mark the
+ * source doesn't contain came from smart punctuation, so it goes back to the
+ * ASCII it was made from. A mark the author typed (or wrote as an entity)
+ * stays.
+ */
+
+import type { MdastNode } from "./mdast.ts";
+
+/** Each group of marks smart punctuation makes, and the ASCII it makes them from. */
+const MARKS: readonly { ascii: string; marks: readonly string[] }[] = [
+  { ascii: '"', marks: ["“", "”"] },
+  { ascii: "'", marks: ["‘", "’"] },
+  { ascii: "---", marks: ["—"] },
+  { ascii: "--", marks: ["–"] },
+  { ascii: "...", marks: ["…"] },
+];
+
+const ANY_MARK = /[“”‘’—–…]/u;
+
+/** A character reference (`&rsquo;`, `&#8217;`), which can spell any mark. */
+const ENTITY = /&[#\da-z]+;/iu;
+
+/** The text as the author typed it, given the source it was parsed from. */
+export const restorePunctuation = (value: string, source: string): string => {
+  if (!ANY_MARK.test(value) || ENTITY.test(source)) {
+    return value;
+  }
+  let restored = value;
+  for (const { ascii, marks } of MARKS) {
+    if (!marks.some((mark) => source.includes(mark))) {
+      for (const mark of marks) {
+        restored = restored.replaceAll(mark, ascii);
+      }
+    }
+  }
+  return restored;
+};
+
+/** The node slice the plugin reads. */
+interface PromptNode extends MdastNode {
+  children?: PromptNode[];
+  name?: string | null;
+  position?: { end: { offset?: number }; start: { offset?: number } };
+  value?: string;
+}
+
+/** The visitor context slice the plugin reads and writes through. */
+interface PromptContext {
+  readonly source: string;
+  setProperty: (node: PromptNode, key: "value", value: string) => void;
+}
+
+/** Restore every text node under `node`. */
+const restoreTexts = (node: PromptNode, ctx: PromptContext): void => {
+  for (const child of node.children ?? []) {
+    const start = child.position?.start.offset;
+    const end = child.position?.end.offset;
+    if (
+      child.type === "text" &&
+      child.value !== undefined &&
+      start !== undefined &&
+      end !== undefined
+    ) {
+      const value = restorePunctuation(
+        child.value,
+        ctx.source.slice(start, end)
+      );
+      if (value !== child.value) {
+        ctx.setProperty(child, "value", value);
+      }
+    }
+    restoreTexts(child, ctx);
+  }
+};
+
+const visit = (node: PromptNode, ctx: PromptContext): void => {
+  if (node.name === "Prompt") {
+    restoreTexts(node, ctx);
+  }
+};
+
+/** Satteri MDAST plugin that undoes smart punctuation in `<Prompt>` bodies. */
+export const promptTextPlugin = () => ({
+  mdxJsxFlowElement: visit,
+  mdxJsxTextElement: visit,
+  name: "blume-prompt-text",
+  options: { position: true },
+});

package/src/markdown/relative-links.ts

@@ -3,7 +3,11 @@ import { fileURLToPath } from "node:url";
 import { dirname, normalize, relative, resolve } from "pathe";
 
 import { mountBasePath } from "../core/base-path.ts";
-import { isIndexFileName, resolveRelativeHref } from "../core/links.ts";
+import {
+  isIndexFileName,
+  resolveRelativeHref,
+  resolveRootFileHref,
+} from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
 import { routeSnapshotReader } from "./route-snapshot.ts";
@@ -71,6 +75,13 @@ interface LocatedPage extends RelativeLinkBase {
 /** A JSX component name (`Card`, `Tree.File`), as opposed to an HTML tag. */
 const COMPONENT_NAME = /^[A-Z]/u;
 
+/**
+ * A root-relative link to a Markdown file (`/guide/new.md#x`), never
+ * `//host`: the one root-relative shape this plugin rewrites, when it names a
+ * content file.
+ */
+const ROOT_FILE_LINK = /^\/(?!\/)[^?#]*\.mdx?(?:[?#]|$)/iu;
+
 /** A plain string attribute value; an expression value isn't a link target. */
 const isStringValue = (value: MdastValue): value is string =>
   typeof value === "string";
@@ -146,7 +157,10 @@ export interface RelativeLinksPluginOptions {
  * snapshot the CLI publishes (or, ejected, the file eject writes), keyed by
  * collection entry: `docs` entries by their path under `contentRoot`, staged
  * entries (remote sources) by the longest trailing path that names one. A file
- * the snapshot doesn't know keeps its links as written.
+ * the snapshot doesn't know keeps its links as written. A root-relative link
+ * to a content file (`/guide/new.md`, see `resolveRootFileHref`) lands on that
+ * file's page too, from any page; one naming no content file is left as
+ * written, since `/guide/new.md` is also a page's Markdown copy.
  *
  * A rewritten route already carries `basePath`, and the `deployment.base`
  * prefix goes on here, unconditionally: the route is one Blume serves, so
@@ -225,11 +239,32 @@ export const relativeLinksPlugin = (
     return undefined;
   };
 
+  /**
+   * The route a root-relative link to a content file (`/guide/new.md`)
+   * means, when it names one (see `resolveRootFileHref`).
+   */
+  const resolveRootFile = (url: string): string | undefined => {
+    const index = contentRoot ? routeIndex() : undefined;
+    if (!(contentRoot && index)) {
+      return undefined;
+    }
+    const route = resolveRootFileHref(url, {
+      contentRoot,
+      deployBase,
+      routeOfFile: (file) =>
+        index.routes.get(entryKey("docs", relative(contentRoot, file))),
+    });
+    return route === undefined ? undefined : mountBasePath(deployBase, route);
+  };
+
   /** The route `url` means on the page at `fileURL`, when it's relative. */
   const resolveUrl = (
     url: string,
     fileURL: URL | undefined
   ): string | undefined => {
+    if (ROOT_FILE_LINK.test(url)) {
+      return resolveRootFile(url);
+    }
     // Cheap first: a target that can't be relative never needs the index. A
     // dotted name (`./node.js`) passes, since only the index knows its route.
     if (

package/src/markdown/route-snapshot.ts

@@ -3,35 +3,45 @@ import { readFileSync, statSync } from "node:fs";
 import { resolve } from "pathe";
 
 import { readRuntimeModule } from "../astro/runtime-modules.ts";
+import type { RuntimeModuleId } from "../astro/runtime-modules.ts";
 
 /**
- * A reader for the `blume:data` snapshot the Markdown link plugins consult for
- * the site's routes: the text the CLI publishes, or — in an ejected app, with
- * no CLI in the process — the snapshot file eject writes (`dataFile`), re-read
- * only when it changes. Resolves to `undefined` when neither is available.
+ * A reader for a runtime module snapshot a Markdown plugin consults: the text
+ * the CLI publishes under `id`, or — in an ejected app, with no CLI in the
+ * process — the file eject writes for it (`file`), re-read only when it
+ * changes. Resolves to `undefined` when neither is available.
  */
-export const routeSnapshotReader = (
-  dataFile?: string
+export const snapshotReader = (
+  id: RuntimeModuleId,
+  file?: string
 ): (() => string | undefined) => {
-  const file = dataFile ? resolve(dataFile) : undefined;
+  const path = file ? resolve(file) : undefined;
   let fileStamp: number | undefined;
   let fileText: string | undefined;
 
   /** The ejected snapshot file's text, re-read only when it changes. */
-  const readDataFile = (path: string): string | undefined => {
+  const readFile = (target: string): string | undefined => {
     let stamp: number;
     try {
-      stamp = statSync(path).mtimeMs;
+      stamp = statSync(target).mtimeMs;
     } catch {
       return undefined;
     }
     if (stamp !== fileStamp) {
       fileStamp = stamp;
-      fileText = readFileSync(path, "utf-8");
+      fileText = readFileSync(target, "utf-8");
     }
     return fileText;
   };
 
-  return () =>
-    readRuntimeModule("blume:data") ?? (file ? readDataFile(file) : undefined);
+  return () => readRuntimeModule(id) ?? (path ? readFile(path) : undefined);
 };
+
+/**
+ * A reader for the `blume:data` snapshot the Markdown link plugins consult for
+ * the site's routes: the text the CLI publishes, or the snapshot file an
+ * ejected app aliases (`dataFile`).
+ */
+export const routeSnapshotReader = (
+  dataFile?: string
+): (() => string | undefined) => snapshotReader("blume:data", dataFile);

package/src/markdown/svg-fallback.ts

@@ -0,0 +1,51 @@
+import { fileURLToPath } from "node:url";
+
+import { dirname, resolve } from "pathe";
+
+import { unmeasurableSvgUrl } from "../core/svg-images.ts";
+import type { MdastNode } from "./mdast.ts";
+
+/**
+ * Sätteri MDAST plugin that points an image embed of a colocated SVG Astro
+ * can't measure (a draw.io export, say: see `core/svg-images.ts`) at its
+ * served original, `/blume-assets/content/…`. A relative image is one Astro
+ * imports and optimizes, and an import it can't read the size of fails the
+ * whole build; a root-relative URL is one it leaves alone, so the page shows
+ * the file as it is. Runs before the base links plugin, which mounts
+ * `deployment.base` on the URL like any other root-relative image.
+ */
+
+interface ImageNode extends MdastNode {
+  url?: string | null;
+}
+
+/** The slice of Sätteri's MDAST visitor context this plugin needs. */
+interface ImageContext {
+  fileURL: URL | undefined;
+  setProperty: (node: MdastNode, key: "url", value: string) => void;
+}
+
+const SVG = /\.svg$/iu;
+
+export const svgFallbackPlugin = () => {
+  // Content image URLs are keyed by their path from the project root, where
+  // Blume runs Astro (see `contentAssetParam`).
+  const projectRoot = resolve(".");
+  return {
+    async image(node: ImageNode, ctx: ImageContext) {
+      const { url } = node;
+      if (!(ctx.fileURL && url && SVG.test(url))) {
+        return;
+      }
+      const served = await unmeasurableSvgUrl(
+        dirname(fileURLToPath(ctx.fileURL)),
+        url,
+        projectRoot
+      );
+      if (served) {
+        ctx.setProperty(node, "url", served);
+      }
+    },
+    name: "blume-svg-fallback",
+  };
+};