blume 2.1.3 → 2.2.1

package/src/cli/commands/validate.ts

@@ -1,5 +1,3 @@
-import { existsSync } from "node:fs";
-
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
@@ -8,11 +6,15 @@ import {
   discoverPages,
   hasGeneratedChangelog,
 } from "../../astro/pages.ts";
+import { normalizeBasePath } from "../../core/base-path.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { validateLinks } from "../../core/links.ts";
 import { buildManifest } from "../../core/manifest.ts";
 import { scanProject } from "../../core/project-graph.ts";
+import { resolveDocsCollection } from "../../core/sources/collection.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { generatedFilePaths } from "../../deploy/generated-files.ts";
+import { referenceRoutes } from "../../openapi/references.ts";
 import { parseIgnoreFlag } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
@@ -56,13 +58,17 @@ export const validateCommand = defineCommand({
       // link-validation blind spot, so silently passing would be misleading.
       diagnostics.push(...project.diagnostics);
 
-      // Custom `.astro` pages and the generated changelog index are servable
-      // routes the content graph can't see — without them, a docs link to e.g.
-      // a custom landing page fails as BLUME_BROKEN_LINK.
+      // Custom `.astro` pages, reference routes (a `scalar()` page), and the
+      // generated changelog index are servable routes the content graph can't
+      // see — without them, a docs link to e.g. a custom landing page fails as
+      // BLUME_BROKEN_LINK.
       const userPages = project.context.pagesRoot
         ? await discoverPages(project.context.pagesRoot)
         : [];
-      const extraRoutes = customStaticRoutes(userPages);
+      const extraRoutes = [
+        ...customStaticRoutes(userPages),
+        ...referenceRoutes(project.config),
+      ];
       if (hasGeneratedChangelog(project, userPages)) {
         extraRoutes.push("/changelog");
       }
@@ -84,15 +90,21 @@ export const validateCommand = defineCommand({
         );
       }
 
-      const publicDir = join(root, "public");
+      // Links to `public/` files and to the files the build generates
+      // (`/llms.txt`, `/sitemap.xml`) resolve too. With no `public/` folder,
+      // the site ships no public files, so links to one are reported.
       diagnostics.push(
         ...(await validateLinks(project.graph, {
           basePath: project.config.basePath,
           checkExternal: Boolean(args.external),
+          configFile: project.context.configFile ?? undefined,
+          contentRoot: resolveDocsCollection(project.config, root).base,
+          deployBase: normalizeBasePath(project.config.deployment.options.base),
           extraRoutes,
+          generatedFiles: generatedFilePaths(project),
           i18n: project.config.i18n,
           ignore,
-          publicDir: existsSync(publicDir) ? publicDir : null,
+          publicDir: join(root, "public"),
           redirects: project.config.redirects,
         }))
       );
@@ -105,8 +117,8 @@ export const validateCommand = defineCommand({
       }
     }
 
-    // `--strict` escalates warnings to failures; info-level notes (e.g.
-    // BLUME_ASSETS_UNCHECKED when there is no public/ dir) stay advisory.
+    // `--strict` escalates warnings to failures; info-level notes stay
+    // advisory.
     const strictFailure =
       Boolean(args.strict) &&
       diagnostics.some((diagnostic) => diagnostic.severity !== "info");

package/src/cli/prepare.ts

@@ -112,7 +112,7 @@ export const prepareProject = async (
   const hadErrors = reportDiagnostics(project.diagnostics, options.root);
   const dropped =
     project.droppedPages > 0
-      ? `${project.droppedPages} page(s) failed frontmatter validation and were dropped from the site. `
+      ? `${project.droppedPages} page(s) failed validation and were dropped from the site. `
       : "";
   const optIn = options.strictOptIn ?? options.mode === "dev";
   if (hadErrors && options.strict) {

package/src/cli/preview-pages.ts

@@ -0,0 +1,161 @@
+import { readFileSync, statSync } from "node:fs";
+import { Server } from "node:http";
+import type { IncomingMessage } from "node:http";
+
+import type { PreviewServer } from "astro";
+import { join } from "pathe";
+
+import { stripBasePath } from "../core/base-path.ts";
+import {
+  compileEveryRedirect,
+  matchCompiledRedirect,
+  requestPath,
+} from "../core/redirect-patterns.ts";
+import type { CompiledRedirect } from "../core/redirect-patterns.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import {
+  answerRequestsFirst,
+  trailingSlashAnswer,
+} from "../core/static-host.ts";
+import type { HostAnswer } from "../core/static-host.ts";
+import type { BlumeManifest } from "../core/types.ts";
+import { platformRedirects } from "../deploy/redirects.ts";
+
+/**
+ * Astro previews a static build on Vite's preview server, which serves the
+ * files in `dist/` and nothing a host would add: the redirect rules the build
+ * writes for it (`_redirects`, `vercel.json`), which carry every pattern
+ * redirect, and the host's handling of a trailing slash (see
+ * `core/static-host.ts`). Its HTML fallback also answers a slashless `/guide`
+ * with `guide.html` whenever that path exists. It checks with
+ * `fs.existsSync`, which a directory passes too. A redirect from
+ * `/guide.html` (a migrated site's URL) has its redirect page written to
+ * `dist/guide.html/index.html`, a directory, so the fallback rewrites
+ * `/guide` to it, Astro's own preview rewrite appends `/index.html`, and the
+ * page at `/guide` becomes a redirect page that refreshes to itself forever.
+ * Hosts look up files, so they serve the page at `guide/index.html`.
+ */
+
+/** Whether `path` is a directory (true) or a file (false); null when absent. */
+const isDirectory = (path: string): boolean | null => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The URL to serve a preview request from in place of the one Vite's HTML
+ * fallback would pick, or null to leave the request alone: the page's own
+ * `index.html` when `dist/<route>.html` is a directory, the redirect page of
+ * a redirect from `<route>.html`. `base` is the normalized
+ * `deployment.base`, which the URL carries and `dist/` doesn't.
+ */
+export const previewPageUrl = (
+  distDir: string,
+  base: string,
+  url: string
+): string | null => {
+  const queryAt = url.search(/[?#]/u);
+  const pathname = queryAt === -1 ? url : url.slice(0, queryAt);
+  if (pathname.endsWith("/")) {
+    return null;
+  }
+  let route: string;
+  try {
+    route = decodeURIComponent(stripBasePath(base, pathname));
+  } catch {
+    return null;
+  }
+  const page = join(distDir, route);
+  if (!page.startsWith(`${distDir}/`)) {
+    return null;
+  }
+  return isDirectory(`${page}.html`) === true &&
+    isDirectory(join(page, "index.html")) === false
+    ? `${pathname}/index.html${queryAt === -1 ? "" : url.slice(queryAt)}`
+    : null;
+};
+
+/**
+ * The configured redirects as a static build's host files carry them, for
+ * the preview to answer as the host would. They're based against the pages
+ * of the last generated project (`blume.manifest.json` in the runtime dir),
+ * which tell a page from a public file and say which moved pages' Markdown
+ * copies move with them.
+ */
+export const previewRedirects = (
+  config: ResolvedConfig,
+  runtimeDir: string
+): CompiledRedirect[] => {
+  if (config.redirects.length === 0) {
+    return [];
+  }
+  let manifest: Pick<BlumeManifest, "routes">;
+  try {
+    manifest = JSON.parse(
+      readFileSync(join(runtimeDir, "blume.manifest.json"), "utf-8")
+    );
+  } catch {
+    manifest = { routes: [] };
+  }
+  return compileEveryRedirect(platformRedirects({ config, manifest }));
+};
+
+/** What a static build's preview answers like a host would. */
+export interface PreviewRouting {
+  /** The normalized `deployment.base` (`""` at the root). */
+  base: string;
+  distDir: string;
+  /**
+   * Whether a path names a folder of HTML in the project's `public/`, served
+   * at its slashed URL (see `publicFolder`).
+   */
+  isPublicFolder: (path: string) => boolean;
+  /** Every configured redirect, as the build's host files carry them. */
+  redirects: readonly CompiledRedirect[];
+}
+
+/**
+ * How the preview answers a request ahead of Vite: a configured redirect
+ * first, as the host's rules do, then the trailing slash, then the page
+ * Vite's fallback would miss ({@link previewPageUrl}).
+ */
+export const previewAnswer = (
+  routing: PreviewRouting,
+  request: Pick<IncomingMessage, "method" | "url">
+): HostAnswer | null => {
+  const url = request.url ?? "/";
+  const redirect = matchCompiledRedirect(routing.redirects, requestPath(url));
+  if (redirect) {
+    return { kind: "redirect", location: redirect[0], status: redirect[1] };
+  }
+  const slash = trailingSlashAnswer(
+    request,
+    routing.base,
+    routing.isPublicFolder
+  );
+  if (slash) {
+    return slash;
+  }
+  const page = previewPageUrl(routing.distDir, routing.base, url);
+  return page === null ? null : { kind: "rewrite", url: page };
+};
+
+/**
+ * Answer each request with {@link previewAnswer} before Vite's middleware
+ * sees it. Astro's static preview hands back Vite's HTTP server beside the
+ * documented fields; without one, the server is left as it is.
+ */
+export const servePreview = (
+  preview: PreviewServer,
+  routing: PreviewRouting
+): void => {
+  if (!("server" in preview && preview.server instanceof Server)) {
+    return;
+  }
+  answerRequestsFirst(preview.server, (request) =>
+    previewAnswer(routing, request)
+  );
+};

package/src/cli/required-secrets.ts

@@ -45,7 +45,6 @@ const adapterSecretOwners = (config: ResolvedConfig): SecretOwner[] => {
       secrets: consent.requiredSecrets,
     });
   }
-  // Upstash's endpoint and token.
   if (rateLimit) {
     owners.push({
       feature: `Rate limiting (${rateLimit.kind})`,

package/src/cli/unknown-flags.ts

@@ -1,5 +1,6 @@
 import type { ArgsDef } from "citty";
 
+import { closestMatch } from "../core/closest-match.ts";
 import type { Diagnostic } from "../core/types.ts";
 
 /** A flag the command doesn't declare, with the declared one it most resembles. */
@@ -74,48 +75,6 @@ const knownFlags = (argsDef: ArgsDef): Map<string, KnownFlag> => {
   return flags;
 };
 
-/** Edit distance between two short strings (insertions, deletions, swaps of one letter). */
-const distance = (from: string, to: string): number => {
-  let previous = Array.from({ length: to.length + 1 }, (_, index) => index);
-  for (const [row, fromChar] of [...from].entries()) {
-    const current = [row + 1];
-    for (const [column, toChar] of [...to].entries()) {
-      current.push(
-        Math.min(
-          (previous[column + 1] ?? 0) + 1,
-          (current[column] ?? 0) + 1,
-          (previous[column] ?? 0) + (fromChar === toChar ? 0 : 1)
-        )
-      );
-    }
-    previous = current;
-  }
-  return previous[to.length] ?? 0;
-};
-
-/**
- * The candidate closest to `name`, when it's close enough to be the likely
- * intent: at most two edits away, and fewer edits than half the candidate's
- * length, so a short typo doesn't "suggest" an unrelated short word.
- */
-export const closestMatch = (
-  name: string,
-  candidates: readonly string[]
-): string | undefined => {
-  let best: { candidate: string; edits: number } | undefined;
-  for (const candidate of candidates) {
-    const edits = distance(name, candidate);
-    if (
-      edits <= 2 &&
-      edits * 2 < candidate.length &&
-      (best === undefined || edits < best.edits)
-    ) {
-      best = { candidate, edits };
-    }
-  }
-  return best?.candidate;
-};
-
 /** A `--name`, `--no-name`, `--name=value`, or `-n` token, taken apart. */
 interface FlagToken {
   /** Whether it carries its value inline (`--port=4000`). */

package/src/components/code-copy.ts

@@ -0,0 +1,51 @@
+/**
+ * What a code block's copy button puts on the clipboard. Most blocks copy as
+ * shown. A terminal session (` ```console `, ` ```shellsession `) shows
+ * prompts and output around its commands, and pasting that into a terminal
+ * runs the `$` and the output as commands, so it copies only the commands,
+ * prompts stripped, one per line.
+ */
+
+/** Shiki's terminal-session language and its alias. */
+const SESSION_LANGUAGES: ReadonlySet<string> = new Set([
+  "console",
+  "shellsession",
+]);
+
+/**
+ * A command line: an optional prefix (`(venv)`, `user@host:~`,
+ * `[user@host dir]`), a prompt character, a space, then the command. The
+ * prefixes are the ones Shiki's session grammar reads, with a virtualenv's
+ * `(venv)` allowed on its own as Pygments' does. Shiki's `>` and Greek
+ * prompts are left out: a `>` line in a transcript is usually output (npm
+ * prints its scripts that way) or a continuation, handled below.
+ */
+const PROMPT =
+  /^(?:\(\S+\)\s*)?(?:(?:sh\S*?|\w\S+[:@]\S+(?:\s+\S+)?|\[\S+?[:@][^\n]+?\].*?)\s*)?[#$%❯➜]\s+(?<command>.*)$/u;
+
+/** The `> ` a shell prints before each continuation of a `\`-ended line. */
+const CONTINUATION_PROMPT = /^> /u;
+
+/**
+ * The commands of a terminal session, prompts stripped and output dropped. A
+ * line after one ending in `\` continues its command. A session with no
+ * prompt at all copies as written: it's commands alone.
+ */
+const sessionCommands = (text: string): string => {
+  const commands: string[] = [];
+  let continuing = false;
+  for (const line of text.split("\n")) {
+    const command: string | undefined = continuing
+      ? line.replace(CONTINUATION_PROMPT, "")
+      : PROMPT.exec(line)?.groups?.command;
+    if (command) {
+      commands.push(command);
+    }
+    continuing = command?.trimEnd().endsWith("\\") ?? false;
+  }
+  return commands.length > 0 ? commands.join("\n") : text;
+};
+
+/** The text to copy from a block of `language` that reads `text`. */
+export const copyableCode = (text: string, language = ""): string =>
+  SESSION_LANGUAGES.has(language.toLowerCase()) ? sessionCommands(text) : text;

package/src/components/code-language.ts

@@ -0,0 +1,75 @@
+/**
+ * A fence language's display name: the label a code block's header shows in
+ * place of its language id, and the tab label of an untitled block in a
+ * `<CodeGroup>`. Shared by the docs layout's script and the tabs element's,
+ * so a block reads the same in both places.
+ */
+
+/** Language id (lowercase, aliases included) → display name. */
+const LANGUAGE_LABELS: ReadonlyMap<string, string> = new Map([
+  ["astro", "Astro"],
+  ["bash", "Bash"],
+  ["c", "C"],
+  ["c#", "C#"],
+  ["c++", "C++"],
+  ["console", "Console"],
+  ["cpp", "C++"],
+  ["cs", "C#"],
+  ["csharp", "C#"],
+  ["css", "CSS"],
+  ["dart", "Dart"],
+  ["diff", "Diff"],
+  ["docker", "Dockerfile"],
+  ["dockerfile", "Dockerfile"],
+  ["elixir", "Elixir"],
+  ["go", "Go"],
+  ["gql", "GraphQL"],
+  ["graphql", "GraphQL"],
+  ["html", "HTML"],
+  ["http", "HTTP"],
+  ["java", "Java"],
+  ["javascript", "JavaScript"],
+  ["js", "JavaScript"],
+  ["json", "JSON"],
+  ["jsonc", "JSONC"],
+  ["jsx", "JSX"],
+  ["kotlin", "Kotlin"],
+  ["kt", "Kotlin"],
+  ["lua", "Lua"],
+  ["markdown", "Markdown"],
+  ["md", "Markdown"],
+  ["mdx", "MDX"],
+  ["php", "PHP"],
+  ["plaintext", "Text"],
+  ["powershell", "PowerShell"],
+  ["ps1", "PowerShell"],
+  ["py", "Python"],
+  ["python", "Python"],
+  ["rb", "Ruby"],
+  ["rs", "Rust"],
+  ["ruby", "Ruby"],
+  ["rust", "Rust"],
+  ["scala", "Scala"],
+  ["scss", "SCSS"],
+  ["sh", "Shell"],
+  ["shell", "Shell"],
+  ["shellsession", "Shell Session"],
+  ["sql", "SQL"],
+  ["svelte", "Svelte"],
+  ["swift", "Swift"],
+  ["text", "Text"],
+  ["toml", "TOML"],
+  ["ts", "TypeScript"],
+  ["tsx", "TSX"],
+  ["txt", "Text"],
+  ["typescript", "TypeScript"],
+  ["vue", "Vue"],
+  ["xml", "XML"],
+  ["yaml", "YAML"],
+  ["yml", "YAML"],
+  ["zsh", "Zsh"],
+]);
+
+/** The display name of a fence language, or the id as written for one without a name here. */
+export const languageLabel = (language: string): string =>
+  LANGUAGE_LABELS.get(language.toLowerCase()) ?? language;

package/src/components/content/AccordionItem.astro

@@ -1,6 +1,7 @@
 ---
 import Icon from "../Icon.astro";
 import { componentSlug } from "../slug.ts";
+import { renderInlineTitle } from "./inline-markdown.ts";
 
 interface Props {
   title: string;
@@ -11,7 +12,12 @@ interface Props {
 }
 
 const { defaultOpen = false, description, icon, id, title } = Astro.props;
+// The id still slugs the title as written, so existing deep links keep
+// working once its Markdown renders.
 const accordionId = id ?? componentSlug(title);
+// The title's inline Markdown (`The \`x\` option`), or undefined for a title
+// shown as written.
+const titleHtml = await renderInlineTitle(title);
 ---
 
 <details
@@ -34,7 +40,16 @@ const accordionId = id ?? componentSlug(title);
         )
       }
       <span>
-        <span class="block">{title}</span>
+        {
+          titleHtml === undefined ? (
+            <span class="block">{title}</span>
+          ) : (
+            <span
+              class="block [&_a]:underline [&_a]:decoration-current/50 [&_code]:font-mono"
+              set:html={titleHtml}
+            />
+          )
+        }
         {
           description && (
             <span class="block font-normal text-muted-foreground text-sm">

package/src/components/content/Callout.astro

@@ -6,6 +6,7 @@ import {
   admonitionType,
 } from "../colors.ts";
 import Icon from "../Icon.astro";
+import { renderInlineTitle } from "./inline-markdown.ts";
 
 interface Props {
   type?: AdmonitionType | "check";
@@ -17,6 +18,9 @@ interface Props {
 const { color, icon, type = "info", title } = Astro.props;
 // `check` is an alias of `success`; fold it once so the tables need one row.
 const kind = admonitionType(type);
+// The title's inline Markdown (a `:::note[Use **this**]` label passes its
+// formatting through as Markdown), or undefined for a title shown as written.
+const titleHtml = title ? await renderInlineTitle(title) : undefined;
 
 const variantClass: Record<AdmonitionType, string> = {
   danger: "border-red-500/25 bg-red-500/10",
@@ -50,7 +54,13 @@ const variantClass: Record<AdmonitionType, string> = {
       the unlayered prose rule): every child a small top margin, none on the
       first, and no trailing bottom margin. */}
   <div class="flex-1 [&>*]:mt-2! [&>*]:mb-0! [&>:first-child]:mt-0!">
-    {title && <p class="font-semibold text-foreground">{title}</p>}
+    {
+      titleHtml === undefined ? (
+        title && <p class="font-semibold text-foreground">{title}</p>
+      ) : (
+        <p class="font-semibold text-foreground" set:html={titleHtml} />
+      )
+    }
     <slot />
   </div>
 </aside>