blume 2.1.3 → 2.2.0

package/src/core/hidden-pages.ts

@@ -0,0 +1,64 @@
+import type { ContentGraph, NavNode, PageRecord } from "./types.ts";
+
+/**
+ * Hidden pages: `sidebar.hidden` (or the top-level `hidden` shorthand) takes a
+ * page out of the navigation, and so out of everything that lists the site's
+ * pages for readers, crawlers, and agents — the sitemap, site search,
+ * llms.txt, the site skill, the MCP server, and the JSON API.
+ *
+ * On a folder's index page the flag only drops the page's own row, the
+ * duplicate of the group row above it: the group row still links the page,
+ * so it is still in the navigation and stays listed everywhere else. Only a
+ * group row counts; a hidden page that an explicit sidebar lists as a page
+ * row is a contradiction `BLUME_NAV_HIDDEN_IN_SIDEBAR` reports instead. The
+ * home page — a tree's root: `/`, or a locale's `/fr` or a version's `/v1.0`
+ * — is the page the root URL serves, so hiding it only drops its row too.
+ */
+
+/** Linked routes per graph, collected once and read for every page. */
+const linkedRoutesByGraph = new WeakMap<ContentGraph, ReadonlySet<string>>();
+
+const collectGroupRoutes = (nodes: NavNode[], into: Set<string>): void => {
+  for (const node of nodes) {
+    if (node.kind === "group") {
+      if (node.route) {
+        into.add(node.route);
+      }
+      collectGroupRoutes(node.children, into);
+    }
+  }
+};
+
+/**
+ * Every route a sidebar group row links to — a generated folder's index page,
+ * or an explicit group's `root` — and every tree's root, across the current
+ * docs' trees (one per locale under i18n) and every archived version's.
+ */
+const linkedRoutes = (graph: ContentGraph): ReadonlySet<string> => {
+  const cached = linkedRoutesByGraph.get(graph);
+  if (cached) {
+    return cached;
+  }
+  // A graph assembled outside `buildContentGraph` (a builder under test) may
+  // carry pages alone; with no trees, no group row links anything.
+  const trees = [
+    graph.navigation,
+    ...Object.values(graph.navigationByLocale ?? {}),
+    ...Object.values(graph.navigationByVersion ?? {}).flatMap((byLocale) =>
+      Object.values(byLocale)
+    ),
+  ];
+  const routes = new Set<string>();
+  for (const tree of trees) {
+    if (tree?.root) {
+      routes.add(tree.root);
+    }
+    collectGroupRoutes(tree?.sidebar ?? [], routes);
+  }
+  linkedRoutesByGraph.set(graph, routes);
+  return routes;
+};
+
+/** Whether a page is hidden from the navigation (see the module comment). */
+export const isHiddenPage = (page: PageRecord, graph: ContentGraph): boolean =>
+  page.meta.sidebar.hidden && !linkedRoutes(graph).has(page.route);

package/src/core/includes.ts

@@ -5,7 +5,17 @@ import { dirname, extname, join, relative, resolve } from "pathe";
 import { nextFenceState } from "./code-fences.ts";
 import type { FenceState } from "./code-fences.ts";
 import matter from "./frontmatter.ts";
-import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
+import { resolveRelativeFile } from "./relative-files.ts";
+import {
+  INLINE_CODE,
+  isLinkElementUrl,
+  linkDefinitions,
+  rewriteCardImages,
+  rewriteElementUrls,
+  rewriteImageTargets,
+  rewriteLinkTargets,
+} from "./sources/normalize.ts";
+import type { LinkDefinition } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
 import { substituteVariables } from "./variables.ts";
 
@@ -360,46 +370,57 @@ const resolveIncludePath = (
   return { path };
 };
 
+/** A relative path written in `fromDir`, as written from `toDir`. */
+const movePath = (path: string, fromDir: string, toDir: string): string => {
+  const moved = relative(toDir, resolve(fromDir, path));
+  return moved.startsWith(".") ? moved : `./${moved}`;
+};
+
 /**
- * Rewrite one line's relative image targets from the included file's
- * directory to the including file's, so a partial's colocated
- * `![](./diagram.png)` still resolves once its markdown lives in the
- * includer. Mirrors `rewriteLine` in `content-assets.ts`: matches run on an
- * inline-code-masked copy while replacements splice into the real line.
+ * An image target written in the included file's directory, rebased onto the
+ * including file's, or `null` when it means the same thing from either: only
+ * filesystem-relative targets move with the file, while URLs, public-dir
+ * absolutes, and anchors stay.
  */
-const rebaseImageLine = (
-  line: string,
+const rebaseImageTarget = (
+  target: string,
   fromDir: string,
   toDir: string
-): string => {
-  const masked = line.replaceAll(INLINE_CODE, (span) =>
-    " ".repeat(span.length)
-  );
-  let out = "";
-  let cursor = 0;
-  for (const match of masked.matchAll(MD_IMAGE)) {
-    const target = match.groups?.target ?? "";
-    // Only filesystem-relative targets move with the file: URLs, public-dir
-    // absolutes, and anchors mean the same thing from either directory.
-    if (
-      target.startsWith("/") ||
-      target.startsWith("#") ||
-      URL.canParse(target)
-    ) {
-      continue;
-    }
-    const rebased = relative(toDir, resolve(fromDir, target));
-    const url = rebased.startsWith(".") ? rebased : `./${rebased}`;
-    const offset =
-      (match.index ?? 0) +
-      targetOffsetIn(match[0], target, match.groups?.title);
-    out += line.slice(cursor, offset) + url;
-    cursor = offset + target.length;
+): string | null =>
+  target.startsWith("/") || target.startsWith("#") || URL.canParse(target)
+    ? null
+    : movePath(target, fromDir, toDir);
+
+/**
+ * A link to a file beside the included file (`./spec.pdf`, see
+ * `resolveRelativeFile`), rebased onto the including file's directory with
+ * its `?query#fragment` kept, or `null` for any other target. A page link
+ * stays as written: it resolves against the including page, wherever the
+ * partial lives.
+ */
+const rebaseFileTarget = (
+  target: string,
+  fromDir: string,
+  toDir: string
+): string | null => {
+  const file = resolveRelativeFile(fromDir, target);
+  if (file === null) {
+    return null;
   }
-  return out + line.slice(cursor);
+  const path = target.slice(0, target.length - file.suffix.length);
+  return `${movePath(path, fromDir, toDir)}${file.suffix}`;
 };
 
-/** Rebase every relative image target in expanded lines, skipping fences. */
+/**
+ * Rebase every relative image target in expanded lines, skipping fences, from
+ * the included file's directory to the including file's, so a partial's
+ * colocated `![](./diagram.png)` still resolves once its markdown lives in
+ * the includer. Every destination form is read and written back in its own
+ * form (`![](<./a b.png> "Title")`; see `rewriteImageTargets`). A link,
+ * a reference definition, or an element URL naming a file beside the partial
+ * moves with it too, the way the build publishes such a file (see
+ * `core/content-assets.ts`).
+ */
 const rebaseImages = (
   lines: string[],
   fromDir: string,
@@ -409,11 +430,80 @@ const rebaseImages = (
     return lines;
   }
   let fence: FenceState = null;
-  return lines.map((line) => {
+  const rebased = lines.map((line) => {
     const next = nextFenceState(line, fence);
     const inFence = fence !== null || next !== null;
     fence = next;
-    return inFence ? line : rebaseImageLine(line, fromDir, toDir);
+    return inFence
+      ? line
+      : rewriteImageTargets(line, (target) =>
+          rebaseImageTarget(target, fromDir, toDir)
+        );
+  });
+  // A `<Card img>` is an image embed too, and its tag may wrap onto later
+  // lines, so it's rebased over the whole text, as are links and elements.
+  const toFile = (target: string): string | null =>
+    rebaseFileTarget(target, fromDir, toDir);
+  return rewriteElementUrls(
+    rewriteLinkTargets(
+      rewriteCardImages(rebased.join("\n"), (target) =>
+        rebaseImageTarget(target, fromDir, toDir)
+      ),
+      toFile
+    ),
+    (url) => (isLinkElementUrl(url) ? toFile(url.value) : null)
+  ).split("\n");
+};
+
+/**
+ * A `.md` partial's HTML comments (`<!-- … -->`), written as MDX comments
+ * (`{/* … *\/}`), for splicing into an `.mdx` page. The partial is read in
+ * the page's format, and MDX has no HTML comments: it shows one as text, so
+ * a note meant to stay hidden would render. A comment can span lines, and
+ * its text keeps every line (with any `*\/` broken up so it can't end the
+ * comment early), so line origins hold. Fenced code and inline code show a
+ * comment rather than make one, so they're left as written.
+ */
+const htmlCommentsAsMdx = (lines: readonly string[]): string[] => {
+  let fence: FenceState = null;
+  let inComment = false;
+  return lines.map((line) => {
+    if (!inComment) {
+      const next = nextFenceState(line, fence);
+      const inFence = fence !== null || next !== null;
+      fence = next;
+      if (inFence) {
+        return line;
+      }
+    }
+    const masked = line.replaceAll(INLINE_CODE, (span) =>
+      " ".repeat(span.length)
+    );
+    let out = "";
+    let at = 0;
+    while (at < line.length) {
+      if (inComment) {
+        const close = line.indexOf("-->", at);
+        const end = close === -1 ? line.length : close;
+        out += line.slice(at, end).replaceAll("*/", "* /");
+        if (close === -1) {
+          break;
+        }
+        out += "*/}";
+        at = close + "-->".length;
+        inComment = false;
+      } else {
+        const open = masked.indexOf("<!--", at);
+        if (open === -1) {
+          out += line.slice(at);
+          break;
+        }
+        out += `${line.slice(at, open)}{/*`;
+        at = open + "<!--".length;
+        inComment = true;
+      }
+    }
+    return out;
   });
 };
 
@@ -532,12 +622,17 @@ const expandStatement = async (
   // Props replace their `{{name}}` references line by line, so every line
   // keeps its origin; they reach the file's own nested includes too.
   const { props } = statement.attributes;
+  const rebased = rebaseImages(
+    props ? lines.map((text) => substituteVariables(text, props)) : lines,
+    dirname(path),
+    dirname(filePath)
+  );
   return {
-    lines: rebaseImages(
-      props ? lines.map((text) => substituteVariables(text, props)) : lines,
-      dirname(path),
-      dirname(filePath)
-    ),
+    lines:
+      extname(path).toLowerCase() === ".md" &&
+      extname(filePath).toLowerCase() === ".mdx"
+        ? htmlCommentsAsMdx(rebased)
+        : rebased,
     origins,
   };
 };
@@ -706,6 +801,51 @@ export const expandIncludes = async (
   };
 };
 
+/**
+ * `text` with each of `definitions` it doesn't define itself appended, so a
+ * reference in it resolves through a definition written elsewhere in the
+ * page (CommonMark definitions are document-wide). Definitions render
+ * nothing; they're left off a text that ends in an open code fence, where
+ * they'd show as code.
+ */
+export const withDefinitions = (
+  text: string,
+  definitions: readonly LinkDefinition[]
+): string => {
+  const own = new Set(
+    linkDefinitions(text).map((definition) => definition.key)
+  );
+  const missing = definitions.filter((definition) => !own.has(definition.key));
+  let fence: FenceState = null;
+  for (const line of text.split("\n")) {
+    fence = nextFenceState(line, fence);
+  }
+  return missing.length === 0 || fence !== null
+    ? text
+    : `${text}\n\n${missing.map((definition) => definition.text).join("\n")}\n`;
+};
+
+/**
+ * A page's source with the link-reference definitions its included partials
+ * write appended, for the render to parse. Each partial is spliced after the
+ * page is parsed (see `markdown/include.ts`), so a reference in the page
+ * (`[PEP 508]`) to a definition in a partial would otherwise stay text,
+ * though an include reads as if written inline. The definitions come from
+ * the expansion every surface shares, so a partial's definition of a file
+ * beside it is already rebased onto the page. The page's own definition of
+ * a label wins.
+ */
+export const withIncludedDefinitions = async (
+  body: string,
+  options: { sourcePath: string; contentRoot?: string }
+): Promise<string> => {
+  if (!hasIncludeStatements(body)) {
+    return body;
+  }
+  const expanded = await expandIncludes(body, options);
+  return withDefinitions(body, linkDefinitions(expanded.text));
+};
+
 /**
  * Resolve one include statement to its fully-expanded markdown text — the
  * render plugin's entry point (it finds the statements as AST nodes and only

package/src/core/last-modified.ts

@@ -27,7 +27,7 @@ const GIT_LOCATION_VARS = new Set([
   "GIT_WORK_TREE",
 ]);
 
-const gitEnv = (): NodeJS.ProcessEnv =>
+export const gitEnv = (): NodeJS.ProcessEnv =>
   Object.fromEntries(
     Object.entries(process.env).filter(([key]) => !GIT_LOCATION_VARS.has(key))
   );
@@ -41,19 +41,50 @@ export const resolveLastModifiedConfig = (
     : { enabled: true, source: value };
 
 /**
- * Parse `git log --format=%x00%cI --name-only` output into a map of
- * repo-root-relative path → most recent committer ISO date. Each commit emits a
- * NUL-prefixed date line followed by the paths it touched; since git logs
- * newest-first, the first date seen for a path wins. Blank lines are ignored.
+ * Parse `git log --format=%x00%cI --name-status -M100%` output into a map of
+ * repo-root-relative path → the committer ISO date of the newest commit that
+ * changed the file. Each commit emits a NUL-prefixed date line followed by a
+ * status line per path it touched (`M\tpath`, `R100\told\tnew`); since git
+ * logs newest-first, the first date seen for a path wins. Blank lines are
+ * ignored.
+ *
+ * A rename (`-M100%` reports only exact ones, where the content is unchanged)
+ * follows the file the way `git log --follow` does for one path: it dates
+ * nothing itself, and the older commits that name the old path date the file
+ * under its current name, so renaming `page.md` to `page.mdx` keeps the page's
+ * date. A file whose visible history starts at a rename (a shallow clone cut
+ * off the commits before it) takes the rename's date.
  */
 export const parseGitLog = (output: string): Map<string, string> => {
   const times = new Map<string, string>();
+  // An older name of a file → its name now, for the commits read after the
+  // rename (older ones).
+  const currentNames = new Map<string, string>();
+  const renamedAt = new Map<string, string>();
   let current: string | null = null;
   for (const line of output.split("\n")) {
     if (line.startsWith("\0")) {
       current = line.slice(1);
-    } else if (line && current && !times.has(line)) {
-      times.set(line, current);
+      continue;
+    }
+    const [status = "", from = "", to] = line.split("\t");
+    const path = to ?? from;
+    if (!(current && path)) {
+      continue;
+    }
+    const name = currentNames.get(path) ?? path;
+    if (status.startsWith("R")) {
+      currentNames.set(from, name);
+      if (!renamedAt.has(name)) {
+        renamedAt.set(name, current);
+      }
+    } else if (!times.has(name)) {
+      times.set(name, current);
+    }
+  }
+  for (const [name, date] of renamedAt) {
+    if (!times.has(name)) {
+      times.set(name, date);
     }
   }
   return times;
@@ -99,8 +130,10 @@ export const gitRepositoryRoot = (root: string): string | null => {
 /**
  * Resolve each source file's last-modified date from git history, keyed by
  * absolute source path. Runs a single `git log` over the given content roots
- * (each local source's own root, which may diverge from `content.root`)
- * and maps repo-root-relative paths back to the given absolute paths
+ * (each local source's own root, which may diverge from `content.root`),
+ * following renames within them (see `parseGitLog`; a file moved in from
+ * outside every root dates from the move), and maps repo-root-relative paths
+ * back to the given absolute paths
  * (monorepo-safe via `rev-parse --show-toplevel`). Returns an empty map if git
  * is unavailable or the project isn't a repo — the feature then simply shows
  * no dates.
@@ -141,7 +174,11 @@ export const gitLastModifiedTimes = (
         "core.quotePath=false",
         "log",
         "--format=%x00%cI",
-        "--name-only",
+        "--name-status",
+        // Exact renames only: git pairs them by blob id without comparing
+        // contents, so following them costs nothing, and a rename with edits
+        // dates the file at that commit either way.
+        "-M100%",
         "--",
         ...contentRoots.map(realPath),
       ],