blume 2.0.2 → 2.1.0

package/src/core/meta.ts

@@ -89,6 +89,38 @@ const withinInclude = (
     (pattern) => !pattern.startsWith("!") && onPathOf(dir, globBase(pattern))
   );
 
+/**
+ * The folder-meta files a filesystem source contributes: `patterns` (every
+ * meta module name, shared `meta.$.*` included, by default) under the source's
+ * root, minus its `exclude` globs, dependencies, and build output, and only in
+ * folders its `include` globs reach. `blume translate` finds the meta files it
+ * translates through this too, so it covers exactly the ones the scan reads.
+ */
+export const findFolderMetaFiles = async (
+  source: FolderMetaSource,
+  patterns: readonly string[] = META_FILES
+): Promise<string[]> => {
+  const found = await glob([...patterns], {
+    absolute: true,
+    cwd: source.root,
+    // Never descend into dependencies or build output — relevant when the
+    // root is the project root (e.g. a `.`-rooted or all-staged project).
+    // The source's own `exclude` applies too: a `meta.ts` under an excluded
+    // folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`) is application
+    // code, not folder meta, and importing it would fail.
+    ignore: [
+      ...(source.exclude ?? []),
+      "**/node_modules/**",
+      "**/.blume/**",
+      "**/dist/**",
+    ],
+    onlyFiles: true,
+  });
+  return found.filter((file) =>
+    withinInclude(relative(source.root, dirname(file)), source.include)
+  );
+};
+
 /**
  * The folder-meta key for a directory. Mirrors the sidebar group path: the
  * source's route prefix (`docs`) followed by the directory relative to the
@@ -155,25 +187,7 @@ export const discoverFolderMeta = async (
   // `content.root` still contributes its folder meta.
   const perSource = await Promise.all(
     list.map(async (source) => {
-      const found = await glob(META_FILES, {
-        absolute: true,
-        cwd: source.root,
-        // Never descend into dependencies or build output — relevant when the
-        // root is the project root (e.g. a `.`-rooted or all-staged project).
-        // The source's own `exclude` applies too: a `meta.ts` under an
-        // excluded folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`)
-        // is application code, not folder meta, and importing it would fail.
-        ignore: [
-          ...(source.exclude ?? []),
-          "**/node_modules/**",
-          "**/.blume/**",
-          "**/dist/**",
-        ],
-        onlyFiles: true,
-      });
-      const files = found.filter((file) =>
-        withinInclude(relative(source.root, dirname(file)), source.include)
-      );
+      const files = await findFolderMetaFiles(source);
       const loaded = await Promise.all(
         files.map(
           async (

package/src/core/navigation.ts

@@ -3,6 +3,7 @@ import { extname } from "pathe";
 import { stripBasePath, withBasePath } from "./base-path.ts";
 import { orderingPrefix, stripOrderingPrefix } from "./ordering-prefix.ts";
 import type {
+  DirectoryMode,
   FolderMeta,
   SidebarDisplay,
   SidebarItemConfig,
@@ -115,11 +116,29 @@ const numericOrder = (segment: string): number => {
   return value ? Math.trunc(Number(value)) : Number.POSITIVE_INFINITY;
 };
 
+/**
+ * The name inside a group folder's parentheses — `(guides)`, or `01-(guides)`
+ * with its ordering prefix outside them — else undefined. A prefix written
+ * inside (`(01-guides)`) stays in the name, where it sorts and drops like any
+ * folder's.
+ */
+const groupName = (raw: string): string | undefined =>
+  (raw.match(GROUP_FOLDER) ?? stripOrderingPrefix(raw).match(GROUP_FOLDER))
+    ?.groups?.label;
+
+/**
+ * A folder's sidebar order: its ordering prefix, or — for a group folder
+ * without one outside the parentheses — the prefix inside them, so
+ * `01-(guides)` and `(01-guides)` both sort like `01-guides`.
+ */
+const folderOrder = (raw: string): number =>
+  numericOrder(
+    orderingPrefix(raw) === undefined ? (groupName(raw) ?? raw) : raw
+  );
+
 /** The nav key of a raw path segment: group label or numeric-stripped name. */
-const segmentKey = (raw: string): string => {
-  const group = raw.match(GROUP_FOLDER)?.groups?.label;
-  return stripOrderingPrefix(group ?? raw);
-};
+const segmentKey = (raw: string): string =>
+  stripOrderingPrefix(groupName(raw) ?? raw);
 
 /**
  * Whether a filename stem is a directory index, ignoring an ordering prefix:
@@ -184,6 +203,7 @@ interface MutableGroup {
   label: string;
   icon?: string;
   collapsed?: boolean;
+  directory?: DirectoryMode;
   display?: SidebarDisplay;
   order: number;
   /** Whether `order` is the node's position in its folder meta `pages` list. */
@@ -221,8 +241,8 @@ const ensureGroup = (
   const group = createGroup(
     segmentKey(rawSegment),
     path,
-    humanize(rawSegment.match(GROUP_FOLDER)?.groups?.label ?? rawSegment),
-    numericOrder(rawSegment)
+    humanize(groupName(rawSegment) ?? rawSegment),
+    folderOrder(rawSegment)
   );
   parent.index.set(rawSegment, group);
   parent.children.push(group);
@@ -287,9 +307,19 @@ interface FallbackFolderMeta {
   meta: (path: string) => FolderMeta | undefined;
 }
 
+/** A folder meta's own fields onto its group, over what the folder implied. */
+const applyMetaFields = (group: MutableGroup, meta: FolderMeta): void => {
+  group.label = meta.title ?? group.label;
+  group.icon = meta.icon ?? group.icon;
+  group.order = meta.order ?? group.order;
+  group.collapsed = meta.collapsed ?? group.collapsed;
+  group.directory = meta.directory ?? group.directory;
+};
+
 /**
- * Apply folder meta (title/order/icon/collapsed/display and explicit page
- * order), plus the index-frontmatter display sugar collected per folder path.
+ * Apply folder meta (title/order/icon/collapsed/display/directory and
+ * explicit page order), plus the index-frontmatter display sugar collected
+ * per folder path.
  */
 const applyFolderMeta = (
   group: MutableGroup,
@@ -328,10 +358,7 @@ const applyFolderMeta = (
     (mirrored ? fallback.indexDisplay.get(group.path) : undefined) ??
     meta?.display;
   if (meta) {
-    group.label = meta.title ?? group.label;
-    group.icon = meta.icon ?? group.icon;
-    group.order = meta.order ?? group.order;
-    group.collapsed = meta.collapsed ?? group.collapsed;
+    applyMetaFields(group, meta);
   }
 
   for (const child of group.children) {
@@ -612,7 +639,15 @@ const hoistTabSections = (
   }
 };
 
-const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
+/**
+ * A group's directory mode: its own, else the nearest one set above it (see
+ * `directory` in `schema.ts`).
+ */
+const toNavNode = (
+  node: MutableNode,
+  display: SidebarDisplay,
+  inheritedDirectory?: DirectoryMode
+): NavNode => {
   if (node.kind === "page") {
     return {
       badge: node.badge,
@@ -625,9 +660,13 @@ const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
       route: node.route,
     };
   }
+  const directory = node.directory ?? inheritedDirectory;
   return {
-    children: node.children.map((child) => toNavNode(child, display)),
+    children: node.children.map((child) =>
+      toNavNode(child, display, directory)
+    ),
     collapsed: node.collapsed,
+    directory,
     display: node.display ?? display,
     icon: node.icon,
     kind: "group",
@@ -722,7 +761,9 @@ const buildFileSystemSidebar = (
     const folderParts = isIndexStem(stem)
       ? routeSegments
       : routeSegments.slice(0, -1);
-    const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
+    const routeDirCount = dirs.filter(
+      (dir) => groupName(dir) === undefined
+    ).length;
     const offset = Math.max(0, folderParts.length - routeDirCount);
     // A frontmatter `slug` publishes the page away from its folder, so its
     // route says nothing about where the folder lives (`guides/a.md` with
@@ -744,7 +785,7 @@ const buildFileSystemSidebar = (
     const folders: string[] = [];
     for (const dir of dirs) {
       parent = ensureGroup(parent, dir);
-      if (!GROUP_FOLDER.test(dir)) {
+      if (groupName(dir) === undefined) {
         consumed += 1;
         folders.push(stripOrderingPrefix(dir));
       }
@@ -785,7 +826,9 @@ const buildFileSystemSidebar = (
   sortNodes(root.children, diagnostics);
   hoistPages(root.children, display, true);
   hoistTabSections(root.children, tabPaths, display);
-  return root.children.map((child) => toNavNode(child, display));
+  return root.children.map((child) =>
+    toNavNode(child, display, root.directory)
+  );
 };
 
 /**
@@ -912,16 +955,24 @@ const buildConfigSidebar = (
   items: SidebarItemConfig[],
   byRoute: Map<string, PageRecord>,
   display: SidebarDisplay,
-  basePath: string
+  basePath: string,
+  inheritedDirectory?: DirectoryMode
 ): NavNode[] => {
   const nodes: NavNode[] = [];
   for (const item of items) {
     if (!isPageRef(item) && item.items) {
+      const directory = item.directory ?? inheritedDirectory;
       nodes.push({
         badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute, display, basePath),
+        children: buildConfigSidebar(
+          item.items,
+          byRoute,
+          display,
+          basePath,
+          directory
+        ),
         collapsed: item.collapsed,
-        directory: item.directory,
+        directory,
         display: item.display ?? display,
         icon: item.icon,
         kind: "group",

package/src/core/page-modes.ts

@@ -0,0 +1,56 @@
+/**
+ * Page layout modes (`mode` frontmatter), Mintlify's names for what a page
+ * shows around its content:
+ *
+ * - `default`: the sidebar, the page's title and table of contents, and the
+ *   page-end links, around the prose column.
+ * - `wide`: no table of contents; the content takes its width.
+ * - `center`: no sidebar or table of contents; a wider column, centered.
+ *   For changelogs and other pages read top to bottom.
+ * - `custom`: only the header. No sidebar, title, breadcrumbs, table of
+ *   contents, page-end links, or site footer, and the content spans the
+ *   page, for a landing page written in MDX.
+ * - `frame`: `custom`, keeping the sidebar.
+ *
+ * Mintlify's `assistant` mode, a full-page chat, has no equivalent.
+ */
+export const PAGE_MODES = [
+  "default",
+  "wide",
+  "center",
+  "custom",
+  "frame",
+] as const;
+
+export type PageMode = (typeof PAGE_MODES)[number];
+
+/** What a page shows around its content, and how wide the content runs. */
+export interface PageModeLayout {
+  /** The page's own chrome: title, description, breadcrumbs, page-end links, and the site footer. */
+  chrome: boolean;
+  sidebar: boolean;
+  toc: boolean;
+  /** `content` is the prose measure, `center` a wider centered column, `full` the whole column. */
+  width: "content" | "center" | "full";
+}
+
+/** The layout a mode gives a page. */
+export const pageModeLayout = (mode: PageMode = "default"): PageModeLayout => {
+  switch (mode) {
+    case "wide": {
+      return { chrome: true, sidebar: true, toc: false, width: "full" };
+    }
+    case "center": {
+      return { chrome: true, sidebar: false, toc: false, width: "center" };
+    }
+    case "custom": {
+      return { chrome: false, sidebar: false, toc: false, width: "full" };
+    }
+    case "frame": {
+      return { chrome: false, sidebar: true, toc: false, width: "full" };
+    }
+    default: {
+      return { chrome: true, sidebar: true, toc: true, width: "content" };
+    }
+  }
+};

package/src/core/project-graph.ts

@@ -1,8 +1,10 @@
 import { isAbsolute, relative } from "pathe";
 
+import { withBasePath } from "./base-path.ts";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
+import { unknownDirectiveDiagnostics } from "./directive-diagnostics.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
@@ -10,16 +12,22 @@ import {
   gitLastModifiedTimes,
   gitRepositoryRoot,
   lastModifiedShallowWarning,
+  realPath,
   resolveLastModifiedConfig,
 } from "./last-modified.ts";
 import { buildManifest } from "./manifest.ts";
 import { discoverFolderMeta } from "./meta.ts";
 import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
+import { pathsUnderPattern } from "./redirect-patterns.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import { normalizeEntry, strippedLineOffset } from "./sources/normalize.ts";
 import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
-import type { ContentSource, SourceLoadResult } from "./sources/types.ts";
+import type {
+  ContentSource,
+  SourceEntry,
+  SourceLoadResult,
+} from "./sources/types.ts";
 import type {
   BlumeManifest,
   ContentGraph,
@@ -28,6 +36,12 @@ import type {
   PageRecord,
   ProjectContext,
 } from "./types.ts";
+import {
+  hasVariables,
+  substituteVariables,
+  undefinedVariables,
+} from "./variables.ts";
+import type { ContentVariables } from "./variables.ts";
 import { versionsDiagnostics } from "./versions.ts";
 
 /** Build mode: drafts are kept in `dev` and dropped in `build`. */
@@ -196,11 +210,34 @@ const normalizeLoadedEntries = (
       }
       pages.push(...normalized.pages);
       allDiagnostics.push(...normalized.diagnostics);
+      if (normalized.pages.length > 0) {
+        allDiagnostics.push(...unknownDirectiveDiagnostics(entry, source.name));
+      }
     }
   }
   return { diagnostics: allDiagnostics, droppedPages, pages };
 };
 
+/**
+ * The local sources' on-disk roots a `git log` pathspec can cover: those
+ * inside the repository at `gitRoot`. A root outside it would fail the log
+ * outright and can never yield dates. Compared by real path, since git spells
+ * its toplevel with every symlink resolved (`/private/tmp/site` for a project
+ * opened as `/tmp/site`); the roots themselves keep the project's spelling.
+ */
+const gitContentRoots = (
+  sources: readonly ContentSource[],
+  gitRoot: string | null
+): string[] => {
+  if (gitRoot === null) {
+    return [];
+  }
+  const top = realPath(gitRoot);
+  return sources
+    .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
+    .filter((dir) => isWithin(top, realPath(dir)));
+};
+
 /**
  * Run the full core pipeline for a project root: load config, resolve paths,
  * discover content and folder meta, build the graph, and assemble the manifest.
@@ -221,6 +258,85 @@ const isBannerShorthand = (
   banner: NonNullable<ResolvedConfig["banner"]>
 ): banner is string => typeof banner === "string";
 
+/**
+ * Report an entry's undefined content variables at their source lines, then
+ * replace the defined ones in the text the scan extracts from: the expanded
+ * text when includes were spliced (its `origins` map lines back to the file
+ * each came from), else the body.
+ */
+const substituteEntryVariables = (
+  entry: SourceEntry,
+  variables: ContentVariables
+): Diagnostic[] => {
+  const { expanded } = entry;
+  const text = expanded?.text ?? entry.body.text;
+  const offset = expanded ? 0 : strippedLineOffset(entry.raw, entry.body.text);
+  const diagnostics = undefinedVariables(text, variables).map(
+    ({ line, name }): Diagnostic => {
+      const origin = expanded?.origins[line - 1];
+      return {
+        code: "BLUME_UNDEFINED_VARIABLE",
+        file: origin?.file ?? entry.sourcePath,
+        line: origin?.line ?? line + offset,
+        message: `{{${name}}} isn't a defined variable, so it would show as written.`,
+        severity: "error",
+        suggestion: `Define "${name}" under variables in blume.config.ts, or put it in inline code to show it as written.`,
+      };
+    }
+  );
+  if (expanded) {
+    expanded.text = substituteVariables(expanded.text, variables);
+  } else {
+    entry.body.text = substituteVariables(entry.body.text, variables);
+  }
+  return diagnostics;
+};
+
+/** {@link substituteEntryVariables} over every loaded entry, when any are defined. */
+const substituteLoadedVariables = (
+  loaded: readonly SourceLoadResult[],
+  variables: ContentVariables
+): Diagnostic[] =>
+  hasVariables(variables)
+    ? loaded.flatMap(({ entries }) =>
+        entries.flatMap((entry) => substituteEntryVariables(entry, variables))
+      )
+    : [];
+
+/**
+ * A pattern redirect that also matches a page. Hosts disagree on which
+ * answers (Vercel and Cloudflare apply the rule ahead of the page, Netlify
+ * and the Node server serve the page), so the pattern is rejected rather than
+ * let the answer depend on the host. `pages` are the served page paths, which
+ * carry `basePath`, as the based `from` does.
+ */
+const redirectPageDiagnostics = (
+  config: ResolvedConfig,
+  pages: readonly string[],
+  configFile: string | null
+): Diagnostic[] =>
+  config.redirects.flatMap((redirect) => {
+    const matched = pathsUnderPattern(
+      withBasePath(config.basePath, redirect.from),
+      pages
+    );
+    const [first] = matched;
+    if (first === undefined) {
+      return [];
+    }
+    const more = matched.length > 1 ? ` and ${matched.length - 1} more` : "";
+    return [
+      {
+        code: "BLUME_REDIRECT_MATCHES_PAGE",
+        file: configFile ?? undefined,
+        message: `The redirect from ${redirect.from} also matches the page ${first}${more}, which some hosts would redirect and others would serve.`,
+        severity: "error",
+        suggestion:
+          "Narrow the pattern to the paths that moved, or move the pages out from under it.",
+      } satisfies Diagnostic,
+    ];
+  });
+
 /** The configured banner link target, when the banner has a link. */
 const bannerLinkHref = (
   banner: ResolvedConfig["banner"]
@@ -327,6 +443,14 @@ export const scanProject = async (
     })
   );
 
+  // Content variables: an undefined name in prose is an error at its source
+  // line, and every defined one is replaced in the text headings, links, and
+  // components are extracted from, so they match the rendered page.
+  const variableDiagnostics = substituteLoadedVariables(
+    loaded,
+    config.variables
+  );
+
   // Folder meta contributed by the sources themselves (the OpenAPI source
   // labels each tag directory with the spec's own tag name). It applies to
   // every locale, so it merges into the shared map — beneath user-authored
@@ -362,12 +486,9 @@ export const scanProject = async (
     // The git pathspecs must cover where the pages actually live: each local
     // source's own on-disk root — a filesystem source's `root`, or a staged
     // local source's tree (an Obsidian vault) — which diverges from the global
-    // `content.root`. A root outside the repository would fail the log outright
-    // and can never yield dates, so those are dropped up front.
+    // `content.root`.
     const gitRoot = gitRepositoryRoot(context.root);
-    const contentRoots = sources
-      .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
-      .filter((dir) => gitRoot !== null && isWithin(gitRoot, dir));
+    const contentRoots = gitContentRoots(sources, gitRoot);
     const gitTimes = gitLastModifiedTimes(
       context.root,
       contentRoots,
@@ -402,14 +523,15 @@ export const scanProject = async (
   const customPages = context.pagesRoot
     ? await discoverPages(context.pagesRoot)
     : [];
+  const extraRoutes = new Set([
+    ...customStaticRoutes(customPages),
+    ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
+  ]);
   const graph = buildContentGraph(pages, {
     bannerHref: bannerLinkHref(config.banner),
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
-    extraRoutes: new Set([
-      ...customStaticRoutes(customPages),
-      ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
-    ]),
+    extraRoutes,
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
@@ -431,6 +553,7 @@ export const scanProject = async (
     diagnostics: [
       ...contentDiagnostics,
       ...includeDiagnostics,
+      ...variableDiagnostics,
       ...folderMeta.diagnostics,
       ...entryIdDiagnostics(
         pages,
@@ -440,6 +563,11 @@ export const scanProject = async (
       ...i18nWarnings,
       ...versionWarnings,
       ...lastModifiedWarnings,
+      ...redirectPageDiagnostics(
+        config,
+        [...manifest.routes.map((route) => route.path), ...extraRoutes],
+        context.configFile
+      ),
     ],
     droppedPages,
     graph,