blume 1.1.2 → 1.1.4

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

@@ -23,6 +23,20 @@ export interface Diagnostic {
     suggestion?: string;
     docsUrl?: string;
 }
+/** One discovered `examples/` file reduced to what Markdown downleveling needs. */
+export interface ExampleMarkdownEntry {
+    /** Shiki language for the fenced block — the file's extension. */
+    lang: string;
+    /** Raw example source, shown verbatim in the agent-facing code fence. */
+    source: string;
+}
+/**
+ * Discovered examples keyed by their `<Component path>` (the file's location
+ * under `examples/`, sans extension). Lets the agent-facing Markdown downlevel
+ * `<Component path="…" />` to the example's source, since the live preview
+ * can't survive the trip to plain Markdown.
+ */
+export type ExampleLookup = Record<string, ExampleMarkdownEntry>;
 /** A heading extracted from page content, used for the TOC and search. */
 export interface Heading {
     depth: number;

package/dist/types/openapi/references.d.ts

@@ -35,6 +35,11 @@ export interface ReferenceSource {
     spec: string;
     /** Per-block Scalar theme name override, if any (Scalar renderer only). */
     theme?: string;
+    /**
+     * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
+     * only). Takes precedence over Blume's derived spec/theme config.
+     */
+    scalar?: Record<string, unknown>;
     /** Display options carried through to the Blume renderer. */
     display: ReferenceDisplay;
     /**

package/docs/advanced/api-reference.mdx

@@ -104,6 +104,26 @@ openapi: {
 
 A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`. Its "Try it" playground calls your **target API directly from the browser** (Blume doesn't proxy), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` and the playground apply to the Scalar renderer only.
 
+### Passing Scalar options
+
+`theme` is a shorthand for the one option most people reach for, but Scalar supports many more. A `scalar` object forwards any [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) straight to the embedded reference — Blume doesn't gate the keys, so anything Scalar accepts flows through:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  renderer: "scalar",
+  spec: "./openapi.yaml",
+  scalar: {
+    localization: { locale: "es" },   // translate Scalar's own UI
+    agent: { disabled: true },         // disable the Scalar Agent
+    hideTestRequestButton: true,
+    orderSchemaPropertiesBy: "preserve",
+  },
+}
+```
+
+Blume's own [`i18n`](/docs/content/i18n) translates the docs chrome, but Scalar has a separate localization system — set `scalar.localization.locale` to translate the embedded reference too. Options in the `scalar` object win over Blume's derived config, so anything set here (including `theme`, `customCss`, or the spec `content`/`url`) overrides Blume's defaults. The same `scalar` block works on the `asyncapi` reference.
+
 ## AsyncAPI
 
 Event-driven APIs use a sibling `asyncapi` block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (`/events`):

package/docs/configuration/index.mdx

@@ -252,6 +252,33 @@ lastModified: 2026-06-20
 
 When enabled, the date is also emitted as schema.org `dateModified` in the page's structured data.
 
+## Date format
+
+Both the "Last updated" stamp and the [changelog](/docs/advanced/changelog) timeline render their dates through the same `dateFormat`, so they read alike. Dates always render in the site's locale; `dateFormat` controls the _shape_. It defaults to the long form (`July 21, 2026`, `2026年7月21日`):
+
+```ts blume.config.ts
+dateFormat: { dateStyle: "long" },
+```
+
+`dateFormat` is a pass-through to [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) options. Use a `dateStyle` preset for a length:
+
+```ts blume.config.ts
+dateFormat: { dateStyle: "medium" },
+```
+
+Or the individual component fields for a numeric house style like `2026/07/21`:
+
+```ts blume.config.ts
+dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
+```
+
+| Option | Description |
+| --- | --- |
+| `dateStyle` | Preset length: `"full"`, `"long"`, `"medium"`, or `"short"`. Can't be combined with the component fields. |
+| `weekday`, `era`, `year`, `month`, `day` | Individual components, e.g. `year: "numeric"`, `month: "2-digit"`. |
+| `timeZone` | IANA time zone. Defaults to `UTC`, so a date reads the same regardless of where the site builds. |
+| `calendar`, `numberingSystem` | Calendar system (e.g. `"japanese"`) and numbering system (e.g. `"arab"`). |
+
 ## SEO
 
 Open Graph images, RSS feeds, and JSON-LD structured data, grouped under `seo`. See the [SEO guide](/docs/configuration/seo) for metadata, frontmatter overrides, and the full reference.

package/package.json

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

package/src/ai/component-markdown.ts

@@ -1,6 +1,7 @@
 import { mdxToMdast } from "satteri";
 
 import { parseYouTubeId } from "../components/content/youtube.ts";
+import type { ExampleLookup } from "../core/types.ts";
 
 /**
  * Downlevel Blume's MDX components to plain Markdown for agent-facing output
@@ -336,6 +337,33 @@ const youtube: ComponentMarkdown = ({ props }) => {
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
 
+/** Fence `code` so its opening/closing run outlengths any backticks inside. */
+const fencedBlock = (lang: string, code: string): string => {
+  const trimmed = code.replace(/(?<!\n)\n+$/u, "");
+  const runs = trimmed.match(/`+/gu);
+  const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+  const fence = "`".repeat(Math.max(3, longest + 1));
+  return `${fence}${lang}\n${trimmed}\n${fence}`;
+};
+
+/**
+ * Build the `<Component>` serializer for a project's discovered examples. The
+ * live preview can't survive the trip to Markdown, so the agent-facing output
+ * carries the example's source — the same code the "Code" tab shows — as a
+ * fenced block. An unknown `path` (or a missing `path` prop) declines, leaving
+ * the JSX verbatim, mirroring the "no example found" note the component renders
+ * on the page.
+ */
+export const exampleComponentSerializers = (
+  examples: ExampleLookup
+): Record<string, ComponentMarkdown> => ({
+  Component: ({ props }) => {
+    const path = typeof props.path === "string" ? props.path : undefined;
+    const example = path === undefined ? undefined : examples[path];
+    return example ? fencedBlock(example.lang, example.source) : null;
+  },
+});
+
 /**
  * The built-in serializer registry, keyed by JSX name. `Step` and `Tab` are
  * intentionally absent: they only carry meaning inside their containers,

package/src/ai/llms.ts

@@ -4,7 +4,10 @@ import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
-import { downlevelComponents } from "./component-markdown.ts";
+import {
+  downlevelComponents,
+  exampleComponentSerializers,
+} from "./component-markdown.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
@@ -163,6 +166,12 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
   const pages = eligiblePages(project).toSorted((a, b) =>
     a.route.localeCompare(b.route)
   );
+  // Downlevel `<Component>` to its example's source; a same-name user
+  // `markdownComponents` entry is spread last and still wins.
+  const components = {
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...config.ai.markdownComponents,
+  };
 
   const sections = await Promise.all(
     pages.map(async (page) => {
@@ -173,7 +182,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       const parsed = matter(raw);
       const body = downlevelComponents(
         applyAgentVisibility(parsed.content),
-        config.ai.markdownComponents,
+        components,
         parsed.data
       ).trim();
       const url = pageUrl(

package/src/ai/markdown.ts

@@ -4,7 +4,10 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
-import { downlevelComponents } from "./component-markdown.ts";
+import {
+  downlevelComponents,
+  exampleComponentSerializers,
+} from "./component-markdown.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 /** One route's raw-Markdown variants. */
@@ -37,6 +40,13 @@ export const buildRawMarkdown = async (
 ): Promise<Record<string, RawMarkdownEntry>> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
+  // Downlevel `<Component>` to its example's source. A user `markdownComponents`
+  // entry of the same name is spread last, so it still wins.
+  const components = {
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...project.config.ai.markdownComponents,
+  };
+
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
     const page = pageById.get(route.id);
     if (page) {
@@ -50,11 +60,7 @@ export const buildRawMarkdown = async (
       const source = applyAgentVisibility(await readRoute(route));
       // The `.md` variant keeps the front-matter block in the output, but its
       // data must also be in scope for `prop={frontmatter.*}` expressions.
-      const md = downlevelComponents(
-        source,
-        project.config.ai.markdownComponents,
-        matter(source).data
-      );
+      const md = downlevelComponents(source, components, matter(source).data);
       const entry: RawMarkdownEntry =
         md === source ? { mdx: source } : { md, mdx: source };
       return [route.path, entry] as const;

package/src/ai/mcp/server.ts

@@ -5,7 +5,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
-import { withBasePath } from "../../core/base-path.ts";
+import { stripBasePath, withBasePath } from "../../core/base-path.ts";
 import { buildOramaIndex, queryOramaIndex } from "../../search/orama-index.ts";
 import type { OramaDoc } from "../../search/orama-index.ts";
 import type { McpData } from "./data.ts";
@@ -81,12 +81,32 @@ const asLimit = (value: unknown): number => {
   return Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT);
 };
 
-/** Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix). */
-const normalizeRoute = (input: string): string => {
-  const noTrailing = input.trim().replace(/\/+$/u, "");
+/**
+ * Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix).
+ * Accepts a full URL too — `search_docs` hits and llms.txt entries carry
+ * `site` + `deployment.base`, and an agent following "pass a route from
+ * `search_docs`" will hand one straight back — reducing it to its base-less,
+ * percent-decoded path.
+ */
+const normalizeRoute = (input: string, data: McpData): string => {
+  let value = input.trim();
+  if (/^https?:\/\//iu.test(value)) {
+    try {
+      value = new URL(value).pathname;
+    } catch {
+      // Not parseable as a URL after all; treat it as a path.
+    }
+  }
+  try {
+    value = decodeURI(value);
+  } catch {
+    // Malformed percent sequence — compare it as written.
+  }
+  const noTrailing = value.replace(/\/+$/u, "");
   const noSuffix = noTrailing.replace(/\.mdx?$/u, "");
   const withSlash = noSuffix.startsWith("/") ? noSuffix : `/${noSuffix}`;
-  return withSlash === "" ? "/" : withSlash;
+  const based = stripBasePath(data.base, withSlash);
+  return based === "" ? "/" : based;
 };
 
 /** Build the absolute (or root-relative) URL for a route. */
@@ -141,8 +161,11 @@ const buildServer = (
         asString(args.query),
         asLimit(args.limit)
       );
+      // `route` is the key `get_page` takes (the tool descriptions promise
+      // it); `url` is where the page is served.
       const results = hits.map((doc: OramaDoc) => ({
         excerpt: excerptFor(doc),
+        route: doc.route,
         title: doc.title,
         url: urlFor(doc.route, data),
       }));
@@ -150,7 +173,7 @@ const buildServer = (
     }
 
     if (name === "get_page") {
-      const key = normalizeRoute(asString(args.route));
+      const key = normalizeRoute(asString(args.route), data);
       const markdown = data.pages[key];
       if (markdown === undefined) {
         return text(

package/src/astro/examples.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
+import type { ExampleLookup } from "../core/types.ts";
 import type { IslandClientMode } from "./islands.ts";
 import { readClientMode } from "./islands.ts";
 
@@ -146,3 +147,15 @@ export const discoverExamples = async (
 
   return { examples, warnings };
 };
+
+/**
+ * Reduce discovered examples to the `<Component path>` → source lookup the
+ * agent-facing Markdown downleveler needs (see {@link BlumeProject.examples}).
+ */
+export const exampleMarkdownLookup = (examples: ExampleSpec[]): ExampleLookup =>
+  Object.fromEntries(
+    examples.map((example) => [
+      example.path,
+      { lang: example.lang, source: example.source },
+    ])
+  );