blume 1.7.2 → 2.0.0

package/src/markdown/include.ts

@@ -7,7 +7,7 @@ import {
   advanceHtmlCommentState,
   expandIncludeTarget,
   hasIncludeStatements,
-  parseIncludeLine,
+  matchIncludeStatement,
 } from "../core/includes.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
 
@@ -151,32 +151,42 @@ export const includePlugin = (options: IncludePluginOptions = {}) => {
   };
 
   /**
-   * Splice every statement line in a text block; `null` when none matched.
-   * Statement detection mirrors the string-level scanner's `.md` line rules
-   * (`parseIncludeLine`, HTML comment tracking) so the rendered page and the
-   * indexed/mirrored surfaces agree on which lines splice: a statement inside
-   * `<!-- -->` or indented like code stays verbatim on both sides.
+   * Splice every statement in a text block; `null` when none matched.
+   * Statement detection is the string-level scanner's (`matchIncludeStatement`
+   * with its `.md` rules, plus HTML comment tracking), so the rendered page and
+   * the indexed/mirrored surfaces agree on what splices: a statement inside
+   * `<!-- -->` or indented like code stays verbatim on both sides, and a
+   * wrapped statement splices whole on both.
    */
   const spliceLines = async (
     node: MdastNode,
     text: string,
     ctx: IncludeVisitorContext
   ): Promise<string | null> => {
+    const source = text.split("\n");
+    const pieces: (string | Promise<string>)[] = [];
     let matched = false;
     let inComment = false;
-    const lines = await Promise.all(
-      text.split("\n").map((line) => {
-        const wasInComment = inComment;
-        inComment = advanceHtmlCommentState(line, inComment);
-        const statement = wasInComment ? null : parseIncludeLine(line);
-        if (!statement) {
-          return line;
-        }
-        matched = true;
-        return splice(node, statement, ctx);
-      })
-    );
-    return matched ? lines.join("\n") : null;
+    for (let index = 0; index < source.length; index += 1) {
+      const line = source[index] ?? "";
+      const wasInComment = inComment;
+      inComment = advanceHtmlCommentState(line, inComment);
+      const match = wasInComment
+        ? null
+        : matchIncludeStatement(source, index, "md");
+      if (match?.kind !== "statement") {
+        pieces.push(line);
+        continue;
+      }
+      matched = true;
+      pieces.push(splice(node, match.statement, ctx));
+      index = match.end;
+    }
+    if (!matched) {
+      return null;
+    }
+    const spliced = await Promise.all(pieces);
+    return spliced.join("\n");
   };
 
   return {
@@ -195,17 +205,25 @@ export const includePlugin = (options: IncludePluginOptions = {}) => {
       if (node.name !== "include") {
         return;
       }
-      // The string-level scanner (search, mirrors, llms-full.txt, the HMR
-      // graph) only recognizes single-line statements; a wrapped element
-      // would render content those surfaces never see, so reject it loudly
-      // instead of splicing it invisibly.
+      // A wrapped element splices only when the string-level scanner (search,
+      // mirrors, llms-full.txt, the HMR graph) reads the same lines as one
+      // statement; anything it can't read would render content those surfaces
+      // never see, so it's rejected loudly instead of spliced invisibly.
       const start = node.position?.start?.line;
       const end = node.position?.end?.line;
       if (start !== undefined && end !== undefined && start !== end) {
-        const message =
-          "<include> must be written on a single line: <include>./path.mdx</include>.";
-        ctx.report({ message, node, severity: "warning" });
-        ctx.replaceNode(node, { raw: errorBlock(message) });
+        const lines = ctx.source.split("\n").slice(start - 1, end);
+        const match = matchIncludeStatement(lines, 0, "mdx");
+        if (match.kind !== "statement" || match.end !== lines.length - 1) {
+          const message =
+            "<include> must sit on a line of its own, or wrap with the path on its own line and no blank lines: <include>./path.mdx</include>.";
+          ctx.report({ message, node, severity: "warning" });
+          ctx.replaceNode(node, { raw: errorBlock(message) });
+          return;
+        }
+        ctx.replaceNode(node, {
+          raw: await splice(node, match.statement, ctx),
+        });
         return;
       }
       ctx.replaceNode(node, {

package/src/markdown/index.ts

@@ -12,6 +12,7 @@ import { codeToHtml } from "shiki";
 import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
+import { externalLinksPlugin } from "./external-links.ts";
 import { MARKDOWN_FEATURES, MDX_FEATURES } from "./features.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
 import { includePlugin } from "./include.ts";
@@ -20,6 +21,7 @@ import { languageIconTransformer } from "./language-icon.ts";
 import { mathPlugin } from "./math.ts";
 import { mermaidPlugin } from "./mermaid.ts";
 import { packageInstallPlugin } from "./package-install.ts";
+import { relativeLinksPlugin } from "./relative-links.ts";
 import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
@@ -87,12 +89,14 @@ 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.
+ * re-refs already-highlighted code. 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 })),
+  ...(options.externalLinks ? [asHastPlugin(externalLinksPlugin())] : []),
 ];
 
 /**
@@ -196,7 +200,7 @@ export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
   className?: string;
   /**
-   * Light/dark Shiki themes (`markdown.codeBlocks.theme`). Defaults to the same
+   * Light/dark Shiki themes (`markdown.code.theme`). Defaults to the same
    * github pair fenced code uses, so out-of-pipeline code stays in lockstep.
    */
   themes?: CodeThemes;
@@ -248,9 +252,14 @@ export const highlightCode = async (
 export interface BlumeMarkdownOptions {
   /**
    * Light/dark Shiki themes for inline `` `code`{:lang} `` highlighting
-   * (`markdown.codeBlocks.theme`). Defaults to the github pair fenced code uses.
+   * (`markdown.code.theme`). Defaults to the github pair fenced code uses.
    */
   codeThemes?: CodeThemes;
+  /**
+   * Open external links in a new tab, marked with an arrow icon and a
+   * screen-reader hint (`markdown.externalLinks`). Off unless `true`.
+   */
+  externalLinks?: boolean;
   /**
    * Wrap `<h2>`–`<h6>` in self-linking anchors (`markdown.headingAnchors`).
    * On unless explicitly `false`.
@@ -271,25 +280,41 @@ export interface BlumeMarkdownOptions {
   /**
    * The docs content root, bounding `<include>` target resolution (and
    * anchoring `/`-leading include paths). When unset, relative includes still
-   * resolve from the including file.
+   * resolve from the including file. Also the base the `docs` collection's
+   * entry ids are relative to, which relative page links resolve through.
    */
   contentRoot?: string;
+  /**
+   * The `blume:data` snapshot file an ejected app aliases. Relative page links
+   * resolve through the snapshot the CLI publishes; with no CLI in the
+   * process, they read this file instead.
+   */
+  dataFile?: string;
 }
 
 /**
- * MDAST plugins that apply to both `.md` and `.mdx`: the base-path link
- * rewrite (added only when a `basePath` or `deployBase` is configured).
+ * MDAST plugins that apply to both `.md` and `.mdx`: relative page links
+ * rewritten to the root-relative route they mean, then the base-path link
+ * rewrite (added only when a `basePath` or `deployBase` is configured), which
+ * layers `deployment.base` over the rewritten routes.
  */
 const blumeSharedMdastPlugins = (
   options: BlumeMarkdownOptions
-): MdastPlugin[] =>
-  options.basePath || options.deployBase
+): MdastPlugin[] => [
+  asMdastPlugin(
+    relativeLinksPlugin({
+      contentRoot: options.contentRoot,
+      dataFile: options.dataFile,
+    })
+  ),
+  ...(options.basePath || options.deployBase
     ? [
         asMdastPlugin(
           baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "")
         ),
       ]
-    : [];
+    : []),
+];
 
 /**
  * The `<include>` splice. Always first: its mutations apply before the next

package/src/markdown/inline-code.ts

@@ -7,11 +7,14 @@
  * marker and replaces the code's text with Shiki tokens (dual github-light/dark
  * via CSS variables, like fenced blocks).
  *
- * Shiki is imported lazily, so it loads only on pages that actually use inline
+ * Shiki is loaded lazily, so it loads only on pages that actually use inline
  * highlighting — and never when `markdown.code.inline` is off (the plugin is not
  * added to the pipeline at all).
  */
 
+import type * as ShikiModule from "shiki";
+
+import { nodeRequire } from "../core/node-require.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
@@ -77,13 +80,16 @@ type InlineHighlighter = (
   }
 ) => Promise<{ children: HastNode[] }>;
 
-// `import()` caches the module, so this dedupes Shiki across calls on its own.
-const loadHighlighter = async (): Promise<InlineHighlighter> => {
-  const mod = await import("shiki");
+// `require` caches the module, so this dedupes Shiki across calls on its own.
+// Not `import()`: the plugin runs after Astro has closed the module runner an
+// installed Blume's config was evaluated in (see `core/node-require.ts`), so
+// every inline snippet would silently lose its highlighting.
+const loadHighlighter = (): InlineHighlighter => {
+  const { codeToHast }: typeof ShikiModule = nodeRequire("shiki");
   // SAFETY: Shiki accepts arbitrary lang/theme strings at runtime (an unknown
   // one rejects the promise, which the caller catches); only its bundled types
   // constrain them to known ids, so the loose signature narrows nothing real.
-  return mod.codeToHast as InlineHighlighter;
+  return codeToHast as InlineHighlighter;
 };
 
 /** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */
@@ -102,7 +108,7 @@ export const inlineCodeHighlightPlugin = (
         return;
       }
       try {
-        const codeToHast = await loadHighlighter();
+        const codeToHast = loadHighlighter();
         const root = await codeToHast(parsed.code, {
           defaultColor: false,
           lang: parsed.lang,

package/src/markdown/relative-links.ts

@@ -0,0 +1,324 @@
+import { readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { dirname, normalize, relative, resolve } from "pathe";
+
+import { readRuntimeModule } from "../astro/runtime-modules.ts";
+import { isIndexFileName, resolveRelativeHref } from "../core/links.ts";
+import type { RelativeLinkBase } from "../core/links.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+interface UrlNode extends MdastNode {
+  url?: string | null;
+}
+
+/** An MDX JSX attribute, as the plugin reads it. */
+interface JsxAttribute {
+  [key: string]: MdastValue;
+  name?: string;
+  type?: string;
+  value?: MdastValue;
+}
+
+/** An MDX JSX element (`<Card href="./install" />`), as the plugin reads it. */
+interface JsxNode extends MdastNode {
+  attributes?: JsxAttribute[];
+  children?: MdastValue[];
+  name?: string | null;
+}
+
+/** The visitor-context slice this plugin uses (see `mdast.ts` for the model). */
+interface RelativeLinksContext {
+  fileURL: URL | undefined;
+  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
+  setProperty: (node: MdastNode, key: "url", value: string) => void;
+}
+
+/** The slice of the `blume:data` snapshot the plugin reads. */
+interface RouteData {
+  config: {
+    i18n?: { defaultLocale: string; locales: { code: string }[] } | null;
+  };
+  routes: {
+    collection: string;
+    entryId: string;
+    fallback: boolean;
+    locale: string;
+    path: string;
+  }[];
+}
+
+/** What the plugin knows about where content files publish. */
+interface RouteIndex {
+  /** `collection` + NUL + `entryId` → the route that entry publishes at. */
+  routes: Map<string, string>;
+  /** Every route the site serves, fallback copies included. */
+  paths: Set<string>;
+  /** Tokens an index file name may carry before its extension. */
+  localeTokens: string[];
+  /** The locale folders beside the default tree (every locale but the default). */
+  localeFolders: string[];
+}
+
+/** A content file, located: its page, and how to find the files beside it. */
+interface LocatedPage extends RelativeLinkBase {
+  /** The route a sibling file publishes at, from its path relative to `file`. */
+  routeOf: (path: string) => string | undefined;
+  /** Every route the site serves, for dotted page names (`./node.js`). */
+  routes: ReadonlySet<string>;
+}
+
+/** A JSX component name (`Card`, `Tree.File`), as opposed to an HTML tag. */
+const COMPONENT_NAME = /^[A-Z]/u;
+
+/** A plain string attribute value; an expression value isn't a link target. */
+const isStringValue = (value: MdastValue): value is string =>
+  typeof value === "string";
+
+const entryKey = (collection: string, entryId: string): string =>
+  `${collection}\0${entryId}`;
+
+/**
+ * Index the snapshot's routes by collection entry. A file shared by every
+ * locale publishes once per locale; the default locale's route stands for it,
+ * and the rendered link moves into the reader's locale afterwards (see
+ * `LocaleLinks.astro`). Fallback copies render another locale's file, so they
+ * never stand for it.
+ */
+const indexRoutes = (data: RouteData): RouteIndex => {
+  const defaultLocale = data.config.i18n?.defaultLocale;
+  const routes = new Map<string, string>();
+  for (const route of data.routes) {
+    if (route.fallback) {
+      continue;
+    }
+    const key = entryKey(route.collection, route.entryId);
+    if (!routes.has(key) || route.locale === defaultLocale) {
+      routes.set(key, route.path);
+    }
+  }
+  const locales = data.config.i18n?.locales.map((locale) => locale.code) ?? [];
+  return {
+    localeFolders: locales.filter((code) => code !== defaultLocale),
+    localeTokens: data.config.i18n ? ["$", ...locales] : [],
+    paths: new Set(data.routes.map((route) => route.path)),
+    routes,
+  };
+};
+
+/**
+ * The same entry path in the default tree: a page in a locale folder that
+ * links a sibling not translated yet (`fr/guides/setup.mdx` missing) means
+ * the default tree's file (`guides/setup.mdx`), whose route — its own `slug`
+ * included — moves into the reader's locale afterwards, onto the fallback
+ * copy (see `LocaleLinks.astro`).
+ */
+const defaultTreePath = (
+  entryId: string,
+  localeFolders: readonly string[]
+): string | undefined => {
+  const slash = entryId.indexOf("/");
+  return slash !== -1 && localeFolders.includes(entryId.slice(0, slash))
+    ? entryId.slice(slash + 1)
+    : undefined;
+};
+
+export interface RelativeLinksPluginOptions {
+  /** The `docs` collection's base directory, which entry ids are relative to. */
+  contentRoot?: string;
+  /**
+   * The `blume:data` JSON file, for an ejected app: with no CLI in the process
+   * to publish the snapshot, the plugin reads the file eject writes instead.
+   */
+  dataFile?: string;
+}
+
+/**
+ * Satteri MDAST plugin that rewrites relative page links (`[Install](./install)`,
+ * `[Setup](../guides/setup.md)`) to the root-relative route they mean, using
+ * the same file-style reading `blume validate` checks them against
+ * (`resolveRelativeHref`). Left as written, the browser resolves them against
+ * the page's slashless URL — so `./install` on an index page (`/guides`) lands
+ * on `/install`, and a `.md` link opens the raw Markdown source instead of the
+ * page. The page's own route, and a linked file's, come from the `blume:data`
+ * 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.
+ *
+ * Runs before the base-links plugin, whose `basePath` layering is idempotent,
+ * so a rewritten route (which already carries `basePath`) only gains the
+ * `deployment.base` prefix.
+ */
+export const relativeLinksPlugin = (
+  options: RelativeLinksPluginOptions = {}
+) => {
+  const contentRoot = options.contentRoot
+    ? resolve(options.contentRoot)
+    : undefined;
+  const dataFile = options.dataFile ? resolve(options.dataFile) : undefined;
+
+  // Parsed once per published snapshot: the CLI republishes on regeneration,
+  // and an unchanged snapshot is the same string, so every page compiled
+  // between regenerations reuses one index.
+  let cached: { index: RouteIndex; text: string } | 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 => {
+    let stamp: number;
+    try {
+      stamp = statSync(path).mtimeMs;
+    } catch {
+      return undefined;
+    }
+    if (stamp !== fileStamp) {
+      fileStamp = stamp;
+      fileText = readFileSync(path, "utf-8");
+    }
+    return fileText;
+  };
+
+  const routeIndex = (): RouteIndex | undefined => {
+    const text =
+      readRuntimeModule("blume:data") ??
+      (dataFile ? readDataFile(dataFile) : undefined);
+    if (text === undefined) {
+      return undefined;
+    }
+    if (cached?.text !== text) {
+      const data: RouteData = JSON.parse(text);
+      cached = { index: indexRoutes(data), text };
+    }
+    return cached.index;
+  };
+
+  /** The page `file` renders, with a resolver for the files beside it. */
+  const locate = (file: string, index: RouteIndex): LocatedPage | undefined => {
+    const locateIn = (
+      collection: string,
+      base: string
+    ): LocatedPage | undefined => {
+      const entryId = relative(base, file);
+      const route = index.routes.get(entryKey(collection, entryId));
+      if (route === undefined) {
+        return undefined;
+      }
+      return {
+        isIndex: isIndexFileName(entryId, index.localeTokens),
+        route,
+        routeOf: (path) => {
+          const target = relative(base, resolve(dirname(file), path));
+          const inDefaultTree = defaultTreePath(target, index.localeFolders);
+          return (
+            index.routes.get(entryKey(collection, target)) ??
+            (inDefaultTree === undefined
+              ? undefined
+              : index.routes.get(entryKey(collection, inDefaultTree)))
+          );
+        },
+        routes: index.paths,
+      };
+    };
+    if (contentRoot && !relative(contentRoot, file).startsWith("../")) {
+      return locateIn("docs", contentRoot);
+    }
+    // A staged entry's id is its path under the staging dir, which the plugin
+    // isn't told: the longest trailing path naming a staged entry wins.
+    const segments = file.split("/");
+    for (let start = 1; start < segments.length; start += 1) {
+      const staged = locateIn(
+        "staged",
+        segments.slice(0, start).join("/") || "/"
+      );
+      if (staged) {
+        return staged;
+      }
+    }
+    return undefined;
+  };
+
+  /** The route `url` means on the page at `fileURL`, when it's relative. */
+  const resolveUrl = (
+    url: string,
+    fileURL: URL | undefined
+  ): string | undefined => {
+    // 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 (
+      !fileURL ||
+      resolveRelativeHref(
+        url,
+        { isIndex: false, route: "/" },
+        undefined,
+        () => true
+      ) === undefined
+    ) {
+      return undefined;
+    }
+    const index = routeIndex();
+    const page = index && locate(normalize(fileURLToPath(fileURL)), index);
+    if (!page) {
+      return undefined;
+    }
+    const next = resolveRelativeHref(url, page, page.routeOf, (route) =>
+      page.routes.has(route)
+    );
+    return next === url ? undefined : next;
+  };
+
+  const rewrite = (node: UrlNode, ctx: RelativeLinksContext): void => {
+    const { url } = node;
+    const next = isStringValue(url) ? resolveUrl(url, ctx.fileURL) : undefined;
+    if (next !== undefined) {
+      ctx.setProperty(node, "url", next);
+    }
+  };
+
+  // A component's string `href` (`<Card href="./install">`) is the same kind
+  // of link, and `blume validate` reads it as one. Lowercase elements are
+  // raw HTML in a `.md` page, which neither rewrites nor checks, so only
+  // components are rewritten; an expression-valued `href={…}` is left alone.
+  const rewriteHref = (node: JsxNode, ctx: RelativeLinksContext): void => {
+    if (!node.name || !COMPONENT_NAME.test(node.name)) {
+      return;
+    }
+    const attributes = node.attributes ?? [];
+    const at = attributes.findIndex(
+      (attribute) =>
+        attribute.type === "mdxJsxAttribute" &&
+        attribute.name === "href" &&
+        isStringValue(attribute.value)
+    );
+    const value = attributes[at]?.value;
+    const next = isStringValue(value)
+      ? resolveUrl(value, ctx.fileURL)
+      : undefined;
+    if (next !== undefined) {
+      // Sätteri can't set a JSX element's attributes in place, so the element
+      // is swapped for a copy; its children carry over and are still visited.
+      ctx.replaceNode(node, {
+        attributes: attributes.map((attribute, position) =>
+          position === at
+            ? { name: attribute.name, type: attribute.type, value: next }
+            : attribute
+        ),
+        children: node.children ?? [],
+        name: node.name,
+        type: node.type,
+      });
+    }
+  };
+
+  // `link` covers inline links; `definition` covers reference-style
+  // definitions (`[x]: ./install`). Images stay with the image pipeline, which
+  // resolves relative embeds from beside the page source.
+  return {
+    definition: rewrite,
+    link: rewrite,
+    mdxJsxFlowElement: rewriteHref,
+    mdxJsxTextElement: rewriteHref,
+    name: "blume-relative-links",
+  };
+};

package/src/markdown/themes.ts

@@ -2,7 +2,7 @@
  * The light/dark Shiki themes Blume highlights code with. Every Shiki surface —
  * fenced code (the generated Astro `shikiConfig.themes`), inline `` `code`{:lang} ``,
  * out-of-pipeline `highlightCode`, and `<Diff>` — resolves to the same pair so a
- * project's `markdown.codeBlocks.theme` shifts them all in lockstep. This is the
+ * project's `markdown.code.theme` shifts them all in lockstep. This is the
  * single home for the github fallback used when nothing is configured.
  */
 
@@ -12,7 +12,7 @@ import type { ThemeRegistrationAny } from "shiki";
 export type CodeTheme = string | ThemeRegistrationAny;
 
 /**
- * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * A light/dark Shiki theme pair (`markdown.code.theme`). A `type` (not an
  * `interface`) so it keeps the implicit index signature Shiki's `themes`
  * parameter (`Partial<Record<string, …>>`) expects.
  */
@@ -22,7 +22,7 @@ export type CodeThemes = {
   light: CodeTheme;
 };
 
-/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+/** The default pair, used when `markdown.code.theme` is unset. */
 export const DEFAULT_CODE_THEMES: CodeThemes = {
   dark: "github-dark",
   light: "github-light",