blume 0.6.2 → 0.6.4

package/dist/types/core/config-input.d.ts

@@ -347,11 +347,6 @@ export interface ThemeConfig {
     mode?: "system" | "light" | "dark";
     /** Corner radius scale. Defaults to `md`. */
     radius?: "none" | "sm" | "md" | "lg";
-    /**
-     * Strict token mode: fail rather than silently fall back when a theme token
-     * is missing. Defaults to `false`.
-     */
-    strict?: boolean;
 }
 /** Public credentials for the Algolia backend (the sync key stays an env var). */
 export interface AlgoliaSearch {
@@ -432,7 +427,7 @@ export interface AskConfig {
 export interface AiConfig {
     /** The Ask AI chat assistant. */
     ask?: AskConfig;
-    /** Emit `llms.txt` (an index of the docs for LLMs). Defaults to `false`. */
+    /** Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`. */
     llmsTxt?: boolean;
 }
 /** An arbitrary analytics `<script>`; set exactly one of `src` or `content`. */

package/dist/types/core/config.d.ts

@@ -48,7 +48,7 @@ import type { Diagnostic } from "./types.ts";
  *
  * **Appearance**
  * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
- *   `mode` (`system`/`light`/`dark`), `background`, and `strict` token mode.
+ *   `mode` (`system`/`light`/`dark`), and `background`.
  * - `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.

package/dist/types/core/schema.d.ts

@@ -2395,9 +2395,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         layout: z.ZodDefault<z.ZodEnum<["sidebar"]>>;
         mode: z.ZodDefault<z.ZodEnum<["system", "light", "dark"]>>;
         radius: z.ZodDefault<z.ZodEnum<["none", "sm", "md", "lg"]>>;
-        strict: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
-        strict: boolean;
         accent: {
             dark: string;
             light: string;
@@ -2420,7 +2418,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             light?: string | undefined;
         } | undefined;
     }, {
-        strict?: boolean | undefined;
         accent?: string | {
             dark: string;
             light: string;
@@ -2599,7 +2596,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         })[] | undefined;
     };
     theme: {
-        strict: boolean;
         accent: {
             dark: string;
             light: string;
@@ -2919,7 +2915,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         vercel?: boolean | undefined;
     } | undefined;
     theme?: {
-        strict?: boolean | undefined;
         accent?: string | {
             dark: string;
             light: string;

package/docs/02-deployment.mdx

@@ -100,6 +100,10 @@ redirects: [{ from: "/old", to: "/new", status: 301 }];
 
 `status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds handle redirects at request time. Static builds emit redirect pages **and** platform files so your host issues a real HTTP redirect: `_redirects` (Netlify, Cloudflare Pages), `vercel.json` (Vercel), and `blume-redirects.json` — a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
 
+:::note
+`from` is matched as an exact path — wildcards and pattern matching (e.g. `/blog/:slug` or `/old/*`) aren't supported. If you need pattern-based rules, handle them in an infrastructure file like `vercel.json` (which supports wildcard `source` patterns) or your host's redirect config instead. A `vercel.json` you ship in `public/` is preserved as-is.
+:::
+
 ## Environment variables
 
 When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it's missing — so the problem surfaces early instead of at the first request:

package/docs/03-faq.mdx

@@ -0,0 +1,132 @@
+---
+title: FAQ
+description: Common questions about Blume — how it compares to other documentation tools, and why a Markdown formatter might collapse your callout directives.
+sidebar:
+  label: FAQ
+---
+
+Answers to questions that come up often. Missing one? [Open an issue](https://github.com/haydenbleasel/blume/issues) or ask the in-page assistant.
+
+## How is Blume different from Mintlify, Fumadocs, and others?
+
+Most documentation tools sit at one of two extremes. **Managed platforms** like Mintlify give you a polished result fast, but the build and hosting are their service — you author inside their system and deploy to their infrastructure. **Component libraries and starters** like Fumadocs, Nextra, or Docusaurus are open-source and flexible, but they hand you an application (a Next.js or React project) that you scaffold, wire up, and maintain before and after you write a word.
+
+Blume takes a third path: **the framework is the template.** You point it at a folder of Markdown and it generates and drives the whole site — navigation, search, theming, Open Graph images, SEO, and AI endpoints — with no app to own. It's fully open-source and self-hostable, so there's no managed service and no vendor lock-in, but there's also no boilerplate to maintain.
+
+|  | Blume | Mintlify | Fumadocs / Nextra / Docusaurus |
+| --- | --- | --- | --- |
+| **Model** | Zero-config framework; content only | Hosted platform | Library + app you scaffold |
+| **Source** | Open-source (MIT) | Closed core | Open-source |
+| **Hosting** | Anywhere — static or a server function | Their managed infrastructure | Anywhere; you build and deploy |
+| **You maintain** | Your Markdown | Your Markdown + platform config | Your Markdown + the app around it |
+| **Rendering** | Astro; core theme ships zero client JS | Their runtime | React/Next.js runtime |
+| **AI features** | `llms.txt`, raw Markdown, Ask AI, MCP — built in, no hosted service | Built in (hosted) | Bring your own |
+
+A few consequences worth calling out:
+
+- **You own the output.** `blume build` produces a plain site you host on Vercel, Netlify, Cloudflare, S3, or your own box. Nothing phones home.
+- **No lock-in, two ways out.** Your content is portable Markdown, and `blume eject` turns the project into a standalone Astro app that still uses the `blume` package when you want full control.
+- **Fast by default.** The core theme is React-free and renders static HTML, so pages score well on Core Web Vitals without tuning. You opt into server features (Ask AI, MCP) only when you need them.
+- **Type-safe configuration.** `blume.config.ts` and every `meta.ts` are real TypeScript validated by a schema — not loosely-typed YAML.
+
+:::note
+This isn't "better than everything" — managed platforms and full frameworks are the right call when you want a hosted product or maximum control over the app. Blume is for teams who want a production-grade docs site without owning either the platform or the plumbing.
+:::
+
+See [Why Blume exists](/docs) for the longer version.
+
+## Is Blume free and open-source?
+
+Yes — Blume is MIT-licensed and free. You install the `blume` package, keep your content in your own repository, and host the build wherever you like. There's no paid tier, no per-seat pricing, and no account to sign up for. The source lives on [GitHub](https://github.com/haydenbleasel/blume).
+
+## Do I need to know Astro, React, or Tailwind?
+
+No. A folder of Markdown is a complete site — navigation, search, and theming are inferred or set with a handful of tokens. You only reach for the underlying stack when you want to customize: [interactive islands](/docs/content/islands) (React), [component overrides](/docs/configuration/customization), or [theme tokens](/docs/configuration/theming) (Tailwind). Even then, [`blume.config.ts`](/docs/configuration) is typed, so your editor guides you.
+
+## Can I use React components and MDX?
+
+Yes. Any page can be `.md` or `.mdx`, and MDX lets you drop in the [built-in components](/docs/content/components) with no imports. You can also add your own `.tsx`/`.jsx` [islands](/docs/content/islands) — Blume auto-enables React only for the pages that use them, so the core theme stays JavaScript-free everywhere else.
+
+## Where can I deploy it?
+
+Anywhere. `blume build` outputs static HTML by default, which you can serve from any static host or CDN — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, or your own server. Server-only features (Ask AI, the MCP server, on-demand rendering) switch the build to a server function through an adapter for Vercel, Node, Netlify, or Cloudflare. See [Deployment](/docs/deployment).
+
+## Does search need a hosted service?
+
+No. [Orama](/docs/configuration/search) builds a local index that works in both dev and production with nothing to host or pay for. For very large sites, [Pagefind](/docs/configuration/search) is one flag away. Either way the index ships as part of your site.
+
+## How do I customize the look?
+
+Start with [theme tokens](/docs/configuration/theming) — accent color, fonts, radius, and a `theme.css` for anything else Tailwind can express. Go further by [overriding built-in components](/docs/configuration/customization) or adding [custom pages](/docs/configuration/customization#custom-pages). When you want the Astro project itself, [`blume eject`](/docs/reference/cli) hands you a standalone app that still uses the `blume` package.
+
+## Why is oxfmt / Ultracite collapsing my directives?
+
+If you format your Markdown with [Ultracite](https://www.ultracite.ai) (which runs oxlint + [oxfmt](https://oxc.rs)) — as Blume itself does — you may notice that container directives get flattened onto a single line after a format pass:
+
+```md
+:::note
+Regenerate the project with blume dev.
+:::
+```
+
+becomes
+
+```md
+:::note Regenerate the project with blume dev. :::
+```
+
+Once the opening `:::note` fence is joined to the prose, it's no longer a directive, so it renders as literal text instead of a [callout](/docs/content/syntax#callouts).
+
+### Why it happens
+
+This is a bug in oxfmt's Markdown formatter (inherited from Prettier's Markdown printer — see [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). When it wraps prose, it treats the `:::` fence lines as ordinary text and joins them with the adjacent line, breaking the directive. It affects every container directive — `:::note`, `:::tip`, `:::warning`, `:::danger`, `:::success`.
+
+We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096); until it's fixed there, the patch below is the workaround.
+
+### The fix
+
+Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships exactly this patch in its own repo, and you can apply the same one in any project.
+
+1. Save the patch as `patches/oxfmt@0.55.0.patch`:
+
+   ```diff patches/oxfmt@0.55.0.patch
+   diff --git a/dist/markdown-Bowe09rB.js b/dist/markdown-Bowe09rB.js
+   index 0fe63ff712e07c9c2188711fa0940f7a7d8f7d74..44435d91a2f5a6711512981c9bcaddedc1760be4 100644
+   --- a/dist/markdown-Bowe09rB.js
+   +++ b/dist/markdown-Bowe09rB.js
+   @@ -1141,7 +1141,14 @@ function Yf(e, r, t) {
+    		case "sentence": return Yi(e, t);
+    		case "word": return Li(e);
+    		case "whitespace": {
+   -			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
+   +			let { next: i, previous: oxfmtFencePrev } = e;
+   +			// Preserve line breaks that sit directly against a `:::` container
+   +			// directive fence, so `proseWrap: "never"` keeps the opening/closing
+   +			// fence on their own lines instead of joining them into the prose (which
+   +			// breaks the directive). Ordinary prose still wraps per proseWrap.
+   +			// See prettier/prettier#19040.
+   +			let oxfmtIsFence = (w) => w != null && typeof w.value === "string" && w.value.startsWith(":::");
+   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
+    			return qt(e, n.value, u);
+    		}
+    		case "emphasis": {
+   ```
+
+2. Register it with your package manager's `patchedDependencies`. With Bun or pnpm, add to `package.json`:
+
+   ```json package.json
+   {
+     "patchedDependencies": {
+       "oxfmt@0.55.0": "patches/oxfmt@0.55.0.patch"
+     }
+   }
+   ```
+
+3. Reinstall so the patch is applied:
+
+   ```package-install
+   bun install
+   ```
+
+:::warning[Version-pinned] The patch targets oxfmt `0.55.0` — its diff references a file hashed to that build (`dist/markdown-Bowe09rB.js`). When you bump oxfmt, regenerate the patch (e.g. `bun patch oxfmt`) or check whether the upstream fix has landed and the patch is no longer needed.
+:::

package/docs/configuration/ai.mdx

@@ -3,19 +3,19 @@ title: AI
 description: Machine-readable docs with llms.txt and an optional in-page Ask AI assistant.
 ---
 
-Blume has several opt-in AI features: machine-readable docs for external tools (`llms.txt`), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Everything is off by default, and static docs stay fully static until you turn a feature on.
+Blume has a few AI features: machine-readable docs for external tools (`llms.txt`, on by default), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Ask AI and MCP are opt-in, and static docs stay fully static until you turn a feature on.
 
 ## llms.txt
 
-Emit machine-readable versions of your docs that coding agents and chat assistants can consume:
+Blume emits machine-readable versions of your docs that coding agents and chat assistants can consume. This is on by default; set `llmsTxt: false` to turn it off:
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  llmsTxt: true,
+  llmsTxt: false,
 }
 ```
 
-With this on, `blume build` writes two files to the root of your site:
+While enabled, `blume build` writes two files to the root of your site:
 
 - **`/llms.txt`** — a compact index: your site title and description, then a linked list of every page with its summary.
 - **`/llms-full.txt`** — the entire corpus: each page's full Markdown body, with its source URL, in one file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/components/layout/Pagination.astro

@@ -28,7 +28,7 @@ const { prev, next, strings } = Astro.props;
         >
           <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
           <span>
-            <span class="block text-muted-foreground text-xs">
+            <span class="block text-muted-foreground text-xs max-md:hidden">
               {strings.previous}
             </span>
             <span class="block font-medium">{prev.label}</span>
@@ -43,7 +43,7 @@ const { prev, next, strings } = Astro.props;
           href={next.route}
         >
           <span>
-            <span class="block text-muted-foreground text-xs">
+            <span class="block text-muted-foreground text-xs max-md:hidden">
               {strings.next}
             </span>
             <span class="block font-medium">{next.label}</span>

package/src/components/layout/RootLayout.astro

@@ -367,11 +367,15 @@ const bannerScript = banner?.dismissible
       class:list={["mx-auto grid grid-cols-1 items-start", gridClass]}
       data-blume-doc-grid
     >
-      {
-        showSidebar && (
       <aside
         aria-label="Primary"
-        class="fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
+        class:list={[
+          "fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4",
+          // A "bare" landing (the changelog index) has no sidebar column on
+          // desktop, but the header hamburger still needs a drawer to open on
+          // mobile — without it the toggle only locked page scroll.
+          !showSidebar && "lg:hidden",
+        ]}
       >
         {
           // Pinned links (blog, changelog, contact…) sit above every section on
@@ -419,9 +423,17 @@ const bannerScript = banner?.dismissible
           // The header's tab bar is hidden below `md`, so the drawer is the only
           // way to move between sections on mobile: list the tabs above the
           // page tree, separated by a divider. Hidden from `md` up, where the
-          // header tabs take over.
+          // header tabs take over — unless the page tree is empty (a tab-scoped
+          // standalone page like the changelog), where they keep the drawer
+          // from opening blank.
           navigation.tabs.length > 0 && (
-            <nav aria-label="Sections" class="mb-4 border-border border-b pb-4 md:hidden">
+            <nav
+              aria-label="Sections"
+              class:list={[
+                "mb-4 border-border border-b pb-4",
+                sidebar.length > 0 && "md:hidden",
+              ]}
+            >
               <ul class="m-0 list-none p-0">
                 {navigation.tabs.map((tab) => (
                   <li>
@@ -460,8 +472,6 @@ const bannerScript = banner?.dismissible
           }
         </nav>
       </aside>
-        )
-      }
       <main class="px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
         <BreadcrumbsSlot crumbs={crumbs} wide={isApiOperation} />
         <TableOfContentsSlot

package/src/core/config-input.ts

@@ -406,11 +406,6 @@ export interface ThemeConfig {
   mode?: "system" | "light" | "dark";
   /** Corner radius scale. Defaults to `md`. */
   radius?: "none" | "sm" | "md" | "lg";
-  /**
-   * Strict token mode: fail rather than silently fall back when a theme token
-   * is missing. Defaults to `false`.
-   */
-  strict?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -512,7 +507,7 @@ export interface AskConfig {
 export interface AiConfig {
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
-  /** Emit `llms.txt` (an index of the docs for LLMs). Defaults to `false`. */
+  /** Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`. */
   llmsTxt?: boolean;
 }
 

package/src/core/config.ts

@@ -56,7 +56,7 @@ import type { Diagnostic } from "./types.ts";
  *
  * **Appearance**
  * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
- *   `mode` (`system`/`light`/`dark`), `background`, and `strict` token mode.
+ *   `mode` (`system`/`light`/`dark`), and `background`.
  * - `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.

package/src/core/navigation.ts

@@ -108,6 +108,16 @@ const pageOrder = (page: PageRecord, filename: string): number => {
   if (filename.replace(extname(filename), "") === "index") {
     return Number.NEGATIVE_INFINITY;
   }
+  // Changelog entries read newest-first, matching the generated timeline. Sort
+  // on the negated publish timestamp so a later date yields a smaller order
+  // under the ascending comparator; undated entries fall back to filename order.
+  if (page.contentType === "changelog") {
+    const iso = page.meta.date ?? page.meta.changelog?.date;
+    const time = iso ? Date.parse(iso) : Number.NaN;
+    if (!Number.isNaN(time)) {
+      return -time;
+    }
+  }
   return numericOrder(filename);
 };
 

package/src/core/schema.ts

@@ -482,7 +482,6 @@ const themeConfigSchema = z
     layout: z.enum(["sidebar"]).default("sidebar"),
     mode: z.enum(["system", "light", "dark"]).default("system"),
     radius: z.enum(["none", "sm", "md", "lg"]).default("md"),
-    strict: z.boolean().default(false),
   })
   .strict();
 
@@ -620,7 +619,7 @@ const aiConfigSchema = z
         }
       })
       .optional(),
-    llmsTxt: z.boolean().default(false),
+    llmsTxt: z.boolean().default(true),
   })
   .strict();
 

package/src/og/card.ts

@@ -80,27 +80,34 @@ export const truncate = (value: string, max: number): string => {
     : value;
 };
 
-// Brand mark sizing: target this height, but scale down so a wide wordmark logo
-// stays within the lockup.
+// Brand mark sizing: target this height, but scale down so an extremely wide
+// logo stays within the lockup. The cap leaves room for a wordmark to render
+// at full height — it stands alone as the brand (no text label beside it).
 const MARK_HEIGHT = 32;
-const MARK_MAX_WIDTH = 100;
+const MARK_MAX_WIDTH = 240;
 // Accept either quote style and a non-zero min-x/min-y; only width/height
 // matter for the aspect ratio. A miss falls back to a square mark.
 const VIEW_BOX =
   /viewBox=(?<q>["'])[\d.-]+[\s,]+[\d.-]+[\s,]+(?<w>[\d.]+)[\s,]+(?<h>[\d.]+)\k<q>/u;
 
+/** The SVG's viewBox aspect ratio (w/h), or null without a usable viewBox. */
+const logoAspect = (svg: string): number | null => {
+  const box = svg.match(VIEW_BOX);
+  const w = Number(box?.groups?.w);
+  const h = Number(box?.groups?.h);
+  return w && h ? w / h : null;
+};
+
 // Render the configured logo as the brand mark. A `currentColor` logo carries
 // no intrinsic color, so it is painted in the foreground to read on the light
 // card, then handed to Takumi as a data URI sized from the SVG's aspect ratio.
 const logoMark = (svg: string): Node => {
   const painted = svg.replaceAll("currentColor", FOREGROUND);
-  const box = painted.match(VIEW_BOX);
-  const w = Number(box?.groups?.w);
-  const h = Number(box?.groups?.h);
+  const aspect = logoAspect(painted);
   let height = MARK_HEIGHT;
-  let width = w && h ? (MARK_HEIGHT * w) / h : MARK_HEIGHT;
+  let width = aspect ? MARK_HEIGHT * aspect : MARK_HEIGHT;
   if (width > MARK_MAX_WIDTH) {
-    height = w && h ? (MARK_MAX_WIDTH * h) / w : MARK_HEIGHT;
+    height = aspect ? MARK_MAX_WIDTH / aspect : MARK_HEIGHT;
     width = MARK_MAX_WIDTH;
   }
   return image({
@@ -152,19 +159,13 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const repo = options.repo?.trim();
   const site = options.site?.trim();
 
+  // Logo only — no brand-name label beside it. A wordmark logo already spells
+  // the name, and rendering the site title next to it duplicated the brand
+  // ("Ultracite  Ultracite"). Without a logo, the accent tile with the brand
+  // initial stands in.
   const header = container({
-    children: [
-      logo ? logoMark(logo) : initialMark(accent, initial),
-      brand
-        ? text(brand, {
-            color: FOREGROUND,
-            fontSize: 30,
-            fontWeight: 500,
-            letterSpacing: "-0.01em",
-          })
-        : container({}),
-    ],
-    style: { alignItems: "center", display: "flex", gap: 18 },
+    children: [logo ? logoMark(logo) : initialMark(accent, initial)],
+    style: { alignItems: "center", display: "flex" },
   });
 
   const body = container({