blume 0.6.0 → 0.6.2

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

@@ -1,8 +1,131 @@
-import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { BlumeConfig } from "./config-input.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 declare const defineConfig: (config: BlumeConfig) => BlumeConfig;
 /** Result of loading + validating a project config. */

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

@@ -112,9 +112,8 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     }>>;
     slug: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
-    type: z.ZodDefault<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    type: string;
     search: {
         exclude: boolean;
         boost?: number | undefined;
@@ -138,6 +137,7 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         badge?: string | undefined;
         order?: number | undefined;
     };
+    type?: string | undefined;
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
@@ -317,9 +317,8 @@ export declare const pageMetaSchema: z.ZodObject<{
     }>>;
     slug: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
-    type: z.ZodDefault<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    type: string;
     search: {
         exclude: boolean;
         boost?: number | undefined;
@@ -343,6 +342,7 @@ export declare const pageMetaSchema: z.ZodObject<{
         badge?: string | undefined;
         order?: number | undefined;
     };
+    type?: string | undefined;
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
@@ -1708,12 +1708,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
              * …). On by default; recognized languages only.
              */
             icons: z.ZodDefault<z.ZodBoolean>;
-            /**
-             * 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.ZodDefault<z.ZodBoolean>;
             /**
              * Wrap long lines instead of scrolling horizontally. Off by default, so
              * code keeps its original line breaks and overflows into a scroll area.
@@ -1721,11 +1715,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             wrap: z.ZodDefault<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             icons: boolean;
-            inline: boolean;
             wrap: boolean;
         }, {
             icons?: boolean | undefined;
-            inline?: boolean | undefined;
             wrap?: boolean | undefined;
         }>>;
         codeBlocks: z.ZodDefault<z.ZodObject<{
@@ -1761,15 +1753,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
          * opt a single image out with `data-no-zoom`.
          */
         imageZoom: z.ZodDefault<z.ZodBoolean>;
-        /**
-         * Enable LaTeX math (`$…$` inline, `$$…$$` block) rendered with KaTeX.
-         * Off by default since `$` is common in prose, shell, and code. MDX only.
-         */
-        math: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         code: {
             icons: boolean;
-            inline: boolean;
             wrap: boolean;
         };
         codeBlocks: {
@@ -1780,11 +1766,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         headingAnchors: boolean;
         imageZoom: boolean;
-        math: boolean;
     }, {
         code?: {
             icons?: boolean | undefined;
-            inline?: boolean | undefined;
             wrap?: boolean | undefined;
         } | undefined;
         codeBlocks?: {
@@ -1795,7 +1779,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         headingAnchors?: boolean | undefined;
         imageZoom?: boolean | undefined;
-        math?: boolean | undefined;
     }>>;
     mcp: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -2664,7 +2647,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
     markdown: {
         code: {
             icons: boolean;
-            inline: boolean;
             wrap: boolean;
         };
         codeBlocks: {
@@ -2675,7 +2657,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         headingAnchors: boolean;
         imageZoom: boolean;
-        math: boolean;
     };
     mcp: {
         enabled: boolean;
@@ -3022,7 +3003,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
     markdown?: {
         code?: {
             icons?: boolean | undefined;
-            inline?: boolean | undefined;
             wrap?: boolean | undefined;
         } | undefined;
         codeBlocks?: {
@@ -3033,7 +3013,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         headingAnchors?: boolean | undefined;
         imageZoom?: boolean | undefined;
-        math?: boolean | undefined;
     } | undefined;
     mcp?: {
         name?: string | undefined;
@@ -3102,8 +3081,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/dist/types/core/sources/types.d.ts

@@ -83,6 +83,12 @@ export interface ContentSource {
     readonly staged: boolean;
     /** Optional route prefix; the source's routes namespace under `/<prefix>/`. */
     readonly prefix?: string;
+    /**
+     * Resolved on-disk root, set by filesystem-backed sources only. Drives
+     * folder-meta discovery (scan under this root) and the docs-collection base;
+     * omitted by remote/CMS/staged sources that have no local tree.
+     */
+    readonly contentRoot?: string;
     /** Pull every entry. Called once per scan. */
     load: () => Promise<SourceLoadResult>;
     /** Validate the source is usable; throws a BlumeError when not. */

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export type { ComponentOverride, ComponentOverrides, IslandDescriptor, } from ".
 export { defineMeta } from "./core/define-meta.ts";
 export type { FolderMetaDefinition, FolderMetaFactory, } from "./core/define-meta.ts";
 export type { UIStrings } from "./core/i18n-ui.ts";
-export type { BlumeConfig, FolderMeta, HydrationMode, ResolvedConfig, } from "./core/schema.ts";
+export type { BlumeConfig } from "./core/config-input.ts";
+export type { FolderMeta, HydrationMode, ResolvedConfig, } from "./core/schema.ts";
 export type { Diagnostic, Heading, NavNode, Navigation, NavTab, PageRecord, } from "./core/types.ts";
 export { getBlumeVersion } from "./core/version.ts";

package/docs/advanced/changelog.mdx

@@ -53,14 +53,22 @@ The optional `changelog` object adds richer metadata for the timeline and feed:
 
 ## The timeline page
 
-Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. Each entry renders newest-first with its date, label, and `category` tag in a left rail beside its content:
+Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. It renders as a focused, full-width timeline — no sidebar or table of contents — with each entry newest-first, showing its date, label, and `category` tag in a left rail beside its content:
 
-- The entry **title** becomes its label — or `v{version}` when there's no title.
+- The entry **title** becomes its label — or `v{version}` when there's no title. It links to that entry's own page, so a release is both a line in the timeline and a shareable permalink.
 - The `category` renders as a tag next to the date.
 - Drafts and `sidebar.hidden` entries are skipped.
 
 The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default timeline.
 
+### Grouped by major version
+
+When your versions follow [semver](https://semver.org) and span more than one major, Blume paginates the timeline by major version. Only the newest major line is shown, with a **Show N.x releases** button at the bottom that reveals the next-oldest major one click at a time:
+
+- Detection is automatic — no configuration. It kicks in only when every listed release parses as `major.minor.patch` and there is more than one major; otherwise the timeline stays flat.
+- It tolerates the scoped tags monorepos publish, so `pkg@2.0.0` groups under `2.x` and `pkg@1.4.0` under `1.x`.
+- It's progressive enhancement: every release is still in the page's HTML (and its RSS feed and search index), so readers without JavaScript — and crawlers — see the complete history. The button only collapses older majors once the page hydrates.
+
 ## From GitHub Releases
 
 Rather than authoring entries by hand, point the built-in [`github-releases` source](/docs/content/sources#github-releases) at a repo and every release becomes a `type: changelog` entry — the same timeline and feed, fed straight from the releases you already publish:

package/docs/configuration/index.mdx

@@ -49,11 +49,9 @@ export default defineConfig({
   // Markdown features
   markdown: {
     imageZoom: true,
-    math: false,
     code: {
       icons: true, // language icon in the code-block header
       wrap: false, // wrap long lines instead of scrolling
-      inline: false, // highlight inline `code{:lang}` snippets
     },
   },
 

package/docs/content/syntax.mdx

@@ -139,7 +139,7 @@ export default defineConfig({
 ```
 ````
 
-Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. Turn it on with `markdown: { code: { inline: true } }`.
+Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. It only kicks in when you add the marker, so plain inline code stays untouched — nothing to switch on.
 
 ### Line numbers
 
@@ -372,24 +372,20 @@ The names `caution`, `error`, `important`, and `warn` are accepted as aliases fo
 
 ## Math
 
-Render LaTeX with KaTeX for formulas in prose or as centered blocks — useful for math-heavy or scientific docs. Inline math goes in `$…$`; block math in `$$…$$`.
-
-The Pythagorean theorem is $a^2 + b^2 = c^2$.
+Render LaTeX with KaTeX as centered blocks — useful for math-heavy or scientific docs. Wrap a formula in `$$…$$`:
 
 $$
 \int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
 $$
 
 ```md
-The Pythagorean theorem is $a^2 + b^2 = c^2$.
-
 $$
-\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
+a^2 + b^2 = c^2
 $$
 ```
 
 :::note
-Math is opt-in because `$` is common in prose and code. Enable it with `markdown: { math: true }` in `blume.config.ts`.
+Math is block-only and on automatically — write `$$…$$` and it renders; write none and KaTeX's stylesheet never ships. There's no inline `$…$` math: a lone `$` (currency, shell variables, code) is always left as literal text, so there's no delimiter to escape and no setting to toggle. Math is an MDX-only feature.
 :::
 
 ## Smart punctuation

package/package.json

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

package/src/astro/generate.ts

@@ -33,6 +33,7 @@ import { validateNavTargets } from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
@@ -330,6 +331,26 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
   return matches.length > 0;
 };
 
+/**
+ * Detect whether the project authors block math (`$$…$$`) in any `.mdx`. Drives
+ * whether the generated runtime imports the `<Math>` component and KaTeX's
+ * stylesheet, so a math-free site ships no KaTeX CSS. Math parsing itself is
+ * always on but block-only, so a literal `$$` in source is a necessary
+ * condition — no false negatives. A stray `$$` (e.g. inside a code fence) merely
+ * over-includes the idempotent import, which is harmless.
+ */
+export const detectUsesMath = async (root: string): Promise<boolean> => {
+  const files = await glob(["**/*.mdx"], {
+    cwd: root,
+    ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+    onlyFiles: true,
+  });
+  const contents = await Promise.all(
+    files.map((file) => readOptional(join(root, file)))
+  );
+  return contents.some((content) => content.includes("$$"));
+};
+
 const writeIfChanged = async (
   path: string,
   content: string
@@ -722,10 +743,14 @@ interface McpPlan {
 
 /**
  * Decide whether (and how) to generate the MCP server. Skipped — with a
- * warning — when a content page already occupies its route, so the user's page
- * keeps working.
+ * warning — when a content page or a custom `.astro` page already occupies its
+ * route, so the user's page keeps working instead of colliding.
  */
-const planMcp = (project: BlumeProject, srcDir: string): McpPlan => {
+const planMcp = (
+  project: BlumeProject,
+  srcDir: string,
+  userPages: { pattern: string }[]
+): McpPlan => {
   const { config } = project;
   const { route } = config.mcp;
   const dir = join(srcDir, "blume-mcp");
@@ -740,11 +765,11 @@ const planMcp = (project: BlumeProject, srcDir: string): McpPlan => {
   if (!config.mcp.enabled) {
     return base;
   }
-  if (project.graph.pages.some((page) => page.route === route)) {
+  if (routeIsTaken(userPages, project.graph.pages, route)) {
     return {
       ...base,
       warnings: [
-        `MCP server route "${route}" is already used by a content page; the MCP server was not generated. Set a different "mcp.route" in blume.config.ts.`,
+        `MCP server route "${route}" is already used by a content or custom page; the MCP server was not generated. Set a different "mcp.route" in blume.config.ts.`,
       ],
     };
   }
@@ -858,9 +883,13 @@ export interface GenerateResult {
  * `type: changelog` entries — or when a release-backed changelog source is
  * configured, so its route (and any nav tab pointing at it) still resolves to an
  * empty timeline on a build where the source could not be fetched (e.g. CI
- * without a token). Skipped when a user content page already owns `/changelog`.
+ * without a token). Skipped when a user content page or a custom `.astro` page
+ * already owns `/changelog`.
  */
-const shouldGenerateChangelog = (project: BlumeProject): boolean => {
+const shouldGenerateChangelog = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean => {
   const hasChangelog = project.graph.pages.some(
     (page) =>
       page.contentType === "changelog" &&
@@ -869,10 +898,10 @@ const shouldGenerateChangelog = (project: BlumeProject): boolean => {
   const hasChangelogSource = (project.config.content.sources ?? []).some(
     (source) => source.type === "github-releases"
   );
-  const changelogRouteTaken = project.graph.pages.some(
-    (page) => page.route === "/changelog"
+  return (
+    (hasChangelog || hasChangelogSource) &&
+    !routeIsTaken(userPages, project.graph.pages, "/changelog")
   );
-  return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
 };
 
 /**
@@ -933,16 +962,21 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
-  const [pages, detectedReact, userTheme, islandDiscovery, exampleDiscovery] =
-    await Promise.all([
-      context.pagesRoot
-        ? discoverPages(context.pagesRoot)
-        : Promise.resolve([]),
-      detectNeedsReact(context.root),
-      readOptional(context.themeFile),
-      discoverIslands(context.root),
-      discoverExamples(context.root, config.examples),
-    ]);
+  const [
+    pages,
+    detectedReact,
+    usesMath,
+    userTheme,
+    islandDiscovery,
+    exampleDiscovery,
+  ] = await Promise.all([
+    context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
+    detectNeedsReact(context.root),
+    detectUsesMath(context.root),
+    readOptional(context.themeFile),
+    discoverIslands(context.root),
+    discoverExamples(context.root, config.examples),
+  ]);
   // Statically analyze `components.ts` overrides (never executed): drives the
   // `islands` group, hydration on layout/mdx overrides, string-path resolution,
   // and the "framework component with no client mode" diagnostic.
@@ -973,7 +1007,7 @@ export const generateRuntime = async (
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
   // normal (server-rendered) page written by `writeMcpFiles`.
-  const mcp = planMcp(project, srcDir);
+  const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
   // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
@@ -1016,6 +1050,7 @@ export const generateRuntime = async (
     write(
       join(srcDir, "content.config.ts"),
       contentConfigTemplate({
+        collection: resolveDocsCollection(config, context),
         config,
         context,
         filesystem: hasFilesystemSource,
@@ -1028,7 +1063,7 @@ export const generateRuntime = async (
         askEnabled,
         exportEpub,
         exportPdf,
-        mathEnabled: config.markdown.math,
+        mathEnabled: usesMath,
         needsReact,
       })
     ),
@@ -1107,7 +1142,7 @@ export const generateRuntime = async (
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (shouldGenerateChangelog(project)) {
+  if (shouldGenerateChangelog(project, pages)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1201,7 +1236,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceTabs(config).map((tab) => tab.path),
   ]);
-  if (shouldGenerateChangelog(project)) {
+  if (shouldGenerateChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
   warnings.push(

package/src/astro/markdown-negotiation.ts

@@ -72,11 +72,20 @@ export const markdownVariantUrl = (
     }
   }
 
-  const pathname =
-    path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  const trimmed = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  // Requests arrive percent-encoded while routes are stored decoded, so a
+  // non-ASCII route (`/ja/はじめに` requested as `/ja/%E3%81%AF…`) must be
+  // decoded before the lookup. Malformed sequences stay verbatim.
+  let pathname = trimmed;
+  try {
+    pathname = decodeURIComponent(trimmed);
+  } catch {
+    // Keep the raw path; it simply won't match a content route.
+  }
   if (!routes.has(pathname)) {
     return null;
   }
   const target = pathname === "/" ? "/index" : pathname;
-  return `${prefix}${target}.md${query}`;
+  // Re-encode: the variant URL goes back into the request pipeline.
+  return `${prefix}${encodeURI(target)}.md${query}`;
 };