blume 2.1.2 → 2.2.0

package/src/ai/relative-links.ts

@@ -12,11 +12,13 @@ import {
   buildFileRouteIndex,
   isIndexFileName,
   resolveRelativeHref,
+  resolveRootFileHref,
   routeOfLinkedFile,
 } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
 import { localizeHref, servesRoute } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { resolveDocsCollection } from "../core/sources/collection.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
 
 /**
@@ -33,7 +35,9 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * `basePath` prefix, a public file (`/spec.pdf`) or image the
  * `deployment.base` alone, and, on a page in a prefixed locale, a page link
  * that locale's copy of the route when it is served
- * (`components/layout/LocaleLinks.astro`). Inline links, images, component
+ * (`components/layout/LocaleLinks.astro`). A root-relative link to a content
+ * file (`/guide/new.md`) lands on that file's page, as on the rendered page
+ * (`resolveRootFileHref`). Inline links, images, component
  * `href`s, and reference definitions are rewritten; fenced and inline code,
  * relative images and asset links, and external URLs are left as written.
  */
@@ -64,6 +68,13 @@ const MAYBE_RELATIVE =
 const MAYBE_PAGE_LINK =
   /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/\/|#)/imu;
 
+/**
+ * Whether a text could hold a root-relative link to a Markdown file
+ * (`[x](/guide/new.md)`), which lands on that file's page whatever the base.
+ */
+const MAYBE_ROOT_FILE =
+  /(?:\]\(|\]:|\shref=["'])[\t ]*<?\/(?!\/)[^\s"'()<>]*\.mdx?\b/imu;
+
 interface Splice {
   column: number;
   length: number;
@@ -85,11 +96,12 @@ const spliceLine = (line: string, splices: readonly Splice[]): string => {
 /**
  * Every routed splice in `text`, by 0-based line: links, images, and
  * reference definitions, as `extractLinks` finds them. An image target goes
- * through `imaged`, everything else through `routed`.
+ * through `imaged`, everything else through `routed`, told whether it's a
+ * raw HTML element's.
  */
 const collectSplices = (
   text: string,
-  routed: (target: string) => string | undefined,
+  routed: (target: string, raw: boolean) => string | undefined,
   imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
   const splices = new Map<number, Splice[]>();
@@ -97,11 +109,13 @@ const collectSplices = (
     splices.set(index, [...(splices.get(index) ?? []), splice]);
   };
   for (const link of extractLinks(text)) {
-    const route = (link.image ? imaged : routed)(link.target);
+    const route = link.image
+      ? imaged(link.target)
+      : routed(link.target, link.raw === true);
     if (route !== undefined) {
       add(link.line - 1, {
         column: link.column - 1,
-        length: link.target.length,
+        length: link.sourceLength ?? link.target.length,
         text: route,
       });
     }
@@ -120,6 +134,10 @@ export const relativeLinkRewriter = (
 ): RelativeLinkRewriter => {
   const { basePath, deployment, i18n } = project.config;
   const deployBase = normalizeBasePath(deployment.options.base);
+  const contentRoot = resolveDocsCollection(
+    project.config,
+    project.context.root
+  ).base;
   const localeTokens = i18n
     ? ["$", ...i18n.locales.map((locale) => locale.code)]
     : [];
@@ -179,7 +197,10 @@ export const relativeLinkRewriter = (
       deployBase !== "" || basePath !== "" || localize !== undefined;
     if (
       !(page.sourcePath || rootLinks) ||
-      !(rootLinks ? MAYBE_PAGE_LINK : MAYBE_RELATIVE).test(text)
+      !(
+        (rootLinks ? MAYBE_PAGE_LINK : MAYBE_RELATIVE).test(text) ||
+        MAYBE_ROOT_FILE.test(text)
+      )
     ) {
       return text;
     }
@@ -197,8 +218,27 @@ export const relativeLinkRewriter = (
       const href = localize ? localizeHref(based, localize) : based;
       return href === target ? undefined : href;
     };
-    const routed = (target: string): string | undefined =>
-      isInternalPath(target) ? rooted(target) : relative?.(target);
+    // A root-relative link naming a content file (`/guide/new.md`) means
+    // that file's page, as a relative one does; a raw `<a href>` keeps it,
+    // as the rendered page's does.
+    const rootFile = (target: string): string | undefined => {
+      const route = resolveRootFileHref(target, {
+        contentRoot,
+        deployBase,
+        routeOfFile: (file) => fileRoutes.bySource.get(file),
+      });
+      if (route === undefined) {
+        return undefined;
+      }
+      const based = mountBasePath(deployBase, route);
+      return localize ? localizeHref(based, localize) : based;
+    };
+    const routed = (target: string, raw: boolean): string | undefined => {
+      if (!isInternalPath(target)) {
+        return relative?.(target);
+      }
+      return (raw ? undefined : rootFile(target)) ?? rooted(target);
+    };
     // An image is always a file: `public/` (or a generated asset endpoint),
     // served under the deployment base but never `basePath`. A relative one
     // is left to `core/content-assets.ts`.

package/src/ai/serializers.ts

@@ -1,5 +1,6 @@
 import type { BlumeProject } from "../core/project-graph.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
+import { changelogComponentSerializers } from "./changelog-components.ts";
 import type { ComponentMarkdown } from "./component-markdown.ts";
 import { exampleComponentSerializers } from "./component-markdown.ts";
 import { openapiComponentSerializers } from "./openapi-components.ts";
@@ -8,18 +9,18 @@ import { openapiComponentSerializers } from "./openapi-components.ts";
  * Every serializer a project brings to a downlevel pass, layered once for all
  * the agent surfaces (`<route>.md`, llms-full.txt, the search and assistant
  * corpora): the built-in families that read project data — examples, then the
- * API reference — under the user's `agents.markdownComponents`, which is spread
- * last so an entry of the same name still wins. One layering, so a new family
- * or a new surface cannot leave one consumer printing raw JSX.
+ * API reference, then the changelog index — under the user's
+ * `agents.markdownComponents`, which is spread last so an entry of the same
+ * name still wins. One layering, so a new family or a new surface cannot leave
+ * one consumer printing raw JSX.
  */
-export const projectComponentSerializers = (
-  project: Pick<BlumeProject, "config" | "examples" | "sources">
-) =>
+export const projectComponentSerializers = (project: BlumeProject) =>
   ({
     ...exampleComponentSerializers(project.examples ?? {}),
     ...openapiComponentSerializers(
       project.sources.find(isOpenApiSource)?.openApiData() ?? {},
       project.config.deployment.options.base
     ),
+    ...changelogComponentSerializers(project),
     ...project.config.agents.markdownComponents,
   }) satisfies Record<string, ComponentMarkdown>;

package/src/ai/site-skill.ts

@@ -6,6 +6,8 @@ import {
 } from "../core/base-path.ts";
 import { CHANGELOG_INDEX_ROUTE } from "../core/changelog-index.ts";
 import { discoverPagesSync } from "../core/custom-pages.ts";
+import { isHiddenPage } from "../core/hidden-pages.ts";
+import { metaDescription } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
 import type { NavNode, PageRecord } from "../core/types.ts";
@@ -67,7 +69,7 @@ const mappedPages = (project: BlumeProject): PageRecord[] => {
       !(
         page.meta.ai.exclude ||
         page.meta.draft ||
-        page.meta.sidebar.hidden ||
+        isHiddenPage(page, project.graph) ||
         page.meta.seo.noindex ||
         page.version !== "" ||
         page.source.name === "openapi" ||
@@ -104,7 +106,9 @@ class PageMap {
       return [];
     }
     this.#listed.add(route);
-    const summary = page.description ? `: ${page.description}` : "";
+    // As `llms.txt` lists it: the page's meta description.
+    const description = metaDescription(page);
+    const summary = description ? `: ${description}` : "";
     return [`- [${linkText(page.title)}](${this.#url(route)})${summary}`];
   }
 

package/src/analytics/head.ts

@@ -50,7 +50,8 @@ export type HeadNode =
  */
 // oxlint-disable-next-line complexity -- each adapter has one exhaustive, type-narrowed dispatch case
 const adapterScripts = (
-  adapter: Exclude<AnalyticsAdapter, { kind: "vercel" }>
+  adapter: Exclude<AnalyticsAdapter, { kind: "vercel" }>,
+  base: string
 ): HeadScript[] => {
   switch (adapter.kind) {
     case "adobe": {
@@ -114,7 +115,7 @@ const adapterScripts = (
       return segmentHead(adapter.options);
     }
     default: {
-      return scriptHead(adapter.options);
+      return scriptHead(adapter.options, base);
     }
   }
 };
@@ -122,9 +123,14 @@ const adapterScripts = (
 /**
  * Map the configured adapters to what `Analytics.astro` renders, in declared
  * order. A second `vercel()` is dropped — two copies of the component would
- * count every pageview twice — so the first one keeps its position.
+ * count every pageview twice — so the first one keeps its position. `base` is
+ * the deployment base a `script()` adapter's root-relative `src` is served
+ * under.
  */
-export const analyticsHead = (adapters: AnalyticsAdapter[]): HeadNode[] => {
+export const analyticsHead = (
+  adapters: AnalyticsAdapter[],
+  base = "/"
+): HeadNode[] => {
   const nodes: HeadNode[] = [];
   let hasVercel = false;
   for (const adapter of adapters) {
@@ -134,7 +140,7 @@ export const analyticsHead = (adapters: AnalyticsAdapter[]): HeadNode[] => {
         nodes.push({ props: adapter.options, type: "vercel" });
       }
     } else {
-      for (const tag of adapterScripts(adapter)) {
+      for (const tag of adapterScripts(adapter, base)) {
         nodes.push({ ...tag, type: "script" });
       }
     }

package/src/analytics/script.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import type { AdapterDescriptor } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { HeadScript } from "./head.ts";
 
 /** Options for {@link script}; set exactly one of `src` or `content`. */
@@ -46,8 +47,17 @@ export const script = (options: ScriptOptions): ScriptAdapter => ({
   runtimeDeps: [],
 });
 
-/** The tag. Explicit `src`/`strategy` win over a same-named spread attribute. */
-export const scriptHead = (options: ScriptOptions): HeadScript[] => {
+/**
+ * The tag. Explicit `src`/`strategy` win over a same-named spread attribute.
+ * A root-relative `src` (`/js/x.js`, a file in `public/`) is served under the
+ * deployment `base`, so it gets the base the way a link does; one already
+ * under it is left alone, and absolute and protocol-relative URLs pass
+ * through.
+ */
+export const scriptHead = (
+  options: ScriptOptions,
+  base: string
+): HeadScript[] => {
   const attributes: HeadScript["attributes"] = { ...options.attributes };
   if (!options.src) {
     return [{ attributes, content: options.content ?? "" }];
@@ -55,6 +65,6 @@ export const scriptHead = (options: ScriptOptions): HeadScript[] => {
   if (options.strategy) {
     attributes[options.strategy] = true;
   }
-  attributes.src = options.src;
+  attributes.src = withBasePath(normalizeBasePath(base), options.src);
   return [{ attributes, content: null }];
 };

package/src/astro/generate.ts

@@ -37,6 +37,7 @@ import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import { withChangelogIndexText } from "../core/changelog-index.ts";
 import {
   missingExampleDiagnostics,
+  unknownPropDiagnostics,
   validateUsedComponents,
 } from "../core/component-diagnostics.ts";
 import {
@@ -46,7 +47,7 @@ import {
 import type { ComponentOverrideAnalysis } from "../core/component-overrides.ts";
 import {
   collectContentAssets,
-  rewriteRelativeImages,
+  rewriteRelativeAssets,
 } from "../core/content-assets.ts";
 import type {
   BlumeBanner,
@@ -55,8 +56,13 @@ import type {
   BlumeFavicon,
   BlumeLogo,
 } from "../core/data.ts";
-import { BlumeError } from "../core/diagnostics.ts";
+import {
+  BlumeError,
+  enrichDiagnostic,
+  formatDiagnostic,
+} from "../core/diagnostics.ts";
 import { writeTextAtomic } from "../core/fs-atomic.ts";
+import { gitIgnoredPaths } from "../core/git-ignored.ts";
 import {
   apiUrl as githubApiUrl,
   editBaseUrl as githubEditBaseUrl,
@@ -79,6 +85,7 @@ import { trimChar } from "../core/trim.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Diagnostic, Navigation } from "../core/types.ts";
 import { getBlumeVersion } from "../core/version.ts";
+import { servedFiles } from "../deploy/generated-files.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import {
   languageIconCss,
@@ -697,7 +704,7 @@ export const collectStaged = (project: BlumeProject): Map<string, string> => {
       // Point it at the served original instead — the same rewrite the
       // agent-facing Markdown gets.
       const text = page.sourcePath
-        ? rewriteRelativeImages({
+        ? rewriteRelativeAssets({
             deployBase: project.config.deployment.options.base,
             projectRoot: project.context.root,
             source: page.body.text,
@@ -1120,9 +1127,22 @@ export const buildRuntimeData = (project: BlumeProject): string => {
   const editBase = github ? githubEditBaseUrl(github) : null;
   const logo = resolveLogo(project);
   const ogLogo = resolveOgMark(project, logo?.svg);
+  // Files git ignores (a generated reference in a gitignored folder) are
+  // never in the repository, so an edit link would 404. One git call covers
+  // every page an edit link is built for.
+  const ignored = editBase
+    ? gitIgnoredPaths(
+        context.root,
+        manifest.routes.flatMap((route) =>
+          route.editUrl === undefined && route.sourcePath
+            ? [route.sourcePath]
+            : []
+        )
+      )
+    : new Set<string>();
 
   const editUrlFor = (sourcePath?: string): string | null => {
-    if (!(editBase && sourcePath)) {
+    if (!(editBase && sourcePath) || ignored.has(sourcePath)) {
       return null;
     }
     const rel = relative(context.root, sourcePath).split("\\").join("/");
@@ -2194,6 +2214,7 @@ export const generateRuntime = async (
           context,
           filesystem: hasFilesystemSource,
           staged: hasStaged,
+          unparsable: project.unparsable,
         })
       ),
       write(
@@ -2308,7 +2329,6 @@ export const generateRuntime = async (
         exportEpub,
         exportPdf,
         needsReact,
-        staged: hasStaged,
       })
     );
   }
@@ -2425,7 +2445,8 @@ export const generateRuntime = async (
     ...[
       ...validateNavTargets(
         project.graph.navigation,
-        navTargetRoutes(project, pages)
+        navTargetRoutes(project, pages),
+        servedFiles(project)
       ),
       ...validateSearchPopularIcons(config.search.popular),
     ].map(diagnosticWarning)
@@ -2449,6 +2470,11 @@ export const generateRuntime = async (
       context.root,
       knownComponentTags
     ).map(diagnosticWarning),
+    // Printed whole, like a scan diagnostic, so the line it names shows.
+    ...unknownPropDiagnostics(project.graph.pages, knownComponentTags).map(
+      (diagnostic) =>
+        formatDiagnostic(enrichDiagnostic(diagnostic), context.root)
+    ),
     ...dependencyWarnings
   );
   if (hasScalarReferences(config)) {

package/src/astro/index.ts

@@ -2,6 +2,7 @@ export { withAdapterRoot } from "./adapter-root.ts";
 export { generateRuntime, prerenderDepsPlugin } from "./generate.ts";
 export { includeHmrPlugin } from "./include-hmr.ts";
 export { withIncludeRefresh } from "./include-refresh.ts";
+export { mdxSourceErrorsPlugin } from "./mdx-source-errors.ts";
 export { variablesVitePlugin } from "./variables.ts";
 export type { GenerateResult } from "./generate.ts";
 export {

package/src/astro/integration.ts

@@ -1,10 +1,12 @@
+import { Server } from "node:http";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { fileURLToPath } from "node:url";
 
-import type { AstroIntegration } from "astro";
+import type { AstroConfig, AstroIntegration } from "astro";
 import { join, relative, resolve } from "pathe";
 
 import { loadEnvFiles } from "../cli/env.ts";
+import { normalizeBasePath } from "../core/base-path.ts";
 import type { CustomPageRoute } from "../core/custom-pages.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
 import { POWERED_BY_HEADERS } from "../core/powered-by.ts";
@@ -15,6 +17,11 @@ import {
   requestPath,
 } from "../core/redirect-patterns.ts";
 import type { CompiledRedirect } from "../core/redirect-patterns.ts";
+import {
+  answerRequestsFirst,
+  publicFolder,
+  trailingSlashAnswer,
+} from "../core/static-host.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { publishBuildArtifacts } from "../deploy/artifacts.ts";
 import type { ArtifactLogger } from "../deploy/artifacts.ts";
@@ -492,6 +499,9 @@ export const blumeIntegration = (
   // The Astro root, kept for the build-artifacts scan: `astro:build:done`
   // receives no config.
   let astroRoot: URL | null = null;
+  // What the dev server's trailing-slash handling needs from the config
+  // (see `core/static-host.ts`): the base the URLs carry, and `public/`.
+  let staticHost: Pick<AstroConfig, "base" | "publicDir"> | null = null;
   return {
     hooks: {
       "astro:build:done": async ({ dir, logger }) => {
@@ -511,6 +521,7 @@ export const blumeIntegration = (
       },
       "astro:config:done": ({ config, injectTypes }) => {
         astroRoot = config.root;
+        staticHost = config;
         const from = fileURLToPath(
           codegenDir ?? defaultCodegenDir(config.root)
         );
@@ -587,6 +598,21 @@ export const blumeIntegration = (
             route: "",
           });
         }
+        // A trailing slash is answered the way a static host answers it,
+        // ahead of Astro's own middleware, which would 404 it (see
+        // `core/static-host.ts`). They're unshifted after this hook runs,
+        // so this goes on the HTTP server instead.
+        if (staticHost && server.httpServer instanceof Server) {
+          const base = normalizeBasePath(staticHost.base);
+          const isPublicFolder = publicFolder(
+            fileURLToPath(staticHost.publicDir)
+          );
+          answerRequestsFirst(
+            server.httpServer,
+            (request) => trailingSlashAnswer(request, base, isPublicFolder),
+            options.poweredBy === false ? {} : POWERED_BY_HEADERS
+          );
+        }
       },
     },
     name: "blume",

package/src/astro/mdx-source-errors.ts

@@ -0,0 +1,46 @@
+/**
+ * A Vite plugin that names an `.mdx` page's file on an error the page throws
+ * while it renders. A `{…}` expression that reads a name nothing defines
+ * (`{user.name}`, or `{{version}}` on a site without that variable) compiles,
+ * then throws a `ReferenceError` from inside the page's module, and Astro pins
+ * it on the route that rendered it: the catch-all every page shares. Setting
+ * the error's `id`, as Vite does for a module that fails, points it at the
+ * page's file instead, so the build report can find the expression (see
+ * `cli/build-failure.ts`) and the dev overlay shows the page.
+ *
+ * It runs after `@astrojs/mdx` and wraps the module's `MDXContent`, the
+ * function the compiler emits for the body and Astro's `Content` export calls
+ * by name. A module without one is left alone.
+ */
+
+/** The Vite plugin slice this needs (structurally typed, like Blume's other plugins). */
+export interface MdxSourceErrorsPlugin {
+  enforce: "post";
+  name: string;
+  transform: (code: string, id: string) => { code: string; map: null } | null;
+}
+
+const MDX_CONTENT = /^\s*function MDXContent\(/mu;
+
+/** The statement that wraps `MDXContent` so its errors carry `id`. */
+const wrapContent = (id: string): string => `
+MDXContent = ((render, id) => function MDXContent(props) {
+  try {
+    return render(props);
+  } catch (error) {
+    if (error instanceof Error && !("id" in error)) error.id = id;
+    throw error;
+  }
+})(MDXContent, ${JSON.stringify(id)});`;
+
+export const mdxSourceErrorsPlugin = (): MdxSourceErrorsPlugin => ({
+  enforce: "post",
+  name: "blume:mdx-source-errors",
+  // A query (`?astroPropagatedAssets`) marks another module made from the
+  // same file, which holds no body.
+  transform(code, id) {
+    return id.endsWith(".mdx") && MDX_CONTENT.test(code)
+      ? { code: code + wrapContent(id), map: null }
+      : null;
+  },
+});