blume 0.7.0 → 1.0.0

package/src/ai/markdown.ts

@@ -3,15 +3,37 @@ import { readFile } from "node:fs/promises";
 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 { applyAgentVisibility } from "./visibility.ts";
+
+/** One route's raw-Markdown variants. */
+export interface RawMarkdownEntry {
+  /**
+   * The agent-facing Markdown served at `/<route>.md`: supported components
+   * downleveled to plain Markdown (`<TypeTable>` → table, `<Callout>` →
+   * blockquote, …). Present only when downleveling changed something, so
+   * component-free pages aren't stored twice.
+   */
+  md?: string;
+  /** The original source, served verbatim at `/<route>.mdx`. */
+  mdx: string;
+}
+
+/** The Markdown an agent should read for a route. */
+export const agentMarkdown = (entry: RawMarkdownEntry): string =>
+  entry.md ?? entry.mdx;
 
 /**
  * Map every route to its raw source Markdown. Powers the `<route>.md` and
- * `<route>.mdx` endpoints, which serve the original source so AI tools — and
- * readers — can fetch any page as plain Markdown.
+ * `<route>.mdx` endpoints: `.mdx` serves the original source so tools can see
+ * exactly what the author wrote, while `.md` downlevels supported components
+ * to plain Markdown for consumers that can't interpret JSX. `<Visibility>`
+ * audiences are resolved for agents in both variants: web-only content is
+ * removed, agents-only unwrapped.
  */
 export const buildRawMarkdown = async (
   project: BlumeProject
-): Promise<Record<string, string>> => {
+): Promise<Record<string, RawMarkdownEntry>> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
@@ -23,9 +45,16 @@ export const buildRawMarkdown = async (
   };
 
   const entries = await Promise.all(
-    project.manifest.routes.map(
-      async (route) => [route.path, await readRoute(route)] as const
-    )
+    project.manifest.routes.map(async (route) => {
+      const source = applyAgentVisibility(await readRoute(route));
+      const md = downlevelComponents(
+        source,
+        project.config.ai.markdownComponents
+      );
+      const entry: RawMarkdownEntry =
+        md === source ? { mdx: source } : { md, mdx: source };
+      return [route.path, entry] as const;
+    })
   );
   return Object.fromEntries(entries);
 };

package/src/ai/mcp/data.ts

@@ -1,8 +1,9 @@
+import { normalizeBasePath } from "../../core/base-path.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { Navigation } from "../../core/types.ts";
 import { buildSearchDocuments } from "../../search/documents.ts";
 import type { OramaDoc } from "../../search/orama-index.ts";
-import { buildRawMarkdown } from "../markdown.ts";
+import { agentMarkdown, buildRawMarkdown } from "../markdown.ts";
 
 /** A page entry surfaced by the `list_pages` MCP tool. */
 export interface McpRoute {
@@ -21,6 +22,12 @@ export interface McpRoute {
  * access at request time. Serialized to `generated/mcp-data.json`.
  */
 export interface McpData {
+  /**
+   * Normalized `deployment.base` (`""` or `/seg`), layered onto routes when
+   * emitting URLs — the site is base-less and routes are base-less manifest
+   * paths, matching the sitemap/llms.txt convention.
+   */
+  base: string;
   documents: OramaDoc[];
   instructions?: string;
   name: string;
@@ -34,13 +41,26 @@ export interface McpData {
 /** Build the MCP data snapshot from a resolved project. */
 export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
   const { config, graph, manifest } = project;
-  const [documents, pages] = await Promise.all([
+  const [documents, rawMarkdown] = await Promise.all([
     // The MCP server is independent of on-page search, so index docs even when
-    // the search provider is `none`.
-    buildSearchDocuments(project, { includeWhenDisabled: true }),
+    // the search provider is `none`. Documents are agent-facing, so
+    // `<Visibility>` resolves like `get_page`/llms-full.txt (web-only content
+    // removed, agents-only kept).
+    buildSearchDocuments(project, {
+      audience: "agents",
+      includeWhenDisabled: true,
+    }),
     buildRawMarkdown(project),
   ]);
 
+  // `get_page` serves the agent variant: components downleveled to Markdown.
+  const pages = Object.fromEntries(
+    Object.entries(rawMarkdown).map(([route, entry]) => [
+      route,
+      agentMarkdown(entry),
+    ])
+  );
+
   const descriptionById = new Map(
     graph.pages.map((page) => [page.id, page.description])
   );
@@ -61,6 +81,7 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
   }
 
   return {
+    base: normalizeBasePath(config.deployment.base),
     documents: documents.map((doc) => ({
       content: doc.content,
       description: doc.description,

package/src/ai/mcp/discovery.ts

@@ -1,7 +1,10 @@
+import { withBasePath } from "../../core/base-path.ts";
 import { MCP_TOOLS } from "./tools.ts";
 
 /** Inputs needed to describe the MCP server in discovery documents. */
 export interface McpDiscoveryInput {
+  /** Normalized `deployment.base` (`""` or `/seg`); the route is base-less. */
+  base: string;
   name: string;
   route: string;
   site: string | null;
@@ -9,10 +12,14 @@ export interface McpDiscoveryInput {
 }
 
 /** The MCP server's address — absolute when a site is configured. */
-const serverUrl = (input: McpDiscoveryInput): string =>
-  // Concatenate rather than `new URL(route, site)` — a root-absolute route
+const serverUrl = (input: McpDiscoveryInput): string => {
+  // The endpoint is a generated Astro page, so it's served under
+  // `deployment.base` like every other route (the sitemap/llms.txt convention).
+  const path = withBasePath(input.base, input.route);
+  // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  input.site ? `${input.site.replace(/\/+$/u, "")}${input.route}` : input.route;
+  return input.site ? `${input.site.replace(/\/+$/u, "")}${path}` : path;
+};
 
 /**
  * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use

package/src/ai/mcp/server.ts

@@ -5,6 +5,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
+import { 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";
@@ -89,10 +90,24 @@ const normalizeRoute = (input: string): string => {
 };
 
 /** Build the absolute (or root-relative) URL for a route. */
-const urlFor = (route: string, site: string | null): string =>
-  // Concatenate rather than `new URL(route, site)` — a root-absolute route
+const urlFor = (route: string, data: McpData): string => {
+  // Routes are base-less manifest paths; layer `deployment.base` on top so the
+  // URL matches where the page is served (the sitemap/llms.txt convention).
+  const path = withBasePath(data.base, route);
+  // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  site ? `${site.replace(/\/+$/u, "")}${route}` : route;
+  return data.site ? `${data.site.replace(/\/+$/u, "")}${path}` : path;
+};
+
+/** A hit's excerpt: its description, else the head of its content with an
+ * ellipsis only when something was actually cut off. */
+const excerptFor = (doc: OramaDoc): string => {
+  if (doc.description) {
+    return doc.description;
+  }
+  const head = doc.content.slice(0, EXCERPT_LENGTH).trim();
+  return doc.content.length > EXCERPT_LENGTH ? `${head}…` : head;
+};
 
 const text = (value: string, isError = false) => ({
   content: [{ text: value, type: "text" as const }],
@@ -127,10 +142,9 @@ const buildServer = (
         asLimit(args.limit)
       );
       const results = hits.map((doc: OramaDoc) => ({
-        excerpt:
-          doc.description || `${doc.content.slice(0, EXCERPT_LENGTH)}…`.trim(),
+        excerpt: excerptFor(doc),
         title: doc.title,
-        url: urlFor(doc.route, data.site),
+        url: urlFor(doc.route, data),
       }));
       return text(JSON.stringify(results, null, 2));
     }
@@ -156,7 +170,7 @@ const buildServer = (
             lastModified: route.lastModified,
             route: route.route,
             title: route.title,
-            url: urlFor(route.route, data.site),
+            url: urlFor(route.route, data),
           })),
           null,
           2

package/src/ai/mcp/tools.ts

@@ -26,7 +26,7 @@ export const MCP_TOOLS: McpToolMeta[] = [
   {
     annotations: READ_ONLY,
     description:
-      "Fetch a single documentation page as its original Markdown source (frontmatter included). Pass a route from `search_docs` or `list_pages`, e.g. `/guides/install`.",
+      "Fetch a single documentation page as agent-optimized Markdown (frontmatter included, components downleveled to plain Markdown). Pass a route from `search_docs` or `list_pages`, e.g. `/guides/install`.",
     name: "get_page",
     title: "Get page Markdown",
   },

package/src/ai/visibility.ts

@@ -0,0 +1,74 @@
+// Mirrors the fence masking in `core/sources/assets.ts`: a fenced code sample
+// that *shows* `<Visibility>` markup must keep showing what the author wrote.
+const CODE_FENCE_BLOCK =
+  /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
+// NUL delimiters cannot appear in authored markdown, so tokens never collide.
+// oxlint-disable-next-line no-control-regex -- the NUL is the collision guard.
+const FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
+
+/** The audience an output surface serves — the component's two `for` values. */
+export type VisibilityAudience = "agents" | "web";
+
+// `<Visibility for="…">…</Visibility>` in either quote style, tolerant of
+// whitespace around the attribute and inside the tags. Non-greedy bodies stop
+// at the first close tag, so nesting is not supported: a nested block closes
+// the outer match early and any remainder passes through verbatim.
+const visibilityBlock = (audience: VisibilityAudience): RegExp =>
+  new RegExp(
+    `<Visibility\\s+for\\s*=\\s*(?:"${audience}"|'${audience}')\\s*>(?<inner>[\\s\\S]*?)</Visibility\\s*>`,
+    "gu"
+  );
+
+const BLOCKS: Record<VisibilityAudience, RegExp> = {
+  agents: visibilityBlock("agents"),
+  web: visibilityBlock("web"),
+};
+
+/**
+ * Resolve `<Visibility>` blocks for one audience: blocks addressed to the
+ * other audience are removed entirely and blocks addressed to `audience` are
+ * unwrapped (tags dropped, body kept), matching what the Astro component
+ * renders on the web. Other `for` values (the component's default) are left
+ * untouched, and markdown with no matching blocks is returned byte-identical,
+ * so raw sources stay raw.
+ */
+export const applyAudienceVisibility = (
+  markdown: string,
+  audience: VisibilityAudience
+): string => {
+  // Mask fenced code blocks so documentation *about* Visibility survives.
+  const fences: string[] = [];
+  const masked = markdown.replace(CODE_FENCE_BLOCK, (block) => {
+    fences.push(block);
+    return `\u0000blume-fence-${fences.length - 1}\u0000`;
+  });
+
+  let touched = false;
+  const filtered = masked
+    .replaceAll(BLOCKS[audience === "agents" ? "web" : "agents"], () => {
+      touched = true;
+      return "";
+    })
+    .replaceAll(BLOCKS[audience], (_match, inner: string) => {
+      touched = true;
+      return inner;
+    });
+
+  // Removing/unwrapping block-level tags leaves runs of blank lines behind;
+  // collapse them only when something matched so untouched files round-trip
+  // exactly. Fences are masked as single-line tokens, so they are unaffected.
+  const tidied = touched ? filtered.replaceAll(/\n{3,}/gu, "\n\n") : filtered;
+
+  return tidied.replaceAll(
+    FENCE_TOKEN,
+    (token, index) => fences[Number(index)] ?? token
+  );
+};
+
+/**
+ * Resolve `<Visibility>` blocks for agent-facing Markdown (llms-full.txt, the
+ * `.md`/`.mdx` mirrors, MCP tools, Ask AI grounding): `for="web"` content is
+ * removed and `for="agents"` content is unwrapped.
+ */
+export const applyAgentVisibility = (markdown: string): string =>
+  applyAudienceVisibility(markdown, "agents");

package/src/astro/component-slots.ts

@@ -91,8 +91,18 @@ ${clause}
 `;
 };
 
+/**
+ * A filesystem-safe, injective token for an override key. Distinct keys must
+ * never share a wrapper file ("Foo.Bar" vs "Foo_Bar" used to collide, racing
+ * the same temp file and silently rendering the wrong component), so every
+ * non-alphanumeric character is hex-escaped rather than collapsed — the same
+ * hardening as `exampleSlug` in templates.ts.
+ */
 const sanitize = (value: string): string =>
-  value.replaceAll(/[^A-Za-z0-9]/gu, "_");
+  value.replaceAll(
+    /[^A-Za-z0-9]/gu,
+    (char) => `_${(char.codePointAt(0) ?? 0).toString(16)}_`
+  );
 
 export const planComponentSlots = (
   componentsFile: string | null,

package/src/astro/generate.ts

@@ -54,7 +54,12 @@ import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
 import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
-import { customOgRoutes, discoverPages, routeIsTaken } from "./pages.ts";
+import {
+  customOgRoutes,
+  discoverPages,
+  hasGeneratedChangelog,
+  routeIsTaken,
+} from "./pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -377,6 +382,16 @@ const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
   vue: "@astrojs/vue",
 };
 
+/**
+ * Adapter package the project must install itself for each deployment
+ * platform whose adapter Blume doesn't ship. Node and Vercel ship with Blume,
+ * so they never need this.
+ */
+const DEPLOYMENT_ADAPTER_DEPS: Record<string, string> = {
+  cloudflare: "@astrojs/cloudflare",
+  netlify: "@astrojs/netlify",
+};
+
 /**
  * Warn when a Vue/Svelte island is present but its Astro integration isn't
  * installed — Vite would otherwise fail opaquely on the generated config import.
@@ -398,6 +413,34 @@ const islandFrameworkWarnings = (
   return warnings;
 };
 
+/**
+ * Warn when the resolved server-output adapter is one the project must install
+ * itself (Netlify/Cloudflare; Node and Vercel ship with Blume). The generated
+ * astro.config.mjs imports the adapter package directly — and on those
+ * platforms the adapter is even auto-selected from env vars — so warn early
+ * rather than let the build die with an opaque ERR_MODULE_NOT_FOUND from the
+ * hidden generated config. Availability mirrors the search-provider check: a
+ * dep resolves from the project root or from the Blume package itself.
+ */
+const deploymentAdapterWarnings = (
+  deployment: ResolvedConfig["deployment"],
+  root: string
+): string[] => {
+  const dep =
+    deployment.output === "server" && deployment.adapter
+      ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter]
+      : undefined;
+  if (
+    dep &&
+    !(canResolveFrom(root, dep) || canResolveFrom(packageRoot(), dep))
+  ) {
+    return [
+      `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
+    ];
+  }
+  return [];
+};
+
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (root: string, config: ResolvedConfig): string | null =>
   config.examples.css ? join(root, config.examples.css) : null;
@@ -461,16 +504,24 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
   return matches.length > 0;
 };
 
+/** Block math (`$$…$$`) or an explicitly authored `<Math …>` component. */
+const containsMath = (content: string): boolean =>
+  content.includes("$$") || content.includes("<Math");
+
 /**
- * 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.
+ * Detect whether the project can render math: block math (`$$…$$`) or an
+ * explicit `<Math>` tag in any local `.md`/`.mdx`, or in staged (non-filesystem)
+ * source bodies. 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 one of those literals 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"], {
+export const detectUsesMath = async (
+  root: string,
+  staged: Iterable<string> = []
+): Promise<boolean> => {
+  const files = await glob(["**/*.{md,mdx}"], {
     cwd: root,
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true,
@@ -478,7 +529,7 @@ export const detectUsesMath = async (root: string): Promise<boolean> => {
   const contents = await Promise.all(
     files.map((file) => readOptional(join(root, file)))
   );
-  return contents.some((content) => content.includes("$$"));
+  return [...contents, ...staged].some(containsMath);
 };
 
 const writeIfChanged = async (
@@ -792,6 +843,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         ? { suggestions: config.ai.ask.suggestions }
         : null,
       banner: resolveBanner(config),
+      basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
       codeWrap: config.markdown.code.wrap,
       description: config.description,
@@ -829,6 +881,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      x: config.seo.x,
     },
     feeds: buildRssFeeds(project).map((feed) => ({
       href: feed.path,
@@ -934,6 +987,7 @@ const writeMcpFiles = async (
   }
   const data = await buildMcpData(project);
   const discoveryInput = {
+    base: data.base,
     name: data.name,
     route: plan.route,
     site: data.site,
@@ -1012,32 +1066,6 @@ export interface GenerateResult {
   warnings: string[];
 }
 
-/**
- * Whether to generate the default `/changelog` index. Written when there are
- * `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 or a custom `.astro` page
- * already owns `/changelog`.
- */
-const shouldGenerateChangelog = (
-  project: BlumeProject,
-  userPages: { pattern: string }[]
-): boolean => {
-  const hasChangelog = project.graph.pages.some(
-    (page) =>
-      page.contentType === "changelog" &&
-      !(page.meta.draft || page.meta.sidebar.hidden)
-  );
-  const hasChangelogSource = (project.config.content.sources ?? []).some(
-    (source) => source.type === "github-releases"
-  );
-  return (
-    (hasChangelog || hasChangelogSource) &&
-    !routeIsTaken(userPages, project.graph.pages, "/changelog")
-  );
-};
-
 /**
  * Statically analyze the user's `components.ts` (never executing it) and plan the
  * generated `components.ts` module plus any hydration wrappers. Returns the plan
@@ -1097,6 +1125,10 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
+  // entryId so i18n duplicates of one entry write a single file. Collected here
+  // so math detection also sees staged bodies (they never live under root).
+  const staged = collectStaged(project);
   // 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. Independent of
@@ -1113,7 +1145,7 @@ export const generateRuntime = async (
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
-    detectUsesMath(context.root),
+    detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
     readOptional(examplesCssFile(context.root, config)),
     discoverIslands(context.root),
@@ -1156,9 +1188,6 @@ export const generateRuntime = async (
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
-  // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
-  // entryId so i18n duplicates of one entry write a single file.
-  const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   // Only emit a project-scanning `docs` collection when a filesystem source
   // actually feeds it. An all-staged project (openapi/notion/…) has only staged
@@ -1303,7 +1332,7 @@ export const generateRuntime = async (
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1363,11 +1392,11 @@ export const generateRuntime = async (
     ),
     write(
       join(srcDir, "pages", "[...slug].md.ts"),
-      rawMarkdownEndpointTemplate()
+      rawMarkdownEndpointTemplate("md")
     ),
     write(
       join(srcDir, "pages", "[...slug].mdx.ts"),
-      rawMarkdownEndpointTemplate()
+      rawMarkdownEndpointTemplate("mdx")
     ),
   ]);
 
@@ -1410,7 +1439,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceTabs(config).map((tab) => tab.path),
   ]);
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
   warnings.push(
@@ -1461,7 +1490,10 @@ export const generateRuntime = async (
 
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
+  warnings.push(
+    ...deploymentAdapterWarnings(config.deployment, context.root),
+    ...islandFrameworkWarnings(frameworks, context.root)
+  );
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,

package/src/astro/integration.ts

@@ -108,7 +108,7 @@ const negotiateMarkdown =
  * Blume's Astro integration. Mounts user-authored pages from `pages/` into the
  * generated runtime via `injectRoute`, keeping each file in its original
  * location so relative imports and `getStaticPaths` keep working, and teaches
- * the dev server to honour `Accept: text/markdown`.
+ * the dev server to honor `Accept: text/markdown`.
  */
 export const blumeIntegration = (
   options: BlumeIntegrationOptions

package/src/astro/markdown-negotiation.ts

@@ -1,7 +1,7 @@
 /**
  * HTTP content negotiation for the raw-Markdown variants. The `<route>.md`
  * endpoints already serve a page's source verbatim; these helpers let the dev
- * server honour `Accept: text/markdown` by transparently rewriting a page
+ * server honor `Accept: text/markdown` by transparently rewriting a page
  * request to its `.md` variant.
  */