blume 0.6.7 → 0.7.0

package/src/deploy/rss.ts

@@ -1,3 +1,4 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { PageRecord } from "../core/types.ts";
 import { escapeXml } from "./xml.ts";
@@ -52,6 +53,11 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     return [];
   }
   const base = site.replace(/\/$/u, "");
+  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
+  // The feed's own `link`/self URL points at the docs root under that base, while
+  // `path` stays base-less (it's also the on-disk output location).
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const rootLink = `${base}${deployBase}`;
 
   const feeds: RssFeed[] = [];
   for (const type of rss.types) {
@@ -70,7 +76,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
         description: page.description,
         // Encode like the sitemap does: a route with spaces or non-ASCII
         // must still yield a valid <link>/<guid> URL after XML decoding.
-        link: encodeURI(`${base}${page.route}`),
+        link: encodeURI(`${base}${withBasePath(deployBase, page.route)}`),
         title: page.title,
       }))
       .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0))
@@ -79,7 +85,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     feeds.push({
       description: config.description,
       items,
-      link: base,
+      link: rootLink,
       path: `/${type}/rss.xml`,
       title: `${config.title} — ${capitalize(type)}`,
       type,
@@ -105,11 +111,12 @@ const renderItem = (item: RssItem): string => {
 
 /** Serialize a resolved feed into an RSS 2.0 XML document. */
 export const renderRssFeed = (feed: RssFeed): string => {
+  const feedSelfHref = `${feed.link}${feed.path}`;
   const channel = [
     `  <title>${escapeXml(feed.title)}</title>`,
     `  <link>${escapeXml(feed.link)}</link>`,
     `  <description>${escapeXml(feed.description ?? feed.title)}</description>`,
-    `  <atom:link href="${escapeXml(`${feed.link}${feed.path}`)}" rel="self" type="application/rss+xml" />`,
+    `  <atom:link href="${escapeXml(feedSelfHref)}" rel="self" type="application/rss+xml" />`,
   ];
   const items = feed.items.map(renderItem).join("\n");
   return `<?xml version="1.0" encoding="UTF-8"?>

package/src/deploy/sitemap.ts

@@ -1,3 +1,4 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { escapeXml } from "./xml.ts";
 
@@ -24,20 +25,23 @@ export const buildSitemap = (project: BlumeProject): string | null => {
   }
 
   const base = site.replace(/\/$/u, "");
-  const urls = project.graph.pages
-    .filter(
-      (page) =>
-        !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)
-    )
+  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
+  const deployBase = normalizeBasePath(project.config.deployment.base);
+  const urls: string[] = [];
+  for (const page of project.graph.pages) {
+    if (page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex) {
+      continue;
+    }
     // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
     // then escape XML metacharacters (notably `&`) so a route like
     // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
     // rejected.
-    .map(
-      (page) =>
-        `  <url><loc>${escapeXml(encodeURI(`${base}${page.route}`))}</loc>${lastmodTag(page.lastModified)}</url>`
-    )
-    .toSorted();
+    const loc = escapeXml(
+      encodeURI(`${base}${withBasePath(deployBase, page.route)}`)
+    );
+    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(page.lastModified)}</url>`);
+  }
+  urls.sort();
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

package/src/markdown/base-links.ts

@@ -0,0 +1,58 @@
+import { isInternalPath, withBasePath } from "../core/base-path.ts";
+import type { MdastNode } from "./mdast.ts";
+
+interface UrlNode extends MdastNode {
+  url?: string | null;
+}
+
+/**
+ * The slice of Satteri's MDAST visitor context this plugin needs. Nodes are
+ * read-only (the tree compiles to an op-stream), so a URL edit is recorded via
+ * `setProperty`, not by mutating the node object.
+ */
+interface MdastUrlContext {
+  setProperty: (node: unknown, key: "url", value: string) => void;
+}
+
+/**
+ * A path whose final segment carries a file extension (`/spec.pdf`, `/logo.svg`)
+ * — treated as a public asset, which Blume serves from `public/` at the site
+ * root and does *not* move under `basePath`. Bare page links (`/guide`) have no
+ * extension. The rare dotted route (`/releases/v1.0`) is left un-based here; the
+ * build-time link checker still resolves it against the route set.
+ */
+const ASSET_PATH = /\.[a-z0-9]+$/iu;
+
+/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
+const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
+
+/**
+ * Satteri MDAST plugin that prepends the site-wide `basePath` to root-relative
+ * internal page links (`[x](/guide)` -> `/docs/guide`), so authors write links
+ * as if mounted at root. Idempotent (via `withBasePath`) and inert for external
+ * URLs, fragments, relative paths, images, and asset links. Only constructed
+ * when a base is set (see `markdown/index.ts`).
+ */
+export const baseLinksPlugin = (basePath: string) => {
+  const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
+    const { url } = node;
+    if (
+      typeof url === "string" &&
+      isInternalPath(url) &&
+      !ASSET_PATH.test(pathOf(url))
+    ) {
+      const next = withBasePath(basePath, url);
+      if (next !== url) {
+        ctx.setProperty(node, "url", next);
+      }
+    }
+  };
+  // `link` covers inline links; `definition` covers reference-style link
+  // definitions (`[x]: /guide`). `image` is intentionally excluded — images are
+  // public assets served at the site root, unaffected by `basePath`.
+  return {
+    definition: rebase,
+    link: rebase,
+    name: "blume-base-links",
+  };
+};

package/src/markdown/code-title.ts

@@ -37,6 +37,16 @@ const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
 const withoutQuotedAttrs = (raw: string): string =>
   raw.replace(QUOTED_ATTR, " ");
 
+// The first bare token is the title (```ts blume.config.ts): a non-empty token
+// that isn't a Shiki line range (`{1,3-5}`), a `key=value` attr, or a reserved
+// `lineNumbers`/`twoslash` keyword.
+const isTitleToken = (token: string): boolean => {
+  if (token.length === 0 || token.startsWith("{") || token.includes("=")) {
+    return false;
+  }
+  return token !== "lineNumbers" && token !== "twoslash";
+};
+
 const parseTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
     return undefined;
@@ -46,20 +56,7 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   if (attrTitle) {
     return attrTitle;
   }
-  // The first bare token is the title (```ts blume.config.ts), skipping Shiki
-  // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`
-  // and `twoslash` keywords.
-  return withoutQuotedAttrs(raw)
-    .trim()
-    .split(/\s+/u)
-    .find(
-      (token) =>
-        token.length > 0 &&
-        token !== "lineNumbers" &&
-        token !== "twoslash" &&
-        !token.startsWith("{") &&
-        !token.includes("=")
-    );
+  return withoutQuotedAttrs(raw).trim().split(/\s+/u).find(isTitleToken);
 };
 
 const hasLineNumbers = (raw: string | undefined): boolean =>

package/src/markdown/index.ts

@@ -8,6 +8,7 @@ import {
 } from "@shikijs/transformers";
 import { codeToHtml } from "shiki";
 
+import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
@@ -16,6 +17,8 @@ import { languageIconTransformer } from "./language-icon.ts";
 import { mathPlugin } from "./math.ts";
 import { mermaidPlugin } from "./mermaid.ts";
 import { packageInstallPlugin } from "./package-install.ts";
+import { DEFAULT_CODE_THEMES } from "./themes.ts";
+import type { CodeThemes } from "./themes.ts";
 
 /** A Shiki transformer, derived from the upstream factories' return type. */
 type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
@@ -54,7 +57,7 @@ type HastPlugin = NonNullable<
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
   const plugins: HastPlugin[] = [
-    inlineCodeHighlightPlugin() as unknown as HastPlugin,
+    inlineCodeHighlightPlugin(options.codeThemes) as unknown as HastPlugin,
   ];
   if (options.headingAnchors !== false) {
     plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
@@ -99,13 +102,6 @@ export const blumeShikiTransformers = (
   return transformers;
 };
 
-/**
- * The light/dark Shiki themes Blume highlights with. Kept in lockstep with the
- * generated Astro config's `shikiConfig.themes` so code highlighted outside the
- * Markdown pipeline (via {@link highlightCode}) matches fenced code exactly.
- */
-const CODE_THEMES = { dark: "github-dark", light: "github-light" } as const;
-
 const escapeHtml = (value: string): string =>
   value
     .replaceAll("&", "&amp;")
@@ -147,6 +143,11 @@ const languageAttrTransformer = (lang: string): ShikiTransformer =>
 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
+   * github pair fenced code uses, so out-of-pipeline code stays in lockstep.
+   */
+  themes?: CodeThemes;
   /** Header title (a filename), matching a fence's `title="..."` meta. */
   title?: string;
 }
@@ -176,7 +177,7 @@ export const highlightCode = async (
       meta: options.title
         ? { __raw: `title="${options.title.replaceAll('"', "")}"` }
         : undefined,
-      themes: CODE_THEMES,
+      themes: options.themes ?? DEFAULT_CODE_THEMES,
       transformers: [
         ...blumeShikiTransformers({ icons: options.icons }),
         astroCodeClassTransformer(options.className),
@@ -200,18 +201,41 @@ const FEATURES = { subscript: true, superscript: true };
 
 /** Options shared by both processors. */
 export interface BlumeMarkdownOptions {
+  /**
+   * Light/dark Shiki themes for inline `` `code`{:lang} `` highlighting
+   * (`markdown.codeBlocks.theme`). Defaults to the github pair fenced code uses.
+   */
+  codeThemes?: CodeThemes;
   /**
    * Wrap `<h2>`–`<h6>` in self-linking anchors (`markdown.headingAnchors`).
    * On unless explicitly `false`.
    */
   headingAnchors?: boolean;
+  /**
+   * Site-wide route mount point (`""` or `/seg`). When set, root-relative
+   * internal page links in content are rewritten under it, so authors write
+   * links as if mounted at root.
+   */
+  basePath?: string;
 }
 
+/**
+ * MDAST plugins that apply to both `.md` and `.mdx`. Currently just the
+ * base-path link rewrite, added only when a `basePath` is configured.
+ */
+const blumeSharedMdastPlugins = (
+  options: BlumeMarkdownOptions
+): MdastPlugin[] =>
+  options.basePath
+    ? [baseLinksPlugin(options.basePath) as unknown as MdastPlugin]
+    : [];
+
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
 export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
   satteri({
     features: { ...FEATURES },
     hastPlugins: blumeHastPlugins(options),
+    mdastPlugins: blumeSharedMdastPlugins(options),
   });
 
 export type BlumeMdxOptions = BlumeMarkdownOptions;
@@ -246,5 +270,6 @@ export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
       directiveToCalloutPlugin(),
       mermaidPlugin(),
       mathPlugin(),
+      ...blumeSharedMdastPlugins(options),
     ] as unknown as MdastPlugin[],
   });

package/src/markdown/inline-code.ts

@@ -12,6 +12,9 @@
  * added to the pipeline at all).
  */
 
+import { DEFAULT_CODE_THEMES } from "./themes.ts";
+import type { CodeThemes } from "./themes.ts";
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
@@ -72,7 +75,9 @@ const loadHighlighter = async (): Promise<InlineHighlighter> => {
 };
 
 /** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */
-export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
+export const inlineCodeHighlightPlugin = (
+  themes: CodeThemes = DEFAULT_CODE_THEMES
+): InlineCodePlugin => ({
   element: {
     filter: ["code"],
     async visit(node, ctx) {
@@ -90,7 +95,7 @@ export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
           defaultColor: false,
           lang: parsed.lang,
           structure: "inline",
-          themes: { dark: "github-dark", light: "github-light" },
+          themes,
         });
         return {
           children: root.children,

package/src/markdown/themes.ts

@@ -0,0 +1,24 @@
+/**
+ * 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
+ * single home for the github fallback used when nothing is configured.
+ */
+
+/**
+ * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * `interface`) so it keeps the implicit index signature Shiki's `themes`
+ * parameter (`Partial<Record<string, …>>`) expects.
+ */
+// oxlint-disable-next-line typescript/consistent-type-definitions -- interface loses the implicit index signature Shiki's `themes` param needs
+export type CodeThemes = {
+  dark: string;
+  light: string;
+};
+
+/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+export const DEFAULT_CODE_THEMES: CodeThemes = {
+  dark: "github-dark",
+  light: "github-light",
+};

package/src/openapi/model.ts

@@ -112,6 +112,7 @@ export const extractOperations = (
 ): { operations: ApiOperationRef[]; tags: ApiTagRef[] } => {
   const operations: ApiOperationRef[] = [];
   const tagOrder: string[] = [];
+  const tagsSeen = new Set<string>();
   const tagMeta = new Map(
     (document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""])
   );
@@ -129,7 +130,8 @@ export const extractOperations = (
       }
       const tag = operation.tags?.[0] ?? UNTAGGED;
       const tagSlug = slugify(tag) || "operations";
-      if (!tagOrder.includes(tag)) {
+      if (!tagsSeen.has(tag)) {
+        tagsSeen.add(tag);
         tagOrder.push(tag);
       }
       let key = operationKey(method, path, operation.operationId);

package/src/openapi/references.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { NavTab } from "../core/types.ts";
 
@@ -139,32 +140,55 @@ export const resolveReferences = (
 export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
   resolveReferences(config).map((ref) => ({
     label: ref.label,
-    path: ref.route,
+    // Blume-rendered operation pages flow through the content pipeline and are
+    // mounted under `basePath`, so their tab must be too. Scalar references are
+    // a single embedded page injected at the raw `route`, left root-anchored.
+    path:
+      ref.renderer === "blume"
+        ? withBasePath(config.basePath, ref.route)
+        : ref.route,
   }));
 
+/**
+ * Accept one resolved reference into the deduped Blume-rendered set, or return
+ * null to skip it. Mutates `seen`/`usedSlugs` so repeated routes/slugs collapse.
+ */
+const blumeReferenceOf = (
+  ref: ReferenceSource,
+  seen: Set<string>,
+  usedSlugs: Set<string>
+): ReferenceSource | null => {
+  if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+    return null;
+  }
+  if (seen.has(ref.route)) {
+    return null;
+  }
+  seen.add(ref.route);
+  // Distinct routes can slugify identically (`/api/v1` and `/api-v1` both
+  // yield `api-v1`). The slug keys the `blume:openapi` data module, so a
+  // collision would let one spec silently overwrite the other while the
+  // loser's pages still point at the shared key — disambiguate.
+  let { slug } = ref;
+  let n = 2;
+  while (usedSlugs.has(slug)) {
+    slug = `${ref.slug}-${n}`;
+    n += 1;
+  }
+  usedSlugs.add(slug);
+  return slug === ref.slug ? ref : { ...ref, slug };
+};
+
 /** Blume-rendered OpenAPI references, deduped by route (first wins). */
 export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
   const seen = new Set<string>();
   const usedSlugs = new Set<string>();
   const result: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
-    if (ref.kind !== "openapi" || ref.renderer !== "blume") {
-      continue;
-    }
-    if (seen.has(ref.route)) {
-      continue;
-    }
-    seen.add(ref.route);
-    // Distinct routes can slugify identically (`/api/v1` and `/api-v1` both
-    // yield `api-v1`). The slug keys the `blume:openapi` data module, so a
-    // collision would let one spec silently overwrite the other while the
-    // loser's pages still point at the shared key — disambiguate.
-    let { slug } = ref;
-    for (let n = 2; usedSlugs.has(slug); n += 1) {
-      slug = `${ref.slug}-${n}`;
+    const accepted = blumeReferenceOf(ref, seen, usedSlugs);
+    if (accepted) {
+      result.push(accepted);
     }
-    usedSlugs.add(slug);
-    result.push(slug === ref.slug ? ref : { ...ref, slug });
   }
   return result;
 };

package/src/openapi/render-mdx.ts

@@ -119,17 +119,22 @@ export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
       });
     }
   }
-  const tagSections = sections
-    .filter((tag) =>
-      operations.some((operation) => operation.tagSlug === tag.slug)
-    )
-    .map((tag) =>
+  const tagSections: string[] = [];
+  for (const tag of sections) {
+    if (!operations.some((operation) => operation.tagSlug === tag.slug)) {
+      continue;
+    }
+    const description = tag.description.trim()
+      ? [mdxSafe(tag.description.trim())]
+      : [];
+    tagSections.push(
       [
         `## ${mdxSafe(tag.name)}`,
-        ...(tag.description.trim() ? [mdxSafe(tag.description.trim())] : []),
+        ...description,
         `<ApiTagOperations source="${spec.slug}" tag="${tag.slug}" />`,
       ].join("\n\n")
     );
+  }
   return {
     body: [
       withDescription(

package/src/openapi/scalar.ts

@@ -87,6 +87,35 @@ const specConfiguration = async (
   }
 };
 
+/**
+ * Accept one resolved reference into the deduped Scalar set, or return null to
+ * skip it (recording a warning for a route collision). Mutates `seen`.
+ */
+const acceptScalarReference = (
+  ref: ReferenceSource,
+  seen: Set<string>,
+  contentRoutes: ReadonlySet<string>,
+  warnings: string[]
+): ReferenceSource | null => {
+  if (ref.renderer !== "scalar") {
+    return null;
+  }
+  if (seen.has(ref.route)) {
+    warnings.push(
+      `Two API reference sources resolve to ${ref.route}; keeping the first.`
+    );
+    return null;
+  }
+  if (contentRoutes.has(ref.route)) {
+    warnings.push(
+      `API reference route ${ref.route} collides with a content page; skipping the reference there.`
+    );
+    return null;
+  }
+  seen.add(ref.route);
+  return ref;
+};
+
 /**
  * Build the Scalar reference page(s) for the project. Only Scalar-rendered
  * references are emitted here (Blume-rendered OpenAPI is staged content). Reads
@@ -105,23 +134,10 @@ export const buildReferenceFiles = async (options: {
   const seen = new Set<string>();
   const accepted: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
-    if (ref.renderer !== "scalar") {
-      continue;
-    }
-    if (seen.has(ref.route)) {
-      warnings.push(
-        `Two API reference sources resolve to ${ref.route}; keeping the first.`
-      );
-      continue;
-    }
-    if (contentRoutes.has(ref.route)) {
-      warnings.push(
-        `API reference route ${ref.route} collides with a content page; skipping the reference there.`
-      );
-      continue;
+    const next = acceptScalarReference(ref, seen, contentRoutes, warnings);
+    if (next) {
+      accepted.push(next);
     }
-    seen.add(ref.route);
-    accepted.push(ref);
   }
 
   const built = await Promise.all(