blume 0.6.0 → 0.6.1

package/src/core/config.ts

@@ -1,16 +1,139 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
 import { findConfigFile } from "./project.ts";
 import { blumeConfigSchema } from "./schema.ts";
-import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { ResolvedConfig } from "./schema.ts";
 import type { Diagnostic } from "./types.ts";
 
 /**
- * Identity helper for authoring `blume.config.ts`. Exists for type inference
- * and a stable future home for plugin hooks; it does not transform input.
+ * Define a Blume site's configuration with full type-checking and editor
+ * autocomplete. Place the call in `blume.config.ts` at your project root and
+ * `export default` the result:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ *
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Everything you need to build with Acme.",
+ * });
+ * ```
+ *
+ * Every field is optional — an empty `defineConfig({})` produces a working
+ * site from the Markdown/MDX in your `docs/` directory. Configure only what you
+ * want to change; sensible defaults fill in the rest.
+ *
+ * This is an identity helper: it returns its input unchanged and exists purely
+ * for type inference (and as a stable home for future plugin hooks). The object
+ * is validated against the Blume schema when the CLI loads it.
+ *
+ * ## Top-level fields
+ *
+ * **Site identity**
+ * - `title` — site title, shown in the header, `<title>`, and OG images.
+ *   Defaults to `"Documentation"`.
+ * - `description` — default meta description, used where a page sets none.
+ * - `logo` — brand mark. A string is an image path/URL; the object form splits
+ *   an `image` mark from wordmark `text` and can override the brand `href`.
+ * - `banner` — site-wide announcement bar; a string, or `{ content, link,
+ *   dismissible }`.
+ *
+ * **Content & navigation**
+ * - `content` — where content lives (`root`, defaults to `docs`) and pluggable
+ *   `sources` (filesystem, remote MDX, GitHub Releases, Sanity, Notion, or a
+ *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
+ *   implicit filesystem source.
+ * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
+ *   switchers), pinned `featured` links, and the `repo` link toggle. Omit
+ *   `sidebar` to generate it from the content tree.
+ * - `redirects` — `{ from, to, status }` rules (301 by default).
+ * - `github` — `{ owner, repo, branch, dir }`, powering "Edit this page" links
+ *   and the header repo link.
+ *
+ * **Appearance**
+ * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
+ *   `mode` (`system`/`light`/`dark`), `background`, and `strict` token mode.
+ * - `markdown` — `code` (language icons, inline highlighting, line wrap),
+ *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
+ * - `toc` — on-page table of contents; `true`/`false` or a heading-level range.
+ * - `lastModified` — "Last updated" stamps from `git` history or frontmatter.
+ * - `feedback` — the per-page "Was this helpful?" widget (on by default).
+ * - `export` — reader-facing PDF/EPUB export actions (off by default).
+ *
+ * **Reference docs**
+ * - `openapi` — native OpenAPI reference: one real page per operation, woven
+ *   into the sidebar and search. Point `sources`/`spec` at your spec.
+ * - `asyncapi` — AsyncAPI reference via the embedded Scalar renderer.
+ *
+ * **Search & AI**
+ * - `search` — search backend `provider` (`orama` by default; `pagefind`,
+ *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
+ *   credential block.
+ * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model) and `llmsTxt`
+ *   (emit `llms.txt`).
+ * - `mcp` — expose the docs as an MCP server for connecting agents.
+ *
+ * **SEO, feeds & analytics**
+ * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`
+ *   JSON-LD, `agentReadability`, and robots `contentSignals`.
+ * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
+ *   GA, …).
+ *
+ * **Deployment & i18n**
+ * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
+ *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`
+ *   (`static`/`server`), and `base` path. Auto-detected on Vercel/Netlify/
+ *   Cloudflare from the platform env.
+ * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
+ *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
+ *
+ * - `examples` — where `<Component path>` previews resolve their source from
+ *   (defaults to `examples/`; supports a glob for colocated registries).
+ *
+ * @example Zero-config — just render the Markdown under `docs/`.
+ * ```ts
+ * export default defineConfig({});
+ * ```
+ *
+ * @example A production docs site with theming, search, and deployment.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Build faster with Acme.",
+ *   logo: { image: "/logo.svg", text: "Acme" },
+ *   github: { owner: "acme", repo: "acme" },
+ *   theme: { accent: "violet", fonts: { body: "inter" }, radius: "lg" },
+ *   navigation: {
+ *     tabs: [
+ *       { label: "Guides", path: "/guides" },
+ *       { label: "API", path: "/api" },
+ *     ],
+ *   },
+ *   search: { provider: "orama" },
+ *   deployment: { site: "https://docs.acme.com", adapter: "vercel" },
+ * });
+ * ```
+ *
+ * @example An OpenAPI reference with the Ask AI assistant enabled.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme API",
+ *   openapi: {
+ *     enabled: true,
+ *     route: "/reference",
+ *     sources: [{ label: "Core", spec: "./openapi.json" }],
+ *   },
+ *   ai: { ask: { enabled: true }, llmsTxt: true },
+ * });
+ * ```
+ *
+ * @param config - The site configuration. All fields are optional.
+ * @returns The same config object, typed for inference.
+ * @see https://useblume.dev/docs for the full configuration reference.
  */
 export const defineConfig = (config: BlumeConfig): BlumeConfig => config;
 

package/src/core/schema.ts

@@ -925,12 +925,6 @@ const codeConfigSchema = z
      * …). On by default; recognized languages only.
      */
     icons: z.boolean().default(true),
-    /**
-     * Syntax-highlight inline `` `code{:lang}` `` snippets. Off by default — most
-     * inline code (flags, file names) reads better plain; opt a snippet in with
-     * a trailing `{:lang}` marker.
-     */
-    inline: z.boolean().default(false),
     /**
      * Wrap long lines instead of scrolling horizontally. Off by default, so
      * code keeps its original line breaks and overflows into a scroll area.
@@ -955,11 +949,6 @@ const markdownConfigSchema = z
      * opt a single image out with `data-no-zoom`.
      */
     imageZoom: z.boolean().default(true),
-    /**
-     * Enable LaTeX math (`$…$` inline, `$$…$$` block) rendered with KaTeX.
-     * Off by default since `$` is common in prose, shell, and code. MDX only.
-     */
-    math: z.boolean().default(false),
   })
   .strict();
 
@@ -1097,8 +1086,12 @@ export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */
 export type LocaleConfig = z.infer<typeof localeSchema>;
-/** User-authored config: the shape accepted by `defineConfig`. */
-export type BlumeConfig = z.input<typeof blumeConfigSchema>;
+/**
+ * User-authored config, straight off the schema. The public, hand-documented
+ * authoring type is `BlumeConfig` in `./config-input.ts`, which a compile-time
+ * guard keeps structurally identical to this.
+ */
+export type BlumeConfigInput = z.input<typeof blumeConfigSchema>;
 /** A configured search backend. */
 export type SearchProvider = (typeof searchProviders)[number];
 /** Resolved robots.txt `Content-Signal` preferences (`null` when disabled). */

package/src/deploy/adapter-output.ts

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
+
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { ProjectContext } from "../core/types.ts";
+
+type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+/**
+ * Server adapters whose deploy bundle lands *outside* Astro's `outDir`, at a
+ * path relative to the Astro project root. Blume points the Astro root at the
+ * hidden `<root>/.blume` runtime, so these adapters write their bundle to
+ * `<root>/.blume/<path>` — where the deploy platform never looks. Each value is
+ * the sub-path to surface up to the real project root.
+ *
+ * `vercel` writes a Build Output API v3 tree at `.vercel/output`; only that
+ * subtree is moved, so a `vercel pull`-ed `.vercel/project.json` sitting at the
+ * project root survives the relocation. `netlify` owns its whole `.netlify`
+ * dir. `node` and `cloudflare` emit into `dist/` (already at the project root),
+ * so they are absent here and need no relocation.
+ */
+export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
+  netlify: ".netlify",
+  vercel: ".vercel/output",
+};
+
+/**
+ * Directory whose contents the deploy platform serves as static files. Build
+ * artifacts (robots.txt, sitemap.xml, llms.txt, …) must be written here to be
+ * served. For a Vercel server build that is the adapter's
+ * `.vercel/output/static`; every other build serves `dist/`.
+ */
+export const deployStaticDir = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): string => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join(context.root, ".vercel", "output", "static");
+  }
+  return context.distDir ?? join(context.root, "dist");
+};
+
+/** Outcome of {@link surfaceAdapterOutput}, for logging and `.gitignore`. */
+export type SurfaceResult =
+  | { moved: false }
+  | { from: string; ignore: string; moved: true; to: string };
+
+/**
+ * Move a server adapter's deploy bundle out of the hidden `.blume` runtime and
+ * up to the project root, where the deploy platform (and `vercel deploy
+ * --prebuilt`) expects it. A no-op for static builds, for adapters that emit
+ * into `dist/`, and when the expected output is absent.
+ */
+export const surfaceAdapterOutput = async (
+  config: ResolvedConfig,
+  context: ProjectContext
+): Promise<SurfaceResult> => {
+  const { adapter, output } = config.deployment;
+  if (output !== "server" || !adapter) {
+    return { moved: false };
+  }
+  const rel = ADAPTER_OUTPUT_PATHS[adapter];
+  if (!rel) {
+    return { moved: false };
+  }
+  const from = join(context.outDir, rel);
+  const to = join(context.root, rel);
+  if (!existsSync(from)) {
+    return { moved: false };
+  }
+  await mkdir(dirname(to), { recursive: true });
+  await rm(to, { force: true, recursive: true });
+  await cp(from, to, { recursive: true });
+  await rm(from, { force: true, recursive: true });
+  // The `.gitignore` entry is the surfaced top-level dir (`.vercel`/`.netlify`),
+  // never the moved sub-path — Vercel's own `.vercel/project.json` lives there
+  // too and must also be ignored.
+  return { from, ignore: `${rel.split("/")[0]}/`, moved: true, to };
+};

package/src/index.ts

@@ -22,8 +22,8 @@ export type {
   FolderMetaFactory,
 } from "./core/define-meta.ts";
 export type { UIStrings } from "./core/i18n-ui.ts";
+export type { BlumeConfig } from "./core/config-input.ts";
 export type {
-  BlumeConfig,
   FolderMeta,
   HydrationMode,
   ResolvedConfig,

package/src/markdown/index.ts

@@ -46,15 +46,16 @@ type HastPlugin = NonNullable<
 
 /**
  * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
- * opt-in; self-linking heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to
- * their own id) are on unless `markdown.headingAnchors` is `false`. Inline code
- * runs first so the anchor wrap re-refs already-highlighted code.
+ * always on: it only fires on an explicit trailing `{:lang}` marker, so plain
+ * inline code is untouched and there's nothing to opt out of. Self-linking
+ * heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to their own id) are on
+ * unless `markdown.headingAnchors` is `false`. Inline code runs first so the
+ * anchor wrap re-refs already-highlighted code.
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
-  const plugins: HastPlugin[] = [];
-  if (options.inline) {
-    plugins.push(inlineCodeHighlightPlugin() as unknown as HastPlugin);
-  }
+  const plugins: HastPlugin[] = [
+    inlineCodeHighlightPlugin() as unknown as HastPlugin,
+  ];
   if (options.headingAnchors !== false) {
     plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
   }
@@ -204,8 +205,6 @@ export interface BlumeMarkdownOptions {
    * On unless explicitly `false`.
    */
   headingAnchors?: boolean;
-  /** Highlight inline `` `code`{:lang} `` snippets (`markdown.code.inline`). */
-  inline?: boolean;
 }
 
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
@@ -215,38 +214,37 @@ export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
     hastPlugins: blumeHastPlugins(options),
   });
 
-export interface BlumeMdxOptions extends BlumeMarkdownOptions {
-  /** Enable KaTeX math parsing and rendering. */
-  math?: boolean;
-}
+export type BlumeMdxOptions = BlumeMarkdownOptions;
 
 /**
  * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
  * components — `package-install` → package-manager tabs, `:::note` →
- * `<Callout>`, and ` ```mermaid ` → a `<blume-mermaid>` element. Used as the
- * `processor` for `@astrojs/mdx` so these apply to
- * `.mdx` only (plain `.md` uses {@link blumeMarkdownProcessor}). Math is opt-in
- * via config since `$` is common in prose and code.
+ * `<Callout>`, ` ```mermaid ` → a `<blume-mermaid>` element, and block math
+ * (`$$…$$`) → the `<Math>` component. Used as the `processor` for
+ * `@astrojs/mdx` so these apply to `.mdx` only (plain `.md` uses
+ * {@link blumeMarkdownProcessor}).
+ *
+ * Math is always on but block-only: `singleDollarTextMath: false` keeps a bare
+ * `$` (currency, shell, code) as literal text and only parses `$$…$$`. The
+ * generated runtime imports the `<Math>` component (and KaTeX's stylesheet) only
+ * when content actually uses `$$`, so a math-free site ships no KaTeX CSS.
  *
  * The plugins are modeled with minimal structural types; bridge them to
  * Satteri's full `MdastPlugin` type at this single boundary.
  */
-export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) => {
-  const plugins: unknown[] = [
-    packageInstallPlugin(),
-    directiveToCalloutPlugin(),
-    mermaidPlugin(),
-  ];
-  if (options.math) {
-    plugins.push(mathPlugin());
-  }
-  return satteri({
+export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
+  satteri({
     features: {
       ...FEATURES,
       directive: true,
-      ...(options.math ? { math: true } : {}),
+      // Block-only: `$$…$$` parses, a bare `$` stays literal text.
+      math: { singleDollarTextMath: false },
     },
     hastPlugins: blumeHastPlugins(options),
-    mdastPlugins: plugins as unknown as MdastPlugin[],
+    mdastPlugins: [
+      packageInstallPlugin(),
+      directiveToCalloutPlugin(),
+      mermaidPlugin(),
+      mathPlugin(),
+    ] as unknown as MdastPlugin[],
   });
-};

package/src/markdown/math.ts

@@ -8,8 +8,9 @@ interface MathNode extends MdastNode {
 /**
  * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
  * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
- * block element; inline math (`$…$`) stays inline. Only active when math is
- * enabled in config, so `$` is otherwise left as literal text.
+ * block element. Blume runs the parser block-only (`singleDollarTextMath:
+ * false`), so a bare `$` stays literal and no `inlineMath` nodes are produced;
+ * the `inlineMath` visitor remains as a harmless safety net.
  */
 export const mathPlugin = () => ({
   inlineMath(node: MathNode, ctx: MdastVisitorContext) {

package/src/registry/eject.ts

@@ -12,6 +12,7 @@ import {
   buildRuntimeData,
   collectStaged,
   detectNeedsReact,
+  detectUsesMath,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
@@ -102,19 +103,25 @@ export const eject = async (root: string): Promise<string[]> => {
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
 
-  const [pages, needsReactRaw, userTheme, rawMarkdown, islands, examples] =
-    await Promise.all([
-      context.pagesRoot
-        ? discoverPages(context.pagesRoot)
-        : Promise.resolve([]),
-      detectNeedsReact(root),
-      context.themeFile
-        ? readFile(context.themeFile, "utf-8")
-        : Promise.resolve(""),
-      buildRawMarkdown(project),
-      discoverIslands(root),
-      discoverExamples(root, config.examples),
-    ]);
+  const [
+    pages,
+    needsReactRaw,
+    usesMath,
+    userTheme,
+    rawMarkdown,
+    islands,
+    examples,
+  ] = await Promise.all([
+    context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
+    detectNeedsReact(root),
+    detectUsesMath(root),
+    context.themeFile
+      ? readFile(context.themeFile, "utf-8")
+      : Promise.resolve(""),
+    buildRawMarkdown(project),
+    discoverIslands(root),
+    discoverExamples(root, config.examples),
+  ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
   const frameworks = new Set<string>([
@@ -192,7 +199,7 @@ export const eject = async (root: string): Promise<string[]> => {
         askEnabled,
         exportEpub,
         exportPdf,
-        mathEnabled: config.markdown.math,
+        mathEnabled: usesMath,
         needsReact,
       }),
       path: join(srcDir, "pages", "[...slug].astro"),

package/src/theme/entry.ts

@@ -435,6 +435,10 @@ blume-diff {
   font-size: 0.8125rem;
 }
 
+.prose :where(td, th) :not(pre) > code {
+  white-space: nowrap;
+}
+
 blume-tabs pre,
 .not-prose > div > pre {
   background: var(--blume-code-background);
@@ -610,9 +614,9 @@ pre:has(.line.focused):hover .line:not(.focused) {
   content: none;
 }
 
-/* Inline code highlighting (markdown.code.inline): Shiki colors the tokens of a
-   \`code\`{:lang} snippet via the same dual-theme CSS variables as fenced blocks,
-   keeping the inline pill background. */
+/* Inline code highlighting: Shiki colors the tokens of a \`code\`{:lang} snippet
+   via the same dual-theme CSS variables as fenced blocks, keeping the inline
+   pill background. Always on — it only fires on the trailing {:lang} marker. */
 .prose code.blume-inline-code span {
   color: var(--shiki-light);
 }