# Blume

> Open-source, markdown-first documentation powered by Astro and Vite.

# blume@1.0.0
Source: https://useblume.dev/changelog/blume-1-0-0

### Major Changes

- 7372fe8: Blume v1.

### Patch Changes

- e922ff5: Stop "Clear conversation" from resurrecting an orphaned answer bubble while a reply is still streaming. Clearing mid-answer emptied the panel, but the in-flight stream kept re-appending its assistant message to the cleared conversation — a growing answer with no question above it. Clearing now aborts the in-flight request and revokes the stream's right to write into the conversation, and asking a new question right after a clear works as before.
- e922ff5: Match locale folders and dot suffixes case-insensitively, the way BCP 47 codes are defined. A configured `pt-BR` with the conventional lowercase `pt-br/` folder (or an `intro.pt-br.mdx` suffix under the `dot` parser) previously fell through as default-locale content at a literal `/pt-br/…` route — and the unconfigured-locale warning, which already compared case-insensitively, stayed silent about it. Those files now route as the configured locale, with the configured casing in routes and labels.
- e922ff5: The generated changelog index's heading, page title, and meta description now come from the translatable `changelog.title` and `changelog.description` UI strings (translated in every built-in pack), joining the reveal button the template already localized. Previously the page rendered a hardcoded English "Changelog" heading, an English " changelog" title suffix, and an English description even on non-English default locales.
- 1e5446f: Lengthen the default changelog description. "Product updates and release notes." is 34 characters — under the 50-character floor search engines want from a meta description, and the generated `/changelog` page uses it for both its meta tag and its on-page subtitle. It now reads "Product updates, new features, and fixes from every release." Sites that set `ui.changelog.description` are unaffected.
- e922ff5: The syntax docs now label callouts and `package-install` blocks as MDX-only, matching the existing notes on diagrams and math. Previously a reader following the page could write `:::note` or a `package-install` fence in a `.md` file and get literal text or a plain code fence with no hint why.
- e922ff5: Apply the js-yaml 4-safe YAML engine to `matter.read` as well. The front-matter wrapper previously exposed gray-matter's own `read` helper unwrapped, so reading a file through it would parse with the removed `safeLoad` default and crash with "Function yaml.safeLoad is removed in js-yaml 4" — the exact failure the wrapper exists to prevent for `matter()` and `matter.stringify()`.
- 68520af: Exclude Vite's pre-bundled dep cache (`node_modules/.vite/`) from @vitejs/plugin-react. Astro's react() replaces the plugin's default `node_modules` exclude, so Babel (carrying the React Compiler) was re-parsing every 500KB+ optimized dep chunk in dev — the source of the "[BABEL] Note: The code generator has deoptimised the styling" messages. Blume's own components stay covered by the compiler.
- e922ff5: Serve image-path icons from under `deployment.base`. `<Icon>` emitted an image icon's path (`/brand/mark.png`) as-is, so on a site deployed under a base path the request went to the domain root and 404'd while `<Card img>`, the logo, and every other image emitter were correctly rebased. Image icons now get the same `withBase` treatment; external URLs, data URIs, and relative paths are untouched.
- e922ff5: `@astrojs/vue` and `@astrojs/svelte` are now declared as optional peer dependencies, matching `@astrojs/netlify` and `@astrojs/cloudflare`. Projects using Vue or Svelte islands must install the matching integration themselves, and package managers now surface and satisfy that requirement instead of the build relying on an undeclared package.
- e922ff5: `blume build --isolated` now reports the build's actual output directory on success. A `server` output build with the Vercel adapter lands its deploy bundle at `.blume-verify/.vercel/output` (it is never surfaced to the project root), but the message previously pointed at `.blume-verify/dist`, which that build never populates.
- e922ff5: The breadcrumb and pagination `<nav>` landmark labels are now translatable via the new `nav.breadcrumb` and `page.pagination` UI strings, with translations in every built-in language pack. Previously both were hardcoded English ("Breadcrumb", "Pagination") while the sibling chrome landmarks were dictionary-driven, so screen readers announced English landmark names on localized sites.
- e922ff5: Fix `ai.markdownComponents` crashing config validation in projects that resolve Zod 4. The schema used the single-argument `z.record(...)` form, which Zod 4 rejects at schema-construction time, so any config parse failed before your settings were even read; it now uses the dual-compatible two-argument form.
- e922ff5: The MCP `get_page` tool's description — shipped user-facing in `tools/list` and the server card — no longer claims to return a page's original Markdown source. The tool serves the agent variant (components downleveled to plain Markdown, `<Visibility>` resolved for agents), and the description now says so.
- e922ff5: The sidebar's panel-stack back arrow and drill-in chevrons now mirror under RTL locales (`rtl:-scale-x-100`), matching the pagination arrows and the panel slide animation, which already flipped direction. Previously the arrows pointed against the reading direction on RTL sites.
- d9590fc: Emit a complete Open Graph card in the page head, so crawlers and social validators stop flagging the metadata as incomplete:

  - `og:url` — the page's canonical URL (rendered only when `deployment.site` is set, or a page overrides `seo.canonical`).
  - `og:type` — `article` on blog posts and changelog entries, `website` everywhere else. Article pages also emit `article:published_time` and `article:modified_time`.
  - `og:site_name` — the site `title`.
  - `og:image:width`, `og:image:height`, `og:image:type`, and `og:image:alt` on Blume's generated OG card, so a crawler can lay it out without fetching the image. An `seo.image` you supply yourself declares none of these, since its dimensions and format are unknown.

- 1e5446f: Give every generated OpenAPI page its own meta description. Operation and overview pages set no `description`, so all of them fell back to the site-wide default — a spec with twenty operations shipped twenty pages carrying one identical description, which search engines treat as duplicate content. Each operation page now derives a description from the spec's own prose (its description, or its summary) followed by the endpoint it documents, and the overview page uses the spec description. These land in `seo.description`, so they feed the meta tag without also printing as a visible subtitle above the body prose.
- 80eb252: Emit X (Twitter) card tags, and add `seo.x` for account attribution:

  ```ts
  seo: {
    x: { handle: "@acme", creator: "@jane" },
  }
  ```

  `handle` becomes `twitter:site` and `creator` becomes `twitter:creator` — the one piece of X card metadata with no Open Graph equivalent to fall back to. A page can credit its own author with `seo.x.creator` frontmatter, which is what a guest post wants. The `@` is optional in both places.

  Every page also now emits `twitter:card`, `twitter:title`, `twitter:description`, and `twitter:image:alt` on the generated card. `twitter:card` previously rendered only when a page had an image; a page without one now gets the compact `summary` card instead of sharing as a bare link.

- e922ff5: The Scalar API reference shell now sets `<html lang>` and `dir` from the default locale, mirroring the changelog index's locale wiring, and renders the same localized skip-to-content link as the other layouts. Previously it hardcoded `lang="en"` with no `dir` — so RTL default locales rendered LTR chrome — and offered keyboard users no way to skip past the navbar.
- e922ff5: The search dialog's section-filter "All" pill is now translatable via the new `search.all` UI string, with translations in every built-in language pack. Previously it rendered hardcoded English inside an otherwise fully localized dialog.
- e922ff5: ⌘K / Ctrl+K now toggles the search dialog: pressing it while the dialog is open closes it, matching how ⌘I toggles the Ask AI panel. Previously the shortcut unconditionally re-opened, calling `showModal()` on an already-open dialog — a silent no-op on evergreen browsers but an `InvalidStateError` on older engines. The `/` shortcut stays open-only, and `open()` itself now guards against an already-open dialog.
- e922ff5: Reject a `toc` config whose `minHeadingLevel` exceeds its `maxHeadingLevel`. An inverted range (including an explicit min above the default max of 3) previously validated fine and silently rendered an empty table of contents on every page; it now fails config validation with a clear message.
- e922ff5: Internal-error stack traces now relativize `.blume/` runtime frames on Windows too. The remap previously matched only POSIX absolute paths, so drive-letter frames like `C:\...\.blume\...` printed the full machine path instead of the project-relative `.blume\...` form tagged `(generated)`.

---

# blume@1.0.1
Source: https://useblume.dev/changelog/blume-1-0-1

### Patch Changes

- 6afb56a: Declare the `blume` bin as `bin/blume.mjs` instead of `./bin/blume.mjs`. The leading `./` is redundant and some package managers normalize it away when linking the binary; dropping it keeps the published manifest consistent with what installers actually write.

---

# blume@1.0.2
Source: https://useblume.dev/changelog/blume-1-0-2

### Patch Changes

- d62dbd0: Harden the pre-paint inline scripts and the route-normalizing regexes against the issues CodeQL flagged.

  The theme and banner scripts in `<head>` used to be built by interpolating config values into JavaScript source with `JSON.stringify`. JSON escaping isn't a code-context escape — `</script>` and U+2028/U+2029 pass straight through it — so a crafted `banner.id` or theme value could break out of the script. Both scripts are now constants and take their values from `data-*` attributes on their own `<script>` tag, which Astro HTML-escapes. `ReferenceLayout` had drifted to its own inline copies of both scripts; it now shares the same module as `RootLayout` and `PageLayout`.

  Route and slug normalization used `/^\/+|\/+$/`-style patterns to trim leading and trailing separators. Those take quadratic time on a long run of the trimmed character, and they run on values that come from outside Blume (configured routes, OpenAPI spec URLs, the site origin), so a pathological config could hang the build. They're replaced by linear trimming helpers in `core/trim.ts`; behavior is unchanged.

---

# blume@1.0.3
Source: https://useblume.dev/changelog/blume-1-0-3

### Patch Changes

- e2f902c: Render the Ask AI trigger from the shared header instead of wiring it up per page. Custom pages built on `PageLayout` (a landing page, most of all) never passed the header's `ask` slot, so the Ask AI button — and the search modal's hand-off to it — silently went missing on them while the generated docs, changelog, and reference pages had it. The header now owns the trigger and reads whether Ask AI is on from the config, so every page gets it; pass `askEnabled={false}` to opt a page out.
- 66b721b: Move the MCP server config under `ai` in `blume.config.ts`, alongside the other agent-facing features. Rename `mcp: { … }` to `ai: { mcp: { … } }` — the shape of the block is unchanged.
- c8ae77e: Fix `ERR_MODULE_NOT_FOUND` in a deployed server function. Surfacing an adapter's deploy bundle out of `.blume` resolved every traced dependency's symlink against the source dir, so the links pointed into a directory the same step then deleted — the function died on its first external import (`Cannot find package '@orama/orama'` with Ask AI or the MCP server enabled). The bundle is now copied verbatim, leaving those links relative and internal to it.

---

# blume@1.0.4
Source: https://useblume.dev/changelog/blume-1-0-4

### Patch Changes

- cf8fa22: Fix the spacing inside directive callouts (`:::note`, `:::success`, …). The global prose paragraph rule leaks a 1rem margin onto the callout's paragraphs even though the callout is `not-prose`, and with a title the body paragraph isn't the first child — so that margin stacked under the title's own gap and left a too-large space between the title and the body. The Callout now overrides that margin locally for a uniform, compact gap between the title, paragraphs, and lists. Callouts without a title and normal prose spacing are unchanged.
- bb5944d: Gate the language icon on `data-language` so it no longer overlaps the first code line on header-less standalone `<CodeBlock>`s. The icon transformer runs whenever icons are on, but a standalone block without a `title` never gets `data-language` (the header bar that reserves the icon's space), so the absolutely-positioned icon sat on top of the first line. Fenced code and titled blocks are unaffected.
- d59be0a: API references (OpenAPI, AsyncAPI) no longer add a header tab automatically. Point a `navigation.tabs` entry at the reference route to surface it — this also lets you control the tab label and scopes the operations sidebar for the native renderer.
- f02b94e: Introduce the `blume-migrate` agent skill. It teaches an AI agent to migrate an existing docs site — Mintlify, Docusaurus, Fumadocs, Nextra, Starlight, or any docs framework — into an idiomatic Blume project: translating the source config to `blume.config.ts`, restructuring content into filesystem-derived navigation (with `redirects` for every moved route), rewriting callouts to `:::` directives, converting icons to Lucide, inlining snippets, and pointing generated API references at `openapi.sources` instead of porting endpoint stubs. Ships with per-framework mapping references, a deterministic Mintlify codemod for the icon/frontmatter pass, and monorepo/Vercel integration recipes. The skill is bundled in the package under `skills/`.
- a421a1e: Make the generated runtime type-check cleanly under `blume check --strict --isolated` (and any project whose `tsconfig` includes the generated files). Previously a valid site could fail with dozens of errors in the generated `.blume-verify` files:

  - The raw-Markdown, RSS, and OG endpoints imported `data.json` directly, so TypeScript widened the JSON (navigation `kind` to `string`, empty arrays to `never[]`, theme mode to `string`) and rejected it against Blume's own types. They now import the typed `blume:data` virtual module.
  - Endpoint handlers (`GET`, `getStaticPaths` callbacks) and the changelog/content-page helper functions had implicit-`any` parameters; they now carry explicit types.
  - The OG endpoint's PNG `Buffer` is wrapped in a `Uint8Array` so it satisfies the `Response` body type, and the empty component-overrides module and the `blume:examples`/`blume:examples-theme` virtual modules now declare types.

  Also stops `blume check --isolated` from reloading a running `blume dev` server: `.blume-verify` is now in Blume's ignored-directory set, so generating the isolated runtime no longer trips the content watcher.

- 6a97cb2: Reserve space for local per-mode SVG logos before they load.
- 5793ccf: Render Mermaid diagrams in `blume dev`. Mermaid statically imports dayjs as CommonJS (`dayjs/dayjs.min.js`), and in dev Vite served that dependency un-pre-bundled, so it exposed no `default` export and mermaid threw `does not provide an export named 'default'` — leaving diagrams blank (the production build already handled the interop). Mermaid now goes through Vite's dependency optimizer, which bundles dayjs with correct CommonJS interop. Because Blume's `import("mermaid")` lives inside `node_modules/blume` — a path Vite's optimizer scan doesn't crawl in a standalone install — the diagram library was never discovered on its own, so it's included explicitly via the nested `blume > mermaid` form (mermaid isn't a direct dependency of the generated project).
- 5c0b0f0: Add custom logo and palette settings for generated Open Graph cards.
- 1bdc849: Truncate long page titles in the previous/next pagination links so they no longer overflow their pill container, and allow inline code inside table cells to wrap instead of forcing the whole table to overflow horizontally.
- f2ffcb5: Prerender Cloudflare adapter builds in Node so build-time `node:` imports resolve. Astro 6 changed the `@astrojs/cloudflare` default prerender runtime from Node to workerd, which broke Blume prerender on Cloudflare (`No such module "node:path"` and `node:fs` usage in Blume's build-time content tooling). The generated `astro.config.mjs` now passes `prerenderEnvironment: "node"` to the Cloudflare adapter. On-demand pages still run in workerd at request time.
- d11a90c: Stop the `Prompt` component's copy button from shifting the layout. On copy, the button's label swapped "Copy prompt" → "Copied", and because the button was sized to its text, it shrank — giving the description beside it more room and reflowing it (a two-line description would collapse to one line, then jump back). Both labels now share a single grid cell, so the button is always sized to the wider "Copy prompt" and never resizes when the state changes.
- fcdc3b3: Match native browser controls, including scrollbars, to the active color theme.
- 3795fbb: Keep root navigation tabs active on descendant routes unless a more specific tab matches.
- e5aa042: Use the `rounded-blume` radius token instead of a hardcoded `rounded-full` on the `PageFeedback` and `Pagination` buttons so they respect the configured `theme.radius`.
- 32e29f0: Keep the text caret inside the search input on mobile. The search dialog was vertically centered, so when the on-screen keyboard opened and the viewport shrank, the dialog re-centered and the input moved up while the native caret stayed put — stranding the cursor below the input, over the results. The dialog is now top-anchored on small screens (like DocSearch/cmdk) so the input sits above where the keyboard appears and doesn't move, and its height is capped to the dynamic viewport so it fits above the keyboard. Desktop keeps its centered layout.
- 7806565: Resolve a section tab's link to its first page when the section has no index page, so the tab no longer 404s. A tab's `path` still scopes its sidebar section and matches the active tab, but the clickable target now falls back to the first page in the section (sidebar order) when nothing lives at the path itself — e.g. `/examples` with only `/examples/hello-world` links to that page instead of a missing `/examples`.
- fe21c54: Wrap markdown tables in a horizontal-scroll container so wide tables no longer overflow the prose column. The wrapper is framed with a rounded border and cell padding, and header labels stay on one line, so a clipped wide table reads as scrollable rather than cut off.

---

# blume@1.1.0
Source: https://useblume.dev/changelog/blume-1-1-0

### Minor Changes

- 9fec53f: Add `blume audit`, an offline site audit that replaces a hosted SEO crawler.

  `blume audit` reads the built `dist/` HTML, joins each page back to the `.mdx` it came from, and reports SEO and site-health issues that name **both** the URL that is wrong and the front matter line that fixes it:

  ```
  ⚠ Meta description too long or too short   5 pages
      /docs/configuration/export    content/docs/configuration/export.mdx:3
      fix: Rewrite `description` in the frontmatter to fit the length range.
  ```

  It runs 87 checks across content, duplicates, indexability, links, redirects, social tags, localization, assets, sitemap, robots.txt, structured data, and AI discovery. Findings are rolled up by check rather than dumped per page, and any tier that didn't run says so. The check set deliberately skips things that can't happen to an Astro-built site (missing hashed bundles, `rel=nofollow`) in favor of checks a crawler can't do — broken `#fragment` anchors, `draft: true` pages that shipped, `llms.txt` held to the sitemap's standard, and Open Graph images verified as bytes.

  Flags:

  - `--url <origin>` also probes a live deployment for what `dist/` can't show (bad rewrites, missing compression, `X-Robots-Tag` deindexing).
  - `--external` probes outbound links.
  - `--claude` / `--codex` write the JSON report and open the agent interactively to fix each finding at its source.
  - `--fail-on <severity>` (default `error`) as the CI gate, plus `--only`/`--skip`, `--json`, `--verbose`, and `--list-checks`.

  `blume validate` is unchanged — it remains the fast source-level link check that needs no build.

### Patch Changes

- 3aee378: Strip trailing slashes from the deploy adapter root with a linear scan instead of a `/\/+$/` regex. The old pattern could backtrack polynomially on a root path containing long runs of `/` (CodeQL `js/polynomial-redos`); the new trim is O(n) and yields the same single-trailing-slash directory URL.
- f779fd5: Make `blume audit --claude`/`--codex` work on Windows: npm installs the agent CLIs as `.cmd` shims that Node only runs through a shell, and cmd.exe can't carry the multi-line prompt as an argument — the handoff now writes the prompt to a file and launches the shim with a one-line pointer, and a missing executable still gets the install hint instead of a raw ENOENT
- d99726a: Account for `deployment.base` throughout the audit: link, sitemap, hreflang, llms.txt, asset, and og:image checks now strip the deployment base from emitted URLs before comparing them to the built file tree, instead of reporting every internal link and sitemap entry as broken on subpath deploys
- d99726a: Make the audit's double-slash check able to fire on the case it was written for: an href like `//docs/x` from a trailing-slash base is now flagged (once per target) instead of being silently skipped as a protocol-relative external link
- d99726a: Replace a raw NUL byte in the audit's duplicate-content grouping key with the `\u0000` escape, so the shipped source is valid text (git diffed it as binary and grep skipped it)
- d99726a: Exempt the home page from the audit's orphan-page check when it lives under a `basePath` — `/docs` was reported as an orphan even though `/` never is
- d99726a: Stop reporting a redirect to a served static file (`/old-whitepaper` → `/files/whitepaper.pdf`) as broken — the audit now resolves redirects against files as well as pages
- d99726a: Keep a gap between the URL and source-file columns in the audit report when a URL reaches the column width, instead of fusing them into one string
- d99726a: Fix two robots.txt matching gaps in the audit: `Disallow: /docs*$` now matches everything under `/docs` (the trailing wildcard absorbs the anchor), and trailing-slash rules like `Disallow: /page/` are matched against the sitemap `<loc>` as served instead of a slash-stripped copy
- d99726a: Only report `ROBOTS_META_UNEXPECTED` when the robots meta actually blocks indexing — a page declaring `index, follow` is no longer claimed to "not be indexed"
- 8d7e779: Format the changelog timeline's dates in the configured locale. The timeline hardcoded `en`, so an i18n site showed two languages at once: a page's "last updated" stamp honored the locale while `/changelog` stayed English. `/changelog` is an unlocalized route whose chrome already renders in the default locale, so its dates now follow that same locale. English sites are unaffected.
- d518958: Add `inline` and `param` props to the `Tabs` component. `inline` renders borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. `param` syncs the active tab to a URL query param instead of the hash; because each group owns its own `param`, several `Tabs` can share a page and every selection is deep-linkable (a link ending in `?install=windows` opens on that tab). Existing boxed, hash-synced `Tabs` and `CodeGroup` are unchanged.
- d9dfdba: Stop shipping underscore-prefixed `.astro` files in `pages/` as routes. Blume injects user pages itself and globbed every `.astro` file, so private partials — shared layouts and home-page sections like `pages/_home/Hero.astro` or `pages/_FeatureBrowser.astro` — were each built into their own HTML page. Page discovery now honors Astro's convention: any file or folder whose name starts with `_` stays importable but is never routed.
- 437ce03: Fix `blume dev` under pnpm's default isolated linker. The generated runtime now checks Astro through the same physical `node_modules` ancestor lookup used by its ESM config, instead of mistaking pnpm's CommonJS-only `NODE_PATH` exposure for a resolvable `astro/config` import.
- 9aad3e6: Add `frontmatter.extend`: opt-in custom frontmatter keys, each validated by a user-supplied schema. Page frontmatter stays strictly validated by default; a project can now declare extra keys (e.g. `owner`, `reviewedAt`) in `blume.config.ts`, mapped to schemas consumed through the Standard Schema interface — so Zod (any version the project installs), Valibot, and ArkType all work. Declared keys are validated on every page (mark them `.optional()` to relax), validated values are preserved on each page record's `custom` field, and every other key keeps the strict typo-catching behavior.
- 368b258: Emit a `_headers` file for static builds so hosts serve the raw AI-ready endpoints with an explicit `charset=utf-8`. Blume's `/<route>.md`, `/<route>.mdx`, and `.txt` outputs (`llms.txt`, `llms-full.txt`) are valid UTF-8, but common static hosts serve them as `text/markdown` / `text/plain` with no charset — so browsers fall back to Windows-1252 and non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. The new `_headers` pins the same `charset=utf-8` Content-Type the dev/server runtime already sends; Netlify and Cloudflare (Pages/Workers static assets) honor it, and hosts that ignore `_headers` (Vercel, S3) are unaffected. The globs carry any `deployment.base`/`basePath` stack, and a `_headers` you ship in `public/` is left untouched — exactly like `_redirects`.
- d99726a: Prefix the `_headers` `.txt` charset rule with only `deployment.base` — `llms.txt`/`llms-full.txt` are served at the deploy root, so a `basePath` deployment shipped a `/docs/*.txt` rule that matched nothing and left the mojibake fix inert
- a4453e4: Upgrade Takumi to v2 via takumi-js. Emoji in titles now render as Twemoji glyphs, fetched once per glyph per build. The OG card palette accepts any CSS color, matching `theme.accent` — a color the renderer can't parse now fails the build instead of silently falling back. `renderOgImage` (exported from `blume/og`) now returns a `Uint8Array` rather than a `Buffer`.
- 548bdd7: Link the RSS feeds from `llms.txt`. The generated index mirrored the docs navigation but never referenced the per-content-type feeds (e.g. `/blog/rss.xml`), so an agent reading `llms.txt` had no pointer to fresh blog posts or changelog entries. The index now closes with an `## RSS Feeds` section listing each configured feed that has pages, under the same condition the feeds themselves exist — RSS enabled and an absolute `deployment.site` — and carrying any `deployment.base` subpath. This mirrors the `artifacts.feeds` list already emitted in `agent-readability.json`.
- d99726a: Fix a data-loss bug in the blume-migrate Mintlify codemod: renaming a key into a parent block that appears earlier in the frontmatter (e.g. `canonical` into an existing `seo:`) deleted the wrong line and left the source key behind; icon remaps also now preserve trailing comments, and the skill references no longer document the pre-1.0.3 top-level `mcp` config
- 8769dd1: Add `seo.og.fonts` to load Google Font families into the Open Graph card renderer. Takumi's built-in font covers only Latin, so a non-Latin page or site title (CJK, and so on) rendered as tofu with no way to fix it. List the families by name — bare strings, or `{ name, weight, style }` for weight/style — and Blume fetches them from Google Fonts at build via Takumi's `googleFonts` helper, registering only the glyph subsets each title uses. Latin text renders unchanged.
- d99726a: Add `seo.og.fonts` to the `OgConfig` authoring type — the schema accepted it but TypeScript rejected it in `blume.config.ts`, making the documented CJK/tofu fix untypeable — and correct the palette doc comment to say any CSS color works, not just hex
- de6403c: Fix the OG image build failing with "Cannot find native binding" on Vercel (Linux). The `googleFonts` OG-font loader is imported from `takumi-js/helpers`, but only the bare `takumi-js` was externalized for the static-prerender Vite environment — which matches by exact specifier, so the subpath (and the native `@takumi-rs/core` backend it pulls in) got bundled into the prerender chunk, relocating the `.node` binding lookup. Externalize `takumi-js/helpers` and the `@takumi-rs/*` packages so the native backend always resolves from `node_modules` at runtime.
- bb9737e: Render authentication requirements in the native OpenAPI reference. Operations that declare security requirements — their own `security`, or the document's root default — now show an **Authorization** section above their parameters: the credential's carrier (`Authorization` header, API-key header/query/cookie), a human label per scheme type (Bearer token, Basic auth, API key, OAuth2, OpenID Connect, Mutual TLS), the scheme's description, and OAuth scopes. Multiple requirement alternatives render as "or" groups (schemes within one requirement are required together), an empty `{}` requirement marks auth as optional, and `security: []` on an operation keeps it public with no section. The generated code samples now send a matching placeholder credential (e.g. `-H "Authorization: Bearer YOUR_TOKEN"`), with a spec-declared explicit header parameter still taking precedence, and a query-borne API key appended to the sample URL. Previously the renderer ignored `security` entirely, so authenticated endpoints were indistinguishable from public ones.
- d99726a: Align the accessible heading level of the Authorization and Parameters sections with Request body and Responses on API reference operation pages
- d99726a: Stop duplicating a query API key in request samples when the spec also declares the credential as an explicit query parameter — the parameter's own example now wins, matching the header behavior
- e6be2f6: Match unordered-list bullets to ordered-list numbers in prose. `--tw-prose-bullets` now defaults to `--blume-muted-foreground` (like `--tw-prose-counters`) instead of `--blume-border`, which rendered bullets much lighter than the numbers beside them.
- d99726a: Normalize `deployment.base` before composing it into redirect targets — a trailing-slash (`/base/`) or bare (`base`) value produced `/base//new` or relative destinations in Astro redirects and the platform redirect files
- 93ea41b: Fix redirects escaping the site under `deployment.base`. A redirect's `to` was only ever rewritten with `basePath`, never with the deployment base, so with `base: "/docs"` a `to: "/new"` emitted a redirect to `/new` — outside the base, 404ing on a subpath deploy (GitHub Pages project sites, most commonly) with no build-time error. Astro applies `base` when it builds the match pattern for `from`, but resolves a destination either by regenerating it from a matching route's segments (which carry no base) or by passing it through verbatim — neither prepends `base`, so Blume now applies it to `to` itself. The two bases also compose correctly: `deployment.base` and `basePath` set together stack as `{base}/{basePath}`, which the old front-prepend could not produce in that order.

  The static host redirect files (`_redirects`, `vercel.json`, `blume-redirects.json`) had the mirror-image bug on the other side: they are matched against the real served URL, but `from` was written without the deployment base, so it never matched. Both sides now carry the full stack. Redirects are authored root-relative in every case, and a base already written into `to` by hand is preserved rather than doubled.

- d99726a: Warn when a `search.popular` link uses an image or inline-SVG icon — the client search island can only render built-in icon names, and the silent fallback to the file glyph was exactly what the validator was meant to catch
- 1c18379: Add `search.popular` to curate the Cmd+K empty-state link list. When set, each `{ href, label, icon? }` entry replaces the default first-six sidebar pages — useful on multi-tab sites where sidebar order surfaces the wrong section. Each `href` is authored root-relative and picks up `basePath` automatically (external URLs pass through); `icon` takes a built-in icon name and defaults to a file glyph. Omit or leave empty to keep the sidebar fallback.
- ea4c560: Stop headings inside a `<Prompt>` block from leaking into the page's table of contents. `Prompt.astro` renders its children into a permanently `hidden` node (used only to build the copy-to-clipboard and Cursor-deeplink text), but `extractHeadings` had no way to know that — any `##` inside a `<Prompt>` was extracted as a real page heading and appeared in the "On this page" sidebar, linking to content that never renders visibly. Heading extraction now tracks `<Prompt>`/`</Prompt>` nesting depth the same way fenced code blocks already are, and skips headings while inside one. Tag detection is anchored to line starts — block-level JSX in MDX starts its own line — so a prose or heading mention of `<Prompt>` never opens a hidden region, and a tag whose attributes span several lines only counts once its closing `>` shows it isn't self-closing.
- c6ca54a: Add a themeable content-column width. A new `--blume-content-width` token (default `42rem`) is exposed as a `max-w-content` utility through Tailwind's `--container-content` theme key, and the article, breadcrumb, mobile table of contents, page feedback, pagination, and last-updated line now use it instead of hardcoding `42rem`. Override `--blume-content-width` to re-measure the whole column at once; the default is unchanged.
- 31ee259: Bundle the Vercel serverless function with its chunks, virtual middleware, and dependencies. With `deployment.output: "server"` and `adapter: "vercel"`, the render function (`.vercel/output/functions/_render.func`) shipped as `entry.mjs` alone, so any server-rendered request — the Docs MCP endpoint, Ask AI — 500'd at runtime with `ERR_MODULE_NOT_FOUND`. The adapter resolves both its Build Output tree and its `@vercel/nft` dependency trace against Astro's `root`, which Blume points at the hidden `.blume` runtime; the trace's base then excluded the server bundle (which lives under `outDir`, outside `.blume`) and collapsed to a single file. The adapter is now shown the real project root, so the trace covers the function's chunks and `node_modules` and the output lands at the project root natively. Projects inside a workspace were unaffected — nft's base search climbed past `.blume` to the workspace root — so this only ever broke standalone projects.

---

# blume@1.1.1
Source: https://useblume.dev/changelog/blume-1-1-1

### Patch Changes

- b5ed87a: Add `seo.og.titles` to name the generated Open Graph card of a custom `.astro` page, keyed by route. A custom page has no frontmatter to read, so its card was titled by humanizing the last URL segment — turning `/cli` into "Cli" with no way to say "CLI". An entry here wins over the humanized segment; `"/"` addresses the home, whose card otherwise carries the site title.
- 52cfa77: Give each GitHub-sourced changelog release page a unique meta description derived from its release notes, instead of every release falling back to the site-wide description. The summary is the notes reduced to plain text — section headings ("### Patch Changes") and changesets' commit-hash bullet prefixes dropped, code fences and link syntax stripped — then cut at a word boundary to fit the 110–160 character search-snippet range `blume audit` checks for. It's carried as `seo.description`, so it feeds the meta/OG/Twitter description tags without adding a visible lede paragraph to the page.
- 20ae16d: Fix `blume check` failing on generated files under a strict tsconfig: island and example wrappers now mirror the wrapped component's props onto `Astro.props` so required props type-check through the spread, and the OG endpoint's `customRoutes` array is explicitly typed so an empty list is no longer an implicit `any[]`.
- 9a6345f: Decouple Twoslash from the project's hoisted TypeScript so sites can use TypeScript 7 (tsgo). The generated Astro config now wires in `blumeTwoslashTransformer` from `blume/markdown`, which compiles Twoslash fences with Blume's own pinned classic TypeScript (passed explicitly as `tsModule` plus `tsLibDirectory` for the default lib files) instead of resolving whatever `typescript` the surrounding project installed — under TS7 that package's main export is a version stub with no compiler API and no `lib.*.d.ts` files, so any `twoslash` fence crashed the build.
- 32ced54: Evaluate `{frontmatter.*}` prop expressions when downleveling components for agent-facing output. Serializers — built-in and `ai.markdownComponents` — now receive the same values the rendered page shows instead of empty props, and the page's front-matter is exposed on the serializer context.
- ff37999: Stop `blume audit` flagging the changelog RSS feed link in llms.txt as a stale entry. The stale-entry check compared each llms.txt target against built pages only, but the generator itself links non-page assets — the changelog RSS feed — so a target the static file index serves now counts as valid, the same way redirect targets may land on a served asset.
- f322ac1: Warn when an index page's own frontmatter `title` diverges from its folder's explicit `meta.title`. The two are resolved independently, so a translator can update one and forget the other — the sidebar looks right while the page's own `<title>`/heading stays stale. Reported as `BLUME_NAV_INDEX_TITLE_MISMATCH` from `blume doctor`/`blume check`. A mismatch is reported once — untranslated pages filled in from the fallback locale are exempt, since their fix is translating the page, not editing the fallback locale's frontmatter.
- eb25103: Link Blume's nested integrations into the generated runtime when npm's split install hoists astro away from them. An `overrides` astro pin plus an incremental `npm install` — the exact steps the Astro-conflict warning recommends — hoists astro to the project root while `@astrojs/mdx` and Blume's other deps stay nested under `node_modules/blume/node_modules`, so fresh checkouts and `blume build --isolated` failed with `Cannot find module '@astrojs/mdx'`. The dependency link now probes for the integrations instead of astro alone and links the nested set, letting astro keep resolving from the hoisted copy.
- 80dc1c1: Fail `blume build` (exit 1) when any page fails frontmatter validation, instead of silently dropping the invalid pages and reporting a green build. Pass `--no-strict` to restore the old lenient behavior — the build then warns how many pages were dropped instead of printing an unqualified success.
- 7c75bb8: Warn when two sidebar siblings (pages or folders) resolve to the same explicit or numeric `order`, instead of silently falling back to an alphabetical tiebreak. Reported as `BLUME_DUPLICATE_SIDEBAR_ORDER` from `blume doctor`/`blume check` and any other diagnostics consumer.

---

# blume@1.1.2
Source: https://useblume.dev/changelog/blume-1-1-2

### Patch Changes

- 6cf2995: Allow custom Shiki theme objects in `markdown.codeBlocks.theme.light` and `markdown.codeBlocks.theme.dark`. Custom themes now flow through fenced code, inline highlighted code, `<CodeBlock>`, and `<Diff>` alongside bundled Shiki theme names.
- cb30a40: Recognize the localized/based root tab when scoping the sidebar. With i18n enabled and header tabs configured, a non-default locale's tabs arrive localized (`/` becomes `/en`), but render-time scoping compared the active tab against a bare `/` — so on any `/en/...` route the root tab was misread as a section tab, and a root-level `(group)` folder (whose path is exactly the locale prefix) collapsed the sidebar to that one group. The same bare comparison blanked the sidebar entirely under a `basePath` with a root tab. The navigation now carries its root in the tabs' own path space (`/`, `/en`, `/docs`) and the sidebar scoping compares against it, so non-default locales show the full tree minus tab-owned sections, matching the default locale.
- aa3f588: Size `<Component>` preview panes to the rendered example instead of the source line count. The generated frame page now observes the example with a ResizeObserver and reports its height to the docs page, which applies it to both the Preview and Code tabs — so short sources that render tall UIs no longer clip, and long sources that render small components no longer float in dead space. The line-count estimate remains the SSR/no-JS initial height (288px floor, 400px ceiling; the measured height is unceilinged up to the viewport), with a height transition so the settle on lazy load doesn't snap. Examples that resize after load keep the pane in sync, and viewport-tracking examples (`h-screen`) can't feed the measurement back into unbounded growth.
- 103733d: Re-point a cache-restored `.blume/node_modules` junction that resolves a superseded Blume install. A restored build cache (e.g. Vercel's) could resurrect the junction pointing into the previous release's store directory; because releases rarely bump Astro, every astro-based health check passed straight through the stale link, and the freshly generated Astro config then imported the old package — crashing on any export added since (`blumeTwoslashTransformer is not a function`). The junction is now dropped and relinked whenever the directory behind it holds a `blume` other than the one running.

---

# blume@1.1.3
Source: https://useblume.dev/changelog/blume-1-1-3

### Patch Changes

- 42522fc: Downlevel `<Component>` to its example's source in agent-facing Markdown. The `/<route>.md` mirror, `llms-full.txt`, and the MCP `get_page` tool now render `<Component path="…" />` as a fenced code block of the example's source (the same code the on-page "Code" tab shows) instead of leaving the raw JSX tag, so agents reading a page get the component's code rather than an opaque element. An unknown path (or a missing `path`) is left verbatim, and a same-name `ai.markdownComponents` serializer still overrides the built-in.
- a71f70e: Add a `dateFormat` config option for the "last updated" stamp and the changelog timeline. Both surfaces previously hardcoded `dateStyle: "long"`; they now share a configurable pass-through to `Intl.DateTimeFormat` options, defaulting to `{ dateStyle: "long" }` so existing sites are unchanged. Set a preset (`dateFormat: { dateStyle: "medium" }`) or a numeric house style (`dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" }`); dates still render in the site's locale and in UTC unless a `timeZone` is given.
- 68fc939: Harden the agent-facing code-fence helper against a polynomial-time regex (ReDoS). Trailing newlines are now stripped with an unambiguous pattern, so example source with many interior blank lines can't force quadratic backtracking.
- ee77cfd: Stop long OpenAPI routes from overflowing the native API reference layout. An operation's heading now wraps a long `METHOD /path` title instead of clipping it off the content column, and the overview list rows stack the summary over the route (each getting the full row width) and wrap a long route inside the card — dropping the duplicate path that overlapped the label when a spec sets no summary.
- 93a94a2: Fix two responsive/mobile layout issues. Twoslash code blocks now wrap their lines on narrow screens instead of pushing the page sideways (hover popups still escape as before), and a long site title in the header now truncates on one line instead of wrapping into the fixed-height bar.
- a27c543: Add a `scalar` passthrough object to the `openapi` and `asyncapi` config blocks (Scalar renderer). Any [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) set there is forwarded verbatim to the embedded `<ScalarComponent>` — `localization` (to translate Scalar's own UI), `agent`, `hideTestRequestButton`, `orderSchemaPropertiesBy`, and the rest. Options in the `scalar` object win over Blume's derived spec/theme config, making it a full escape hatch to Scalar's API; the dedicated `theme` field remains the ergonomic shorthand.
- fa07dc4: Create the `.blume/node_modules` dependency junction when an isolated linker (Bun's `isolated` mode, pnpm) dedupes the workspace's own `astro` dependency to Blume's copy. The walk from `.blume/` found the "correct" astro through the workspace's direct-dep symlink — in a directory holding none of Blume's integrations — so the junction was skipped and the build died on `Cannot find module '@astrojs/mdx'`.

---

# blume@1.1.4
Source: https://useblume.dev/changelog/blume-1-1-4

### Patch Changes

- e4506a0: Keep the Ask AI panel open when Escape dismisses the search dialog stacked on top of it. The panel's window-level Escape listener fired alongside the dialog's native cancel, closing both surfaces when the user only meant to close search.
- e4506a0: Stop reporting every `blume audit --claude`/`--codex` launch failure as "not found on PATH". Only a missing executable (`ENOENT`) gets the install hint now; any other spawn failure (`EACCES`, `EMFILE`, …) surfaces as itself instead of being masked by an irrelevant install suggestion.
- e4506a0: Strip `deployment.base` before comparing canonical and sitemap URLs in `blume audit`. Canonicals and `<loc>`s are emitted as `site + base + route` while page URLs come from the base-less file tree, so on a subpath deployment every page false-fired `CANONICAL_BAD_TARGET`, `NON_CANONICAL_IN_SITEMAP`, and `INDEXABLE_PAGE_NOT_IN_SITEMAP` — and the duplicate-content checks silently skipped every page (each one looked like it canonicalized elsewhere).
- e4506a0: Percent-decode pathnames before comparing them against the built file tree in `blume audit`. Sitemap `<loc>`s are `encodeURI`'d and `URL#pathname` re-encodes non-ASCII, while page URLs and file-index keys are raw on-disk names — so a non-ASCII route (e.g. a Japanese slug) false-fired `SITEMAP_BAD_URL`, and a percent-encoded href false-fired `LINK_TO_BROKEN`.
- e4506a0: Probe live URLs under `deployment.base` in `blume audit --url`. Page URLs come from the base-less build tree, but the deployed site serves everything (pages, robots.txt, sitemap.xml) under the base — so auditing a healthy subpath deployment produced a wall of `HTTP_4XX` findings from probing the wrong URLs.
- e4506a0: Strip query strings and fragments from redirect destinations before `blume audit` checks them against the build. A working redirect to `/guide#setup` or `/search?q=x` was reported `REDIRECT_BROKEN` because the suffixed path is not a file-tree member.
- e4506a0: Apply `basePath` to configured redirects before `blume audit` resolves them. Redirects are authored as if mounted at root and gain the base at build time, but the audit compared them raw against built page URLs that carry the base — so every redirect on a `basePath` site was reported `REDIRECT_BROKEN`, while `LINK_TO_REDIRECT` and `REDIRECT_SOURCE_IS_PAGE` could never fire.
- e4506a0: Keep `/` separators in Sanity and Notion slugs. Slugging deleted slashes along with other punctuation, so a `guides/setup` slug was mashed into `guidessetup` — and two documents whose slugs differ only by a slash silently overwrote each other. Segments are now slugged individually.
- e4506a0: Stop promoting a `title="…"` embedded in another code-fence meta attribute's quoted value (`caption='set title="X" here' file.ts`) to the block title. Other quoted attributes are blanked before the explicit-title scan, so the bare-token title (`file.ts`) wins as intended.
- 4294b00: Carry the resolved `dateFormat` config into the runtime data and its `BlumeDataConfig` type. A configured `dateFormat` was silently dropped from the serialized site data, so the date stamps always rendered the default long style, and `blume check` failed with ts(2339) on `data.config.dateFormat` in the generated catch-all page.
- e4506a0: Fall through to the next platform env var when one is set but empty. `VERCEL_PROJECT_PRODUCTION_URL=""` dead-ended the chain before `VERCEL_URL` (same for Netlify's `URL`/`DEPLOY_PRIME_URL`/`DEPLOY_URL`), leaving `deployment.site` unset so canonicals, OG images, and the sitemap silently switched off for that deploy.
- e4506a0: Leave the `.blume/node_modules` junction alone when it already points at the right target. It was deleted and re-created on every dev regeneration in the split-install layout, opening a window in which the dev server's module resolution raced a missing `node_modules` and intermittently failed with "Cannot find package".
- e4506a0: Watch `blume.config.ts`, `theme.css`, and `components.ts` via their parent directory in `blume dev`. Watching the file path tracks the inode, so a rename-replace save (vim and most "atomic save" editors) orphaned the watcher after the first save — every later edit was silently ignored until the server restarted.
- e4506a0: Localize internal `navigation.featured` hrefs per locale, like header tabs. A pinned `/changelog` link rendered on `/fr/…` pages always targeted the default-locale route, kicking the reader out of their language.
- e4506a0: Stop opening a phantom code fence on a line-leading inline backtick span. A paragraph line like ` ```inline``` ` is not a fence opener (CommonMark forbids backticks in a backtick fence's info string), but the heading/link scanner treated it as one and silently dropped every heading and link after it from the TOC, search index, and anchor validation.
- e4506a0: Stop misreading a body-leading thematic break as front matter in heading extraction. A stripped body opening with `---` followed by a blank line lost every heading up to the next `---` line — missing TOC and search entries, and false `BLUME_BROKEN_ANCHOR` findings from `blume validate`.
- e4506a0: Strip the locale directory from a shared `.$` file's nav path with the `dir` parser. `fr/changelog.$.mdx` kept its `fr/` segment, silently routing the default locale's record inside the French URL namespace, the French copy to `/fr/fr/changelog`, and conjuring a spurious "Fr" sidebar group.
- e4506a0: Skip images that are themselves links when wiring click-to-zoom. A linked image (`[![alt](/shot.png)](https://example.com)`) navigates on click, so the zoom binding only flashed an overlay in the instant before navigation while the `cursor-zoom-in` affordance promised a zoom that never happened.
- e4506a0: Extract markdown link targets with balanced parentheses and image-wrapped labels intact. `[wiki](https://en.wikipedia.org/wiki/Foo_(bar))` was truncated at the inner `)` and reported as a broken link, and the outer target of `[![alt](/img.png)](/target)` was never validated at all (the nested image's own target still is).
- e4506a0: Make the MCP tools' contract hold together: `search_docs` hits now include the `route` the tool description promises (alongside `url`), and `get_page` accepts a full URL or a base-prefixed path — an agent following "pass a route from `search_docs`" no longer gets "No page found" for a page that exists on a site with `deployment.site` or `deployment.base` configured.
- ff0b2b0: Fix `.md` pages serving stale content in `blume dev`. The generated dev config kept Vite's watcher out of Astro's cache dir, which suppressed the `data-store.json` change events Astro relies on to invalidate content in a running dev server — so edited Markdown bodies (rendered into the data store at load time) kept serving the old HTML even after a hard reload, while `.mdx` pages (rendered through their own module) updated fine. The watcher ignore is now scoped to migrated (`content.root: "."`) projects, the only layout whose glob loader would otherwise churn on Astro's own cache writes.
- e4506a0: Pair backtick code in OpenAPI descriptions the way CommonMark does — a run only closes on an _equal-length_ run. A lone inline backtick followed by a code fence used to "close" on the fence's first backtick, leaving `{`/`<` in the surrounding prose unescaped (an MDX compile error that fails the operation page's build) and entity-escaping the fence body.
- e4506a0: Stop escaping `>` in OpenAPI descriptions rendered to MDX. It isn't MDX-special on its own, and escaping it turned a common `> **Note:** …` blockquote into a literal "&gt; Note:" paragraph.
- e4506a0: Give every distinct OpenAPI tag a unique slug. Slugging strips all non-ASCII, so two non-Latin tags (`ペット`, `注文`) both collapsed to `operations` — merging their routes and sidebar groups and dropping the second tag's overview section. Colliding slugs now gain `-2`, `-3`, … in first-seen order.
- e4506a0: Leave shifted and alted keyboard chords to the browser. Ctrl+Shift+I (DevTools) toggled the Ask AI panel and Ctrl+Shift+K (Firefox web console) opened the search dialog, because the ⌘I/⌘K matchers ignored the Shift and Alt modifiers.
- e4506a0: Resolve explicit sidebar refs written with a trailing slash. A hand-written `"guides/"` normalized to `/guides/`, missed the slashless `/guides` route, and the item was silently dropped from the sidebar with no diagnostic.
- 6554485: Keep the docs sidebar scrolled to the current page across navigations. Each page load previously reset the sidebar's own scroll container to the top, so on long sidebars the viewport visibly jumped away from the link you just clicked. A pre-paint inline script now centers the active link when it would otherwise be out of view — this also fixes deep links landing with the current page's link below the fold. Short sidebars, and pages whose active link is already visible, are untouched.
- e4506a0: Only unwrap a _single_ rendered paragraph in `<Prompt>`, `<Frame>`, and `<Tooltip>`. The greedy unwrap matched across multiple paragraphs, injecting unbalanced `</p>`/`<p>` tags via `set:html` — a multi-paragraph description, caption, or tooltip label broke the surrounding layout when the parser re-parented the stray tags.
- e4506a0: Dedupe repeated `<Update>` ids on a page, mirroring the accordion id dedupe. Two entries labeled "Bug fixes" produced duplicate DOM ids, so the second entry's self-anchor permalink jumped to the first one; later duplicates now gain `-2`, `-3`, … and their header anchors follow.
- e4506a0: Make `useAskAI().reset()` revoke the in-flight stream, matching the built-in island. Resetting mid-answer used to let the next chunk re-append an orphaned assistant bubble onto the emptied conversation, and a fetch error after reset resurrected the entire pre-reset history. The request is now aborted and stale writes are discarded.

---

# blume@1.2.0
Source: https://useblume.dev/changelog/blume-1-2-0

### Minor Changes

- 217975c: Add a top-level `integrations` array to `blume.config.ts` for registering Astro integrations. Entries are schema-validated as an array (each element is left for Astro to validate) and appended after Blume's built-in integrations in declaration order, with no sorting or deduplication. The generated Astro config loads them through a portable bridge back to `blume.config.ts` rather than serializing the instances, so function-bearing hooks survive across build, `blume dev`, config regeneration, and eject. Install and version each integration in the site itself — Blume neither adds it to the runtime's dependencies nor manages its Astro compatibility.
- 592af35: Add `blume eval`, a test suite for your docs. An AI agent — Claude Code by default, Codex with `--agent codex`, spawned from your own installation with no API keys held by Blume — answers the questions in `evals.yaml` using ONLY the documentation, served over a private MCP stdio bridge to an agent locked out of its file, shell, and web tools; a judge pass then grades each answer against the expected facts you listed. Any question the docs can't answer fails CI (relax with `--threshold`), each failure is anchored to the source page that should answer it, `--json` emits the validate/audit-compatible machine report, `--fix` hands the failing report to the agent to edit the docs interactively, and `blume eval init` drafts a starter evals file from your existing docs. No build or deployment is needed — the docs snapshot is computed from the content tree.
- 2063196: Let a header tab declare its link target with `href`. A tab's `path` scopes its sidebar section and doubles as the link, so a section whose `path` isn't a page of its own falls back to the section's first page rather than linking to a 404. That fallback only sees the content tree, so a tab pointing at a route generated outside it — the automatic `/changelog` index, or a custom page under `pages/` — lands on the section's first entry instead of the page the reader expected. Setting `href` keeps the tab on the declared route; the field is optional and tabs that omit it resolve exactly as before. Declared hrefs are localized and rebased like any other route, so they work under i18n and a `deployment.base`.
- 55e176a: Support external Ask AI endpoints on static sites and per-source OpenAPI search, llms.txt, and crawler indexing controls.

### Patch Changes

- 18e1d8d: Stop Cloudflare server builds from declaring unused `SESSION` KV and `IMAGES` bindings in the generated wrangler config. Without a configured session driver, `@astrojs/cloudflare` force-enables KV-backed sessions — making `wrangler deploy` demand a real KV namespace nothing reads — and defaults images to the runtime Cloudflare Images binding. Blume never reads `Astro.session` and every HTML route prerenders, so the generated Astro config now sets an inert in-memory session driver and `imageService: "compile"`, which pre-optimizes images at build time with sharp.
- 38475cb: `blume init` now adds `node_modules/` to the generated `.gitignore` alongside Blume's runtime and build output directories.
- 0c8f78d: Make the entire sidebar navigation back row clickable. When a drilled-in section has no index page, the chevron and title now form a single full-width back button; when it does have one, the title link and back button each fill their side of the row so there are no dead zones, and both get row hover states.
- 812b09e: Fix nested `<Tree>` folder chevrons, nested `<Accordion>` chevrons, and a nested object schema's "Show properties" toggle reflecting an ancestor's open state instead of their own. All three rotated or flipped on Tailwind's `group-open:` variant, which matches any open ancestor `.group` — the same leak as the nested sidebar chevron — so a collapsed disclosure inside an expanded one showed an open indicator. Each indicator is now scoped to its own `details`.
- 812b09e: Fix a nested sidebar group's chevron pointing down while the group is collapsed. The chevron rotated on Tailwind's `group-open:` variant, which matches any descendant of an open `.group` — and since every collapsible group in the tree is a `.group`, expanding a parent rotated the chevrons of its collapsed children too, so the arrow disagreed with the items it was hiding. The rotation is now scoped to the group's own `details`, leaving each chevron to reflect only its own open state.
- d5d6b7a: Fix the EPUB page action failing in dev with `epub is not a function`. `epub-gen-memory`'s browser bundle is a browserified UMD, and its dynamic import lives inside `node_modules/blume`, which Vite's optimizer scan doesn't crawl — so in dev it was served as raw ESM, where the UMD finds no `exports`/`define`, exposes no `default`, and strands its callable on `window.epubGen`. It now joins mermaid in `optimizeDeps.include`, naming the `/bundle` subpath that is actually imported, since optimizing the package root leaves that entry unoptimized. Production builds already bundled it correctly and are unchanged.
- 55e176a: Pagefind now honors search exclusions: pages with `search.exclude` frontmatter (and hidden pages, unless `search.indexing.includeHiddenPages` opts them in) no longer appear in local search results.

---

# blume@1.2.1
Source: https://useblume.dev/changelog/blume-1-2-1

### Patch Changes

- a015b0a: Match CJK and Thai content in the default Orama search provider. With `i18n.defaultLocale` set to a language written without spaces (Japanese, Chinese, Korean, Thai), the search index now uses a word-segmenting tokenizer built on `Intl.Segmenter` — previously every query in those scripts silently returned zero results because the default tokenizer collapsed the text to no tokens. The fix covers the search dialog, the MCP server's `search_docs` tool, and Ask AI grounding, and keeps Latin terms matching case-insensitively on mixed-language sites.
- 454e67f: Match every hoverable sidebar navigation row — the back rows, routed panel header, and flat group header — to the shared 0.65rem navigation radius.
- 17d520b: Style the desktop sidebar scrollbar with a thin, theme-colored thumb and a transparent track. The mobile drawer and the page scrollbar keep their platform defaults. Requires Tailwind CSS 4.3 or later, which is now the declared minimum.

---

# blume@1.3.0
Source: https://useblume.dev/changelog/blume-1-3-0

### Minor Changes

- a089dbc: Upgrade the AI SDK to v7. The generated Ask AI endpoint now passes `instructions` instead of the deprecated `system` option, and the optional provider peer dependencies moved to their AI SDK 7-compatible majors: `@openrouter/ai-sdk-provider@^3` and `@ai-sdk/openai-compatible@^3`. If your Ask AI backend uses one of those providers, upgrade the provider package when you update Blume; gateway-backed setups need no changes.
- 56979c0: Built-in image optimization for local images. A relative image reference (`![alt](./diagram.png)`) next to your content is now optimized at build time end-to-end — compressed, converted to WebP, and stamped with intrinsic `width`/`height` so the layout doesn't shift while it loads. sharp now ships as a Blume dependency, so the Astro image service works out of the box under every installer (it was previously unresolvable from the generated runtime under isolated linkers, failing the build with "Could not find Sharp"). Agent-facing surfaces (`/<route>.md`, `/<route>.mdx`, llms-full.txt, MCP) rewrite relative references to a new `/blume-assets/content/…` endpoint serving the original files, so image links in raw Markdown resolve instead of 404ing; the same endpoint serves remote-source assets materialized under `.blume/public/blume-assets`, which builds previously never shipped. A new `image` config (`domains`, `remotePatterns`) authorizes remote hosts for optimization, mapping directly onto Astro's `image` config.
- bd2b8cb: Custom fonts: `theme.fonts` roles now accept any Google/Fontsource/Bunny/Fontshare family by name (`{ name, provider?, weights?, fallback? }`) and local font files (`{ name, variants: [{ src, weight?, style? }] }`) alongside the curated slugs — all self-hosted and optimized through Astro's Fonts API. `seo.og.fonts` gains a matching local form (`{ name, src, weight?, style? }`), and when a config sets `theme.fonts` explicitly, the generated Open Graph cards now render in the theme's display and body fonts automatically (explicit `og.fonts` still wins; `og.fonts: []` opts out). Sites that never touched `theme.fonts` are unaffected.
- 6e293cf: Publish a Web Bot Auth signature directory from `ai.webBotAuth.keys`. The configured public JWKs are served at `/.well-known/http-message-signatures-directory` with the registered media type on every build surface (static hosts via `_headers`, Vercel server builds via a Build Output content-type override), advertised in `agent-readability.json`, and validated to be public-key-only — a JWK containing private material is rejected at config time.
- 64bac00: Publish Agent Skills for discovery from `ai.skills`. Point the new config field at a directory of skills (each subdirectory holding a `SKILL.md`) and the build publishes them per the Agent Skills Discovery RFC v0.2.0: single-file skills verbatim at `/.well-known/agent-skills/<name>/SKILL.md`, skills with supporting resources as deterministic `.tar.gz` archives (execute bits preserved), and a discovery index at `/.well-known/agent-skills/index.json` with the v0.2.0 `$schema` and per-skill SHA-256 digests. Artifacts get explicit media types on static hosts, the index is advertised in `agent-readability.json`, and spec-invalid skills are skipped with a build warning.
- 4e7a824: Generate an RFC 9727 API catalog at `/.well-known/api-catalog`. The linkset is derived from the site's configured APIs — each OpenAPI/AsyncAPI reference (anchored at its docs route, with `service-doc` and, for remote specs, `service-desc` relations) and the hosted MCP server (with its discovery document as the service description). Served as `application/linkset+json` on every build surface, advertised via a `rel="api-catalog"` homepage Link header and in `agent-readability.json`. Sites with no APIs emit no catalog.
- f4e6ce7: Serve Markdown to agents through `Accept: text/markdown` content negotiation on Vercel server builds. The build splices header-conditional rewrite rules into the Vercel routing config, so a content-page request that prefers `text/markdown` gets the page's raw-Markdown mirror at the same URL — with `Vary: Accept` on both variants — and `agent-readability.json` now advertises `contentNegotiation` only on deployments that honor the header.
- 7d426b2: Add `seo.og.site` and `seo.og.description` overrides for the generated OG card's footer URL and subtitle, and accept `false` on them (and on `seo.og.logo`) to hide that layer of the card entirely
- a730bef: Check DNS-AID agent discovery in `blume audit`. When `deployment.site` is set, the network tier (`--url`) queries `_index._agents.<host>` for ServiceMode SVCB/HTTPS records over DNS-over-HTTPS and reports the exact record to publish when none exist, plus whether the answers are DNSSEC-authenticated. Set `BLUME_DOH_URL` to use your own resolver.
- cacab69: Register WebMCP tools on every page. Agentic browsers with a model context (`navigator.modelContext` or `document.modelContext`, `provideContext` or `registerTool`) get the docs' read-only surface as in-page tools: `search_docs` (lazy-loads the configured search client on first call), `get_page` (a page's raw-Markdown mirror), and `list_pages` (the llms.txt index). The script is tiny and no-ops in browsers without the API. On by default; set `ai.webmcp: false` to opt out.
- 8567927: Advertise the agent-facing surface with an RFC 8288 `Link` header on the homepage. The header points agents at `agent-readability.json` and `llms.txt` (`rel="describedby"`) and the homepage's raw-Markdown mirror (`rel="alternate"; type="text/markdown"`), and is emitted on every surface Blume controls: the dev server, the `_headers` file on static builds (Netlify/Cloudflare), and the routing config on Vercel server builds.
- 8c46244: Align the MCP server card with the SEP-2127 Server Card extension schema. `/.well-known/mcp/server-card.json` now declares the published `$schema`, a reverse-DNS `name` derived from the site host, `title`, `websiteUrl`, and `remotes` transport endpoints (absolute, so present once the site URL is known), alongside initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. The advertised tool set and existing `transport`/`url` fields are unchanged.

### Patch Changes

- a92b52f: Align the table of contents, search results, search preview, and Ask AI scrollbars with the sidebar's thin scrollbar styling
- 1794284: Update katex to ^0.18.1
- a4f4a62: Update tailwindcss to ^4.3.3
- 4202f80: Rank Japanese and Chinese search results by whole compound terms rather than their parts. Dictionary segmentation cuts a term like 資金決済法 into 資金 / 決済 / 法, and because Orama scores a bag of words, a page mentioning each fragment somewhere could outrank the page the term is about — on one 65-page Japanese site every law-name query returned its index page first. Han, Hiragana and Katakana runs are now indexed as overlapping character bigrams, and queries on those indexes look for documents carrying all of a term's bigrams before falling back to the any-token default, so sentence-like queries still return their closest pages. Korean and Thai keep their segmented words, and Latin terms are still indexed whole — though on a Japanese or Chinese index a query of several Latin words now also prefers pages carrying all of them, with the same any-token fallback.
- 04d37f1: Give the code-block copy button a visible surface and cap code block height

  The copy button previously rendered transparent over the code, making it hard to see against syntax-highlighted lines. It is now an opaque chip with hover states and a check icon that swaps in after copying. Code blocks taller than 24rem now scroll vertically in place (on the inner code scroller, so the header bar and copy button stay put), with thin theme-colored scrollbars matching the sidebar treatment and a brighter thumb in dark mode. The scroller is keyboard-focusable (the tab stop moves from the pre to the element that actually scrolls), print output renders capped blocks in full, and the Component source pane keeps its own measured height. Copy success is now announced to screen readers via a polite live region, using the existing localized "Copied!" string.

- 76ce58f: Let Mermaid diagrams take the full content width instead of shrink-wrapping to the SVG's 300px fallback size; small diagrams stay centered and diagrams that set `useMaxWidth: false` still scroll horizontally
- cbec130: Include `deployment.base` in the generated OG card's footer site text, so a subpath deploy (like a GitHub Pages project site) shows `user.github.io/repo` instead of the bare shared host
- 87a3e9a: Drop empty table header rows. GFM requires a header row, so a table that doesn't want one is authored with blank header cells (`| | |`) — that used to render as a dead band above the body; the empty `<thead>` is now removed. A header cell containing any non-text content (an image, an icon) still counts as non-empty.
- 5951ee0: Support @sanity/client v7. The optional peer dependency range is now `^6.21.0 || ^7.0.0`, and `blume init` scaffolds new Sanity projects with v7.
- f3334cd: Harden two code-scanning findings: the WebMCP search tool now strips search-hit markup so no `<` fragment (such as a dangling `<script`) can survive mangled highlighting, and the API catalog trims the configured site origin with the linear `trimEnd` helper instead of a quadratic trailing-slash regex.
- 67bdef6: Define the `<skill>` placeholder in the blume-migrate skill so the codemod and oxfmt-patch commands resolve to the skill's own directory instead of failing on a literal `<skill>` path
- 1500d32: Resolve the bundled docs path from the installed `blume` package instead of a bare `node_modules/blume/docs`. The `blume` and `blume-migrate` skills now tell agents to locate the package from the workspace that depends on it (via `require.resolve('blume/package.json')`), so the docs lookup works in pnpm workspace monorepos where the package is not installed at the repository root.
- ea3c5fd: `blume audit --verbose` now prints each finding's full message under the affected page, so link checks name the broken target instead of only the page containing it.
- 3afcf7a: Move Blume's own `zod` dependency from v3 to v4 (`^4.3.6`), the major Astro 7, Scalar, and the MCP SDK already use, so an install resolves one Zod major instead of a v3 copy hoisted beside nested v4 copies. That mixed tree is what made partially updated `node_modules` (a restored CI cache that a dependency bump left half-reconciled) resolve Scalar's schemas against a Zod without `z.function().optional`, failing builds with `TypeError: z.function(...).optional is not a function`. Resolved configs and frontmatter parse exactly as before: shorthand defaults that Zod 4's `.default()` would return unparsed — collapsing blocks like `theme` or `seo` to a bare `{}` instead of their fully-defaulted shape — now use `.prefault()`, which keeps Zod 3's parse-the-default semantics. `frontmatter.extend` schemas still go through the Standard Schema contract, so any Zod version (or Valibot, or ArkType) works there unchanged.

---

# blume@1.3.1
Source: https://useblume.dev/changelog/blume-1-3-1

### Patch Changes

- 4d7dc87: Negotiate `Accept: text/markdown` on the homepage even when it's a landing page. A user-authored home page has no Markdown source, so agent requests for a markdown homepage previously fell through to HTML; the homepage's mirror now falls back to the `llms.txt` index — the machine-readable map of the site — served at `/index.md` and wired into the dev server, the Vercel routing config, and the homepage `Link` header's `rel="alternate"` entry.
- ff31ab5: Remove a polynomial-backtracking regex from the font-name slugifier's dash trim
- 02eb6c7: Fix the homepage `Link` header and `Vary: Accept` never being sent on Vercel deploys. The injected header routes sat after `handle: "filesystem"` in the Build Output config — the miss phase, which prerendered static responses never reach — so agent-readiness checkers saw no `Link` header on `GET /`. Both header routes now ride in the main phase, ahead of static-file matching.
- de62812: Stamp an `x-markdown-tokens` header (estimated token count, ~4 characters per token) on Markdown responses, following the Cloudflare Markdown for Agents convention: the raw-Markdown endpoints send it on dev and server-rendered responses, and the Vercel routing config carries it on the negotiated homepage.

---

# blume@1.4.0
Source: https://useblume.dev/changelog/blume-1-4-0

### Minor Changes

- 6afe539: Add declared facets: `content.types.<type>.facets` names custom frontmatter keys whose values become filterable metadata. Faceted values ride along on search documents (`blume-search.json` and the MCP snapshot), and the MCP `search_docs` and `list_pages` tools accept a `filters` object matching against them (`{"domain": "architecture", "status": "enforced"}`, every entry must match) — so a knowledge base holding RFCs, runbooks, or policies can drive progressive-disclosure agent workflows straight off its static content. Results carry their facet values, `list_pages` shows each page's, and the shared Orama index gains a `facetTerms` enum-array field so one static schema serves every project's facet keys. Each facet name must be a declared custom key (per-type or `frontmatter.extend`, validated at config load), and string, number, and boolean values facet — numbers and booleans stringified.
- 7e9f7dd: Add `blume translate`: agent-driven i18n translation with a committed freshness ledger and a CI drift gate.

  `blume translate --claude` (or `--codex`) finds every default-locale page that is missing or outdated in each configured locale and translates it headlessly with your local agent CLI — Blume builds the prompts, disables the agent's tools, validates each reply's structure (frontmatter reconstructed from the source, code-fence counts preserved), and writes the files itself. A committed `blume.translations.json` ledger records the source hash behind every translation, so reruns are incremental, and hand-authored translations are adopted rather than overwritten (only `--force` retranslates them). Under the `dir` parser, folder-nav `meta.ts` titles are translated too, copying every other key verbatim so per-locale sidebars keep their ordering. `blume translate --check` is the read-only CI gate: it exits non-zero when any translation is missing or stale, with `--json` emitting the shared diagnostics report shape.

- 6afe539: Let MCP clients filter by content type. `search_docs` and `list_pages` accept an optional `contentTypes` array that narrows results to pages of the given frontmatter `type`s (`["rfc"]`, `["blog", "changelog"]`), so an agent working against a site that mixes docs with RFCs, runbooks, or policies can scope retrieval to the kind of page it needs. Search hits now name their content type alongside the title, route, and excerpt, search documents carry the resolved type end to end (`blume-search.json` included), and the shared Orama index gains a `contentType` enum field filtered with an exact `where` match — the same mechanism the locale filter uses.
- 6afe539: Add per-type frontmatter schemas via `content.types.<type>.frontmatter`. Where `frontmatter.extend` declares custom keys site-wide, a per-type declaration scopes them to pages whose frontmatter `type` matches — so a project can require an RFC's `status` or a runbook's `service` without loosening every other page. Keys follow the same rules as `extend`: any Standard Schema library validates them (Zod at whatever version the project installs, Valibot, ArkType), every declared key is checked on every page of the type so required schemas enforce type-wide, and validated values land on the page record's `custom` field. A declaration for `content.defaultType` applies to pages that set no `type`, a key declared only for another type stays unknown elsewhere (typo-catching is unchanged), and a key can't be declared both site-wide and per-type.

### Patch Changes

- f88d256: Honor `Accept: text/markdown` on Cloudflare server builds. Deployed Workers sites ignored the header — the `.md` mirrors were reachable only at their explicit URLs — because the ASSETS binding serves the prerendered content pages before the Worker script runs, and even a request that does reach the Worker is answered by `@astrojs/cloudflare`'s handler straight from that binding, ahead of the only place Astro middleware runs. No middleware could ever see a content-page request, so the negotiation now lives in the deploy bundle itself: after `astro build`, Blume writes a small wrapper Worker in front of the adapter's entry and scopes `assets.run_worker_first` in `dist/server/wrangler.json` to the content routes (grouped into a handful of route globs, merged with any user-configured rules, and staying within Wrangler's rule limits).

  When the client prefers Markdown, the wrapper serves the page's prerendered `.md` mirror from the assets binding with `Vary: Accept`; every other request is delegated to the Astro Worker untouched, so only content routes pay the extra Worker hop. Cloudflare does not apply `_headers` to worker-first routes, so the wrapper re-stamps what the static layer would otherwise add on the routes it takes over — the homepage agent-discovery `Link` header, the homepage `x-markdown-tokens` estimate, and the Markdown `charset=utf-8` — while negative rules keep the raw `.md`/`.mdx` URLs on the static fast path with their `_headers` treatment intact. The agent readability manifest now advertises `contentNegotiation` on Cloudflare server builds too.

- bd939ba: Keep configured `redirects` off the Cloudflare worker-first routes, so they ship the status you configured instead of a permanent 301. On a server build Blume routes `redirects` through Astro's own config, and `@astrojs/cloudflare` turns those into `dist/client/_redirects` entries carrying the exact status — a file only Cloudflare's static layer reads. But `assets.run_worker_first` is derived from the _first path segment_ of the content routes, so a single page at `/docs/reference` emits `/docs/*`, which swallows every redirect under `/docs` — `/docs/api`, `/docs/api/run-query`, and so on. Inside a worker-first route the static layer never runs, `_redirects` is never consulted, and Astro's SSR redirect handler answers instead. That handler honors the configured status only when the destination resolves to a discrete route, which under Blume it never does (every page is served from `[...slug]`), so `computeRedirectStatus` defaults a GET to **301**. A configured 302 was therefore served as a permanent redirect that browsers cache more or less forever — the opposite of what a temporary redirect is for, and unfixable from the config.

  The generated Worker wiring now emits a negative `run_worker_first` rule for every configured redirect a positive rule would otherwise claim, so the static layer keeps serving it. The exemptions are derived from the merged rule set, so redirects claimed by your own `run_worker_first` rules are exempted too (a configured `true` is rewritten to its array spelling `/*` so the negatives can ride along), and they compare full served URLs, so subpath deploys (`deployment.base`) guard their content routes correctly. A redirect that no rule would have claimed gets no rule, and a path that is also a content route is never exempted — the page owns it, and taking it off the Worker would silently disable its Markdown negotiation; a docs-only site redirecting `/` is exempted like any other path. A retired section collapses to a `{path}` + `{path}/*` pair, which is two rules however many URLs it held, but only when no content route lives underneath, and only the request spellings a positive actually claims are emitted, conserving Wrangler's cap of 100 rules. A rule over Wrangler's 100-character limit collapses to its nearest safe ancestor glob instead of costing the whole site its negotiation. The exemptions ride along into the coarse fallback, where `/*` claims everything and they matter more rather than less; if even that cannot fit the limits the negotiation is skipped entirely, since a redirect cached as permanent is a worse outcome than raw Markdown staying at its explicit `.md` URL.

- 2e231bc: Serve configured `redirects` from the generated Cloudflare Worker itself instead of carving them out of `assets.run_worker_first`. The wrapper Worker now bakes in a redirect table and answers any redirect a worker-first rule claims with its exact configured status, before delegating to the Astro Worker; redirects outside every worker-first rule still never invoke the Worker and are served by the static layer from `_redirects`, as before.

  Unlike the negative-rule exemptions this replaces, a baked-in table costs nothing against Wrangler's caps of 100 rules and 100 characters — so a large or deeply nested redirect set can no longer push the rule set into the coarse fallback or cost the site its `Accept: text/markdown` negotiation, and redirects claimed by your own `run_worker_first` rules (including a bare `true`) are answered correctly without rewriting your configuration. A redirect at a content route's own path is still never honored — the page owns it — and non-ASCII destinations are percent-encoded into the `Location` header.

- 50a9ea7: Keep `blume dev` from tearing down React islands built from project components. The generated runtime is the Vite root, so user pages, islands, and alias-reachable components were invisible to the dep optimizer's startup scan — and the Babel-injected `react/compiler-runtime` import can never be scanned — so their dependencies were only discovered mid-session. That re-optimization served a second React copy to islands hydrating at that moment, crashing them with "Invalid hook call". The generated config now points the optimizer's startup scan at user pages, the `islands/` directory, and tsconfig-alias directories, and force-includes the compiler runtime, so every dependency hydration can reach is part of the first optimization run.
- 7e9f7dd: Backfill every built-in UI language pack with the chrome strings added since launch — the Export menu, "Copy code", "Copy Codex command", the Ask AI panel, navigation and theme-toggle labels, the 404 page, and the newer search dialog strings — so localized sites no longer show English for those surfaces. The "Open in v0/ChatGPT/Claude/…" provider labels, previously hardcoded, now localize through a new `actions.openIn` template (`"Open in {name}"`).
- b62278b: Emit `_headers` on a Cloudflare server build, so the agent-discovery surface it already generates is actually advertised.

  `buildHomeLinkHeader()` had three consumers and every one excluded this deployment: the `_headers` writer returned early unless `output === "static"`, the Vercel routing-config injection only runs for that adapter, and the middleware that calls `res.setHeader("Link", …)` is mounted on `astro:server:setup`, so it is dev-only. A Cloudflare _server_ build therefore served no homepage `Link` header at all, and no `Content-Type` on the extensionless well-known files — an API catalog went out with no media type rather than `application/linkset+json`.

  The gate is now `readsHeaderFiles()`, which is true for any static build and additionally for a Cloudflare server build: the Worker serves `dist/client` through its ASSETS binding, and Workers static assets honor `_headers` from that directory exactly as Pages does. Node server builds stay excluded, because the standalone server's static handler ignores the file and writing it there would be inert. Vercel server builds stay excluded because their headers arrive through the routing config, which this would duplicate.

  Two related corrections fell out of testing it against a real Cloudflare server build, and both apply to static builds as well:

  - The user opt-out is now checked at `public/_headers` rather than in `dist`. `@astrojs/cloudflare` writes its own `_headers` during the build (an immutable `Cache-Control` for `/_astro/*`), so testing `dist` read an adapter-generated file as a user opt-out and skipped silently — the fix above would not have fired without this.
  - When a `_headers` already exists in the output, its rules are preserved and the generated ones are appended, so the adapter's caching rule and Blume's discovery rules coexist. On a static build this changes behavior for a `_headers` that reached `dist` some way other than `public/` (an integration writing it directly, say): that file previously suppressed generation entirely and is now appended to. Shipping `public/_headers` remains the opt-out.

  The charset rules in this file remain redundant on a server build, where the runtime endpoint sets `Content-Type` on the Response itself; they are harmless, because a static-asset rule only applies to a file served from that directory. The `Link` and well-known media-type rules are the part that was missing, and the previous comment's reasoning — that server adapters set Content-Type themselves — was true of the charset rules only and had been applied to the whole file.

- f9f045c: Fix `blume check` failing on the generated MCP endpoint when `ai.mcp` is enabled. JSON imports widen literal types, so `mcp-data.json` could never satisfy `McpData`'s discriminated navigation nodes; the generated endpoint now asserts the snapshot back to `McpData` at the JSON boundary.
- 7e9f7dd: The header's search field and language switcher now collapse to compact icon buttons below the `lg` breakpoint (previously `sm`), and the logo mark no longer shrinks when the header runs out of room — fixing the mid-width squeeze where the inline tab bar pressed the two controls into each other.
- eb8e1dc: Restore the content inset on `Tab` panels that mix a code fence with prose. The panel dropped its padding via `:has(>pre)`, a rule meant for code-only panels — a fence owns its own frame, so insetting it again double-pads it. But the bare selector also matched a panel holding a fence _and_ prose, stripping the padding from the prose as well; combined with `[&>:last-child]:mb-0!` a trailing paragraph ended up flush against the panel border with no space on any side, and lost its left inset so text started hard against the frame. The rule is now `[&:has(>pre):not(:has(>:not(pre,template)))]`, so `p-0` applies only when the panel holds nothing but fences and mixed panels keep the inset like every other code-block host. `template` is excluded because a `Tab` with an `icon` renders a `<template data-blume-tab-icon>` that stays a permanent child — the tabs script clones its content into the trigger rather than moving the node. That rules out the two naive "is the fence alone?" tests, each for a different reason: `:only-child` sees two children on every icon tab and so silently reintroduces the double inset, while `:only-of-type` ignores the `template` (it only counts sibling `pre` elements) and therefore matches a single fence but stops matching a code-only panel holding two or more of them.
- aa33ae7: Write a Cloudflare server build's artifacts where the Worker can actually serve them. `@astrojs/cloudflare` declares `preserveBuildClientDir: true`, so it keeps Astro's `dist/client` + `dist/server` split and points the ASSETS binding in the `dist/server/wrangler.json` it generates at `../client` — the deployed Worker serves `dist/client` and nothing above it. Blume still treated `dist/` as the served root, so `robots.txt`, `sitemap.xml`, `llms.txt`, `llms-full.txt`, `agent-readability.json`, `.well-known/api-catalog`, and the Pagefind index all landed one directory too high and 404'd in production, and `blume audit` crawled `dist/` and read `client/` as a route segment, reporting ~118 phantom broken links. `deployStaticDir` and its isolated-build mirror `isolatedStaticDir` now resolve to `dist/client` for a Cloudflare server build, matching the existing Node standalone handling. Cloudflare static builds are unaffected — they have no client/server split, so the `outDir` root is still what ships.
- 8d4fd17: Allow `search.popular` icons to use image paths/URLs and inline SVG, matching nav icons. Markup is resolved on the server before the Cmd+K island runs.
- 7e9f7dd: Header tab labels (and tab dropdown item labels) accept a per-locale map alongside the plain-string form: `label: { en: "Docs", fr: "Documentation" }`. Each locale's navigation resolves its own entry, falling back to the default locale's and then the map's first entry, so an i18n site can translate its header without forking the config.
- 7e9f7dd: Locales accept an optional `style` — freeform guidance like "Brazilian Portuguese, informal você" that rides along in every `blume translate` prompt, pinning register and dialect from a locale's first translation and winning over an existing translation's style on reruns.
- 7e9f7dd: `blume translate` now shows the agent the existing translation when retranslating a stale page and instructs it to match its register, dialect, and terminology, so a small source edit yields a minimal retranslation instead of a from-scratch rewrite that can flip style.

---

# blume@1.4.1
Source: https://useblume.dev/changelog/blume-1-4-1

### Patch Changes

- 8865982: The built-in Ask AI panel now streams through the public `useAskAI` hook instead of carrying its own near-identical copy of the client — one implementation now owns request shaping, the optimistic assistant bubble, stale-stream and abort guards, and the error-body-is-not-an-answer rule. `useAskAI` gains an optional `errorMessage` option so custom UIs (and the built-in panel, which passes its localized dictionary string) can control the failure notice shown in the transcript.
- dc5c97a: Measure WebP and AVIF images in the audit's Open Graph checks. The hand-rolled header parser only understood PNG, JPEG, and GIF, so builds whose image pipeline emits modern formats — including Blume's own sharp-based optimization — silently skipped every OG image dimension check. Dimensions now come from the image-size package, which covers 25+ formats; unknown or truncated files still yield no finding.
- 57e1525: Watch project inputs in `blume dev` with chokidar. Raw `fs.watch` required two documented platform workarounds — watching single files through their parent directory so rename-replace saves (vim and most atomic-save editors) don't orphan the watcher, and `recursive` handling for directories. chokidar (the watcher Vite itself uses) owns both, and one watcher now covers the pages directory, config, theme, and component override files.
- 9dfabd6: Respect `NO_COLOR`, `FORCE_COLOR`, and terminal detection in all CLI output. Diagnostics, the audit/eval/translate reports, and internal error reports previously emitted raw ANSI escape codes unconditionally, so piping a command to a file (`blume validate > report.txt`) or reading CI logs outside a color-capable terminal showed literal `[31m` sequences. All five hand-rolled palettes now go through consola's color utilities, which disable styling when the output is not a color-capable terminal and honor the standard `NO_COLOR`/`FORCE_COLOR` overrides.
- 28f2a9d: Escape HTML through one complete entity table. Four call sites each hand-rolled their own escape map with different coverage: the search popular-links icon markup escaped only `&` and `"` while building an `src` attribute, the fallback code-block renderer escaped only `&`, `<`, and `>`, and the search dialog and XML feeds carried their own full tables. All four now use html-escaper's five-entity escape (the same one Astro uses internally), so every site covers `&`, `<`, `>`, `"`, and `'` consistently.
- 7af2f4a: Check the Node version in `blume doctor` against the package's full `engines.node` range with semver. The previous check stripped the range down to a bare version triple and compared segments numerically, so any real range expression (`^22.12.0 || >=24`, prerelease tags) degraded into comparisons against `NaN` and the check silently stopped working.
- 6d7abb4: Parse `.env` files with dotenv — the same parser Vite applies to these files at build time. The previous line-based parser silently truncated multi-line double-quoted values at the first newline, corrupting PEM-style credentials (`-----BEGIN PRIVATE KEY-----` blocks) before the content scan could use them, and its escape handling diverged from what the rest of the toolchain sees in the same file. The `.env.local`/`.env` cascade from the working directory up to the repository root is unchanged, and shell/CI values still win.
- 016e5cf: Use the unified ecosystem's own utilities for two hand-rolled markdown helpers: directive label text extraction now goes through `mdast-util-to-string`, and the `<TypeTable>` Markdown downlevel builds its GFM table with `markdown-table`, which owns delimiter-row and cell padding rules instead of string concatenation.
- 738c071: Replace the hand-rolled image lightbox with medium-zoom. The `markdown.imageZoom` behavior is unchanged — click to zoom, dismiss on click/scroll/Escape, opt out per image with `data-no-zoom`, images inside links stay plain — but the FLIP transform math, natural-size capping, and transition-teardown races now belong to a 2 kB library built for exactly this. The library is lazy-loaded only on pages that contain a zoomable image, and reduced-motion preferences disable the transitions as before.
- 863ad44: Generate OpenAPI request examples with openapi-sampler, the generator behind Redoc. Two visible improvements over the hand-rolled sampler: `readOnly` fields no longer appear in request-body samples (they are server-generated and were previously included even though the schema declared them read-only), and format-aware placeholders replace generic ones — `email`, `uuid`, `uri`, and friends produce realistic values instead of `"<format>"`. Declared `example`/`const`/`default`/`enum` values keep their precedence, and circular `$ref` chains still terminate safely.
- 19de528: Derive changelog meta descriptions by parsing release notes as GitHub-flavored markdown (mdast) instead of chaining strip regexes. The regex chain mis-handled real release-note shapes: tilde fences and fences of more than three backticks leaked their code into the description, an image followed by a link containing `)` truncated wrong, and prose like `a * b` or `x > y` lost characters to a blanket punctuation strip. The parsed tree drops headings, code, and raw HTML; keeps link text and inline-code content; and the word-boundary truncation is unchanged.
- 4d0590b: Match remote source `include` globs with picomatch — the same engine the filesystem source already uses through tinyglobby. The remote MDX source previously compiled globs with a minimal hand-rolled translator, so the same `include` array meant different things depending on source type: negation patterns (`!drafts/**`), character classes (`[0-9]`), nested braces, and extglobs silently failed to match on remote sources. The matcher is now also compiled once per enumeration instead of once per file × pattern, which matters on large GitHub trees.
- 842ed9c: Remove single-call delegation wrappers left over from the library migrations: the remote source's glob-matcher factory, the search dialog's `escapeHtml`, the XML escaper module, the directive label's text collector, and the env-file `parseEnv` export now call picomatch, html-escaper, mdast-util-to-string, and dotenv directly. Wrappers that carry real behavior (the atomic-write helper's mkdir/fsync policy, the audit image sizer's null-on-unknown contract, the OpenAPI sampler's error guard) are unchanged. If you deep-imported the undocumented `escapeHtml` from `blume/components/layout/search/types`, import `escape` from html-escaper instead.
- 909c2fd: Fix two false-positive sources in the audit's robots.txt check by matching rules with robots-parser. The hand-rolled matcher never read `Allow:` directives, so the common lockdown pattern (`Disallow: /` plus `Allow: /docs/`) flagged every sitemap URL as blocked; and it treated each `User-agent:` line independently, so consecutive agent lines heading one rule group (as the spec defines) dropped rules that do apply to `*`. robots-parser resolves Allow/Disallow by longest match and handles agent groups correctly; wildcard and `$`-anchor behavior is unchanged.
- 7120f63: Parse sitemaps in the audit with fast-xml-parser instead of regex scanning. Sitemaps the audit reads can come from other generators (including remote ones during network audits), and three legal constructs were invisible to the regex scan: CDATA-wrapped `<loc>` values, numeric character references like `&#38;`, and namespace-prefixed elements (`<sm:loc>`). All three now parse; the shallow contract — the loc list, per-loc lastmod, and urlset-vs-index detection — is unchanged.
- 57673ee: Parse the project's tsconfig with get-tsconfig when deriving `@/`-style Vite aliases. The hand-rolled JSONC parser could corrupt a config whose string values contained `", }"` (its trailing-comma strip ran over string contents), and its `extends` resolution accepted two forms real tsc rejects (relative paths naming a directory, bare specifiers resolved through a package `main`). get-tsconfig follows tsc's own semantics — JSONC, the full `extends` chain including TS 5.0 arrays, inherited-path rebasing, and `${configDir}` substitution, which now works in alias targets.
- 8e9f3d0: Make atomic file writes safe under concurrency. The translation runner, its ledger, and the runtime generator each wrote through a temp file named `<path>.<pid>.tmp` — a name that is not unique within a process, so two concurrent writers to the same target (translate lanes run up to 16-wide; staged content writes fan out in parallel) could interleave through a shared temp file. All three now write through npm's write-file-atomic, whose temp names are unique per call and which preserves file modes on overwrite.

---

# blume@1.4.2
Source: https://useblume.dev/changelog/blume-1-4-2

### Patch Changes

- fdfd1fe: Advertise agent discovery in every page's head, not just the homepage header

  An agent that enters the site on a deep page — a search result, a shared link — never sees the homepage-only `Link` response header, so it had no path to `agent-readability.json`. Every rendered page now carries the discovery links in its HTML head: `describedby` links to `agent-readability.json` and `llms.txt`, plus a `text/markdown` `alternate` pointing at the page's own raw-Markdown mirror. Because the links travel with the prerendered HTML, they also work on hosts where Blume can't set response headers at all (GitHub Pages, S3).

- 5f735ae: Raise minimum versions of astro, mermaid, dompurify, undici, js-yaml, and @astrojs/vercel to pull in upstream security fixes

---

# blume@1.4.3
Source: https://useblume.dev/changelog/blume-1-4-3

### Patch Changes

- c19bfeb: Render Ask AI answers through a dedicated `Marked` instance instead of mutating the shared `marked` singleton, so other components importing `marked` no longer inherit the panel's `breaks` option and citation link rewriting.
- d16f0a5: Keep keyboard focus inside the Ask AI panel while it is a small-screen overlay: everything behind it turns inert until it closes, so Tab no longer escapes into the covered page. The desktop docked panel stays non-modal and the page remains interactive.
- e59cbd2: Add `ai.ask.instructions` for custom system-prompt text (identity, language, tone). It is appended to the built-in instructions on every backend, so the grounding and citation contract stays intact.
- 421fa82: Locate Ask AI grounding excerpts for queries in languages written without word spaces. Query terms are now segmented with `Intl.Segmenter` (with a Unicode-aware regex fallback) instead of a Latin-only pattern, so Japanese, Chinese, Korean, and Thai questions center the injected excerpt on the matching section instead of always sending the head of the page. Content and query are NFC-normalized so decomposed text still matches.
- e59cbd2: Warn at build time, naming the exact package to install, when the configured Ask AI backend's provider SDK isn't installed — instead of failing with an opaque unresolved-import error.
- 9a1b71c: Bound concurrent file reads during audit crawling, example/island discovery, and math detection with `p-map`. These previously fanned out one unbounded `fs` call per discovered file, which on large sites risked `EMFILE` and held every page's HTML in memory at once.
- 9156701: Keep punctuation out of the index terms the segmenting search tokenizer produces. `Intl.Segmenter` follows UAX #29, which holds connector punctuation, combining marks, format characters and mid-number punctuation _inside_ a word, so `スネーク_ケース` and `robots.txt` each arrived as a single word-like segment and were indexed as they stood — reachable only by retyping the punctuation, and unreachable from `ケース` or `txt`. Word-like segments made of nothing but a symbol became index terms of their own. Segments are now split into runs of letters, combining marks and digits — marks are spelling, so Thai vowel and tone signs and the voicing in decomposed kana survive, as do a word-internal apostrophe (`don't`) and punctuation flanked by digits (`1.0.3`, `1,000`) — and each boundary ends a bigram run the same way a space or an interpunct does, so no window spans it. Text is also NFC-normalized before segmenting, so decomposed input indexes the same terms as a composed query.
- 051bceb: Count audit prose words with `Intl.Segmenter` seeded by the page's `lang`. The whitespace split it replaces counted a fully written Japanese or Chinese page as a handful of "words", tripping `BLUME_AUDIT_LOW_WORD_COUNT` on every page of a CJK site.
- 156d5ff: Preserve the request query string when the Cloudflare wrapper Worker answers a configured redirect. The baked-in redirect table now matches the static layer's `_redirects` semantics: the incoming query string is forwarded to the destination unless the destination specifies its own, so inbound links carrying UTM or ref parameters keep them across a retired URL.
- 2cb73cc: Slug Accordion, Tab, and Update ids through `github-slugger` via one shared helper instead of three identical per-component copies. Component ids now slug exactly like heading anchors: unicode letters are kept (`Español` → `español` instead of `espaol`) and underscores survive. Titles that relied on the old ASCII-only stripping get new ids, so hash deep-links to such components change once.
- c37b42a: Consolidate four divergent route normalizers (OpenAPI references, Ask AI retrieval, the MCP server, and the Scalar page generator) onto one shared `normalizeRoute` in core, and retire the last quadratic edge-trimming regexes in favor of the linear `trim` helpers.
- 92e1d2e: Spawn agent CLIs (claude/codex handoffs, eval and translate runners) through `cross-spawn` instead of `shell: true` on Windows. cmd.exe no longer parses the argument list — codex's `-c` flags carry JSON that shell quoting could mangle, and the interactive handoff no longer hand-builds a quoted command line — and a missing executable now rejects with `ENOENT` on every platform instead of surfacing as cmd.exe's exit code 9009.
- d56e235: Declare `p-retry` and `nanotar` as dependencies. Both were imported by `openapi/parse.ts` and `ai/tar.ts` but only declared in the monorepo root, so installs of the published package could fail to resolve them.
- be0d582: Deduplicate the `escapeRawHtml`/`unwrapParagraph` helpers that were copied verbatim into `<Prompt>`, `<Frame>`, and `<Tooltip>` into one shared module. No behavior change.
- e5a374a: Hand the CLI's `.env`/`.env.local` cascade to `dotenv.config({ path })` instead of a hand-rolled apply loop. The walk up to the repo root stays; the first-wins ordering, never-clobber-`process.env` semantics, and best-effort file handling now come from dotenv itself.
- d67135f: Cut GitHub Releases meta descriptions on grapheme boundaries. The UTF-16 slice could split a surrogate pair at the 160-character cap, emitting invalid Unicode (a lone surrogate) into `seo.description`.
- 5056321: Harden the search excerpt sanitizer: any `<` that does not begin a bare `<mark>` tag is now entity-escaped instead of passed through. A remote excerpt containing `<!--` could previously open an HTML comment inside the results list and swallow the rest of the excerpt, highlights included. Rendering of legitimate text is unchanged.
- 7c37792: Keep the Ask AI overlay's inert sweep current while it is open. The sweep snapshotted `<body>`'s children at open time, so anything portaled in afterwards (an image-zoom backdrop, a mermaid render, another island) stayed tabbable behind the overlay; a MutationObserver now folds late arrivals into the sweep.
- 614ecb2: Measure header logo SVG dimensions with `image-size` instead of a hand-rolled attribute regex. This is the same parser the OG card already uses for the brand mark, so the two can no longer disagree about one logo, and spellings the regex missed (unquoted attributes, `em`/`pt` lengths, a `>` inside another attribute value) now measure correctly.
- 0db1528: Define each MCP tool's input once in zod and derive both the runtime argument parsing and the JSON Schema advertised by `tools/list` from that single definition, so the two can no longer drift. The lenient agent-friendly coercions are preserved: a bare string is accepted for an array field, `[]`/`{}` mean "no filter", and out-of-range limits clamp instead of rejecting.
- 9229cf2: Extract search-index plain text by parsing Markdown (GFM included) and walking the tree instead of regex-stripping the source. Reference-style links, autolinks, setext headings, and table cells now index their text; literal `*`/`~`/`>` in prose are no longer blanked; and the inner prose of block-level JSX components stays indexed. Applies to the client index and every hosted-provider sync, so rankings may shift slightly on re-index.
- fec3400: Build agent-skill `.tar.gz` archives with `nanotar` instead of a hand-rolled ustar writer, keeping the path validation, deterministic attributes, and sync gzip layer. The header byte layout changes once with this release, so each published skill's archive digest changes on the next build; digests remain stable from then on and are now pinned by a golden test.
- b6fe173: Pace Notion source API requests through a bounded request pool (default 3 concurrent, configurable via `concurrency`) and jitter the 429 backoff, so large databases import within Notion's rate limits instead of failing the build with `BLUME_SOURCE_FETCH_FAILED`.
- 9560ed2: Measure the OG-card brand mark's aspect ratio with `image-size` (already a dependency) instead of a viewBox regex. Legitimate SVG spellings the regex missed — `viewBox = "…"` with spaces, newline-separated values, explicit width/height attributes without a viewBox — no longer silently render a squashed square mark.
- fc92c24: Flatten OpenAPI descriptions into meta descriptions with a real markdown parse (`mdast-util-to-string`) instead of regex stripping. Literal punctuation in spec prose survives — `snake_case` no longer becomes `snakecase`, `C#` no longer becomes `C` — in the `seo.description` tags of generated reference pages.
- 7f1b355: Leave tilde-fenced code blocks in OpenAPI spec descriptions verbatim when escaping MDX-special characters, matching how backtick fences are already handled. Braces inside a `~~~` fence no longer ship as literal `&#123;` entities on rendered reference pages.
- ea04c90: Replace three hand-rolled concurrency pools with `p-limit`/`p-map`: the Notion source's request semaphore, the link-audit probe pool, and the translate runner's worker lanes and ledger-flush mutex. Behavior is unchanged — bounds, FIFO ordering, and the flush-before-next-item guarantee all carry over — with ~100 fewer lines to maintain.
- 40cb5d1: Drive remote OpenAPI spec fetch retries through `p-retry` instead of a hand-rolled loop. The behavior is unchanged — three attempts, exponential backoff capped at 10s, non-retryable statuses abort immediately, and a sane `Retry-After` replaces the backoff rather than stacking on it (now covered by a test).
- b15a87a: Render `package-install` command tabs through `package-manager-detector` (the engine behind `ni`), with the yarn tab pinned to Berry. Previously the yarn tab mixed Berry-only commands (`yarn dlx`, `--immutable`) with Classic-only ones (`yarn global add`), so no single yarn version could run every rendered command; global installs on the yarn tab now render npm's form, since Berry removed `yarn global`. `blume eject` also detects the project's package manager from its lockfile instead of only the invoking user agent, which was absent (silently defaulting to npm) whenever the CLI was run directly.
- 39367e2: Strip all markup except bare `<mark>` highlights from Pagefind excerpts before rendering them in the search dialog and preview pane, so a compromised or tampered search index can't inject HTML into reader pages. The other providers already escape their excerpts.
- 0900dc7: Parse `llms.txt` link targets with a real Markdown parse instead of a `](url)` regex in the audit crawler. Reference-style links and angle-bracket destinations now resolve, link titles no longer leak into URLs, and link-shaped strings inside fenced code blocks are no longer probed as claims.
- 4b04a52: Locate code regions in OpenAPI descriptions with a CommonMark parse instead of fence-emulating regexes when escaping MDX-special characters. The parser is the authority on backtick pairing, tilde closers, unclosed fences, and fences nested in blockquotes (which the regexes mis-handled by escaping entities into the quoted code). Indented blocks keep escaping as prose — MDX has no indented code form.
- abd6be5: Collapse the dev server's regeneration debounce and single-flight coalescer into `perfect-debounce`, whose contract covers both: watch bursts debounce at 80ms and a trigger during a running scan marks exactly one trailing rerun instead of starting an overlapping scan. The heap-exhaustion guarantee the old coalescer carried is pinned by a dedicated test against the library.
- f2ca3f6: Escape Markdown syntax in Portable Text prose spans. Span text is plain text by the Portable Text contract, but a literal `*`, `_`, `[`, backtick, `~`, or `<` typed in Sanity was interpreted as Markdown or raw HTML in the rendered page; those characters now render as themselves. Code-marked spans stay verbatim.
- 61a1146: Coalesce the page-actions menu and `<Component>` preview-pane resize handlers to one layout pass per animation frame. Both previously re-read layout on every resize event, causing needless main-thread churn during a live resize drag.
- 2094270: Honor the HTTP-date form of `Retry-After` (RFC 9110's `Wed, 21 Oct 2015 07:28:00 GMT` spelling) when retrying remote OpenAPI spec fetches. Previously only delta-seconds were parsed and date values were silently ignored.
- 3d6789b: Strip `:` and control characters from filename-derived route segments, so files like `Guide: Architecture.md` build instead of crashing route generation with "The URL must be of scheme file".
- a7ad63a: Give the search dialog proper combobox semantics: the input announces as `role="combobox"` with `aria-expanded`/`aria-controls`/`aria-autocomplete`, results render in a labeled `role="listbox"` with grouped `role="option"` rows, and the highlighted result is surfaced through `aria-activedescendant` and `aria-selected`. Screen readers previously heard nothing while arrowing through results.
- 1a83df2: Guard the search dialog's localStorage reads and writes so blocked storage (Safari "Block All Cookies", sandboxed webviews) degrades to session-default preferences instead of throwing during setup and leaving search unable to open.
- 3b59b8f: Hash staged source content and asset filenames with SHA-256 (64-bit prefix) instead of a 31-bit DJB2 hash. The old hash named downloaded CMS assets, where a collision — plausible from ~46k items — silently served the wrong file. The first build after upgrading re-downloads remote source assets once under the new names.
- f14ac3f: Consolidate the six hand-rolled clipboard + "Copied" flashes (code blocks, page actions, color swatches, prompts, API panels, Ask AI) into one shared helper. Every copy affordance now announces success to a screen-reader live region (previously only code blocks did), never confirms a failed write, and holds its confirmation through rapid repeat clicks instead of reverting early.
- e511d02: Join `deployment.site` with emitted paths through one shared helper built on `ufo`'s `joinURL`. Eight emitters (sitemap, RSS, robots, llms.txt, the MCP server and discovery documents, the API catalog, agent-readability) had drifted across three different trailing-slash treatments; they now agree, and a site configured with extra trailing slashes can no longer produce double-slash URLs.
- 19f1f7d: Split the sitemap into a sitemap index over numbered `sitemap-N.xml` chunks when a site exceeds 50,000 URLs, the per-file cap search engines enforce. Smaller sites keep the single classic `sitemap.xml`.
- c3f058d: Keep Unicode letters in OpenAPI tag slugs, and label tag sidebar groups with the spec's own tag names. Slugs derived from OpenAPI tag names and reference-source labels now keep Unicode letters and numbers (with NFC normalization) instead of stripping them to hyphens, and tag sidebar groups take their label directly from the spec's `tags[].name` (overridable with a `meta.ts` title), so authored casing like `OAuth2` or `Größe` renders verbatim. Note that operation-page URLs change for specs whose tag names, operation ids, or source labels contain non-ASCII characters — if such URLs are already deployed, add entries under `redirects` in `blume.config` to forward the old routes.
- e81ab33: Harden the search excerpt sanitizer against tag splicing: every `<` is now consumed by a single scan, so dropping a disallowed tag can no longer join the text around it into a fresh one.
- 6c747bc: Treat a document-leading `---` followed by a blank line, or one with no closing fence, as a thematic break instead of front matter, so bodies that open with a divider (e.g. a Notion page whose first block is one) build instead of crashing with a YAML parse error.
- 032df5f: Keep Unicode letters in CMS/frontmatter slugs. The slugifier's ASCII-only keep-class deleted every non-ASCII character, so a Japanese/Chinese/Cyrillic `slug` collapsed to empty (forcing Sanity/Notion routes onto opaque document-id fallbacks) and accented slugs were mangled (`café` → `caf`). ASCII slugs are byte-identical; sites with non-ASCII CMS slugs get readable routes where the id fallback previously applied — set up redirects if those fallback URLs were shared.
- 0ade7e6: Resolve OG card accent presets from the theme's own OKLCH palette instead of a separate hand-synced hex table. The card's "blue" was Tailwind's blue, not the site's — social cards now render exactly the accent the site shows. Custom (non-preset) accents are unaffected.
- edf5b78: Fix the `/blume-assets` endpoint's traversal guard on Windows: it compared a forward-slash directory against `path.resolve` output (backslashes there), which 404'd every staged remote-source asset. The guard now uses `path.relative`, which also closes the sibling-directory-name edge a bare prefix test admits.

---

# blume@1.5.0
Source: https://useblume.dev/changelog/blume-1-5-0

### Minor Changes

- 94b0678: Add docs versioning. The latest documentation lives at the content root with unprefixed URLs; each past version is a frozen snapshot directory cut with the new `blume version <id>` command, which copies the tree, rewrites root-absolute links to stay inside the snapshot, and registers the id in `blume.config.ts`. With a `versions` block configured, the header grows an automatic version switcher (same-page navigation, falling back to the version root), every archived page shows a localized "you're viewing an old version" notice with a go-to-latest link, and archived pages default their canonical to the same page in the live docs — the SEO treatment guides recommend and no docs framework automates — while version-only pages stay self-canonical and per-version `canonical: "self"` and `noindex` remain available. Search scopes results to the version being viewed with a remembered "All versions" toggle across Orama, FlexSearch, Algolia, and Typesense, and the agent surface is version-aware: the MCP `search_docs`/`list_pages` tools default to the current docs and accept an archived id or `"all"` (plus a new `locale` filter), `get_navigation` serves snapshot and per-locale trees, `llms.txt` sections archived versions with an "(archived)" label, `llms-full.txt` stays current-only, and the sitemap drops archived pages whose canonical points at a live equivalent. Versioning composes with i18n (snapshot outermost on disk, locale outermost in URLs), snapshots keep their own folder meta and translations, and `blume translate` never retranslates them.

### Patch Changes

- b954287: Tighten types across the package: `unknown`-typed parameters, returns, and open dictionaries are replaced with precise named types, and every remaining type assertion carries a documented invariant (adopting ultracite's anti-slop lint preset).
- c8d1624: Native AsyncAPI renderer. The `asyncapi` block now defaults to `renderer: "blume"` — one real page per `send`/`receive` operation, grouped by tag (or channel address) in a tab-scoped sidebar, with message payload and header schema tables, channel parameters, protocol bindings, an Authorization section derived from `securitySchemes`, protocol-aware code samples (`wscat`/`WebSocket` for ws, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT), and full participation in site search, `llms.txt`, and OG images. AsyncAPI 2.x specs are normalized to 3.x automatically with the official AsyncAPI converter, so `publish`/`subscribe` map onto stable operation URLs. The `asyncapi` block gains `renderer`, `codeSamples`, and `expandSchemas` for full parity with `openapi`; per-source `includeInSearch`/`includeInLlms`/`noindex` now apply to AsyncAPI sources too.

  **Behavior change:** AsyncAPI references were previously always rendered by the embedded Scalar SPA. Set `asyncapi: { renderer: "scalar" }` to keep the old behavior.

- 84055a7: Measure the audit's title and meta-description limits in display columns rather than characters. What a search engine truncates is the space the text takes up, and a character count only stands in for that where every character is one column wide — true of Latin text and of nothing else. Counted in characters, one range cannot serve both scripts: the same 110–160 was at once too strict for a Japanese description (which says in ~60 characters what English needs ~120 for, so every page of a Japanese site reported `BLUME_AUDIT_DESCRIPTION_LENGTH`) and too loose for a Japanese title (60 characters render as wide as 120 Latin ones and truncate, and nothing was reported). Widths come from `string-width`, so a fullwidth or wide character counts 2 and ASCII or precomposed (NFC) Latin text scores exactly as it did before — an English site's findings are unchanged. (Two knowable divergences: an emoji now counts 2 columns instead of its UTF-16 code units, and a decomposed (NFD) combining mark counts 0 instead of 1.) The changelog and OpenAPI generators, which trim their derived meta descriptions to the same snippet range, now budget in display columns too, so generated pages keep passing the audit in every script.
- a749fd7: `blume eject` no longer drops `ai.ask.instructions`: the ejected Ask AI endpoint now carries the custom system-prompt text, matching the hidden runtime.
- eab66c5: Per-group sidebar display modes on the generated sidebar. A folder can opt its group into `flat`, `group`, or `page` without an explicit `navigation.sidebar` config: set `display` in the folder's `meta.ts`, or — sugar for folders with an `index` page — `sidebar.display` in the index page's frontmatter. A generated group's effective mode resolves index frontmatter first, then folder meta, then the global `navigation.sidebar.display`, then the `flat` default; a group's value applies to that group only, and nested subgroups resolve their own chain. `page`-mode drill-in panels stay route-aware and list the index page first, loose pages hoist above sibling groups only where a sibling renders `flat` (self-delimiting `group`/`page` rows keep authored interleaving), and under i18n a fallback-filled index page never overrides a locale's own `meta.ts` display. `sidebar.display` anywhere it is dead — a non-index page, the content root's own index page, or any page under an explicit config sidebar — reports a new `BLUME_SIDEBAR_DISPLAY_IGNORED` warning instead of being silently dropped. Explicit config sidebars render exactly as before.

---

# blume@1.5.1
Source: https://useblume.dev/changelog/blume-1-5-1

### Patch Changes

- ca28fb8: Generate an Open Graph card for the changelog index. The `/changelog` page previously shipped no `og:image` (and fell back to X's compact summary card); it now gets the same generated card every other page has, served at `/og/changelog.png`.
- ca28fb8: Stop doubling the site title in the changelog index's document title. The page passed "{site title} {Changelog}" to a layout that suffixes "- {site title}" itself, producing titles like "Acme Changelog - Acme"; it now reads "Changelog - Acme".
- 8db1ecb: The default display font is now Inter, matching the body font — default sites download one text family instead of two (Inter Tight's files alone were ~190 KB per page). To keep the tightened display look, headings now get `letter-spacing: -0.05em` from the theme itself, which also means any font you configure for `display` reads correctly at heading sizes instead of depending on tracking built into the font. Inter Tight remains available as the `inter-tight` slug.
- ca28fb8: Let a user-supplied `ogImage` on `PageLayout` declare its alt text and pixel size via the new `ogImageAlt` and `ogImageSize` props, emitted as `og:image:alt` / `og:image:width` / `og:image:height` — the metadata Blume's generated cards already declare automatically.
- ca28fb8: Emit schema.org JSON-LD from `PageLayout`, so custom pages — most importantly a custom home page — carry the same `WebSite` structured-data graph the docs pages do. On by default; pass `structuredDataEnabled={false}` to opt a page out.
- ca28fb8: Keep the trailing slash on the home page's canonical, `og:url`, and hreflang URLs (`https://site/` instead of `https://site`), so they byte-match the sitemap's `<loc>` for the root route.
- ca28fb8: Warn when `lastModified` runs in a shallow git clone. CI platforms usually check out limited history, which silently dropped most git-derived dates — sitemap `<lastmod>` and "Last updated" stamps vanished in production while working locally. The build now emits a `BLUME_SHALLOW_GIT_HISTORY` warning pointing at the fix (`VERCEL_DEEP_CLONE=true` on Vercel, `fetch-depth: 0` for actions/checkout).
- bad025f: Smooth out page navigation: every link now prefetches on hover/viewport, and same-origin navigations opt into cross-document view transitions in supporting browsers, replacing the hard flash between pages with a crossfade. Respects `prefers-reduced-motion`.
- 8db1ecb: Preload only the font weights above-the-fold text actually renders in (body 400/500, display 500/600, mono 400) instead of every configured face. On a default site this cuts the per-page font preloads from ten files (~260 KB) to a handful (~50 KB), bandwidth that was competing with the critical CSS and pushing out mobile LCP. All other faces still load on demand through their `@font-face` rules with `font-display: swap`.
- ca28fb8: Redirect trailing-slash URLs to their slashless twins on Vercel with a 308. `/docs/` and `/docs` previously both served 200 as duplicate URLs; the routing config now collapses the slashed form onto the canonical slashless one (the root `/` is untouched).

---

# blume@1.5.2
Source: https://useblume.dev/changelog/blume-1-5-2

### Patch Changes

- 7650327: Add `ai.ask.retrieval` — `maxResults`, `excerptChars`, and `contextBudget` — so a site can size how much documentation each Ask AI question injects into the model's prompt. Injected characters are the dominant term in time-to-first-token, and on a self-hosted backend the fixed 10,000-character grounding could push a single question past 40 seconds. The three knobs stay separate because they aren't interchangeable: `contextBudget` caps the total, `excerptChars` decides how deep into one long page an excerpt reaches, and `maxResults` caps how many pages retrieval adds (the page the reader is viewing is injected on top of them). Defaults are unchanged (6 / 2000 / 10000), so existing sites behave exactly as before.
- 0c2c985: Try It message composer on native AsyncAPI operation pages. Each `send`/`receive` operation ships an interactive **Try it** panel: a payload editor prefilled from the message's `examples` (or a value sampled from the payload schema when the message declares none) and validated against the payload schema as you type, an input per channel parameter, and a server picker fed by the channel's `servers` with a free-text URL override. The protocol-aware code samples (`wscat`, browser `WebSocket`, `kcat`, `mosquitto_pub`/`mosquitto_sub`) stay in lockstep with the form, filling the channel address template with the parameter values you type. On `ws`/`wss` bindings the panel also connects live to the resolved channel URL, shows connection state, sends composed messages, and logs received frames with timestamps — there's no reconnect logic; other protocols get the composer and copyable CLI samples, since Blume doesn't fake broker connectivity from a browser tab. The panel is server-rendered collapsed and loads its JavaScript only when a reader first opens it; `asyncapi.playground` mirrors `openapi.playground`, so it's on by default with the native renderer and `false` turns it off. `playground.proxy` stays OpenAPI-only, and no broker credentials are collected or persisted for event operations.
- e2dbf74: Adopt Astro's client router (`<ClientRouter />`) for page navigation. Same-origin link clicks now swap the new page into the live document instead of tearing it down for a full load, so navigation is flicker-free in every browser — including Firefox, which has no cross-document paint holding and briefly flashed a blank frame between pages. Navigations animate with native view transitions where supported and Astro's fade fallback elsewhere, both honoring `prefers-reduced-motion`; the sidebar keeps its scroll position across pages; search results navigate through the router too; and PostHog analytics captures a pageview per client-side navigation. The Scalar API reference intentionally keeps full-page loads (it is a SPA that mounts once per document), and the cross-document `@view-transition` rule from the previous release is gone — the router supersedes it.
- 97a9b30: Support a dark-mode favicon. A dark mark is invisible against dark browser chrome, so Blume now auto-detects a `-dark` sibling of your icon file — the same name and directory with `-dark` before the extension, like `icon.svg` → `icon-dark.svg` — and emits both icons behind `media="(prefers-color-scheme: …)"`, preceded by a plain light link so crawlers and browsers that ignore media queries on icons still get a sensible mark. Only the sibling of the icon Blume resolved is picked up, so an unrelated `-dark` file can't pair with your mark by accident. Ship one icon and nothing changes: a single `<link rel="icon">`, as before. The bundled Blume fallback now ships a light variant too, so a site with no icon of its own keeps a visible favicon in dark mode in browsers that honor media queries on icon links.
- 2597b38: Ignore repo-locating `GIT_*` environment variables (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE` and friends) when resolving git last-modified dates and shallow-clone status. A parent git process exports an absolute `GIT_DIR` to its hooks, so a build run from inside one — a husky hook, a post-merge script, a CI wrapper — silently read the wrong repository and dropped every page's date.
- 0c2c985: Try It playground on native OpenAPI operation pages. Each operation ships an interactive **Try it** panel: a form generated from the operation's parameters and request-body schema, prefilled from the spec's examples, with a server picker fed by the spec's `servers` and auth inputs matching the operation's security schemes (bearer, API key, basic, and a token paste field for OAuth2). Values typed into the form update the generated code samples live, and **Send** fires the request directly from the browser — with an optional proxy for APIs that don't allow cross-origin requests from the docs site (`openapi.playground.proxy`: a URL of your own, or `true` for the built-in `/_api-proxy` server route). The panel is server-rendered collapsed and loads its JavaScript only when a reader first opens it; it's on by default with the native renderer, and `playground: false` turns it off.
- e31ff0a: Add `ai.openInChat` to configure the "Open in chat" page action: `false` hides it, and an array of provider keys (`"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"`) shows just that subset, in order.
- 5f41cbb: Keep the Ask AI panel alive across page navigations. The island now rides the client router with `transition:persist`, so the conversation, a draft question, and the open panel all survive moving between pages instead of resetting on every click. The island re-anchors its portaled panel and the desktop content-push attribute after each swap, and the mobile overlay's focus containment re-applies to the new page's content.
- 6eceaea: Segment search text for every non-Latin default locale, not just Japanese, Chinese, Korean, and Thai. Orama's default tokenizer keeps only basic Latin letters and digits, so when `i18n.defaultLocale` was a Cyrillic, Greek, Hebrew, or Devanagari language the index collapsed to zero tokens and every query silently returned no hits. The script now comes from `Intl.Locale.maximize()` — `sr-Latn` keeps Orama's tokenizer while `az-Cyrl` is segmented — with legacy tags (`ja_JP.UTF-8`, `zh-cmn-Hans`) resolved by their language subtag, and Latin terms on a segmented index fold diacritics so café still matches cafe. The tokenizer follows the default locale for the whole index, so non-Latin translations on a Latin-default site are unchanged.
- 0c2c985: Harden the Try It playground: empty auth inputs no longer send their redaction placeholder as a real credential (the live request goes out anonymous instead), pre-network URL/header errors are reported as themselves rather than as a CORS failure, spec-derived names are escaped before selector interpolation, external proxy URLs that already carry a query string join with `&`, blank required parameters stay visible in samples and sends, and mid-edit invalid JSON renders as a string literal in the JS/Python samples instead of broken syntax. The AsyncAPI composer now connects with an empty payload editor, prefills channel parameters from declared defaults/examples/enums instead of the sampler literal `string`, and degrades a no-example, no-schema payload to `{}` rather than `null`. The built-in CORS proxy allowlist skips templated server URLs, and a proxy with no allowable origin warns at build time.
- c289eff: Stop `blume validate` reporting colocated images as broken assets. A relative image embed (`![](./diagram.png)`) — the form the docs recommend for local images, since those are optimized at build time — was resolved into a site route and then looked for under `public/`, where it never lands: the image pipeline emits it to `_astro/` from beside the content. Every such reference came back as `BLUME_BROKEN_ASSET`, so `--strict` failed on a site whose pages render the image correctly. Validation now accepts an image embed whose file exists next to its page source, passing the raw target through the same resolver that decides which colocated images the `/blume-assets/content` endpoint serves, so the two can't disagree about what one is. Everything that resolver would skip is still reported: a plain link to a relative path (only image nodes go through the pipeline), a `?query`/`#fragment` suffix, a case-mismatched or directory-shaped name (which breaks on the case-sensitive production build), and a reference that resolves nowhere — the last with a diagnostic that points at the page's folder rather than `public/`, and even when no `public/` directory exists.
- 1517f9c: Fix the sidebar rendering empty on archived version pages when header tabs are configured. A version tree's navigation root is versionized while tab paths stay in current-docs space, so the root tab was misread as a section tab that owns no group in the snapshot; it is now recognized as the root tab — via a single shared containment check used by sidebar scoping, tab-section pruning, and hoisting alike — and the archived sidebar renders its full tree. Header tabs also no longer claim `aria-current` on archived pages: they link back to the current docs, so none of them is the current page there.

---

# blume@1.5.3
Source: https://useblume.dev/changelog/blume-1-5-3

### Patch Changes

- b6770b3: Fix fully unstyled frames during client-router navigations. Astro hoists the CSS of components rendered after the head has streamed (a page's MDX content, for one) into the body as stylesheet links, and the client router neither preloads nor persists body stylesheets — so swapping in a page painted a frame or two with no CSS applied before its sheet loaded. The layouts now load an incoming page's body stylesheets into the head and wait for them before the swap, and keep the loaded copy across it.

---

# blume@1.6.0
Source: https://useblume.dev/changelog/blume-1-6-0

### Minor Changes

- 089f0d2: Native GraphQL API reference. Point the new top-level `graphql` config block at a schema — SDL text or an introspection JSON result, local or remote — and Blume generates one real page per root field (grouped as Queries, Mutations, and Subscriptions) plus one page per named type (Objects, Input Objects, Enums, Interfaces, Unions, and custom Scalars), all in the sidebar, search, llms.txt, and OG images like any hand-written doc. Operation pages show arguments with defaults and deprecations, a generated example operation with typed variables and a matching example response, live code samples, and the same Try it playground the OpenAPI reference ships — a plain JSON POST of `{ query, variables }` against the configured `endpoint`, with `playground.proxy` support for CORS-restricted APIs. Type pages cross-link every type reference and list where each type is used.
- 65e3853: Add `github.host` so docs hosted on a GitHub Enterprise instance get working repo links. Every repo-derived URL — the header mark, per-page edit links, the agent manifest's `repository`, the OG card's slug, and `<GithubInfo>` — was built against a hardcoded `github.com`, so an Enterprise repo produced links into the public site. `host` defaults to `https://github.com`, must be an HTTP(S) URL, and is normalized to its origin so nothing lands mid-link. The REST base `<GithubInfo>` queries is derived from it (an `api.` subdomain for an Enterprise Cloud data-residency tenant, `/api/v3` for Enterprise Server) or set outright with `github.api`, and a `host` prop points one card at a different instance. `<GithubInfo>` withholds its token from a cleartext-HTTP API base rather than sending it over the wire, and warns once per base so a private repo's missing counts are explained.
- 2fa67b8: Custom heading anchors and table-of-contents markers, matching Fumadocs' syntax so migrated content works verbatim. Append `[#custom-id]` to any heading to pin its anchor id — the marker never renders, links keep working after a heading is reworded, and pinned anchors stay identical across translated locales, where auto-generated ids differ per language. `[!toc]` keeps a heading on the page but out of the table of contents; `[toc]` does the reverse, adding a TOC-only entry that renders as an invisible anchor target so its link still scrolls somewhere — useful for labeling sections built from components rather than prose. Markers chain in any order (`## Heading [toc] [#id]`), work in Markdown and MDX, are stripped from search indexing, and `blume validate` resolves anchor links against pinned ids (including case-sensitive ones). Marker parsing is always on: a heading that previously ended in literal marker-shaped text now parses as marked — wrap the bracket text in inline code (`` ## Using `[toc]` ``) to render it literally. The one exception is CommonMark's own: a trailing bracket whose label has a link-reference definition on the page (`[toc]: /url`, including one nested in a block quote or list item) is a shortcut reference link and stays in the heading text; a bare `[toc]:` with no destination defines nothing.
- beec2d2: Add `navigation.actions` and `navigation.cta` — plain links in the header, and the one filled button. `navigation.featured` pins secondary links to the top of the sidebar and there was no header slot at all, so a docs site arriving from a hosted platform lost whatever its old top bar asked the reader to do. `cta` is singular by contract. Both hide below the `sm` breakpoint, where the header has room for the logo and the drawer toggle and nothing else — except `cta` on a page with no navigation toggle, where it stays, since nothing else can surface it on a phone.
- beec2d2: `navigation.repo` now takes a URL as well as a boolean. `github` drives the per-page edit link, the header mark and the agent manifest's `repository` together, so a project whose docs repo is private had to unset all three — and then had no way to show a mark at all. An absolute URL points it anywhere on GitHub, an organization for instance, while `true` keeps deriving it from `github` and `false` still hides it.
- a669f80: The Notion source now targets `@notionhq/client` v5 and Notion's data source API: a database is read through its first data source. Upgrade the peer dependency with `npm install @notionhq/client@^5`.
- 9ec4de4: Add a built-in `obsidian` content source. Point it at an Obsidian vault and Blume reads the notes in place — no export step, and nothing generated into your repo:
  
  ```ts
  export default defineConfig({
    content: {
      sources: [{ type: "obsidian", vault: "vault", prefix: "notes" }],
    },
  });
  ```
  
  - `[[Wikilinks]]` become route links, addressed by note name across the whole vault the way Obsidian addresses notes: custom link text (`[[Note|label]]`, and `[[Note\|label]]` inside a table), heading anchors (`[[Note#Install]]`, `[[#Install]]`), block references (`[[Note#^id]]`), full and partial paths (`[[folder/Note]]`, `[[Note.md]]`), and a frontmatter `slug`. A name two notes share resolves to an exact path match first, then to the first note in vault order, and warns only when a link actually resolves through the collision.
  - Heading anchors resolve against the target note's real headings, matched the way Obsidian writes them (inline formatting stripped) and slugged by the same pass that fills the page manifest.
  - Frontmatter keeps Blume's page meta plus any key declared in `frontmatter.extend` or, for notes of that type, in a content type's `frontmatter`; every other Obsidian property (including `tags`, `aliases`, and `cssclasses`) is dropped, so a vault written with the Properties UI builds cleanly.
  - Locale directories and version snapshots inside the vault publish under their locale and version like filesystem content.
  - An unresolved wikilink degrades to plain text with a warning, and one to a missing heading keeps the page link; single-line `%%comments%%` are stripped and a wikilink inside an HTML comment is left alone; fenced, indented, and inline code pass through verbatim; symlinked folders are followed; untitled notes take their filename as the title; dot-folders (`.obsidian`, `.trash`, plugin caches) and the usual never-content directories are skipped by both the scan and the dev watcher; `blume version cut` leaves a vault inside `content.root` out of the snapshot.
  - Vault notes get git "Last updated" dates when the vault is inside the repository, and "Edit this page" links through `github.dir` for a vault beside a monorepo docs app.
  
  `blume init` offers the source and seeds a first note. Not yet lowered: callouts, embeds, multi-line comments, aliases as link targets, and backlinks.
  
  Also in this release: `frontmatter`'s `stringify` no longer re-parses a string body (a body opening with a `---` divider was read as a second front matter block), and git last-modified dating now skips the scan entirely when no local source exposes a content root — a custom staged source that sets `sourcePath` without a `contentRoot` is no longer dated — set `contentRoot` on the source to date its pages.
- 20a5da5: Content includes: `<include>./path.mdx</include>` splices another file into a page at build time — the same syntax Fumadocs ships, so migrated content works unchanged. Markdown/MDX targets are embedded as content (front matter stripped, nested includes with cycle detection, relative images rebased onto the including page); any other extension — or an explicit `lang` attribute — embeds the file as a fenced code block, with `meta` for the fence meta string. Paths resolve relative to the including file, or from the content root with a leading `/`. Spliced content flows through every surface: headings join the page's table of contents and anchor index, search indexes the included text, the `.md`/`.mdx` mirrors and llms-full.txt serve the expanded document, broken links inside a partial are reported against the partial file, and editing a partial in `blume dev` reloads the pages that include it. Underscore-prefixed files (`_snippets/`) are already excluded from routing, so partials need no configuration. Unresolvable statements surface as `BLUME_INCLUDE_NOT_FOUND`, `BLUME_INCLUDE_CYCLE`, and `BLUME_INCLUDE_OUTSIDE_ROOT` diagnostics.

### Patch Changes

- 68f48c1: Downlevel components in the Ask AI grounding corpus, the way the `.md` mirror, `llms-full.txt` and MCP `get_page` already do. Ask AI was built from the search documents' verbatim Markdown, so a page whose body is a `<CardGroup>` of `<Card>`s reached the model as JSX with no prose in it — and section landing pages, which are exactly that shape, rank first for section-level questions. `prop={frontmatter.*}` expressions now resolve here too.
- fd08e26: Require Astro 7.2.3+, which renames the dev SSR entry to `virtual:astro:server-app` so full reloads no longer re-request it with a spurious `.js` suffix — and drop the `serverAppResolvePlugin` shim that worked around the old id corrupting the dev server on content renames.
- 1715b14: Give each AsyncAPI channel or operation that references the same component its own copy before traits merge. The aliases shared one object, so the first merge leaked into the second and stripped `traits` from the component table entry itself.
- 0fe3d43: Darken the green and orange text that misses WCAG AA in light mode. Both drew at `-700` over a 15% tint of their own hue, landing at 4.32:1 and 4.44:1 against the 4.5:1 bar for text that size, while every other hue already cleared it (teal 4.69:1, red 5.17:1, blue 5.71:1, purple 5.82:1, violet 6.00:1, yellow 6.02:1). At `-800` they reach 6.20:1 and 6.25:1, with the fill weight unchanged. This covers the GET and PUT method badges (and GraphQL `QUERY`), the matching badges in a reference's sidebar, 2xx and 4xx response status chips, and `<Badge>`'s `success` and `warning` variants. The `deprecated` label on an operation moves too: at `orange-600` on the page background it was 3.59:1, the worst of the set. Dark mode was already passing and is unchanged.
- 0fe3d43: Darken the callout icons that miss the WCAG 1.4.11 non-text contrast bar in light mode. A callout's icon names its type, so it is meaningful UI rather than decorative: `check`/`success` and `warning` sat at 2.94:1 and 2.95:1 against their own tint and now take `-700` (4.52:1 and 4.67:1), and `note`'s icon was muted-foreground at 70% over the muted surface (2.68:1) and is now full strength (4.64:1). Dark mode was already passing.
- 4c0fdfc: Keep camelCase word boundaries in API reference operation routes. An `operationId` went through the generic slugger, which lowercases before it replaces non-slug characters, so `processSlackInteraction` collapsed to `/reference/integrations/processslackinteraction`. Operation ids are usually camelCase because OpenAPI generators reuse them as SDK method names, and renaming them just to get readable URLs couples SDK naming to presentation. The key now hyphenates the boundaries first: a lower-case letter or digit followed by a capital, and the last capital of an acronym before a capitalized word, so `processSlackInteraction` becomes `process-slack-interaction` and `getHTTPResponse` becomes `get-http-response`. Already kebab-case ids and the method-plus-path fallback are unchanged. GraphQL field and type names and AsyncAPI operation ids derive their routes through the same key, so a GraphQL `addPet` mutation moves from `/graphql/mutations/addpet` to `/graphql/mutations/add-pet` and an AsyncAPI `publishUserSignedup` operation from `publishusersignedup` to `publish-user-signedup`.
- 0fe3d43: Darken the typed `<Card>` icons and the stroked `<Badge>` variants that still missed the light-mode contrast bar. A card's `check`, `warning`, and `note` icons carried the same values the callout icons moved off (2.94:1, 2.95:1, and 2.68:1 against their tint) and now share the callout table. A stroked badge has no fill of its own and inherits whatever surface it sits on — inside a `note` callout, `success` at `-700` was 4.47:1 — so `success` and `warning` now take `-800` whether filled or stroked.
- 68f48c1: Downlevel `<Card>` and `<CardGroup>` to Markdown on the agent-facing surfaces. Both are Blume's own components and neither had a serializer, so a section landing page — the shape `blume init` scaffolds and the Mintlify migrator emits — published raw JSX to `/<route>.md`, `llms-full.txt`, MCP `get_page` and the Ask AI corpus. A card becomes its title as a link over its body, with the `cta` last; a group becomes everything it holds, block by block. Serializers in `ai.markdownComponents` gain `childBlocks()` — every direct child of the element in order, each already downleveled — which is what `CardGroup` is built on.
- e823872: Harden two scanners against pathological input: HTML comments stripped before anchor detection are replaced with a space so their neighbors can't splice into new markup, and `github.dir` plus source/meta route prefixes trim slashes linearly instead of with a regex that was quadratic on a run of `/`.
- ce20984: Make room for the copy button in code blocks that have no language bar to hold it. Inside a component whose chrome is `not-prose` — `<Tabs>`, `<CodeGroup>`, `<Steps>`, `<Callout>`, `<Card>`, `<Accordion>` and the rest — the bar is cleared but the button is not, and the block's `padding-top` was the 1rem chosen for a block with no chrome at all, so the button painted over the first line of code. The same applied to an untitled `<CodeBlock>` in plain prose, which renders no bar. Both now reserve the button's strip, as does a raw `<pre><code>` block written in prose, which gets a button but has no language bar either; the clearance is keyed on the docs layout that injects the button, so a custom page layout without it keeps the plain inset.
- 35b5c6a: Support trailing `{#custom-id}` heading markers as an equivalent of `[#custom-id]` — verbatim in `.md`, and as the escape `\{#custom-id\}` in `.mdx`, where a bare `{…}` is a JSX expression. `blume check` now reports a bare `{#id}` in an `.mdx` page (or in a partial it includes) as `BLUME_MDX_CURLY_ANCHOR` instead of leaving it to fail at compile time, and `blume translate` is told to preserve the marker. Fragment-link validation also recognizes ids on raw HTML elements (`<a id="…">`, including tags wrapped over several lines) as anchor targets, ignoring ids inside code, inline code, HTML comments, `<Prompt>` blocks, and component props.
- ce20984: Drop the page-actions divider when the rail has no table of contents. The actions block carries its own top border as a separator under the contents, but the contents only render when a page has a heading within `toc.minHeadingLevel`–`toc.maxHeadingLevel` — so on a page without one the block drew a rule across the top of an empty column. The rail now decides once whether an outline renders and passes that to the block (`divider` prop, default on), so the two cannot disagree.
- 1715b14: Keep a spaced Shiki line range (` ```ts {1, 3-5} `) as one fence-meta token. The range used to split on its whitespace, and the `3-5}` fragment was promoted to the code block's title.
- ce20984: Cap the search dialog's section-filter row so the results keep the dialog. The dialog is a fixed height and the filter chips wrapped without a bound, so on a site with many sections the chips took the height and the results list got the remainder — measured on an 18-section corpus, the row wanted 266px of the 480 and left about one visible result. The row now shows two rows of chips plus the top of a third as the scroll cue, chips no longer wrap on long section names, the selected chip is scrolled into view when the chips reorder as the query narrows, and each chip exposes its selected state as `aria-pressed`.
- 6d4ffec: Load the font subsets your locales need. Remote fonts used to load only the Latin subset, so Vietnamese, Central European, Cyrillic, and Greek text fell back to the system font. Blume now derives subsets from `i18n.locales`, and remote families accept a `subsets` option to pin the list.
- 1715b14: Treat an empty `graphql.endpoint` like an omitted one. The playground and code samples fall back to the endpoint placeholder instead of targeting an empty URL.
- ceb7a9f: Fix the image lightbox becoming impossible to close after the first in-page navigation. `medium-zoom` injected its stylesheet into `<head>` once, when its module first loaded, and the client router's head swap discarded it on the next navigation; with the transition rule gone, the close animation's `transitionend` never fired, so Escape, a backdrop click, and scrolling all left the zoomed image open (and the `zoom-in` cursor disappeared) until a hard reload. The stylesheet now ships in the layout's page CSS, which the router carries across swaps, and the library loads as its `pure` build with no runtime injection.
- 03f5b36: Upgrade js-yaml to v5. Front matter parses exactly as before: dates still become `Date` objects and `<<` merge keys still resolve.
- aee337e: JSON-LD can now say what a site is and who runs it. `seo.organization` adds an **Organization** node to every page — name and URL default to the site's, with a logo, `sameAs` profiles, the email and telephone as a `ContactPoint`, and the address as a `PostalAddress` — which the WebSite and article nodes cite as `publisher`. `seo.software` adds a **SoftwareApplication** node to the homepage with the product's name, description, category, operating system, license, an `Offer` when a price is set (`0` for free software), and registry or repository `sameAs` links; `software: true` takes every default. Both need `deployment.site`, and custom pages built on `PageLayout` or `RootLayout` pick them up automatically.
- dff7930: Scan link-reference definitions in linear time. A line of deeply nested block-quote or list containers that never reaches a `[label]:` no longer backtracks exponentially while headings are extracted.
- aee337e: `llms.txt` now tells agents when to use the site and where its machine-readable surface lives. A new `ai.llmsTxt.details` option inserts free-form Markdown after the title and summary — the llms.txt spec's details block — for "when to use" guidance, the install command, or the package name in the site's own words. The generated file also closes with two sections that need no configuration: **Agent skills** lists each skill published through `ai.skills` with its description, and **Agent resources** links every artifact the build emits — `llms-full.txt`, the per-page `.md` mirror, the MCP server and its discovery document, the skills index, the API catalog, `agent-readability.json`, and the sitemap — each only when it exists.
- aee337e: The hosted MCP server now exposes every page as an MCP resource alongside its tools. `resources/list` enumerates the pages at their served URLs (a `blume:` URI when no `deployment.site` is configured) with a `text/markdown` type, title, and description; `resources/read` returns the page's agent Markdown — the same output `get_page` serves — and accepts a listed URI, a bare route, or a `.md` mirror URL. An unknown URI answers with the protocol's resource-not-found code. The server card advertises the `resources` capability, so clients and readiness scanners that attach context by URI can browse the docs without calling a tool.
- 1715b14: Corrections to the `blume-migrate` skill: a Docusaurus or Fumadocs folder with `collapsible: false` maps to that folder's `display: "flat"` instead of being dropped, several Fumadocs GraphQL sources map to `graphql.sources` rather than a single `spec`, a Nextra `docsRepositoryBase` on a non-`github.com` origin sets `github.host` to that origin, and the favicon convention reads `icon.{svg,png,ico}` or `favicon.{svg,png,ico}`.
- 24ac208: Darken `--blume-muted-foreground` from `oklch(0.54 0 0)` to `oklch(0.53 0 0)` and lighten the `tip` tint on callouts and cards from `accent/10` to `accent/6` so muted body text clears WCAG AA on every tinted surface, not just on the page. At `0.54` muted text was 5.06:1 on the background but 4.38:1 inside a `danger` callout and 4.50:1 inside an `info` one; at `0.53` those rise to 4.57:1 and 4.69:1 and the page to 5.28:1. `tip` tints with the configurable accent, whose default is near black, so no text lightness alone could make it safe — even at `0.53` it sat at 4.25:1 over the 10% tint. At 6% it clears 4.5:1 against any accent (4.62:1 worst case on pure black). Dark-mode tokens are unchanged.
- aee337e: The default 404 page now helps readers and agents recover instead of dead-ending. Under a "Where to look next" heading it links every top-level section (each tab's resolved target), the sitemap when a `deployment.site` makes one possible, and `llms.txt` when it's enabled — so an agent that followed a stale URL lands on a real HTTP 404 whose body points at the site map and the docs index. The three new labels (`notFound.suggestions`, `notFound.sitemap`, `notFound.llms`) are translatable through `ui` like the rest of the page's copy.
- 43931fb: Localize the "Open in chat" prompt. The prompt handed to the chat provider ("Read `<url>` so I can ask you questions about this page.") was hardcoded in English regardless of the site's locale. It now comes from the UI dictionary as `actions.openInChatPrompt` — with `{url}` replaced by the page's raw-Markdown URL at load time — so localized sites send a localized prompt, every shipped starter pack carries a translation, and `i18n.ui` can override the wording like any other chrome string.
- ce20984: Keep long unbreakable tokens inside the content column. Prose sat at `overflow-wrap: normal`, so an API permission, a broker list, a bare URL used as its own link text or a module-qualified name in a generated reference painted past the column — and nothing between the paragraph and the viewport clips it, so the run landed in the document's scroll width and dragged the whole page sideways on a phone. Headings had their own opt-in; the property is now set once on the prose root and inherited, so running text, headings and inline code are covered by the same rule. Tables are unchanged: an auto-layout column always grows to fit its widest token, so a wide table still relies on its scroll wrapper.
- 5559319: Close the site's dropdowns — the page actions (Export, Open in chat, Connect to MCP), the header language switcher and the nav selectors — when clicking outside them, pressing Escape, or moving keyboard focus out of the panel, instead of leaving the panel open until its own trigger is clicked again. Escape returns focus to the trigger when pressed from inside the menu, and an Escape aimed at the search dialog no longer closes a menu beneath it.
- ce20984: Give the API reference's sticky sample panel its own scroll region. A grid item's sticky containing block is its grid row, and the row is as tall as its tallest item — so expanding a request schema on the left made the left column tower over the panel and handed sticky an enormous travel budget, pinning the panel with everything below the viewport fold unreachable until the left column ended. Bounding it to the viewport turns the overhang into a scroll. The tradeoff runs the other way on an operation with a short left column and a long sample: the row is then only as tall as the capped panel, and the overhang is reached by scrolling the panel rather than the page; a playground response is scrolled into view when it lands below that fold. The scroll region is styled like the sidebar and the table of contents — thin, border-colored thumb, inset from the Request card's edge, stable gutter — wheel input chains to the page once the panel reaches its end, and the focus ring on the panel's first control is no longer clipped by the scroller's edge. Applies to the OpenAPI, AsyncAPI and GraphQL operation pages, which now share one `OperationPanel` component.
- 1715b14: Give the API playground proxy a 30-second upstream deadline, shared across a redirect chain. The client already aborted its own request after 30 seconds, but that never reached the server-side fetch, so a documented API that accepted the connection and never answered held a server request slot until the platform killed it. A timed-out upstream is now the same JSON 502 as an unreachable one.
- 1715b14: Emit the request body in the playground's JavaScript and Python code samples as the raw editor text, never re-read as a JavaScript object literal or Python dict. The generated sample now sends byte-for-byte what the live request sends: a `__proto__` key stays a key, an id past 2^53 keeps its digits, and `1e400` is not re-serialized as `Infinity`.
- beec2d2: A protocol-relative `navigation.featured` href (`//host/path`) no longer picks up a locale prefix on non-default locales, where it became `/fr//host/path`. `localizePath` now draws the same line as `withBasePath`: a leading slash alone doesn't make a route.
- fe966ca: Redesign the default 404 page: a two-column layout with the title and home link on the left and a vertical "Where to look next" list of sections, sitemap, and llms.txt on the right, stacking on small screens.
- e2153d5: Restore live Markdown hot reload in migrated `.`-rooted projects. Astro's content watcher now honors the docs collection's negated globs, so the generated dev config no longer hides Astro's cache dir from the watcher — the escape hatch that previously cost `.md` body edits a dev-server restart in that layout.
- 2bfe840: Accept `@sanity/client` v8 as a peer dependency for the Sanity content source.
- fc24f9d: Keep a Scalar-rendered API reference on the page's theme. Scalar decided light or dark on its own — from its own localStorage key or the OS setting — and never read Blume's `data-theme`, so a reader whose stored preference disagreed with what their browser reports to `prefers-color-scheme` (Brave with its own dark color scheme over a light OS, for one) got a light navbar over a dark reference, with two toggles that didn't agree. The reference layout now pins Scalar's color mode to the current theme before it mounts, which also hides Scalar's own switch, and mirrors later flips of Blume's toggle onto the embed. A `scalar.forceDarkModeState` or `scalar.darkMode` set through the escape hatch is left to Scalar, as before.
- dd1ed31: Add `search.indexing.includeCodeBlocks` to index fenced code (body and title) in the source-built search indexes — the client index, hosted syncs, and the MCP `search_docs` tool — while keeping the plain-text default. `.mdx` pages are now parsed as MDX for indexing, and components are downleveled with the same serializers the agent surfaces use, so prose and fences inside `<Steps>`/`<Tabs>` and the text a `<Card>` or `<TypeTable>` shows are indexed instead of being folded into raw HTML.
- 1715b14: Keep an explicit script subtag when a search locale carries a POSIX suffix. `az_Cyrl.UTF-8` fell back to `az`, which maximizes to Latin script, so segmentation stayed off and Cyrillic content produced no search tokens; `sr_Latn.UTF-8` did the reverse. The codeset and modifier suffix is now dropped before the tag is parsed.
- 52ac092: Add a `syncKey` prop to `Tabs`: only groups sharing the same key switch together, so unrelated groups that happen to share a tab title stay independent. Nested tab groups now also keep their own panels instead of having them adopted by an ancestor group.
- d009a19: Keep the dark theme on the page during client-side navigation. The client router replaces the root element's attributes with the incoming page's, which dropped `data-theme` until Blume re-applied it after the swap; in between, the router's scroll restoration computed the new page's styles with the light palette, so the sidebar, header tabs, language selector, search button, feedback buttons, previous/next links and page actions visibly animated from light to dark on every navigation. The theme is now stamped onto the incoming document before the swap, so it never drops.
- ce20984: Emit `data-depth` on each table-of-contents item. The heading's level was computed and then written only into an inline `padding-inline-start`, so a project wanting to style the rail by level had to match on that style string — which breaks silently if the indent ever changes.
- 52ac092: Add `ts2js` code fences: mark a `ts` or `tsx` block with the `ts2js` meta keyword and it renders as synced TypeScript/JavaScript tabs, with the JavaScript variant generated automatically — type syntax and type-only imports stripped, formatting, comments, and JSX preserved.
- 72c9abe: Parse the project's `tsconfig.json` path aliases with the TypeScript compiler API instead of `get-tsconfig`. Blume's `get-tsconfig` v4 and Astro's pinned v5 left two copies in every install, and a stale CI `node_modules` cache could drop Astro's nested copy, failing `blume build` with `The requested module 'get-tsconfig' does not provide an export named 'readTsconfig'`. TypeScript already ships with Blume, so there is now one fewer dependency and alias resolution follows tsc exactly.
- aee337e: `blume build` now audits the Vercel function bundle after a server build and fails when the bundle is missing a package its server code imports. The Vercel adapter's dependency trace silently drops any bare import it can't resolve from the project root — under an isolated linker (pnpm, Bun's isolated mode) that includes Blume's own runtime dependencies, such as the MCP server's `@modelcontextprotocol/sdk` — and the deployed function then fails on every request with `FUNCTION_INVOCATION_FAILED` while the build, CI, and warm-cache previews all stay green. The build now reports each missing package with the chunk that imports it and the `npm install -D …` line that fixes it; a missing Blume dependency fails the build, a project's own missing external is a warning.

---

# blume@1.6.1
Source: https://useblume.dev/changelog/blume-1-6-1

### Patch Changes

- e6fc45f: Every copy affordance (Copy as Markdown, code blocks, MCP commands, prompts, color swatches, API panels) now falls back to the legacy `copy` command when the Clipboard API is unavailable or denied — in-app browsers, WebViews, insecure origins, and after a denied permission prompt — instead of doing nothing. When nothing lands on the clipboard even then, the Copy as Markdown and MCP actions flash a localized **Copy failed** label (new `actions.copyFailed` UI string, translated in every shipped pack) rather than showing no feedback at all; the other copy buttons still show no confirmation.
- 743b36b: Copy as Markdown now works in Safari and Firefox. The action fetches the page's Markdown on click, and the clipboard write used to be issued only after that fetch resolved — outside the click's user activation, which those browsers require for a clipboard write — so it failed on every click. The write is now issued inside the click with the Markdown still loading (a promised `ClipboardItem`), and browsers without that API keep the previous fetch-then-write path.
- 316df45: The default 404 page now has a Markdown twin at `/404.md` — the not-found message plus the same recovery links as the HTML page (every top-level section, the sitemap, and `llms.txt`), absolute once `deployment.site` is set. On a Vercel server build, a request for a missing page that sends `Accept: text/markdown`, or asks for a `.md`/`.mdx` URL no page backs, gets that Markdown body with the `404` status instead of the HTML shell, so agents recover from a stale URL without parsing page chrome. Both variants are skipped together when a project owns `/404` with its own `pages/404.astro` or a `404.md` content page.
- ccc3ac1: Scan an `examples.source` directory that lives outside the project root for Tailwind utilities in `<Component />` preview frames, and resolve relative `@source` paths in `theme.css` and `examples.css` from the file that declares them. A monorepo can now point Blume at sibling workspace packages without knowing the generated runtime's directory layout.
- 1df9208: Generated OG cards now show the page's own description as the subtitle (its `seo.description`, else `description`), matching the page's `og:description`, and fall back to the site-wide `seo.og.description` only for pages without one. `seo.og.description: false` still hides the subtitle on every card.
- db10b26: Keep Astro's and Vite's caches inside the hidden `.blume` runtime instead of under its `node_modules`, which is a junction into Blume's package directory. Two projects that resolve the same Blume install (a monorepo building docs and a sandbox in parallel) previously shared one content data store, so pages of whichever build lost the race rendered as 404s.
- 872caf4: Add a per-source `seoDescriptionSuffix` option to the `openapi`, `asyncapi`, and `graphql` reference blocks. Generated operation pages derive their meta description from the operation's own prose followed by a generated English sentence ("Reference for the `GET /pets` endpoint in the Petstore API."), which kept every page distinct but left non-English sites with half-translated metadata that no amount of authored prose could fix. Set `seoDescriptionSuffix: false` on a source to describe its pages with the spec's `description` (or `summary`) alone; an operation with neither falls back to its language-neutral title (`GET /pets`, the channel and action, or the GraphQL field or type name), so no page ships an empty description. The default is unchanged.
- 7869217: Serve the runtime's data snapshots from memory instead of `.blume/src/generated/*.json`. The page data behind `blume:data`, the parsed API specs, the static search index, the raw-Markdown and content-asset maps, the MCP and Ask corpora, and the rendered RSS feeds are now published into an in-process registry by the generator and served to Vite as virtual modules, so a content edit in `blume dev` invalidates exactly the modules whose data changed and reloads the browser — no JSON write, no file-watcher round trip, and nothing half-written for the dev server to observe. `blume eject` is unchanged: the ejected project keeps the JSON files and aliases each module to them.
- ac4e501: Update dependencies: Astro 7.3, `@astrojs/mdx` 8 with `@astrojs/markdown-satteri` 0.4 (MDX now compiles through the Sätteri processor Blume already configures), takumi 2.13, citty 0.2, zod 4.5, and the latest patch releases of the remaining runtime dependencies. A bare `--host` before another flag (`blume dev --host --open`) still binds all interfaces under citty's new argument parser.
- 743b36b: `blume version <id>` now preserves the line endings of a CRLF `blume.config.ts` when it inserts the new entry into `versions.archived`, instead of introducing a lone LF ahead of the entry.

---

# blume@1.6.2
Source: https://useblume.dev/changelog/blume-1-6-2

### Patch Changes

- abd8daf: Every site now serves a read-only **JSON docs API** — the REST twin of the MCP tools, over the same page snapshot — described by an OpenAPI 3.1 document at `/openapi.json`. `/api/docs/pages.json` lists every page with its route, title, description, content type, locale, facets, and the URLs of its rendered, Markdown, and JSON forms; `/api/docs/pages/{route}.json` returns one page as JSON with its agent Markdown; `/api/docs/navigation.json` returns the navigation tree. All three are prerendered, so static sites serve them as files. Under server output, `/api/docs/search?q=` runs the same full-text search as the MCP `search_docs` tool, with the same `limit`, `contentTypes`, `locale`, `version`, and `filters[key]` scoping, and any `/api/…` URL no endpoint answers gets a 404 problem document instead of the HTML page. Errors everywhere are RFC 9457 problem details (`application/problem+json`) with a stable `code`, a `detail`, and a `resolution` hint. The OpenAPI document is generated per build from config — one `operationId`, typed parameters, and response schemas per operation — and also documents the `.md` mirrors, `llms.txt`, `llms-full.txt`, `agent-readability.json`, and the MCP endpoint, so function-calling frameworks that ingest OpenAPI get the same reach an MCP client has. It's linked from the RFC 9727 API catalog, `agent-readability.json`, `llms.txt`, and the homepage `Link` header as `rel="service-desc"`. The default 404 page gains a JSON twin at `/404.json` alongside its Markdown one, wired into Vercel server builds for requests that send `Accept: application/json` or ask for a `.json` URL no file backs. Set `ai.api: false` to publish none of it; a `public/openapi.json` you ship yourself takes over that route.

---

# blume@1.6.3
Source: https://useblume.dev/changelog/blume-1-6-3

### Patch Changes

- 7d3fb47: Drop the strip of empty space above code blocks inside `<CodeGroup>`, `<Tabs>`, `<Steps>`, `<Callout>` and the other flush contexts. The 2.5rem top inset added to keep the copy button off a long first line read as a rendering bug over a one-line install command. A code switcher (a `<CodeGroup>`, a `ts2js` fence, code-only `<Tab>`s) now hosts a single copy button in its tab strip that copies whichever panel is showing, and every other bar-less block keeps the plain 1rem inset with enough end padding on the scrolling code that a long first line's tail clears the overlay button.

---

# Einführung
Source: https://useblume.dev/de/docs

Leg Markdown oder MDX in einen Ordner, führe `blume dev` aus und erhalte eine produktionsreife Dokumentations-Website — Navigation, Suche, Theming, Open-Graph-Bilder und eine umfangreiche Komponentenbibliothek — ohne App-Boilerplate, die geschrieben oder gepflegt werden muss.

**[Schnellstart](/docs/quickstart)**

Installiere Blume und veröffentliche deine erste Seite in wenigen Minuten.

**[Konfiguration](/docs/configuration)**

Passe Titel, Theme, Suche und Deployment an.

## Warum es Blume gibt

Dokumentation sollte schnell, KI-fähig und konfigurationsfrei sein — bis dahin, dass gar kein Starter-Template nötig ist. Manche Dokumentationswerkzeuge übergeben dir eine komplette Codebasis zur Pflege, bevor du überhaupt ein Wort geschrieben hast. Andere bauen das Template um deine Inhalte herum, binden dich aber an ihren gehosteten Dienst.

Blume vereint das Beste aus beiden Welten. Das Framework ist das Template, sodass du nur deine Inhalte anfasst. Wenn du anpassen möchtest, kannst du zunächst die eingebauten Komponenten ersetzen, die einzelne Konfigurationsdatei ändern oder sogar ejecten, wenn du die Astro-Website direkt haben möchtest. Die [FAQ](/docs/faq) erläutert, wie sich das im Vergleich zu Mintlify, Fumadocs und den übrigen verhält.

## Was Blume anders macht

### Standardmäßig schnell

Blume baut auf Astro und Vite auf und rendert standardmäßig statisches HTML — schnell, cachebar und günstig zu hosten. Das Kern-Theme liefert kein Client-Framework-JS aus, sodass Seiten von Haus aus bei den Core Web Vitals gut abschneiden. Dev-Start und Hot Reload fühlen sich Vite-nativ an, und du aktivierst Server-Funktionen nur dann, wenn du sie brauchst.

### Sofort KI-fähig

Jede Blume-Website spricht fließend Maschine. Sie gibt [`llms.txt` und `llms-full.txt`](/docs/configuration/ai) aus, liefert das rohe Markdown jeder Seite, indem du `.md` an deren URL anhängst, stellt eine [von OpenAPI beschriebene JSON-API](/docs/configuration/ai#json-api) bereit und bietet Lesern auf jeder Seite die Aktionen **Copy as Markdown** und **Open in chat**. Ergänze einen optionalen **Ask AI**-Assistenten auf der Seite oder hoste einen [**MCP-Server**](/docs/configuration/ai#mcp-server), damit Coding-Agenten wie Claude Code und Cursor deine Dokumentation direkt durchsuchen und lesen können — kein Scraping, kein gehosteter Dienst. Dein Markdown ist die maßgebliche Quelle für Menschen wie für Modelle.

### Keine Konfiguration — nicht einmal das Template

Ein Ordner mit Dokumentation ist ein vollständiges Projekt. Es gibt keinen Starter zum Klonen, kein Astro oder Tailwind einzurichten und kein Template zu pflegen. Die Navigation wird aus deinen Dateien abgeleitet, die [Suche](/docs/configuration/search) funktioniert in Dev und Produktion ohne gehosteten Dienst, und Theming besteht aus einer Handvoll Tokens. Alles hat einen sinnvollen Standardwert; Konfiguration ist etwas, worauf du zurückgreifst, nicht etwas, womit du anfängst.

### Typsicher bis ins Mark

Deine [`blume.config.ts`](/docs/configuration) und jede [`meta.ts`](/docs/content/meta) sind echtes TypeScript — validiert durch ein Schema und geschrieben mit `defineConfig` und `defineMeta`. Dein Editor vervollständigt jede Option automatisch und erkennt Tippfehler, ungültige Werte und fehlende Felder schon während des Tippens, lange vor einem Build. Konfiguration ist Code, den du refaktorieren, berechnen und dem du vertrauen kannst — kein lose typisiertes YAML.

## Alles inklusive

- **Komponenten** — Callouts, Cards, Steps, Tabs, Accordions, Badges, Dateibäume und Parametertabellen, in MDX nutzbar [ohne Imports](/docs/content/components).
- **Lokale Suche** — Orama funktioniert in Dev und Produktion; Pagefind ist für große Websites nur ein Flag entfernt. Kein gehosteter Index.
- **KI** — [`llms.txt`, rohe Markdown-URLs, eine JSON-API mit OpenAPI-Beschreibung, Copy as Markdown, Open in chat, ein Ask-AI-Assistent und ein gehosteter MCP-Server](/docs/configuration/ai).
- **Navigation** — aus Dateien abgeleitet, verfeinert mit `meta.ts` oder Konfiguration.
- **SEO** — Metadaten, Open-Graph-Bilder, RSS-Feeds und JSON-LD, [eingebaut](/docs/configuration/seo).
- **Anpassung** — Komponenten-Overrides, React-Islands, eigene Seiten, Theme-Tokens und eine Registry für Quellkomponenten über `blume add`.
- **Eject** — `blume eject` erzeugt ein eigenständiges Astro-Projekt, das weiterhin das `blume`-Paket verwendet.

## Wie es funktioniert

Die Blume-CLI findet deine Inhalte, baut einen Content-Graphen auf und generiert ein verstecktes Astro-Projekt unter `.blume/`, das sie für Dev und Build steuert. Die generierte Laufzeitumgebung ist ein Implementierungsdetail — du schreibst Markdown, Blume erledigt den Rest — bis du dich entscheidest zu ejecten und sie selbst zu übernehmen.

## Nächste Schritte

**[Konfiguration](/docs/configuration)**

Passe Titel, Theme, Suche und Deployment an.

**[Komponenten](/docs/content/components)**

Entdecke die eingebaute Komponentenbibliothek.

**[KI](/docs/configuration/ai)**

Liefere `llms.txt` und einen Ask-AI-Assistenten aus.

**[CLI](/docs/reference/cli)**

Jeder `blume`-Befehl und jedes Flag.

---

# OpenAPI / AsyncAPI
Source: https://useblume.dev/de/docs/advanced/api-reference

Richte Blume auf eine OpenAPI-Spezifikation aus, und es generiert eine native API-Referenz: eine **echte Seite pro Operation**, nach Tag gruppiert in einer tab-bezogenen Seitenleiste, mit Schema-Tabellen, Request-/Response-Beispielen, generierten Codebeispielen und einem interaktiven [„Try it“](#try-it-playground)-Panel. Da jede Operation eine echte Blume-Seite ist, erhält sie eine eigene URL, erscheint in der **Website-Suche** und in `llms.txt` und bekommt ein Open-Graph-Bild – genau wie jedes handgeschriebene Dokument. Die folgende Konfiguration richtet Blume beispielhaft auf die öffentliche Petstore-Spezifikation aus.

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}
```

Damit wird die Referenz unter `/reference` eingebunden (eine Übersichtsseite), wobei jede Operation unter `/reference/<tag>/<operation>` liegt. Die `spec` ist entweder eine `http(s)`-URL oder ein Pfad zu einer lokalen Datei in deinem Projekt. Blume parst sie mit [Scalars OpenAPI-Parser](https://github.com/scalar/scalar) – Swagger-2.0- und OpenAPI-3.0-Spezifikationen werden automatisch auf 3.1 aktualisiert. Du dokumentierst stattdessen eine GraphQL-API? Sieh dir die [GraphQL-Referenz](/docs/advanced/graphql) an.

Die Referenz fügt nicht von sich aus einen Header-Tab hinzu. Um sie sichtbar zu machen, richte einen [Navigations-Tab](/docs/content/navigation#tabs) auf ihre Route aus – dadurch wird auch die Operations-Seitenleiste für den nativen Renderer eingegrenzt:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
Operationen werden für die Suche anhand ihrer **Zusammenfassung und ihres Tags** indexiert. Die gerenderten Schema-Tabellen und Codebeispiele werden nicht per Volltext indexiert; die Suche findet Titel und Abschnitt einer Operation und verlinkt dann auf deren eigene Seite.
:::

## Eine lokale Spezifikation

Ein relativer Pfad wird ausgehend vom Projektstammverzeichnis aufgelöst und zur Build-Zeit gelesen. Sowohl JSON als auch YAML funktionieren:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}
```

## Route

`route` bestimmt, wo die Referenz eingebunden wird – die Übersichtsseite und das Präfix für jede Operations-Route (und die Route, auf die du einen Navigations-Tab ausrichtest):

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}
```

## Codebeispiele und Schemata

`codeSamples` bestimmt, welche Sprachen pro Operation gerendert werden (eingebaut: `curl`, `js`, `python`); `expandSchemas` zeigt verschachtelte Schema-Zeilen von Anfang an ausgeklappt statt eingeklappt:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}
```

## „Try it“-Playground

Nativ gerenderte Operationsseiten liefern standardmäßig ein interaktives **Try it**-Panel. Blume erzeugt das Formular aus der Operation selbst: ein Eingabefeld pro Pfad-, Query- und Header-Parameter, ein Body-Editor auf Basis des Request-Body-Schemas, alles mit den Beispielen aus der Spezifikation vorbelegt. Eine Server-Auswahl listet die `servers` der Spezifikation auf, mit einem Freitextfeld für jede andere Basis-URL, und die Auth-Eingaben richten sich nach der [aufgelösten Sicherheit](#autorisierung) der Operation – Bearer-Token, API-Key und Basic-Anmeldeinformationen, OAuth2 als Feld zum Einfügen eines Tokens (bring einen Access Token mit; Blume führt den Flow nicht aus).

Panel und Codebeispiele bleiben im Gleichschritt: Werte, die du ins Formular tippst, aktualisieren die generierten Beispiele live, sodass ein kopierter curl-Befehl immer exakt dem entspricht, was **Send** tun würde. Und es drängt sich nicht auf – das Panel wird serverseitig eingeklappt gerendert, und sein JavaScript wird erst geladen, wenn Lesende es zum ersten Mal öffnen. Wer es nie anfasst, lädt auch nichts davon herunter.

`playground: false` ist der komplette Ausschalter:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}
```

### Anmeldeinformationen

In die Auth-Felder eingegebene Anmeldeinformationen bleiben im Arbeitsspeicher und verschwinden beim Neuladen. Mit **Remember on this device** werden sie im `localStorage` gespeichert, begrenzt auf den Origin der Doku – sie werden nirgendwo anders hingeschickt als an die aufgerufene API. Codebeispiele zeigen weiterhin Platzhalter (`YOUR_TOKEN` und Konsorten), egal was eingegeben wurde, sofern nicht **Include my values in samples** aktiviert wird.

### CORS und der Proxy

Wie beim [Scalar-Renderer](#der-scalar-renderer) gehen Anfragen **direkt aus dem Browser** an die Ziel-API, daher muss die API Cross-Origin-Anfragen von der Doku-Website zulassen (`Access-Control-Allow-Origin`). Für APIs, die das nicht können, setzt du `playground.proxy`: Eine URL leitet Anfragen über einen von dir gehosteten Proxy, und `true` aktiviert die eingebaute Route `/_api-proxy` – die einen Server-Build braucht und daher [`deployment.output: "server"`](/docs/deployment#server-rendering) voraussetzt:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}
```

Der eingebaute Proxy leitet nur Anfragen an die Origins weiter, die deine Spezifikationen in `servers` deklarieren – auch über Redirects hinweg –, sodass eine öffentliche Doku-Bereitstellung nicht auf andere Hosts in ihrem Netzwerk gerichtet werden kann. Eine ins Panel getippte **Custom base URL** ist kein dokumentierter Server: Bei aktiviertem Proxy werden Anfragen an sie mit einem 403 abgelehnt.

## Mehrere Spezifikationen

Verwende `sources`, um mehr als eine Spezifikation zu veröffentlichen. Jede Quelle erhält ihre eigene Übersichtsroute, Operationsseiten und einen Header-Tab. Gib jeder ein `label` (wird für den Tab und zur Ableitung ihrer Route verwendet) oder setze eine explizite `route`:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}
```

`spec` ist eine Kurzform für ein `sources` mit einem einzigen Eintrag, du greifst also nur dann zu `sources`, wenn du mehr als eine hast.

### Indexierung pro Quelle

Generierte Seiten nehmen standardmäßig an der Suche, an `llms.txt` und an der Crawler-Indexierung teil. Eine sekundäre oder überlappende Spezifikation kann sich von jeder dieser Oberflächen abmelden, ohne ihre Seiten zu verstecken oder sie aus der Navigation zu entfernen:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}
```

- `includeInSearch: false` hält die Übersicht und die Operationen der Quelle aus der Website-Suche heraus.
- `includeInLlms: false` hält sie aus beiden `llms.txt`-Dateien heraus.
- `noindex: true` fügt Crawler-Noindex-Metadaten hinzu und entfernt die Seiten aus der Sitemap.

Die Meta-Description jeder Operationsseite ist die `description` (oder `summary`) der Operation selbst, gefolgt von einem generierten Satz, der den Endpunkt benennt – „Reference for the `GET /pets` endpoint in the Petstore API.“ –, sodass auch eine Spezifikation aus knappen einzeiligen Zusammenfassungen pro Seite eine eigenständige Beschreibung in Snippet-Länge ausliefert. Dieser Satz ist englisch. Auf einer Website, deren Spezifikationstexte in einer anderen Sprache verfasst sind, setzt du an der Quelle `seoDescriptionSuffix: false`, um ihn wegzulassen und jede Seite allein mit dem verfassten Text zu beschreiben; eine Operation, die weder eine `description` noch eine `summary` hat, fällt auf ihren Titel zurück (`GET /pets`), sodass keine Seite mit leerer Beschreibung ausgeliefert wird:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}
```

Beim [Scalar-Renderer](#der-scalar-renderer) gilt nur `noindex` – eine von Scalar gerenderte Referenz liegt ohnehin außerhalb von Blumes Suche und `llms.txt`, sodass die beiden `include*`-Einstellungen dort nichts bewirken können.

## Autorisierung

Operationen, die [Sicherheitsanforderungen](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) deklarieren, rendern oberhalb ihrer Parameter einen Abschnitt **Authorization**, und die generierten Codebeispiele senden eine Platzhalter-Anmeldeinformation (`Authorization: Bearer YOUR_TOKEN`, einen API-Key-Header oder einen Query-Key – je nachdem, was das Schema verlangt). Es gibt nichts zu konfigurieren: Blume liest `security` aus der Spezifikation, sodass die Referenz immer dem entspricht, was die API tatsächlich durchsetzt.

Die OpenAPI-Semantik wird unverändert übernommen:

- Die eigene `security` einer Operation überschreibt die Standardeinstellung auf Dokumentebene; `security: []` markiert sie als **öffentlich** und rendert keinen Authorization-Abschnitt.
- Mehrere Anforderungseinträge sind Alternativen – gerendert als „oder“-Gruppen; alle Schemata innerhalb eines Eintrags sind gemeinsam erforderlich. Die erste Alternative fließt in die Codebeispiele ein.
- Ein leerer `{}`-Eintrag bedeutet, dass die Authentifizierung für diese Operation **optional** ist, und der Abschnitt weist darauf hin.
- OAuth2-Scopes werden pro Schema aufgelistet; `description`s der Schemata aus `components.securitySchemes` werden inline gerendert.

## Der Scalar-Renderer

Der native Renderer ist die Standardeinstellung – die Operationsseiten, die Suchintegration und der [„Try it“-Playground](#try-it-playground) weiter oben sind alle sein Werk. Wenn du stattdessen lieber die eigenständige API-Referenz von [Scalar](https://scalar.com) einbetten möchtest – mit eigener Seitenleiste, Suche, eigenem Theme und eigenem Request-Client auf einer einzigen Route – setze `renderer: "scalar"`:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}
```

Eine von Scalar gerenderte Referenz ist ein eigenständiges Embed auf einer eigenen Route – sie fügt sich nicht in Blumes Seitenleiste, Suche oder `llms.txt` ein, und Blumes [`playground`](#try-it-playground)-Konfiguration gilt für sie nicht. Blumes Hell-/Dunkel-Umschalter folgt sie allerdings sehr wohl: Das Embed wird beim Einbinden auf das Theme der Seite festgelegt und wechselt mit ihm mit, sodass Scalars eigener Theme-Umschalter ausgeblendet wird (setze `scalar.forceDarkModeState` oder `scalar.darkMode`, um den Farbmodus wieder an Scalar zu übergeben). Scalar bringt einen eigenen Request-Client mit, der deine **Ziel-API direkt aus dem Browser** aufruft (die Route `playground.proxy` steht hier nicht zur Verfügung), daher muss die API Cross-Origin-Anfragen von der Doku-Website zulassen (`Access-Control-Allow-Origin`). `theme` gilt nur für den Scalar-Renderer.

### Scalar-Optionen übergeben

`theme` ist eine Kurzform für die Option, zu der die meisten greifen, aber Scalar unterstützt noch viele weitere. Ein `scalar`-Objekt leitet jede beliebige [Scalar-Konfiguration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) direkt an die eingebettete Referenz weiter – Blume schränkt die Schlüssel nicht ein, sodass alles durchgereicht wird, was Scalar akzeptiert:

```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",
  },
}
```

Blumes eigenes [`i18n`](/docs/content/i18n) übersetzt die Doku-Oberfläche, aber Scalar hat ein separates Lokalisierungssystem – setze `scalar.localization.locale`, um auch die eingebettete Referenz zu übersetzen. Optionen im `scalar`-Objekt haben Vorrang vor der von Blume abgeleiteten Konfiguration, sodass alles, was hier gesetzt wird (einschließlich `theme`, `customCss` oder der Spezifikations-`content`/`url`), Blumes Standardwerte überschreibt. Derselbe `scalar`-Block funktioniert auch bei der `asyncapi`-Referenz.

## AsyncAPI

Ereignisgesteuerte APIs verwenden einen gleichrangigen `asyncapi`-Block mit derselben Struktur – und demselben nativen Renderer. Jede `send`-/`receive`-Operation wird zu einer echten Seite mit Schema-Tabellen für Message-Payload und -Header, Channel-Parametern, Protokoll-Bindings, einem Authorization-Abschnitt, der aus den `securitySchemes` der Spezifikation abgeleitet wird (auf Server- und Operationsebene, Alternativen als „oder“-Gruppen), und einem [„Try it“](#try-it-für-events)-Message-Composer. Nur die Standardroute unterscheidet sich (`/events`):

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}
```

AsyncAPI-**2.x-Spezifikationen werden automatisch auf 3.x normalisiert** – mit dem offiziellen AsyncAPI-Konverter, sodass `publish`-/`subscribe`-Channels auf `send`-/`receive`-Operationsseiten mit stabilen URLs abgebildet werden; ein späteres Aktualisieren der Spezifikationsdatei selbst über den Konverter verschiebt daher nichts. Operationen werden nach Tag gruppiert; Operationen ohne Tag werden unter ihrer Channel-Adresse gruppiert.

Codebeispiele sind **protokollbewusst** und richten sich nach dem Binding der Operation (oder dem Protokoll ihrer Server): `wscat` und ein Browser-`WebSocket`-Snippet für WebSockets, `kcat` für Kafka, `mosquitto_pub`/`mosquitto_sub` für MQTT. `codeSamples` filtert diese Auswahl – genauso, wie es beim `openapi`-Block die Sprachen auswählt; ein Protokoll ohne unterstütztes Tool rendert nur das Message-Payload-Beispiel statt eines erfundenen Clients.

Alles oben Dokumentierte gilt unverändert weiter, [`playground`](#try-it-für-events) eingeschlossen: `route`, `sources` mit `label`/`route`, `expandSchemas`, die Flags für die [Indexierung pro Quelle](#indexierung-pro-quelle) (`seoDescriptionSuffix` inklusive – der generierte Satz benennt statt eines Endpunkts den Channel und die Aktion) sowie die Suchindexierung nach Zusammenfassung und Tag der Operation.

Mit `renderer: "scalar"` wechselst du zurück zur eingebetteten Scalar-SPA, wo – wie bei OpenAPI – nur `noindex` gilt. Scalar hat keinen eigenen AsyncAPI-Playground; das Embed erkennt den Dokumenttyp automatisch und rendert Channels, Operationen, Messages und einen Models-Abschnitt, dieser Tausch kostet dich also den Composer.

### „Try it“ für Events

Nativ gerenderte Operationsseiten liefern auch hier ein **Try it**-Panel, zu denselben Bedingungen wie beim [OpenAPI-Panel](#try-it-playground): serverseitig eingeklappt gerendert, mit JavaScript, das erst geladen wird, wenn Lesende es zum ersten Mal öffnen.

Unabhängig vom Protokoll öffnet das Panel mit einem Payload-Editor, der aus den `examples` der Message vorbelegt ist – oder, wenn die Message keine deklariert, aus einem Wert, der aus dem Payload-Schema gezogen wurde – und beim Tippen gegen das Message-Payload-Schema validiert wird. Darunter sitzen ein Eingabefeld pro Channel-Parameter und eine Server-Auswahl, die aus den `servers` des Channels gespeist wird, mit einem Freitextfeld für jede andere URL. Die protokollbewussten Codebeispiele bleiben genauso im Gleichschritt mit dem Formular wie curl, js und python bei einer HTTP-Operation: Die Vorlage der Channel-Adresse wird mit den von dir eingegebenen Parameterwerten gefüllt, sodass ein kopiertes `wscat`-, `WebSocket`-, `kcat`- oder `mosquitto_pub`-Snippet dem entspricht, was im Formular steht.

Live-Verbindungen gibt es nur für WebSockets. Bei einem `ws`- oder `wss`-Binding verbindet sich das Panel mit der aufgelösten Channel-URL, zeigt den Verbindungsstatus an und protokolliert jeden Frame mit Zeitstempel. AsyncAPI 3 beschreibt eine Aktion aus Sicht der API, und das Panel folgt dem: Eine `receive`-Operation ist eine, die die API von dir empfängt, also bekommt sie einen **Send**-Button, der die zusammengestellte Payload veröffentlicht; eine `send`-Operation streamt dir nur Messages zu, also verbindet sie sich und protokolliert. Es gibt keine Reconnect-Logik – sobald ein Socket geschlossen ist, bleibt er geschlossen, bis du dich erneut verbindest. Kafka, MQTT, AMQP und alle anderen Protokolle bekommen den Composer und die kopierbaren CLI-Beispiele, und das Panel sagt das auf der Seite auch so: Blume täuscht keine Broker-Verbindung aus einem Browser-Tab vor.

`asyncapi.playground` spiegelt `openapi.playground` – beim nativen Renderer standardmäßig aktiv, und `false` ist der komplette Ausschalter:

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}
```

:::note
`playground.proxy` gilt nicht für Event-Operationen. Er leitet HTTP-Anfragen weiter, und eine WebSocket-Verbindung geht direkt aus dem Browser an den in der URL genannten Server – es gibt also nichts, wovor sich ein Proxy setzen könnte.
:::

Der Event-Composer sammelt keine Broker-Anmeldeinformationen. Der Abschnitt **Authorization** jeder Operationsseite dokumentiert, was der Broker erwartet, und eine WebSocket-Verbindung überträgt nur das, was ohnehin schon in der URL steht. Für Event-Operationen wird nichts gespeichert.

---

# Blog
Source: https://useblume.dev/de/docs/advanced/blog

Ein Blog ist in Blume einfach Inhalt mit einem Typ. Markiere eine Seite mit `type: blog` und Blume stattet sie automatisch mit einem RSS-Feed und umfangreicheren Artikel-Metadaten aus. Anders als beim [Changelog](/docs/advanced/changelog) wird keine Übersichtsseite generiert – die Landingpage stellst du selbst zusammen, wodurch das Design vollständig in deiner Hand bleibt.

## Einen Beitrag schreiben

Ein Beitrag ist eine ganz normale `.md`- oder `.mdx`-Seite mit `type: blog` im Frontmatter. Üblicherweise liegen Beiträge unter `blog/`, entscheidend ist aber der Typ – nicht der Ordner:

```mdx blog/introducing-blume.mdx lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
```

Gib jedem Beitrag ein `date`, damit Feed-Einträge neueste zuerst sortiert werden und ein `pubDate` erhalten, sowie eine `description` – sie wird sowohl für die Feed-Zusammenfassung als auch für SEO verwendet.

## Der RSS-Feed

Blume erzeugt einen Blog-Feed unter **`/blog/rss.xml`**, sortiert nach `date` mit den neuesten Einträgen zuerst. Feeds benötigen eine absolute Site-URL, setze daher [`deployment.site`](/docs/deployment); Blume fügt dann auf jeder Seite ein `<link rel="alternate">`-Tag ein, damit Leser den Feed automatisch finden.

Der Feed ist standardmäßig aktiviert. Feinjustieren kannst du ihn unter [`seo.rss`](/docs/configuration/seo#rss-feeds):

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

Entferne `"blog"` aus `rss.types`, um den Feed zu überspringen.

## Strukturierte Daten

Wenn [strukturierte Daten](/docs/configuration/seo#structured-data) aktiviert sind, wird jeder Beitrag als schema.org-**`BlogPosting`** mit seiner Beschreibung und seinem Veröffentlichungsdatum ausgegeben – dem umfangreicheren Artikeltyp, den Suchmaschinen bei Blog-Inhalten erwarten.

## Eine Übersichtsseite erstellen

Blume generiert keine `/blog`-Landingpage, du erstellst sie also selbst. Die einfachste Möglichkeit ist eine Inhaltsseite, die jeden Beitrag von Hand verlinkt:

```mdx blog/index.mdx lineNumbers
---
title: Blog
description: News and writing from the team.
---

<CardGroup cols={2}>
  <Card title="Introducing Blume" href="/blog/introducing-blume">
    Why we built a markdown-first docs framework.
  </Card>
</CardGroup>
```

Um Beiträge stattdessen automatisch aufzulisten, füge unter `pages/blog/index.astro` eine [eigene Seite](/docs/advanced/custom-pages) hinzu, die aus Astros `docs`-Content-Collection liest und jeden Eintrag mit seiner Route aus `blume:data` verknüpft:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    date: entry.data.date,
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }))
  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

Wie du das in das vollständige Site-Layout einbettest, erfährst du unter [Eigene Seiten](/docs/advanced/custom-pages#using-the-site-layout).

**[Eigene Seiten](/docs/advanced/custom-pages)**

Binde die Blog-Übersicht ein und lies aus blume:data.

**[SEO](/docs/configuration/seo)**

Feeds, Open-Graph-Bilder und strukturierte Daten.

---

# Changelog
Source: https://useblume.dev/de/docs/advanced/changelog

Blume bringt ein Changelog von Haus aus mit. Schreiben Sie jedes Release als normale Inhaltsdatei, kennzeichnen Sie es mit `type: changelog`, und Blume sammelt jeden Eintrag in einer generierten Timeline-Seite und einem RSS-Feed – kein Layout zu bauen, keine Liste zu pflegen. Oder verzichten Sie ganz auf die Dateien und [beziehen Sie Ihr Changelog aus GitHub Releases](#from-github-releases).

## Einen Eintrag schreiben

Ein Changelog-Eintrag ist eine gewöhnliche `.md`- oder `.mdx`-Seite mit `type: changelog` im Frontmatter. Üblicherweise liegen sie unter `changelog/`, aber entscheidend ist der Typ – nicht der Ordner:

```mdx changelog/v1-2-0.mdx lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks
```

Geben Sie jedem Eintrag ein `date`, damit Timeline und Feed die neuesten zuerst sortieren. Ein YAML-Datum ohne Anführungszeichen ist in Ordnung – Blume normalisiert es.

### Das `changelog`-Objekt

Das optionale `changelog`-Objekt ergänzt reichhaltigere Metadaten für Timeline und Feed:

| Prop | Type | Default | Description |
| - | - | - | - |
| `changelog.version?` | `string` | - | Release-Version. Fällt auf ein Label mit v-Präfix zurück, wenn kein Titel vorhanden ist. |
| `changelog.category?` | `string` | - | Wird als Tag neben dem Eintrag angezeigt, z. B. Release, Features, Fixes. |
| `changelog.date?` | `string` | - | Veröffentlichungsdatum. Kann hier oder auf oberster Ebene stehen – beides speist Timeline und RSS-Feed. |

## Die Timeline-Seite

Sobald Sie mindestens einen Eintrag mit `type: changelog` haben, generiert Blume automatisch eine **`/changelog`**-Seite. Sie wird als fokussierte Timeline über die volle Breite gerendert – ohne Seitenleiste oder Inhaltsverzeichnis – mit den neuesten Einträgen zuerst und zeigt Datum, Label und `category`-Tag in einer linken Spalte neben dem Inhalt:

- Der **Titel** des Eintrags wird zu seinem Label – oder `v{version}`, wenn kein Titel vorhanden ist. Er verlinkt auf die eigene Seite des Eintrags, sodass ein Release zugleich eine Zeile in der Timeline und ein teilbarer Permalink ist.
- Die `category` wird als Tag neben dem Datum gerendert.
- Entwürfe und Einträge mit `sidebar.hidden` werden übersprungen.

Die Seite erscheint nur, wenn die Route `/changelog` nicht bereits belegt ist. Um sie durch Ihr eigenes Design zu ersetzen, fügen Sie unter `pages/changelog.astro` eine [benutzerdefinierte Seite](/docs/advanced/custom-pages) hinzu – sie übernimmt, und Blume generiert die Standard-Timeline nicht mehr.

Da diese Seite generiert und nicht verfasst wird, ist sie nicht Teil des Inhaltsbaums – ein Header-[Tab](/docs/content/navigation#tabs), der auf `/changelog` zeigt, löst daher zum neuesten Eintrag auf. Geben Sie dem Tab ein `href`, um auf der Übersichtsseite selbst zu landen:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

### Nach Major-Version gruppiert

Wenn Ihre Versionen [Semver](https://semver.org) folgen und mehr als eine Major-Version umfassen, paginiert Blume die Timeline nach Major-Version. Es wird nur die neueste Major-Reihe angezeigt, mit einer Schaltfläche **Show N.x releases** am unteren Rand, die die nächstältere Major-Version mit je einem Klick einblendet:

- Die Erkennung erfolgt automatisch – ohne Konfiguration. Sie greift nur, wenn jedes aufgeführte Release als `major.minor.patch` geparst wird und es mehr als eine Major-Version gibt; andernfalls bleibt die Timeline flach.
- Sie kommt mit den Scoped Tags zurecht, die Monorepos veröffentlichen, sodass `pkg@2.0.0` unter `2.x` und `pkg@1.4.0` unter `1.x` gruppiert wird.
- Es handelt sich um Progressive Enhancement: Jedes Release steht weiterhin im HTML der Seite (sowie im RSS-Feed und im Suchindex), sodass Leser ohne JavaScript – und Crawler – die vollständige Historie sehen. Die Schaltfläche klappt ältere Major-Versionen erst ein, sobald die Seite hydratisiert.

## Aus GitHub Releases

Statt Einträge von Hand zu verfassen, richten Sie die eingebaute [`github-releases`-Quelle](/docs/content/sources#github-releases) auf ein Repository, und jedes Release wird zu einem Eintrag mit `type: changelog` – dieselbe Timeline und derselbe Feed, direkt gespeist aus den Releases, die Sie ohnehin veröffentlichen. Blumes eigenes [Changelog](/changelog) ist so aufgebaut:

```ts blume.config.ts
content: {
  sources: [
    { type: "filesystem", root: "content" },
    {
      type: "github-releases",
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    },
  ],
}
```

Der Name des Releases wird zum Titel, sein Tag zu `changelog.version`, und sein Veröffentlichungsdatum sortiert die Timeline. Jede Release-Seite erhält außerdem eine eindeutige Meta-Description, die aus ihren Notes zusammengefasst wird – Markdown entfernt, Abschnittsüberschriften und Changeset-Commit-Hash-Präfixe verworfen, gekürzt auf die Länge des Such-Snippets, die [`blume audit`](/docs/reference/cli#auditing-the-built-site) prüft – statt auf die Site-Beschreibung zurückzufallen. Ein privates Repository authentifiziert sich über die Umgebungsvariable `GITHUB_TOKEN`. Alle Optionen finden Sie unter [Content sources](/docs/content/sources#github-releases).

## Der RSS-Feed

Blume erstellt außerdem einen Changelog-Feed unter **`/changelog/rss.xml`**, sortiert nach `date` mit den neuesten zuerst. Feeds benötigen eine absolute Site-URL, setzen Sie also [`deployment.site`](/docs/deployment); Blume fügt dann auf jeder Seite ein `<link rel="alternate">`-Tag ein, damit Leser den Feed automatisch entdecken.

Der Feed ist standardmäßig aktiviert. Feinjustieren können Sie ihn unter [`seo.rss`](/docs/configuration/seo#rss-feeds):

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

Entfernen Sie `"changelog"` aus `rss.types`, um den Feed wegzulassen und die Timeline beizubehalten.

## Strukturierte Daten

Wenn [strukturierte Daten](/docs/configuration/seo#structured-data) aktiviert sind, wird jeder Changelog-Eintrag als schema.org-**`TechArticle`** mit Beschreibung und Veröffentlichungsdatum ausgegeben, sodass Suchmaschinen Releases als datierte Artikel indexieren können.

**[Frontmatter](/docs/reference/frontmatter#changelog)**

Das vollständige Frontmatter-Schema für das Changelog.

**[Custom Pages](/docs/advanced/custom-pages)**

Ersetzen Sie die generierte Timeline durch Ihr eigenes Layout.

---

# Benutzerdefinierte Seiten
Source: https://useblume.dev/de/docs/advanced/custom-pages

Der Großteil einer Blume-Website besteht aus Markdown, aber manchmal benötigst du eine Route, die _kein_ Dokument ist — eine Landingpage, eine Preisseite, einen handgebauten Blog- oder Changelog-Index oder ein interaktives Dashboard. Lege eine `.astro`-Datei in deinem **pages**-Ordner ab, und Blume bindet sie als echte Route ein, direkt neben deinen Inhalten.

## Eine Seite hinzufügen

Erstelle im Stammverzeichnis deines Projekts einen `pages/`-Ordner und füge eine `.astro`-Datei hinzu:

```astro pages/pricing.astro lineNumbers
---
import data from "blume:data";
---

<h1>Pricing for {data.config.title}</h1>
```

`blume dev` erkennt sie sofort, und `blume build` rendert sie vorab zu statischem HTML. Der Ordnername ist über [`content.pages`](/docs/configuration#content) konfigurierbar (Standard `"pages"`).

Benutzerdefinierte Seiten behalten ihren ursprünglichen Speicherort auf der Festplatte, sodass relative Importe, Komponentenimporte und [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) genau so funktionieren wie in einem einfachen Astro-Projekt — Blume bindet jede Datei dort ein, wo sie liegt, statt sie zu kopieren.

## Dateien und Routen

Der Pfad jeder Datei innerhalb des pages-Ordners wird zu ihrer Route. `index` verweist auf den übergeordneten Ordner, und dynamische `[param]`-Segmente bleiben erhalten:

| Datei                     | Route         |
| ------------------------- | ------------- |
| `pages/pricing.astro`     | `/pricing`    |
| `pages/blog/index.astro`  | `/blog`       |
| `pages/blog/[slug].astro` | `/blog/:slug` |
| `pages/changelog.astro`   | `/changelog`  |

Eine benutzerdefinierte Seite **gewinnt** gegenüber einer generierten Route mit demselben Pfad. Fügt man beispielsweise `pages/changelog.astro` hinzu, ersetzt das Blumes [generierte Changelog-Zeitleiste](/docs/advanced/changelog) durch deine eigene.

## Website-Daten lesen

Importiere `blume:data`, um dieselbe aufgelöste Konfiguration, Navigation, Routen und Feeds zu lesen, die auch der Rest der Website verwendet:

```astro pages/all-pages.astro lineNumbers
---
import data from "blume:data";
---

<h1>All pages</h1>
<ul>
  {
    data.routes
      .filter((route) => route.indexable)
      .map((route) => (
        <li>
          <a href={route.path}>{route.title}</a>
        </li>
      ))
  }
</ul>
```

Innerhalb eines Blume-Projekts ist das Modul automatisch typisiert. Du kannst die Struktur mit `import type { BlumeData } from "blume"` auch explizit einbinden — für typisierte Hilfsfunktionen, Props oder deine eigene tsconfig:

```ts
import type { BlumeData, BlumeRoute } from "blume";

const indexable = (data: BlumeData): BlumeRoute[] =>
  data.routes.filter((route) => route.indexable);
```

Das Modul stellt Folgendes bereit:

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `BlumeDataConfig` | - | Aufgelöste Website-Einstellungen: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host und die REST-API-Basis — null, wenn nicht gesetzt), search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap und imageZoom. |
| `navigation` | `Navigation` | - | Die aus deinen Inhalten abgeleitete Seitenleiste, Tabs und Auswahlelemente (Standard-Locale). |
| `navigationByLocale` | `Record<string, Navigation>` | - | Navigationsbäume pro Locale, indiziert nach Locale-Code. Leer, sofern i18n nicht konfiguriert ist. |
| `routes` | `BlumeRoute[]` | - | Jede Inhaltsseite: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }. |
| `feeds` | `BlumeFeed[]` | - | Generierte RSS-Feeds: { href, title }. |
| `fontCssVars` | `string[]` | - | CSS-Variablennamen für die konfigurierten Schriftarten (Astro-<Font>-Integration). |
| `ui` | `UIStrings` | - | Aufgelöste UI-Chrome-Zeichenketten für die Standard-Locale (Beschriftungen für Suche, Seitenleiste und Fußzeile). |
| `uiByLocale` | `Record<string, UIStrings>` | - | UI-Zeichenketten pro Locale, indiziert nach Locale-Code. Leer, sofern i18n nicht konfiguriert ist. |

`routes` enthält Seiten-Metadaten, aber kein Frontmatter wie `type` oder `date`. Um eine nach Inhaltstyp gefilterte Liste zu erstellen — einen Blog- oder Changelog-Index — kombiniere es mit Astros `docs`-Inhaltssammlung, die das Frontmatter enthält:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

// Each route's id matches its collection entry id.
const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

## Laufzeit-Hilfsfunktionen

`blume/runtime` bündelt die gängigen Datenmuster, sodass du nicht auf die Interna von `blume:data` zugreifen musst.

**`getBlumeCollection(data, query?)`** wählt Inhaltsrouten aus — gefiltert nach Sammlung, Locale oder Pfadpräfix, wobei Entwürfe und ausgeblendete Seiten ausgeschlossen und die Ergebnisse nach Pfad sortiert werden — genau das, was ein benutzerdefinierter Index braucht:

```astro pages/blog/index.astro lineNumbers
---
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const posts = getBlumeCollection(data, { prefix: "/blog" });
---

<ul>
  {posts.map((post) => (
    <li><a href={post.path}>{post.title}</a></li>
  ))}
</ul>
```

**`<BlumePage>`** rendert den Textkörper eines Inhaltseintrags innerhalb einer benutzerdefinierten Seite, wobei Blumes integrierte MDX-Komponenten (Hinweisboxen, Karten, Schritte …) bereits eingebunden sind — um ein Dokument auf einer Landingpage hervorzuheben oder einen maßgeschneiderten Index zu bauen, der echte Inhalte zeigt:

```astro pages/index.astro lineNumbers
---
import BlumePage from "blume/components/BlumePage.astro";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const [intro] = getBlumeCollection(data, { prefix: "/docs" });
---

{intro && <BlumePage id={intro.entryId} />}
```

Übergib `components`, um eigene Überschreibungen oder Islands hinzuzufügen (die in der generierten Laufzeitumgebung liegen und standardmäßig nicht importiert werden), und `collection`, um aus einer anderen Sammlung als `"docs"` zu lesen.

## Das Website-Layout verwenden

`RootLayout` verleiht einer benutzerdefinierten Seite das komplette Dokumentations-Chrome — Kopfzeile, Seitenleiste, Suche, Inhaltsverzeichnis und Theme —, indem es sie in dasselbe dreispaltige Raster einbettet, das auch die generierten Seiten verwenden. Für eine Landing- oder Marketingseite steht dieses Raster im Weg, greif deshalb stattdessen zu **`PageLayout`**: Es liefert die Dokumenthülle, die Kopfzeile, das Theme und die Schriftarten und dann einen einzelnen `<slot />` über die volle Breite (keine Seitenleiste, kein Fließtext, kein Inhaltsverzeichnis). Ein optionaler `footer`-Slot wird nach `<main>` gerendert:

```astro pages/index.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
import Footer from "./_home/Footer.astro";

const { config } = data;
---

<PageLayout
  site={{ title: config.title, description: config.description }}
  logo={config.logo}
  banner={config.banner}
  analytics={config.analytics}
  navigation={data.navigation}
  favicon={config.favicon}
  fontCssVars={data.fontCssVars}
  themeMode={config.theme.mode}
  searchEnabled={config.search.enabled}
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  page={{ title: "Acme — the fastest docs", description: config.description }}
>
  <section class="mx-auto max-w-5xl px-6 py-24">
    <h1>Build docs that fly</h1>
  </section>
  <Footer slot="footer" />
</PageLayout>
```

Die Kopfzeile, die eine benutzerdefinierte Seite erhält, ist dieselbe wie bei den Dokumentationsseiten, sodass das darin enthaltene Chrome mitkommt: Suche, der Theme-Umschalter, der Sprachwechsler und — wenn [Ask AI](/docs/configuration/ai) konfiguriert ist — der Ask-AI-Auslöser. Nichts davon muss pro Seite eingerichtet werden. Übergib `askEnabled={false}`, um den Ask-Auslöser auf einer Seite wegzulassen und ihn überall sonst beizubehalten.

Die Übergabe von `siteUrl` (und `ogEnabled`) leitet automatisch das `canonical` der Seite und ein generiertes `og:image` ab: Blume rendert für jede statische benutzerdefinierte Seite eine Open-Graph-Karte — einschließlich der Startseite, der am häufigsten geteilten URL —, ausgeliefert unter `/og/<route>.png` (`/og/index.png` für `/`). Die Startseiten-Karte verwendet den Website-Titel mit der Beschreibung als Kopfzeile; eine tiefer liegende Seite wird nach ihrem letzten Pfadsegment benannt. Setze `ogImage` oder `canonical` explizit, um eines von beiden zu überschreiben. `ogImage` erwartet einen wurzelrelativen Pfad — eine Datei in `public/`, die anhand von [`deployment.site`](/docs/deployment) zu der absoluten URL aufgelöst wird, die Crawler benötigen — oder eine externe URL, die unverändert durchgereicht wird:

```astro pages/index.astro lineNumbers
<PageLayout
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  ogImage="/opengraph-image.png"
  ogImageAlt="Acme — the fastest docs"
  ogImageSize={{ width: 1200, height: 630 }}
  page={{ title: config.title }}
>
  <!-- page content -->
</PageLayout>
```

Nur diese eine Seite ändert sich — jede andere Route behält ihre generierte Karte —, und so gibst du allein der Startseite ein maßgeschneidertes Teilen-Bild. Die generierte Karte gibt ihre Größe und ihren Alternativtext von sich aus an Crawler weiter; übergib bei deinem eigenen `ogImage` zusätzlich `ogImageAlt` und `ogImageSize`, damit die Teilen-Karte dieselbe Behandlung erhält.

Die Seite gibt außerdem schema.org-JSON-LD aus — denselben `WebSite`-Graphen, den auch die Dokumentationsseiten mitführen, damit die Startseite (üblicherweise eine benutzerdefinierte Seite) nicht die eine URL ohne strukturierte Daten ist. Übergib `structuredDataEnabled={config.structuredData}`, um sie mit der [`structuredData`](/docs/configuration/seo)-Konfiguration synchron zu halten, oder `structuredDataEnabled={false}`, um sie für eine Seite abzuschalten.

`page.title` wird wortwörtlich als Dokumenttitel verwendet (ohne `- siteTitle`-Suffix), da Marketingseiten üblicherweise ihren eigenen festlegen. Um einer benutzerdefinierten Seite stattdessen das komplette Dokumentations-Chrome zu geben — Seitenleiste, Inhaltsverzeichnis und alles Weitere —, bette sie in `RootLayout` ein, das Layout, das auch die generierten Seiten verwenden. Beziehe die erforderlichen Props direkt aus `blume:data`:

```astro pages/pricing.astro lineNumbers
---
import RootLayout from "blume/components/layout/RootLayout.astro";
import data from "blume:data";
---

<RootLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  banner={data.config.banner}
  navigation={data.navigation}
  page={{ title: "Pricing", route: "/pricing" }}
  headings={[]}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  indexable={true}
>
  <h1>Pricing</h1>
</RootLayout>
```

:::note
`RootLayout` ist Teil der generierten Laufzeitumgebung, daher können sich seine Props zwischen Releases ändern. Wenn du ein Layout möchtest, das vollständig dir gehört, verwandelt [`blume eject`](/docs/configuration/customization#eject) `.blume/` in ein normales Astro-Projekt, das dir uneingeschränkt gehört.
:::

## 404-Seite

Blume liefert ab Werk eine standardmäßige **Nicht gefunden**-Seite mit: eine zentrierte „404“-Meldung, eingebettet in das Website-Chrome (Kopfzeile, Suche, Theme), die für jede nicht zugeordnete URL ausgeliefert wird. `blume build` schreibt sie nach `404.html`, was statische Hoster automatisch ausliefern, und `blume dev` zeigt sie für unbekannte Routen an. Unterhalb der Meldung verlinkt eine Liste **Wo du als Nächstes nachsehen kannst** jeden Abschnitt der obersten Ebene sowie die Indizes `sitemap.xml` und [`llms.txt`](/docs/configuration/ai#llmstxt), sofern vorhanden, damit eine lesende Person — oder ein Agent, der einer veralteten URL gefolgt ist — einen Weg zurück hat.

Die Seite hat außerdem ein Markdown-Gegenstück unter `/404.md` und ein JSON-Gegenstück unter `/404.json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)-Problemdetails) mit denselben Rückkehr-Links (absolute URLs, sobald [`deployment.site`](/docs/deployment) gesetzt ist), dazu die [`openapi.json`](/docs/configuration/ai#json-api)-Beschreibung, wenn die JSON-API aktiviert ist. Bei einem [Vercel-Server-Build](/docs/deployment#server-rendering) erhält eine Anfrage nach einer fehlenden Seite, die [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation) sendet oder eine `.md`-URL anfordert, hinter der keine Seite steht, diesen Markdown-Textkörper mit dem Status `404` statt der HTML-Hülle; eine Anfrage, die `Accept: application/json` sendet oder eine `.json`-URL anfordert, hinter der keine Datei steht, erhält das Problemdokument — sodass ein Agent nie eine Seite voller Chrome parsen muss, um zu erfahren, wohin es weitergeht.

Um sie durch deine eigene zu ersetzen, füge eine `pages/404.astro` hinzu. Sie übernimmt die `/404`-Route genauso, wie `pages/changelog.astro` den Changelog übernimmt — deine Seite gewinnt, und die Standardseite entfällt. Bau sie wie jede andere benutzerdefinierte Seite, in `PageLayout` oder `RootLayout`:

```astro pages/404.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
---

<PageLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  navigation={data.navigation}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  page={{ title: "Page not found", route: "/404" }}
  noindex={true}
>
  <section class="mx-auto max-w-2xl px-6 py-24 text-center">
    <h1>This page took a wrong turn</h1>
    <a href="/">Back to home</a>
  </section>
</PageLayout>
```

Um das Standarddesign beizubehalten, aber seine Formulierungen zu ändern — auch für andere Sprachen —, überschreibe die `notFound`-[UI-Zeichenketten](/docs/content/i18n) (`title`, `description`, `home`) über `i18n.ui`.

## Interaktive Seiten

Benutzerdefinierte Seiten sind gewöhnliches Astro, sodass du React- (oder Framework-beliebige) [Islands](/docs/configuration/customization#interactive-islands) mit einer Hydratations-Direktive einbinden kannst. React wird automatisch aktiviert, sobald dein Projekt eine `.tsx`- oder `.jsx`-Datei enthält.

**[Anpassung](/docs/configuration/customization)**

Komponenten-Überschreibungen, React-Islands, die Registry und Eject.

**[Blog](/docs/advanced/blog)**

Beiträge verfassen und einen benutzerdefinierten Blog-Index erstellen.

---

# GraphQL
Source: https://useblume.dev/de/docs/advanced/graphql

Richte Blume auf ein GraphQL-Schema aus, und es generiert eine native API-Referenz: eine **echte Seite pro Root-Feld** — Queries, Mutations und Subscriptions — plus eine **Seite pro benanntem Typ** (Objects, Input Objects, Enums, Interfaces, Unions und Custom Scalars). Jede Seite zeigt Argumente, Standardwerte, Deprecations und Verwendungs-Backlinks, daneben eine generierte Beispieloperation, Code-Beispiele und ein interaktives [Try it](#try-it-playground)-Panel. Da jede Seite eine echte Blume-Seite ist, bekommt sie ihre eigene URL, taucht in der **Website-Suche** und in `llms.txt` auf und erhält ein Open-Graph-Bild — genau wie jedes handgeschriebene Dokument.

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
}
```

Damit wird die Referenz unter `/graphql` eingebunden (eine Übersichtsseite), mit Root-Feldern unter `/graphql/queries/<field>`, `/graphql/mutations/<field>` und `/graphql/subscriptions/<field>` sowie Typen, gruppiert nach Art, unter `/graphql/objects/<type>`, `/graphql/enums/<type>` und so weiter.

Die `spec` ist entweder ein Pfad zu einer lokalen Datei in deinem Projekt oder eine `http(s)`-URL und akzeptiert zwei Formate:

- **SDL-Text** — eine `.graphql`-Datei mit Typdefinitionen.
- **Ein Introspection-Ergebnis** — das JSON, das beim Ausführen der Standard-Introspection-Query entsteht, entweder in der rohen `{ "__schema": … }`-Form oder als vollständiger `{ "data": { "__schema": … } }`-Response-Envelope.

Der `endpoint` ist die URL der laufenden GraphQL-API. Ein Schema benennt — anders als ein OpenAPI-Dokument — keinen Server, also ist der Endpoint das Ziel für das Try-it-Panel und die generierten Code-Beispiele. Lässt du ihn weg, werden die Beispiele mit einer Platzhalter-URL gerendert, die Leser ersetzen.

Die Referenz fügt von sich aus keinen Header-Tab hinzu. Um sie sichtbar zu machen, richte einen [Navigations-Tab](/docs/content/navigation#tabs) auf ihre Route aus — das begrenzt auch die Sidebar der Referenz:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}
```

## Generierte Beispiele

Jede Operationsseite enthält eine vollständige, gültige Beispieloperation — eine Variable pro Argument, typisiert anhand des Schemas, mit einem tiefenbegrenzten Selection Set über den Rückgabetyp — plus passende Beispielvariablen und eine Beispielantwort, die dieselbe Auswahl widerspiegelt. Code-Beispiele zeigen den exakten HTTP-Request (ein JSON-`POST` von `{ query, variables }`) in jeder konfigurierten Sprache:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  codeSamples: ["curl", "js"],   // built in: curl, js, python
}
```

## Typseiten

Benannte Typen bekommen ihre eigenen, direkt verlinkbaren Seiten, in der Sidebar nach Art gruppiert: Felder und Input-Felder mit verlinkten Typen, Enum-Werte, Union-Mitglieder, Interface-Implementierungen sowie einen Abschnitt **Verwendet von**, der die Operationen auflistet, die den Typ zurückgeben oder annehmen, und die anderen Typen, die ihn referenzieren. Spec-definierte Scalars (`String`, `Int`, …) bekommen keine Seiten; Custom Scalars schon, inklusive ihrer `specifiedBy`-URL.

## Mehrere Schemas

Jeder Eintrag in `sources` rendert ein Schema auf seiner eigenen Route. Ein `endpoint` pro Quelle überschreibt den auf Block-Ebene:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  endpoint: "https://api.example.com/graphql",
  sources: [
    { label: "Public API", spec: "./schema.graphql" },
    {
      label: "Admin API",
      route: "/graphql-admin",
      spec: "./admin.graphql",
      endpoint: "https://admin.example.com/graphql",
    },
  ],
}
```

Jede Quelle nimmt dieselben [Steuerungen pro Quelle](/docs/advanced/api-reference#per-source-indexing) entgegen wie der OpenAPI-Block: `includeInSearch`, `includeInLlms`, `noindex` und `seoDescriptionSuffix` (hier benennt der generierte Satz die Query, die Mutation oder den Typ — „Referenz für die `pets`-Query in der GraphQL-API.“).

## Try-it-Playground

Query- und Mutation-Seiten rendern ein interaktives Panel: Bearbeite den Request-Body (die Query und die Variablen), richte ihn auf deinen Endpoint oder eine eigene URL aus und sende ihn ab — die Code-Beispiele aktualisieren sich live, sodass das, was du kopierst, Byte für Byte dem entspricht, was gesendet wurde. Deaktiviere es mit `playground: false`. Subscription-Seiten zeigen stattdessen die generierte Operation und ein Beispiel-Event: Subscriptions laufen über einen zustandsbehafteten Transport (WebSocket oder SSE), den der einzelne HTTP-`POST` des Playgrounds nicht sprechen kann.

Wenn deine GraphQL-API keine Cross-Origin-Requests von der Docs-Site erlaubt, leite Sendungen über einen CORS-Proxy — eine eigene URL oder `true` für den eingebauten `/_api-proxy`-Endpoint (der `deployment.output: "server"` erfordert). Der eingebaute Proxy leitet nur an Origins weiter, die deine dokumentierten Specs deklarieren — jeder konfigurierte GraphQL-`endpoint`, plus jede absolute `servers[].url` aus einer dokumentierten [OpenAPI-Spec](/docs/advanced/api-reference) — sodass ein öffentliches Docs-Deployment nicht auf andere Hosts gerichtet werden kann. Damit ist `endpoint` für einen funktionierenden Proxy erforderlich: ohne ihn hat der Proxy keine Origin, die er für diese Referenz erlauben könnte, und lehnt jede Sendung ab (der Build warnt davor).

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
  playground: { proxy: true },
}
```

---

# Skills
Source: https://useblume.dev/de/docs/advanced/skills

Blume liefert [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills) mit — Playbooks, die einem Coding-Agenten (Claude Code, Codex, Cursor) beibringen, wie er eine Blume-typische Aufgabe erledigt, ohne dass du es ihm erklären musst. Sie liegen auf GitHub im Ordner `skills/` des Repos und sind im installierten Paket unter `skills/` gebündelt, sodass jeder Agent direkt auf eine `SKILL.md` verwiesen werden kann.

## Blume

Der zentrale Skill. Er bringt dem Agenten bei, was Blume ist und wie man eine Website aufsetzt, schreibt und konfiguriert — vom Dateisystem abgeleitete Navigation, das Config-Schema, Content-Komponenten — und verweist ihn auf die vollständige Dokumentation, die im installierten Paket gebündelt ist (das Verzeichnis `docs/` innerhalb von `blume`, aufgelöst von dort, wo dein Paketmanager es installiert — in einem pnpm-Monorepo ist das das `node_modules` des abhängigen Workspaces, nicht das Repo-Root). Installiere ihn in jedem Projekt, in dem dir ein Agent beim Erstellen deiner Dokumentation hilft:

```bash
npx skills add haydenbleasel/blume
```

## Selbstaktualisierende Dokumentation

`blume-update-docs` hält deine Dokumentation mit dem Produkt synchron, das sie beschreibt. Bei jedem Durchlauf — typischerweise nach einem Zeitplan, den du in deinem Agent-Runner konfigurierst — prüft der Skill kürzlich gemergte PRs, Changelogs, Config-Schemas und CLI-Hilfetexte gegen die Doku-Inhalte, aktualisiert nur Seiten, die inhaltlich veraltet sind (Arbeiten hinter Feature-Flags werden ignoriert), verifiziert das Ergebnis mit `blume build` und öffnet oder aktualisiert einen `blume/*`-Pull-Request. Wenn sich nichts verändert hat, meldet er einen sauberen No-Op, statt einen störenden PR zu öffnen.

```bash
npx skills add haydenbleasel/blume --skill blume-update-docs
```

Blume hostet die Automatisierung nicht — binde den Skill in eine geplante Aufgabe in Claude Code, eine Codex- oder Cursor-Automatisierung oder ein schlichtes Cron ein, mit der Berechtigung, die Repo-Historie zu lesen und PRs zu öffnen. Ein typischer wöchentlicher Prompt:

```text
Use the blume-update-docs skill. Review the PRs merged within the last 7 days and compare them to the docs content. Ignore work behind feature flags. If docs need updates, make them, verify the docs build, and open a blume/* PR. If not, report what you checked and do not open a PR.
```

---

# Konfigurationsdatei
Source: https://useblume.dev/de/docs/configuration

Blume liest `blume.config.ts` aus dem Stammverzeichnis deines Projekts. Umschließe deine Konfiguration mit `defineConfig`, um Autovervollständigung und Typprüfung zu erhalten — jedes Feld ist optional und hat einen sinnvollen Standardwert.

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});
```

## Ein vollständiges Beispiel

Ein umfassenderes Beispiel, das die gängigsten Optionen abdeckt (den Rest findest du in der Anleitung zur jeweiligen Funktion):

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [sitemap()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — see the Search guide
  search: {
    provider: "orama",
  },

  // Markdown features
  markdown: {
    imageZoom: true,
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
    },
    codeBlocks: {
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // AI — see the AI guide
  ai: {
    llmsTxt: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — see the Deployment guide
  deployment: {
    output: "static",
    site: "https://docs.example.com",
  },
});
```

## Website

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `title` | `"Documentation"` | Name der Website — wird im Header, in Seitentiteln und OG-Karten angezeigt. |
| `description` | — | Standard-Meta-Beschreibung, wird für SEO und OG verwendet. |
| `logo` | — | Bildmarke und/oder Wortmarke, die im Header angezeigt wird. |
| `banner` | — | Websiteweite Ankündigungsleiste über dem Header. |

### Logo

Verweise mit `logo` auf eine SVG-Datei, und Blume bindet sie inline ein, sodass ein Logo mit `currentColor` automatisch dem hellen und dunklen Theme folgt:

```ts blume.config.ts
logo: "/logo.svg",
```

Die SVG-Datei kann im Stammverzeichnis deines Projekts oder in `public/` liegen. Die Marke besteht aus einer Bildmarke (`image`) plus einer Wortmarke (`text`); in der Objektform kannst du beide unabhängig voneinander festlegen:

```ts blume.config.ts lineNumbers
logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},
```

`image` nimmt denselben Wert wie die Kurzform entgegen — einen einzelnen Pfad oder `{ light, dark, alt }` für getrennte helle/dunkle Grafiken (Rasterbilder müssen in `public/` liegen).

`text` steuert die Wortmarke unabhängig von der Bildmarke:

- **Lässt du `text` weg**, verwendet die Marke den `title` deiner Website (Standardverhalten).
- **Setze `text: ""`**, um nur die Bildmarke anzuzeigen — praktisch, wenn das Logobild die Wortmarke bereits enthält.
- **Setze `text` ohne `image`** für ein reines Text-Logo.

### Favicon

Es gibt keine Favicon-Option — Blume erkennt es automatisch anhand des Dateinamens, so wie Next.js es tut. Lege eine `icon`- oder `favicon`-Datei (`.svg`, `.png` oder `.ico`) in das Stammverzeichnis deines Projekts oder in das Verzeichnis `public/`, und sie wird zum Symbol im Browser-Tab:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/
```

Sind mehrere vorhanden, gewinnt SVG vor PNG vor ICO, und eine Datei in `public/` wird gegenüber einer im Stammverzeichnis bevorzugt. Findet Blume kein Icon, greift es auf die eigene Bildmarke zurück.

Eine dunkle Bildmarke verschwindet vor dunkler Browser-Oberfläche, deshalb kannst du eine zweite Datei für den Dunkelmodus mitliefern. Lege eine `-dark`-Geschwisterdatei neben deine Icon-Datei — gleicher Name, gleiches Verzeichnis, mit `-dark` vor der Dateiendung (`icon.png` → `icon-dark.png`) — und Blume gibt beide Icons hinter einer `prefers-color-scheme`-Media-Query aus, plus ein einfaches helles Tag für Browser und Crawler, die Media Queries bei Icons ignorieren:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/
```

Verwendet wird nur die Geschwisterdatei des Icons, das Blume ausgewählt hat — eine `-dark`-Datei mit einem anderen Namen bleibt unbeachtet, sodass sich keine unbeteiligte Datei versehentlich mit deiner Bildmarke paaren kann. Die dunkle Datei ist optional; bei nur einem Icon gibt Blume wie bisher ein einzelnes Tag aus. Blumes eigene Fallback-Bildmarke bringt beide Varianten mit.

### Apple-Touch-Icon

Das Symbol, das iOS verwendet, wenn jemand deine Website zum Home-Bildschirm hinzufügt, wird auf dieselbe Weise erkannt. Lege eine `apple-icon`-Datei (`.png`, `.jpg` oder `.jpeg`) — oder eine `apple-touch-icon.png`, den Namen, den die meisten Favicon-Generatoren ausgeben — in das Stammverzeichnis deines Projekts oder in das Verzeichnis `public/`, und Blume richtet `<link rel="apple-touch-icon">` für dich ein. Es gibt keinen Standardwert; wird keine Datei gefunden, wird kein Tag ausgegeben.

```
my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/
```

Lege die Datei in `public/` statt in das Stammverzeichnis des Projekts: iOS ignoriert die Inline-Daten-URI, die Blume für ein Icon im Stammverzeichnis verwendet, sodass nur eine Datei in `public/` (ausgeliefert unter `/apple-icon.png`) zuverlässig auf den Home-Bildschirm gelangt. Anders als beim Favicon gibt es hier keine `-dark`-Geschwisterdatei — iOS ignoriert Media Queries bei Home-Bildschirm-Icons, eine dunkle Variante könnte also nie ausgeliefert werden.

### Banner

Zeige eine websiteweite Ankündigungsleiste über dem Header an. Übergib eine Zeichenkette oder ein Objekt mit einem Link und einer Schließen-Schaltfläche:

```ts blume.config.ts
banner: "Docs are in beta — expect changes.",
```

```ts blume.config.ts lineNumbers
banner: {
  content: "Blume v1 is here!",
  link: { text: "Read more", href: "/blog/v1" },
  dismissible: true,
  id: "v1",
},
```

Ist `dismissible` aktiviert, zeigt die Leiste eine Schließen-Schaltfläche und bleibt für diese Besucherin bzw. diesen Besucher danach ausgeblendet. Der Schlüssel für das Ausblenden basiert standardmäßig auf dem Inhaltstext, sodass eine Bearbeitung der Nachricht das Banner zurückbringt; setze eine feste `id`, damit es über Bearbeitungen hinweg ausgeblendet bleibt.

## Inhalte

Wo deine Inhalte liegen und wie Blume sie findet. Unter [Seiten](/docs/content) erfährst du, wie aus Dateien Routen werden.

```ts blume.config.ts lineNumbers
content: {
  root: "docs",
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `root` | `"docs"` | Ordner, den Blume nach Inhalten durchsucht. |
| `include` | `["**/*.{md,mdx}"]` | Globs, die auf Inhaltsdateien passen. |
| `exclude` | `["**/_*", "**/.*"]` | Zu ignorierende Globs (Dateien mit Unterstrich und Punkt am Anfang). |
| `pages` | `"pages"` | Ordner für benutzerdefinierte `.astro`-Seiten. |
| `defaultType` | `"doc"` | Seiten-`type`, der verwendet wird, wenn das Frontmatter ihn weglässt. |
| `types` | `{}` | Inhaltsdefinitionen pro Typ — benutzerdefinierte Frontmatter-Schlüssel, die auf Seiten eines `type` beschränkt sind. Siehe [Frontmatter](#frontmatter). |

Statische Assets liegen in `public/` — eine Datei unter `public/logo.png` wird unter `/logo.png` ausgeliefert, sodass eine Referenz wie `![](/images/create.png)` auf `public/images/create.png` verweist. Bilder, die über einen **relativen Pfad** referenziert werden (`![](./diagram.png)`), liegen stattdessen neben deinen Inhalten und werden [beim Build optimiert](/docs/content/syntax#links-and-images).

## Bilder

Lokale Bilder, die über einen relativen Pfad referenziert werden, werden beim Build automatisch optimiert — komprimiert, in WebP konvertiert und mit intrinsischen `width`/`height`-Attributen versehen, damit das Layout beim Laden nicht springt. Es gibt nichts zu konfigurieren; Hinweise zum Verfassen findest du unter [Links und Bilder](/docs/content/syntax#links-and-images).

Externe Bilder werden standardmäßig unverändert ausgeliefert. Damit Blume sie ebenfalls beim Build herunterlädt und optimiert, autorisiere ihre Hosts:

```ts blume.config.ts lineNumbers
image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `domains` | `[]` | Hostnamen, deren externe Bilder optimiert werden dürfen. |
| `remotePatterns` | `[]` | Musterbasierte Autorisierung (`protocol`, `hostname`, `port`, `pathname`); Hostnamen akzeptieren die Platzhalter `*.` (eine Ebene) und `**.` (beliebige Tiefe). |

## Frontmatter

Das Frontmatter einer Seite wird streng validiert — ein unbekannter Schlüssel lässt den Build fehlschlagen, sodass Tippfehler früh auffallen. Um projektspezifische Metadaten zu hinterlegen (eine verantwortliche Person, ein Prüfdatum), deklariere die zusätzlichen Schlüssel unter `frontmatter.extend`, jeweils zugeordnet zu einem von dir bereitgestellten Schema:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

Jede [Standard-Schema](https://standardschema.dev)-Bibliothek funktioniert — Zod (in der Version, die dein Projekt installiert), Valibot, ArkType. Schlüssel außerhalb der Erweiterung bleiben streng validiert, das Erkennen von Tippfehlern ändert sich also nicht. Zur Validierungssemantik siehe [Benutzerdefinierte Schlüssel](/docs/reference/frontmatter#custom-keys).

Schlüssel unter `extend` gelten websiteweit. Um Schlüssel nur auf Seiten eines Inhaltstyps vorzuschreiben — der `status` eines RFCs, der `service` eines Runbooks — deklariere sie stattdessen pro Typ unter `content.types`:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

Ein Schlüssel kann websiteweit oder pro Typ deklariert werden, nicht beides. Wie die Zuordnung aufgelöst wird, erfährst du unter [Schlüssel pro Typ](/docs/reference/frontmatter#per-type-keys).

`facets` benennt die benutzerdefinierten Schlüssel, deren Werte zu filterbaren Metadaten werden: Sie werden mit den Suchdokumenten mitgeführt (`blume-search.json` und der MCP-Index), und die [MCP-Tools](/docs/configuration/ai#mcp-server) akzeptieren eine `filters`-Eingabe, die gegen sie abgeglichen wird, sodass ein Agent zum Beispiel nur `enforced`-RFCs in der Domäne `architecture` abrufen kann. Jedes Facet muss ein deklarierter benutzerdefinierter Schlüssel sein — pro Typ oder websiteweit — und nur Zeichenketten-Werte (oder in Zeichenketten umgewandelte Zahlen/Booleans) werden facettiert.

## GitHub

Verweise Blume mit `github` auf dein Repository. Das versorgt den [Repository-Link](/docs/content/navigation#repository-link) im Header sowie die [Seitenaktionen](/docs/content/navigation#page-actions) **Edit on GitHub** und **Give feedback**:

```ts blume.config.ts lineNumbers
github: {
  owner: "acme",
  repo: "docs",
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `owner` | — | GitHub-Konto oder -Organisation, der bzw. dem das Repository gehört. |
| `repo` | — | Name des Repositorys. |
| `branch` | `"main"` | Branch, auf den die Bearbeitungslinks verweisen. |
| `dir` | — | Pfad vom Repository-Stammverzeichnis zum Projektstammverzeichnis (für Monorepos). |
| `host` | `"https://github.com"` | Origin der GitHub-Instanz, für Enterprise-Installationen. Muss HTTP(S) sein; wird auf ihren Origin normalisiert. |
| `api` | aus `host` abgeleitet | REST-API-Basis, für `<GithubInfo>` gegen eine Enterprise-Instanz. Muss HTTP(S) sein; wird auf einen Origin und Pfad normalisiert. |

### GitHub Enterprise

Dokumentationen, deren Repository auf einer GitHub-Enterprise-Instanz liegt, setzen `host`, und jeder aus dem Repository abgeleitete Link — die Bildmarke im Header, Bearbeitungslinks, das Agenten-Manifest — verweist dann auf diese Instanz statt auf die öffentliche Website:

```ts blume.config.ts lineNumbers
github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}
```

Die REST-API-Basis, die [`<GithubInfo>`](/docs/content/components) abfragt, wird aus `host` abgeleitet: Ein Enterprise-Cloud-Tenant mit Datenresidenz (`acme.ghe.com`) wird über seine `api.`-Subdomain ausgeliefert, und jeder andere Host wird als Enterprise Server behandelt (`/api/v3`). Setze `api` explizit, wenn deine Instanz woanders liegt.

:::warning
Eine Instanz, die nur über einfaches HTTP erreichbar ist, rendert ihre Zahlen weiterhin, aber `GITHUB_TOKEN` wird von der Anfrage zurückgehalten, statt im Klartext gesendet zu werden — die Karte eines privaten Repositorys kommt also ohne sie zurück.
:::

:::note
`host` deckt Links ab, die Blume aus `github` ableitet. Um nur die Bildmarke im Header woanders hinzuleiten — etwa auf eine Organisation, wenn das Docs-Repository selbst privat ist — verwende [`navigation.repo`](/docs/content/navigation#repository-link) mit einer absoluten URL.
:::

## Zuletzt geändert

Zeige am Ende jeder Seite eine Zeile „Zuletzt aktualisiert am …“ an. Standardmäßig deaktiviert; setze `lastModified` auf `true`, um das Datum jeder Seite aus ihrer Git-Historie abzuleiten:

```ts blume.config.ts
lastModified: true,
```

| Wert | Beschreibung |
| --- | --- |
| `false` | Deaktiviert (Standard). |
| `true` | Datum aus der Git-Historie lesen (Commit-Daten). |
| `{ type: "git" }` | Dasselbe wie `true`, nur explizit geschrieben. |
| `{ type: "frontmatter" }` | Git nie ausführen — ausschließlich das Frontmatter-Feld `lastModified` verwenden. |

Die Git-Quelle liest den jüngsten Commit, der die jeweilige Datei berührt hat, funktioniert also in jedem Git-Repository — auch in Monorepos — und benötigt die Historie des Repositorys zur Build-Zeit. CI-Plattformen checken üblicherweise einen flachen Klon aus, wodurch die meisten Daten stillschweigend verloren gehen (der Build warnt in diesem Fall mit `BLUME_SHALLOW_GIT_HISTORY`): Setze auf Vercel die Umgebungsvariable `VERCEL_DEEP_CLONE=true`; bei `actions/checkout` setze `fetch-depth: 0`. Das seiteneigene `lastModified`-Frontmatter gewinnt immer, was praktisch ist, um ein Datum festzuschreiben oder für Dateien, die noch nicht committet sind:

```mdx page.mdx
---
title: My page
lastModified: 2026-06-20
---
```

Ist die Funktion aktiviert, wird das Datum außerdem als schema.org-`dateModified` in den strukturierten Daten der Seite ausgegeben.

## Datumsformat

Sowohl der Stempel „Zuletzt aktualisiert“ als auch die Zeitleiste des [Changelogs](/docs/advanced/changelog) rendern ihre Daten über dasselbe `dateFormat`, damit sie sich gleich lesen. Daten werden immer in der Sprache der Website gerendert; `dateFormat` steuert die _Form_. Standardmäßig wird die lange Form verwendet (`21. Juli 2026`, `2026年7月21日`):

```ts blume.config.ts
dateFormat: { dateStyle: "long" },
```

`dateFormat` wird direkt an die Optionen von [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) durchgereicht. Verwende eine `dateStyle`-Voreinstellung für eine bestimmte Länge:

```ts blume.config.ts
dateFormat: { dateStyle: "medium" },
```

Oder die einzelnen Komponentenfelder für einen numerischen Hausstil wie `2026/07/21`:

```ts blume.config.ts
dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
```

| Option | Beschreibung |
| --- | --- |
| `dateStyle` | Voreingestellte Länge: `"full"`, `"long"`, `"medium"` oder `"short"`. Nicht mit den Komponentenfeldern kombinierbar. |
| `weekday`, `era`, `year`, `month`, `day` | Einzelne Komponenten, z. B. `year: "numeric"`, `month: "2-digit"`. |
| `timeZone` | IANA-Zeitzone. Standard ist `UTC`, sodass ein Datum unabhängig vom Build-Ort gleich gelesen wird. |
| `calendar`, `numberingSystem` | Kalendersystem (z. B. `"japanese"`) und Nummerierungssystem (z. B. `"arab"`). |

## SEO

Open-Graph-Bilder, RSS-Feeds und strukturierte JSON-LD-Daten, gruppiert unter `seo`. Metadaten, Frontmatter-Überschreibungen und die vollständige Referenz findest du in der [SEO-Anleitung](/docs/configuration/seo).

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `og.enabled` | automatisch | Open-Graph-Bilder pro Seite — aktiv, sobald eine Website-URL gesetzt ist. |
| `rss.enabled` | `true` | Feeds für Blog- und Changelog-Inhalte erzeugen. |
| `rss.types` | `["blog", "changelog"]` | Inhaltstypen, die jeweils einen Feed erhalten. |
| `rss.limit` | `50` | Maximale Anzahl an Einträgen pro Feed. |
| `sitemap` | `true` | sitemap.xml erzeugen (benötigt deployment.site). |
| `robots` | `true` | robots.txt mit einem Sitemap-Link erzeugen. |
| `structuredData` | `true` | schema.org-JSON-LD im Head jeder Seite ausgeben. |

Diese Funktionen entfalten ihre volle Wirkung mit einer absoluten [`deployment.site`](/docs/deployment) für vollständige URLs.

## Inhaltsverzeichnis

Die Gliederung „Auf dieser Seite“ ist standardmäßig aktiviert und listet `H2`–`H3`-Überschriften auf. Schalte sie mit `toc` ab oder ändere den Überschriftenbereich:

```ts blume.config.ts
export default defineConfig({
  toc: false, // hide it everywhere
});
```

Oder schränke stattdessen den Überschriftenbereich ein:

```ts blume.config.ts
export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});
```

## Funktionsoptionen

Zu jeder dieser Optionen gibt es eine eigene Anleitung. Das Konfigurationsfeld ist der Einstiegspunkt:

| Feld | Was es konfiguriert | Anleitung |
| --- | --- | --- |
| `theme` | Akzentfarbe, Eckenradius, Schriften, heller/dunkler Modus | [Theming](/docs/configuration/theming) |
| `navigation` | Explizite Seitenleiste und Header-Tabs | [Navigation](/docs/content/navigation) |
| `search` | Anbieter (Orama, Pagefind, Algolia und weitere) und Indizierung | [Suche](/docs/configuration/search) |
| `markdown` | Optionen für das Markdown-Rendering — Codeblöcke, Überschriftenanker, Bildzoom | [Syntax](/docs/content/syntax) |
| `ai` | `llms.txt`, Ask AI und der gehostete MCP-Server für Coding-Agents | [KI](/docs/configuration/ai) |
| `analytics` | Vercel, PostHog und benutzerdefinierte Skripte | [Analytics](/docs/configuration/analytics) |
| `seo` | Metadaten, OG-Bilder, Feeds, strukturierte Daten | [SEO](/docs/configuration/seo) |
| `deployment` | Ausgabemodus, Adapter und Website-URL | [Deployment](/docs/deployment) |
| `redirects` | Permanente und temporäre Weiterleitungen | [Deployment](/docs/deployment#redirects) |
| `integrations` | Astro-Integrationen, die nach Blumes eingebauten angehängt werden | [Anpassung](/docs/configuration/customization#astro-integrations) |

## Rangfolge

Einstellungen werden von der niedrigsten zur höchsten Priorität aufgelöst, sodass du nur überschreibst, was du brauchst:

1. **Blume-Standardwerte**

    Ein sinnvoller Standardwert für jedes Feld.

2. **blume.config.ts**

    Deine projektweite Konfiguration.

3. **Ordner-Meta**

    [`meta.ts`](/docs/content/meta) für Titel und Sortierung eines Abschnitts.

4. **Seiten-Frontmatter**

    Überschreibungen pro Seite gewinnen.

---

# KI
Source: https://useblume.dev/de/docs/configuration/ai

Blume bietet einige KI-Funktionen: maschinenlesbare Dokumentation für externe Werkzeuge (`llms.txt` und eine [JSON-API](#json-api) mit OpenAPI-Beschreibung, beide standardmäßig aktiviert), einen **Ask AI**-Assistenten direkt auf der Seite und einen gehosteten **MCP-Server** für Coding-Agents. Ask AI und MCP sind optional zuschaltbar, und statische Dokumentation bleibt vollständig statisch, bis du eine Funktion aktivierst.

## llms.txt

Blume erzeugt maschinenlesbare Versionen deiner Dokumentation, die Coding-Agents und Chat-Assistenten verarbeiten können. Dies ist standardmäßig aktiviert; setze `llmsTxt: false`, um es abzuschalten:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: false,
}
```

Solange die Funktion aktiviert ist, schreibt `blume build` zwei Dateien in das Stammverzeichnis deiner Website:

- **`/llms.txt`** — ein kompakter Index: Titel und Beschreibung deiner Website, gefolgt von einer verlinkten Liste aller Seiten mit ihrer Zusammenfassung, gegliedert in Abschnitte, die deine Seitenleiste widerspiegeln — Ordner und Gruppen werden zu Überschriften, sodass ein Agent die Struktur der Dokumentation sieht und nicht einen einzigen flachen Block.
- **`/llms-full.txt`** — der gesamte Korpus: der vollständige Markdown-Text jeder Seite samt ihrer Quell-URL, in einer einzigen Datei.

Entwurfsseiten werden ausgeschlossen. Setze [`deployment.site`](/docs/deployment), damit die Links und Quell-URLs auf absolute Adressen aufgelöst werden.

`llmsTxt` akzeptiert außerdem eine Objektform mit Stellschrauben dafür, was die Dateien enthalten. Wenn deine [API-Referenz](/docs/advanced/api-reference) eine Platzhalter- oder Beispielspezifikation dokumentiert, setze `openapi: false`, um die daraus generierten Seiten aus beiden Dateien herauszuhalten:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    enabled: true, // default
    openapi: false, // exclude generated API reference pages
  },
}
```

Die Objektform akzeptiert außerdem `details`: Markdown, das in `llms.txt` direkt nach Titel und Zusammenfassung steht, vor den Seitenabschnitten — der freiformige "details"-Block der [llms.txt-Spezifikation](https://llmstxt.org). Hier ist der Ort, um Agents zu sagen, _wann_ sie zu deinem Produkt greifen sollen und wie sie es aufrufen, wonach Readiness-Scanner ausdrücklich suchen; ein Installationsbefehl und der Paketname gehören ebenfalls hierher:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    details: [
      "## When to use Acme",
      "",
      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
    ].join("\n"),
  },
}
```

`llms.txt` schließt mit zwei generierten Abschnitten, die keinerlei Konfiguration benötigen. **Agent skills** listet jeden über [`ai.skills`](#skills-discovery) veröffentlichten Skill samt seiner Beschreibung auf (dort sagt ein Skill, wann er zu verwenden ist). **Agent resources** verlinkt jedes maschinenlesbare Artefakt, das der Build erzeugt — `llms-full.txt`, den seitenweisen [Roh-Markdown](#raw-markdown)-Spiegel, den [MCP-Server](#mcp-server) und sein Discovery-Dokument, den Skills-Index, den [API-Katalog](#api-catalog), [`agent-readability.json`](#agent-readability) und die [Sitemap](/docs/configuration/seo#sitemap) — jeweils nur dann, wenn es existiert, sodass ein Agent, der nichts als `llms.txt` liest, dennoch die gesamte Oberfläche findet.

Um eine einzelne Seite aus beiden Dateien herauszuhalten, setze `ai.exclude` in deren Frontmatter:

```mdx
---
title: Internal notes
ai:
  exclude: true
---
```

Die Seite wird weiterhin gerendert, bleibt in der Suche und behält ihren Platz in der Sitemap — nur die `llms.txt`-Dateien überspringen sie.

Um die volle Kontrolle über eine der beiden Dateien zu übernehmen, lege deine eigene `llms.txt` oder `llms-full.txt` in deinem `public/`-Ordner ab. Wie ein eigenes Favicon wird sie automatisch übernommen und anstelle der generierten Datei ausgeliefert — überschreibst du eine, generiert Blume die andere trotzdem.

## Rohes Markdown

Hänge `.md` oder `.mdx` an die URL einer beliebigen Seite an, um deren rohe Markdown-Quelle abzurufen — perfekt für LLMs, Coding-Agents und "Als Markdown kopieren"-Workflows. Das steht für jede Seite zur Verfügung, in der Entwicklung wie in der Produktion, ohne jede Konfiguration.

| URL               | Liefert                                        |
| ----------------- | ---------------------------------------------- |
| `/quickstart`     | Die gerenderte Seite                           |
| `/quickstart.md`  | Reines Markdown, mit umgewandelten Komponenten |
| `/quickstart.mdx` | Die rohe MDX-Quelle, exakt wie geschrieben     |

Verschachtelte Routen funktionieren genauso (`/content/syntax.md`), und die Startseite wird unter `/index.md` ausgeliefert.

Die `.md`-Variante _reduziert_ Komponenten auf reines Markdown für Konsumenten, die kein JSX interpretieren können: `<TypeTable>` wird zu einer Markdown-Tabelle, `<Callout>` zu einem beschrifteten Blockzitat, `<Steps>` zu einer nummerierten Liste, `<Tabs>` zu fett beschrifteten Abschnitten, `<Card>` zu seinem Titel als Link über seinem Rumpf (und `<CardGroup>` zu den Karten, die sie enthält) und `<YouTube>` zu einem Link. Props werden mit dem `frontmatter` der Seite im Gültigkeitsbereich ausgewertet, sodass ein Prop wie `title={frontmatter.status}` denselben Wert ergibt, den die gerenderte Seite anzeigt. Alles, was sich nicht originalgetreu umwandeln lässt — eine eigene Komponente oder ein aus einem Import berechnetes Prop — bleibt unverändert, und Komponenten-Markup innerhalb von Code-Blöcken wird nie angetastet. Dieselbe Umwandlung gilt für `llms-full.txt` und das `get_page`-Tool des MCP-Servers, sodass jede an Agents gerichtete Oberfläche sauberes Markdown liefert. Wenn du die untransformierte Quelle möchtest, verwende die `.mdx`-Variante.

### Content Negotiation

Agents müssen die `.md`-Konvention nicht kennen: Wird die eigentliche URL einer Seite mit einem [`Accept: text/markdown`](https://acceptmarkdown.com)-Header angefragt, wird die Markdown-Variante unter derselben Adresse ausgeliefert, mit `Vary: Accept`, damit Caches die beiden auseinanderhalten. Der Entwicklungsserver berücksichtigt den Header von Haus aus, und ein [Vercel- oder Cloudflare-Server-Build](/docs/deployment#server-rendering) verdrahtet dieselbe Aushandlung automatisch in das Deployment — Routing-Regeln auf Vercel, ein generierter Worker auf Cloudflare — ganz ohne Konfiguration. Die Startseite handelt immer aus, selbst wenn sie eine eigene Landing Page statt einer Inhaltsseite ist: Ihr Markdown-Spiegel fällt auf den [`llms.txt`](#llmstxt)-Index zurück, sodass ein Agent, der beim Website-Stamm nach Markdown fragt, die maschinenlesbare Karte der Website erhält. Markdown-Antworten tragen außerdem einen `x-markdown-tokens`-Header — eine geschätzte Token-Anzahl (~4 Zeichen pro Token), gemäß der Konvention von [Cloudflares Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — auf jeder Oberfläche, auf der Blume die Antwort-Header kontrolliert: dem Entwicklungsserver, serverseitig gerenderten Antworten und der ausgehandelten Startseite auf Vercel und Cloudflare. Andere Deploy-Ziele liefern vorgerenderte Seiten aus einer statischen Schicht ohne Hook zur Anfragezeit aus, sodass Agents dort die `.md`-URL direkt abrufen; das [Agent-Readability-Manifest](#agent-readability) weist `contentNegotiation` nur auf Deployments aus, die den Header berücksichtigen.

Auch fehlende Seiten handeln aus. Jeder Build erzeugt eine Markdown-[404-Seite](/docs/advanced/custom-pages#404-page) unter `/404.md` — die Nicht-gefunden-Meldung, gefolgt von Rettungslinks zu jedem Abschnitt der obersten Ebene, zur Sitemap und zu `llms.txt` — und auf Vercel erhält eine Anfrage an eine nicht existierende URL, die Markdown bevorzugt, oder jede `.md`-URL ohne Seite dahinter, genau diesen Rumpf mit einem echten `404`-Status statt der HTML-Hülle.

### Eigene Komponenten-Serializer

Gib deinen eigenen Komponenten mit `ai.markdownComponents` eine Markdown-Form — eine Zuordnung von JSX-Name zu Serializer. Jeder Serializer erhält die `props` der Komponente (statisch aus den MDX-Attributen ausgewertet, mit dem `frontmatter` der Seite im Gültigkeitsbereich), ihre `children` (bereits auf Markdown reduziert) und die `frontmatter`-Daten der Seite und gibt den Ersatz zurück — oder `null`, um das JSX unverändert zu lassen:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import type { ComponentMarkdown } from "blume";

const chart: ComponentMarkdown = ({ props }) =>
  `![${props.title}](/charts/${props.slug}.png)`;

export default defineConfig({
  ai: {
    markdownComponents: {
      Chart: chart,
    },
  },
});
```

Für Container-Komponenten extrahiert `childComponents("Name")` direkte Kinder anhand des Tags — genauso, wie der eingebaute `<Steps>`-Serializer seine `<Step>`-Elemente sammelt —, und `childBlocks()` gibt jedes direkte Kind der Reihe nach zurück, Komponenten wie Prosa, jeweils bereits auf einen Markdown-Block heruntergestuft (der eingebaute `<CardGroup>`-Serializer ist einfach nur diese Blöcke, durch Leerzeilen verbunden). Ein gleichnamiger Eintrag ersetzt einen eingebauten Serializer, sodass du umgestalten kannst, wie `<Callout>` heruntergestuft wird — oder `null` zurückgeben, um eine Komponente vollständig auszunehmen.

Serializer leben in `blume.config.ts`, nicht in `components.tsx`: Die Konfigurationsdatei wird zur Build-Zeit ausgeführt, während die Komponentendatei nur statisch analysiert wird (sie darf `.astro`-Dateien importieren, die außerhalb des Website-Builds nicht laufen können). Deine Komponenten selbst bleiben genau wie zuvor in `components.tsx` registriert — `markdownComponents` ergänzt lediglich deren an Agents gerichtete Markdown-Form.

## Als Markdown kopieren

Jede Seite verfügt über eine Aktion **Als Markdown kopieren** — bei den [Seitenaktionen](/docs/content/navigation#page-actions) unterhalb des Inhaltsverzeichnisses —, die das rohe Markdown der Seite in die Zwischenablage kopiert. Es ist dieselbe Quelle, die unter der [`.md`-URL](#raw-markdown) oben ausgeliefert wird, bereit zum Einfügen in ein LLM, ein Issue oder deine Notizen. Sie ist auf jeder Seite verfügbar, in der Entwicklung wie in der Produktion, ohne jede Konfiguration.

Wo die Clipboard-API nicht verfügbar ist oder der Browser sie verweigert — In-App-Browser, WebViews, unsichere Origins —, greift die Aktion auf den althergebrachten Kopierbefehl zurück, und landet nichts in der Zwischenablage, meldet die Schaltfläche **Kopieren fehlgeschlagen** (lokalisiert über `actions.copyFailed`), statt stumm zu bleiben. Dieselbe Rückfallebene stützt jede Kopieren-Schaltfläche, die Blume rendert.

## Im Chat öffnen

Die Aktion **Im Chat öffnen** öffnet die aktuelle Seite in einem KI-Assistenten — v0, ChatGPT, Claude, T3 Chat, Scira oder Cursor — vorbefüllt mit einem Prompt, der ihn auf das rohe Markdown der Seite verweist, sodass er Fragen zu dem beantworten kann, was du gerade liest:

> Read `https://your-site/this-page.md` so I can ask you questions about this page.

Wie "Als Markdown kopieren" erfordert dies keine Einrichtung. Der Assistent ruft die Seite über ihre öffentliche URL ab, es funktioniert also, sobald die Seite bereitgestellt ist.

Der Prompt ist Teil des [UI-Wörterbuchs](/docs/content/i18n#translated-ui) (`actions.openInChatPrompt`), sodass lokalisierte Websites ihn in ihrer Sprache senden, und `i18n.ui` kann den Wortlaut überschreiben — behalte dabei den Platzhalter `{url}`, der durch die Roh-Markdown-URL der Seite ersetzt wird.

Um die Aktion anzupassen, setze `ai.openInChat`. `false` blendet sie vollständig aus, und ein Array von Anbieter-Schlüsseln — `"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"` — zeigt genau diese Anbieter, in der Reihenfolge, in der du sie aufführst:

```ts blume.config.ts lineNumbers
ai: {
  openInChat: ["claude", "chatgpt", "cursor"],
}
```

Um einen kopierfertigen Prompt direkt in deine Inhalte einzubetten — statt einer seitenweiten Aktion —, verwende die [Prompt-Komponente](/docs/content/components#prompt), die eine beschriftete Zeile mit einer Schaltfläche **Prompt kopieren** und einem optionalen Link zum Öffnen in Cursor rendert.

## Ask AI

Füge einen Assistenten hinzu, der Leserfragen in einem Chat-Panel auf der Seite beantwortet, gestützt auf einen streamenden Server-Endpunkt und das [AI SDK](https://ai-sdk.dev):

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "gateway", // default
    model: "openai/gpt-5.5",
  },
}
```

### Vorgeschlagene Fragen

Befülle den leeren Zustand mit einigen Einstiegs-Prompts. Jeder wird als anklickbarer Vorschlag gerendert — ein Klick sendet ihn ab — mit einem optionalen [Lucide-Icon](/docs/content/components#icon) neben der Beschriftung:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    suggestions: [
      { label: "What is Blume?", icon: "rocket" },
      { label: "How do I write a docs page?", icon: "file-text" },
      { label: "How do I configure the theme?", icon: "settings" },
    ],
  },
}
```

`label` ist die Frage, die gestellt wird; `icon` ist optional. Lässt du `suggestions` ungesetzt (oder leer), öffnet sich das Panel mit einem schlichten Eingabefeld.

### Eigene Anweisungen

Ergänze mit `instructions` deinen eigenen System-Prompt-Text — Identität, Sprache, Tonfall oder alles andere, was der Assistent im Hinterkopf behalten soll:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    instructions:
      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
  },
}
```

Dein Text wird den eingebauten Anweisungen **hinzugefügt**, statt sie zu ersetzen: Der eingebaute Teil trägt den [Fundierungs](#grounding)-Vertrag — nur aus den abgerufenen Seiten antworten, sie als Markdown-Links zitieren —, von dem die Zitate im Chat-Panel abhängen, er bleibt also unangetastet, was auch immer du ergänzt.

### Fundierung

Ask AI ist **in deiner Dokumentation fundiert**. Für jede Frage ruft es die relevantesten Seiten ab — über denselben lexikalischen [Orama](/docs/configuration/search)-Index, der auch die Suche auf der Seite antreibt — und fügt sie in den System-Prompt des Modells ein, sodass Antworten aus deinen Inhalten stammen statt aus dem Eigenwissen des Modells. Dem Assistenten wird aufgetragen, nur aus den abgerufenen Seiten zu antworten, zu sagen, wenn etwas nicht abgedeckt ist, und die Seiten zu zitieren, aus denen er geschöpft hat.

Die Seite, auf der sich der Leser gerade befindet, wird dem Kontext zuerst hinzugefügt und dient dazu, den Abruf auf die Sprache dieser Seite einzugrenzen, sodass Antworten dort relevant bleiben, wo der Leser sich in der Dokumentation befindet. Der Abruf läuft zur Anfragezeit aus einem in den Build eingebackenen Snapshot, funktioniert also unabhängig von deinem [Such](/docs/configuration/search)-Anbieter — selbst wenn die Suche auf `none` gesetzt ist — und benötigt keine Konfiguration.

Die Fundierung ist für jedes Backend aktiv außer **[Inkeep](#backends)**, das seinen eigenen Abruf über die in seinem Dashboard indizierten Inhalte durchführt.

### Abrufumfang

Wie viel Dokumentation eine Frage mit sich trägt, ist der größte Hebel dafür, wie lange der Leser auf das erste Wort wartet: Das Modell liest jedes eingefügte Zeichen, bevor es ein Token ausgibt. Bei einem gehosteten Spitzenmodell ist das unsichtbar, bei einem selbst gehosteten Backend dominiert es. `retrieval` bemisst ihn:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    retrieval: {
      maxResults: 3, // fewer pages retrieved per question
      excerptChars: 1200, // shorter excerpt from each one
      contextBudget: 3000, // smaller total injection
    },
  },
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `maxResults` | `6` | Pro Frage abgerufene Dokumente. |
| `excerptChars` | `2000` | Zeichen, die von jeder abgerufenen Seite behalten werden. |
| `contextBudget` | `10000` | Insgesamt eingefügte Zeichen, über alle Auszüge hinweg. |

Die drei sind nicht austauschbar. `contextBudget` deckelt die gesamte Einfügung, `excerptChars` entscheidet, wie tief der Auszug in eine einzelne lange Seite hineinreicht — erhöhe es, wenn eine Seite die ganze Antwort enthält und der Auszug sie abschneidet —, und `maxResults` deckelt, wie viele Seiten der Abruf hinzufügt. Die Seite, die der Leser gerade betrachtet, wird zusätzlich zu den abgerufenen eingefügt, sodass eine Antwort bis zu eine Seite mehr zitieren kann, als `maxResults` angibt.

Die Standardwerte passen zu einem gehosteten Modell. Senke sie, wenn du von eigener Hardware ausspielst und die Zeit bis zum ersten Token wichtiger ist als die Trefferabdeckung; Antworten bleiben so oder so fundiert, und dem Assistenten wird aufgetragen, zu sagen, wenn etwas nicht abgedeckt ist, statt die Lücke zu füllen.

### Externer Endpunkt

Du hast bereits ein API-Backend für KI? Richte das Panel darauf aus und halte den Dokumentations-Build statisch:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}
```

Blume sendet denselben `POST`-Body wie seine eingebaute Route:

```json
{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}
```

Gib eine erfolgreiche Antwort zurück, deren Body ein reiner UTF-8-Textstream ist. Liegt der Endpunkt auf einem anderen Origin, erlaube den Dokumentations-Origin per CORS: Akzeptiere `OPTIONS` und `POST`, lass den `content-type`-Request-Header zu und gib die CORS-Header sowohl beim Preflight als auch bei der gestreamten Antwort zurück. Mit gesetztem `endpoint` erzeugt Blume die Chat-Oberfläche, aber keine Server-Route, keinen Fundierungs-Snapshot, keine Anbieter-Abhängigkeit und keine Warnung zu Anbieter-Geheimnissen; dein Backend verantwortet Abruf, Authentifizierung, Ratenbegrenzung, Modellzugriff und Zitate.

### Server-Ausgabe erforderlich

Blumes eingebautes Ask-AI-Backend ist eine Server-Route (`POST /api/ask`) und kann daher nicht auf einem statischen Build laufen. Wechsle zur Server-Ausgabe und wähle einen Adapter:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

Ein statischer Build mit aktiviertem Ask AI und ohne externen `endpoint` schlägt sofort fehl, mit einer Meldung, die dich auffordert, `deployment.output` auf `server` zu setzen. Siehe [Deployment](/docs/deployment) für die Adapter.

### Backends

Standardmäßig läuft Ask AI über das **Vercel AI Gateway**: `model` ist eine `provider/model`-Zeichenkette, du wechselst Modelle also durch deren Änderung (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5` und so weiter), ohne ein Anbieter-SDK installieren zu müssen. Das Gateway liest `AI_GATEWAY_API_KEY` aus deiner Umgebung und wird bei einem Deployment auf Vercel automatisch verdrahtet.

Setze `provider`, um Ask AI anderswohin zu leiten. Jedes Backend liest seinen API-Schlüssel aus einer Umgebungsvariablen und streamt über ein Anbieter-SDK, das du in deinem Projekt installierst — nur dasjenige, das du verwendest:

| `provider` | `model` | Umgebungsvariable für den API-Schlüssel | Zu installierendes SDK |
| --- | --- | --- | --- |
| `gateway` (Standard) | eine `provider/model`-Zeichenkette über das AI Gateway | `AI_GATEWAY_API_KEY` | keines — wird mit Blume mitgeliefert |
| `openrouter` | ein beliebiges [OpenRouter](https://openrouter.ai)-Modell | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
| `llmgateway` | ein beliebiges [LLMGateway](https://llmgateway.io)-Modell | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
| `inkeep` | ein [Inkeep](https://inkeep.com)-QA-Modell | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
| `openai-compatible` | was auch immer dein Endpunkt ausliefert | mit `apiKeyEnv` gesetzt | `@ai-sdk/openai-compatible` |

Die SDKs sind optionale Peer-Abhängigkeiten, füge deinem Projekt also dasjenige hinzu, das dein Backend benötigt (z. B. `npm install @openrouter/ai-sdk-provider`). Fehlt es, warnt der Build mit dem exakten Paketnamen, bevor Vite den Import nicht auflösen könnte.

Um zum Beispiel OpenRouter zu verwenden:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openrouter",
    model: "anthropic/claude-sonnet-4-5",
  },
}
```

Jeder OpenAI-kompatible Endpunkt funktioniert über `openai-compatible` — gib die `baseUrl` und die Umgebungsvariable an, die seinen Schlüssel enthält:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openai-compatible",
    baseUrl: "https://my-gateway.example.com/v1",
    apiKeyEnv: "MY_GATEWAY_API_KEY",
    model: "gpt-4o",
  },
}
```

Setze `apiKeyEnv` (und, bei den benannten Anbietern, `baseUrl`) bei jedem Backend, um auf eine andere Umgebungsvariable oder einen Proxy zu verweisen.

:::note
**Inkeep** antwortet aus den Inhalten, die du im Inkeep-Dashboard indiziert hast — es führt seinen eigenen Abruf durch —, weshalb Blume es unfundiert lässt. Jedes andere Backend ist in den Seiten dieser Website [fundiert](#grounding).
:::

Schlüssel werden mit `process.env` gelesen, was die Adapter Node, Vercel und Netlify abdeckt. Auf Cloudflare stellst du den Schlüssel über das [Runtime-Binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) der Plattform bereit. Das Aktivieren von Ask AI schaltet außerdem React für die Insel auf der Seite ein — siehe [Anpassung](/docs/configuration/customization#interactive-islands).

### Ratenbegrenzung

Der Endpunkt `POST /api/ask` ist **nicht authentifiziert** — er muss es sein, damit der Assistent auf der Seite ihn aufrufen kann. Blume validiert jede Anfrage — weist fehlerhafte Bodys ab, begrenzt sie auf 1–40 Nachrichten und akzeptiert nur die Rollen `user`/`assistant`, sodass ein Aufrufer keinen eigenen System-Prompt einschleusen und die Route nicht als allgemeinen LLM-Proxy zweckentfremden kann —, um zu begrenzen, wie viel ein einzelner Aufruf gegen dein Modell verbrauchen kann; es kann jedoch niemanden davon abhalten, den Endpunkt wiederholt aufzurufen. Falls Kostenmissbrauch ein Anliegen ist, stelle der Route eine Ratenbegrenzung voran — die Edge-Ratenbegrenzung deines Hosters (z. B. die von Vercel), eine Middleware oder die Ausgabelimits pro Schlüssel deines Modellanbieters.

## MCP-Server

Hoste einen [Model-Context-Protocol](https://modelcontextprotocol.io)-Server, damit Coding-Agents (Claude Code, Cursor, VS Code, claude.ai-Connectors) deine Dokumentation direkt durchsuchen und lesen können — ohne Scraping:

```ts blume.config.ts lineNumbers
ai: {
  mcp: {
    enabled: true,
    route: "/mcp", // where the server is mounted
  },
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `enabled` | `false` | Den MCP-Server erzeugen und hosten. |
| `route` | `/mcp` | Pfad, unter dem der Streamable-HTTP-Endpunkt hängt. |
| `name` | Titel | Clients angezeigter Servername (Standard: Titel). |
| `instructions` | — | Optionaler System-Hinweis für verbindende Agents. |

Der Server stellt schreibgeschützte Tools bereit — `search_docs`, `get_page`, `list_pages` und `get_navigation` — sowie jede Seite als MCP-Ressource (`resources/list` zählt die Seiten unter ihren ausgelieferten URLs mit dem Typ `text/markdown` auf; `resources/read` gibt das Agent-Markdown der Seite zurück, dieselbe Ausgabe wie `get_page`), sodass Clients, die Kontext per URI anhängen, die Dokumentation durchstöbern können, ohne ein Tool aufzurufen. Er veröffentlicht Discovery-Dokumente unter `/.well-known/mcp.json` und `/.well-known/mcp/server-card.json`. Die Server Card folgt dem Server-Card-Erweiterungsschema [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) (Reverse-DNS-`name`, `remotes`-Transport-Endpunkte), mit initialize-förmigen Kompatibilitätsfeldern (`serverInfo`, `capabilities`, `transports`) für Scanner, die gegen die frühere Revision des Vorschlags gebaut wurden. Das Menü **Mit MCP verbinden** jeder Seite bietet eine Kopieren-und-loslegen-Installation für Claude Code, Cursor, VS Code und Codex (angezeigt, sobald [`deployment.site`](/docs/deployment) gesetzt ist).

`search_docs` betreibt seinen eigenen Volltextindex und funktioniert damit unabhängig von deinem [Such](/docs/configuration/search)-Anbieter — und sogar, wenn die Suche auf `none` gesetzt ist. Der MCP-Server ist eine von der Suche auf der Seite getrennte Funktion.

`search_docs` und `list_pages` akzeptieren beide einen optionalen `contentTypes`-Filter, der die Ergebnisse auf Seiten der angegebenen Frontmatter-[`type`s](/docs/reference/frontmatter) eingrenzt — `["rfc"]`, `["blog", "changelog"]` —, sodass ein Agent, der mit einer Website arbeitet, die Dokumentation mit RFCs, Runbooks oder Richtlinien mischt, den Abruf auf die Art von Seite eingrenzen kann, die er benötigt. Jedes Ergebnis nennt seinen Inhaltstyp, und die Ausgabe von `list_pages` zeigt die verwendeten Typen.

Beide Tools akzeptieren außerdem ein `filters`-Objekt, das gegen die Facetten abgleicht, die eine Website pro Inhaltstyp deklariert ([`content.types.<type>.facets`](/docs/configuration#frontmatter)) — eigene Frontmatter-Schlüssel, deren Werte zu filterbaren Metadaten werden:

```json
{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}
```

Jeder `filters`-Eintrag muss zutreffen (Ergebnisse tragen ihre Facettenwerte, und `list_pages` zeigt die jeder Seite), sodass eine Wissensdatenbank Agent-Workflows mit progressiver Offenlegung antreiben kann — die verbindlichen Standards aufzählen, nur innerhalb dieser suchen — ganz ohne eigenen Server.

### Server-Ausgabe erforderlich

Der MCP-Server ist ein aktiver Endpunkt (`/mcp`) und kann daher nicht auf einem statischen Build laufen. Wechsle zur Server-Ausgabe und wähle einen Adapter:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "node", // or "vercel" | "netlify" | "cloudflare"
  site: "https://docs.example.com",
}
```

Ein statischer Build mit `ai.mcp.enabled` schlägt sofort fehl, mit einer Meldung, die dich auffordert, `deployment.output` auf `server` zu setzen. Siehe [Deployment](/docs/deployment) für die Adapter. Nach dem Deployment verbindest du dich aus Claude Code heraus mit:

```bash
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

## JSON-API

Jede Blume-Website liefert ihre Dokumentation außerdem über eine kleine schreibgeschützte **JSON-API** aus — das REST-Pendant zu den Tools des [MCP-Servers](#mcp-server), über denselben Seiten-Snapshot, für Agents und Function-Calling-Frameworks, die schlichtes HTTP sprechen statt MCP. Sie ist standardmäßig aktiviert und benötigt keinerlei Konfiguration:

| Endpunkt | Liefert |
| --- | --- |
| `/api/docs/pages.json` | Jede Seite mit ihrer Route, ihrem Titel, ihrer Beschreibung, ihrem Inhaltstyp, ihrem Locale, ihren Facetten und den URLs ihrer gerenderten, ihrer Markdown- und ihrer JSON-Form. |
| `/api/docs/pages/{route}.json` | Eine Seite: ihr Indexeintrag plus das Agent-Markdown (derselbe Rumpf, den `get_page` zurückgibt). `{route}` ist die Seitenroute ohne führenden Schrägstrich, `index` für die Startseite. |
| `/api/docs/navigation.json` | Der Navigationsbaum — Header-Tabs und die Hierarchie der Seitenleiste. |
| `/api/docs/search?q=` | Volltextsuche, mit derselben Eingrenzung über `limit`, `contentTypes`, `locale`, `version` und `filters[key]` wie bei `search_docs`. Nur bei Server-Ausgabe. |
| `/openapi.json` | Die OpenAPI-3.1-Beschreibung der gesamten maschinenlesbaren Oberfläche. |

Der Seitenindex, die seitenweisen Dokumente und die Navigation werden vorgerendert, eine statische Website liefert sie also als Dateien von jedem beliebigen Hoster aus. Die Suche ist ein aktiver Endpunkt und existiert nur unter [Server-Ausgabe](/docs/deployment#server-rendering), wo sie denselben Index betreibt wie `search_docs`. Fehler sind Problem Details nach [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (`application/problem+json`) mit einem stabilen `code`, einem `detail` und einem `resolution`-Hinweis, der dem Agent sagt, wohin er als Nächstes gehen soll — eine fehlende Seite, eine leere Suchanfrage oder, bei Server-Ausgabe, jede `/api/…`-URL, die kein Endpunkt beantwortet:

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

Das **OpenAPI-Dokument** unter `/openapi.json` wird pro Build aus deiner Konfiguration erzeugt, es beschreibt also nur das, was die bereitgestellte Website tatsächlich ausliefert: jeden JSON-Endpunkt mit eindeutiger `operationId`, typisierten Parametern und Antwortschemata, dazu die Text-Oberflächen daneben — die [`.md`-Spiegel](#raw-markdown), [`llms.txt`](#llmstxt) und `llms-full.txt`, [`agent-readability.json`](#agent-readability) — sowie den [MCP-Endpunkt](#mcp-server), wenn er aktiviert ist. Frameworks, die Tools aus einer OpenAPI-Beschreibung bauen, erhalten dieselbe Reichweite wie ein MCP-Client. Das Dokument ist aus dem [API-Katalog](#api-catalog), dem [Readability-Manifest](#agent-readability), dem `Link`-Header der Startseite als `rel="service-desc"` und aus `llms.txt` verlinkt.

Nichts davon rührt an deine eigene [API-Referenz](/docs/advanced/api-reference): Eine dokumentierte Spezifikation wird in Seiten gerendert, niemals unter `/openapi.json` ausgeliefert, und der Katalog führt beide auf. Eine `public/openapi.json`, die du selbst ausliefert, übernimmt diese Route (die JSON-Endpunkte bleiben). Der `/api/…`-Catch-all tritt zur Seite, wenn ein Dokumentationsabschnitt aus dem `/api`-Namensraum ausgeliefert wird (`content/api/overview.md`) oder eine eigene Seite eine Rest-Route unter `/api/` besitzt, sodass diese Seiten weiterhin gewinnen. Setze `ai.api` auf `false`, um nichts davon zu veröffentlichen:

```ts blume.config.ts lineNumbers
ai: {
  api: false,
}
```

## Agent-Lesbarkeit

Blume schreibt ein Manifest **`/agent-readability.json`** in den Stamm deiner Website, das die in dieser Seite beschriebene, an Agents gerichtete Oberfläche indexiert — sodass ein Agent sie mit einem einzigen Abruf entdecken kann, statt Konventionen zu erraten oder HTML zu scrapen. Wie `llms.txt` ist es standardmäßig aktiviert:

```ts blume.config.ts lineNumbers
seo: {
  agentReadability: true,
}
```

Das Manifest listet nur auf, was du aktiviert hast — das Spiegelmuster für [rohes Markdown](#raw-markdown), die [JSON-API](#json-api) und ihre OpenAPI-Beschreibung, [`llms.txt`](#llmstxt) und `llms-full.txt`, den [MCP-Server](#mcp-server) und sein Discovery-Dokument, den [Ask AI](#ask-ai)-Endpunkt, die [Sitemap](/docs/configuration/seo#sitemap) und [RSS-Feeds](/docs/configuration/seo#rss-feeds) — neben deinem Website-Namen, der Beschreibung, dem Quell-Repository und der [Content-Signal](/docs/configuration/seo#content-signals)-Nutzungsrichtlinie. URLs sind absolut, wenn [`deployment.site`](/docs/deployment) gesetzt ist, andernfalls stammrelativ:

```json agent-readability.json
{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "https://docs.example.com/{route}.md"
    },
    "api": {
      "openapi": "https://docs.example.com/openapi.json",
      "pages": "https://docs.example.com/api/docs/pages.json",
      "search": "https://docs.example.com/api/docs/search"
    },
    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
    "llmsTxt": "https://docs.example.com/llms.txt",
    "mcp": {
      "discovery": "https://docs.example.com/.well-known/mcp.json",
      "url": "https://docs.example.com/mcp"
    }
  },
  "description": "Docs for the Acme API.",
  "generator": "blume@1.0.0",
  "name": "Acme Docs",
  "site": "https://docs.example.com",
  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
  "repository": "https://github.com/acme/docs"
}
```

Das Feld `contentNegotiation` erscheint nur, wenn die bereitgestellte Website den Header `Accept: text/markdown` tatsächlich berücksichtigt — siehe [Content Negotiation](#content-negotiation); bei jedem anderen Deployment weist das Manifest nur das `.md`-Spiegelmuster aus.

Setze `seo.agentReadability` auf `false`, um es zu überspringen, oder liefere deine eigene `public/agent-readability.json` aus, um zu übernehmen — Blume überschreibt niemals eine Datei, die du in `public/` ablegst.

### Discovery-Link-Header

Agents, die eine Website sondieren, wissen nicht, dass sie nach dem Manifest suchen sollen — deshalb weist Blume es zusätzlich in einem `Link`-Antwort-Header nach [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) auf der Startseite aus, unter Verwendung IANA-registrierter Beziehungstypen:

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
  </openapi.json>; rel="service-desc"; type="application/json",
  </agent-readability.json>; rel="describedby"; type="application/json",
  </llms.txt>; rel="describedby"; type="text/plain",
  </index.md>; rel="alternate"; type="text/markdown"
```

Jeder Eintrag erscheint nur, wenn die zugehörige Funktion aktiv ist. Der `alternate`-Link verweist auf den Markdown-Spiegel der Startseite — das [rohe Markdown](#raw-markdown) der Seite selbst, wenn die Startroute eine Inhaltsseite ist, oder den synthetisierten `llms.txt`-Fallback, wenn sie eine Landing Page ist. Der `service-desc`-Link ([RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)) verweist auf die OpenAPI-Beschreibung der [JSON-API](#json-api), und `api-catalog` auf den [generierten API-Katalog](#api-catalog). Der Header wird auf jeder von Blume kontrollierten Oberfläche mitgeliefert: dem Entwicklungsserver (prüfe ihn mit `curl -I localhost:4321`), statischen Builds über die erzeugte `_headers`-Datei (Netlify und Cloudflare) und Vercel-Server-Builds über die Routing-Regeln des Deployments.

Nicht jeder Agent tritt jedoch über den Stamm ein — wer einem Suchergebnis oder einem geteilten Link folgt, landet auf einer tief liegenden Seite und sieht den Header der Startseite nie. Deshalb trägt jede gerenderte Seite dieselben Discovery-Links auch in ihrem HTML-`<head>`, unter Verwendung derselben IANA-registrierten Beziehungen:

```html
<link
  rel="describedby"
  href="/agent-readability.json"
  type="application/json"
/>
<link rel="describedby" href="/llms.txt" type="text/plain" />
<link rel="alternate" href="/docs/example.md" type="text/markdown" />
```

Hier verweist der `alternate`-Link auf den [Roh-Markdown-Spiegel](#raw-markdown) _der jeweiligen Seite_, sodass ein Agent direkt von dem HTML, auf dem er gelandet ist, zur token-effizienten Version springen kann. Da die Head-Links mit dem vorgerenderten HTML mitreisen, funktionieren sie auch bei Hostern, die `_headers` ignorieren und überhaupt keine eigenen Antwort-Header senden können (GitHub Pages, S3) — ganz gleich, über welche Seite der Agent eintritt.

### API-Katalog

Wenn die Website APIs veröffentlicht, generiert Blume einen API-Katalog nach [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) unter `/.well-known/api-catalog` — ein [Linkset](https://www.rfc-editor.org/rfc/rfc9264), das Agents ermöglicht, deine APIs allein von der Domain aus aufzuzählen, ausgeliefert mit seinem registrierten Medientyp `application/linkset+json` auf jeder Build-Oberfläche. Es gibt nichts zu konfigurieren: Der Katalog wird aus dem abgeleitet, was ohnehin in `blume.config.ts` steht. Jede [OpenAPI- oder AsyncAPI-Referenz](/docs/advanced/api-reference) wird zu einem Eintrag, verankert an ihrer gerenderten Dokumentationsroute, wobei `service-doc` auf diese Dokumentation zeigt und `service-desc` auf die Spezifikation, sofern sie unter einer abrufbaren URL liegt; die eigene [JSON-API](#json-api) der Website wird zu einem Eintrag, der durch ihre `/openapi.json` beschrieben wird; und der [MCP-Server](#mcp-server) wird zu einem Eintrag mit seinem Discovery-Dokument als Dienstbeschreibung:

```json .well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://docs.example.com/reference",
      "service-doc": [
        { "href": "https://docs.example.com/reference", "type": "text/html" }
      ],
      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
    },
    {
      "anchor": "https://docs.example.com/api/docs",
      "service-desc": [
        {
          "href": "https://docs.example.com/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://docs.example.com/mcp",
      "service-desc": [
        {
          "href": "https://docs.example.com/.well-known/mcp.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    }
  ]
}
```

Eine Website ohne API-Referenzen, ohne MCP-Server und mit abgeschalteter [JSON-API](#json-api) erzeugt keinen Katalog — es stünde nichts darin. Wie überall gewinnt eine Datei `public/.well-known/api-catalog`, die du selbst auslieferst, gegenüber der generierten.

### WebMCP

[WebMCP](https://webmachinelearning.github.io/webmcp/) ist eine aufkommende Browser-API, mit der eine Seite Tools direkt bei einem agentischen Browser registrieren kann — ohne separate Serververbindung. Jede Blume-Seite registriert die schreibgeschützte Oberfläche der Dokumentation im Modellkontext der Seite: `search_docs` (Website-Suche), `get_page` (das [rohe Markdown](#raw-markdown) einer Seite) und `list_pages` (den [`llms.txt`](#llmstxt)-Index). Das Skript ist winzig, lädt keinerlei Suchmaschinerie, bis ein Tool tatsächlich aufgerufen wird, und tut in jedem Browser ohne die API stillschweigend nichts — was heute auf alle außerhalb der [Early Preview von Chrome](https://developer.chrome.com/blog/webmcp-epp) zutrifft. Es registriert sich an derjenigen Oberfläche, die die im Fluss befindliche Spezifikation bereitstellt (`navigator.modelContext` oder `document.modelContext`), über `provideContext` oder das tool-weise `registerTool`.

Es ist standardmäßig aktiviert; setze `webmcp: false`, um es abzuwählen:

```ts blume.config.ts lineNumbers
ai: {
  webmcp: false,
}
```

### Skills-Discovery

Wenn dein Projekt [Agent Skills](https://agentskills.io) mitliefert — [das Blume-Repo selbst tut das](#agent-skill) —, richte `ai.skills` auf das Verzeichnis aus, das sie enthält, und der Build veröffentlicht sie zur Discovery gemäß dem [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc):

```ts blume.config.ts lineNumbers
ai: {
  skills: "./skills",
}
```

Der Pfad wird relativ zu deinem Projektstamm aufgelöst, und jedes Unterverzeichnis mit einer `SKILL.md` wird zu einem veröffentlichten Skill. Ein Skill, der aus einer einzelnen `SKILL.md` besteht, wird wortgetreu nach `/.well-known/agent-skills/<name>/SKILL.md` kopiert (`type: "skill-md"`); ein Skill mit unterstützenden Ressourcen (`scripts/`, `references/`, `assets/`) wird in ein deterministisches `.tar.gz` gebündelt (`type: "archive"`), damit seine relativen Verweise nach dem Entpacken aufgelöst werden, unter Beibehaltung der Ausführungs-Bits von Skripten. Der Discovery-Index unter `/.well-known/agent-skills/index.json` trägt das `$schema` der Version v0.2.0 und pro Skill dessen Namen, Typ, Beschreibung (aus dem Frontmatter der `SKILL.md`), Artefakt-URL sowie den SHA-256-Digest, gegen den Clients Downloads verifizieren.

Skills mit fehlendem oder spezifikationswidrigem `name`/`description` werden mit einer Build-Warnung übersprungen, statt fehlerhaft veröffentlicht zu werden, und eine `public/.well-known/agent-skills/index.json`, die du selbst auslieferst, übernimmt die gesamte Oberfläche.

### DNS-basierte Discovery (DNS-AID)

[DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) ist ein aufkommender IETF-Entwurf, mit dem Agents die KI-Oberfläche einer Website entdecken können, bevor sie eine einzige HTTP-Anfrage stellen, indem sie ServiceMode-[SVCB/HTTPS-Einträge](https://www.rfc-editor.org/rfc/rfc9460) an einem wohlbekannten DNS-Einstiegspunkt abfragen. DNS-Einträge liegen in deiner Zone, nicht im Build, weshalb dies die eine Discovery-Oberfläche ist, die Blume nicht für dich veröffentlichen kann — lege stattdessen einen Eintrag bei deinem DNS-Anbieter an:

```txt
_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
```

Verwende den Eintragstyp `HTTPS`, wenn dein Anbieter ihn anbietet (Vercel DNS tut das; den reinen `SVCB`-Typ unterstützt es nicht), andernfalls einen ServiceMode-`SVCB`-Eintrag mit den Parametern `alpn` und `port`. Der Entwurf empfiehlt außerdem, die Zone mit DNSSEC zu signieren, damit validierende Resolver authentifizierte Antworten zurückgeben — Anbieter wie Cloudflare aktivieren das mit einem Klick, während manche (darunter Vercel DNS) es überhaupt nicht unterstützen.

`blume audit --url <origin>` prüft das für dich: Wenn [`deployment.site`](/docs/deployment) gesetzt ist, fragt die Netzwerkstufe den Einstiegspunkt über DNS-over-HTTPS ab und meldet den exakt zu veröffentlichenden Eintrag, falls keiner existiert, sowie ob die Antworten DNSSEC-authentifiziert sind. Setze `BLUME_DOH_URL`, um die Abfrage auf deinen eigenen Resolver zu richten, falls dein Netzwerk die öffentlichen (Google, Cloudflare) blockiert.

### Web Bot Auth

[Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) wirkt in die andere Richtung: Es geht nicht darum, dass Agents deine Dokumentation lesen, sondern darum, dass **die Agents deiner Organisation sich ausweisen**, wenn sie anderswo Anfragen stellen. Deine Agents signieren ihre Anfragen mit [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421), und empfangende Websites verifizieren sie gegen ein auf deiner Domain veröffentlichtes Verzeichnis öffentlicher Schlüssel. Wenn deine Organisation Agents betreibt und deine Blume-Website unter der Domain liegt, als die sie sich ausweisen, veröffentliche deren öffentliche Schlüssel:

```ts blume.config.ts lineNumbers
ai: {
  webBotAuth: {
    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
  },
}
```

Blume liefert das JWKS dann unter `/.well-known/http-message-signatures-directory` mit seinem registrierten Medientyp auf jeder Build-Oberfläche aus. Das Verzeichnis ist per Definition öffentlich, weshalb die Konfiguration nur öffentliche Schlüssel zulässt — ein JWK, das privates Material enthält (`d`, `p`, `q`, …), scheitert an der Validierung mit einem Fehler, statt eine geleakte Zugangsberechtigung auszuliefern. Erzeuge ein Ed25519-Paar mit:

```bash
node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
```

Der öffentliche JWK kommt in die obige Konfiguration; der private dorthin, wo dein signierender Agent läuft (ein Secret Manager, niemals das Repo). Wenn deine Organisation keine Agents betreibt, überspringe dies — ein leeres Verzeichnis weist nichts aus, das der Verifikation wert wäre.

Da `blume.config.ts` zur Build-Zeit ausgeführt wird, muss der Schlüssel nicht fest einprogrammiert sein — lade ihn aus einer Build-Zeit-Umgebungsvariablen, um die Konfiguration frei von Schlüssel-Blobs zu halten und ohne Commit zu rotieren:

```ts blume.config.ts lineNumbers
const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;

export default defineConfig({
  ai: {
    webBotAuth: {
      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
    },
  },
});
```

Umgebungen ohne die Variable veröffentlichen kein Verzeichnis, und ein so geladener Schlüssel wird genauso validiert wie ein inline angegebener — einschließlich der Prüfung auf privates Material. (Der öffentliche Schlüssel ist kein Geheimnis, ihn inline zu committen ist also genauso in Ordnung; die Umgebungsvariable ist eine Frage der Ergonomie, keine der Sicherheit.)

## Agent Skill

Baust du eine Blume-Website mit Hilfe eines Coding-Agents? Installiere den Blume-[Agent Skill](https://docs.claude.com/en/docs/claude-code/skills), damit er weiß, wie Blume funktioniert, ohne dass du es ihm erklärst:

```bash
npx skills add haydenbleasel/blume
```

Der Skill vermittelt dem Agent, was Blume ist und wie man eine Website aufsetzt, schreibt und konfiguriert, und verweist ihn auf die vollständige, im installierten Paket mitgelieferte Dokumentation (das Verzeichnis `docs/` innerhalb von `blume`, wo auch immer dein Paketmanager es installiert).

Er ist einer der [von Blume mitgelieferten Agent Skills](/docs/advanced/skills), neben einem Skill, der die Dokumentation aus einem geplanten Agent-Lauf heraus mit deinem Produkt synchron hält.

---

# Analytics
Source: https://useblume.dev/de/docs/configuration/analytics

Blume bindet Analytics für dich über einen einzigen `analytics`-Block in `blume.config.ts` ein. Vercel Web Analytics und PostHog werden erstklassig unterstützt, und eine `scripts`-Ausweichlösung deckt alle anderen Anbieter ab — Plausible, Fathom, Google Analytics, Umami und den Rest.

Analytics wird **nur in Produktions-Builds** geladen. Die Skripte werden von `blume build` ausgegeben, niemals von `blume dev`, sodass lokaler Traffic nie in deinen Dashboards landet und du kein separates „Entwicklungs“-Projekt brauchst.

:::note
Analytics ist optional. Ohne `analytics`-Block bindet Blume nichts ein.
:::

## Vercel Web Analytics

Setze `vercel: true`, um [Vercel Web Analytics](https://vercel.com/docs/analytics) hinzuzufügen. Blume bindet das First-Party-Skript von Vercel ein, das von deiner eigenen Domain ausgeliefert wird, sobald Web Analytics für das Projekt im Vercel-Dashboard aktiviert ist.

```ts blume.config.ts lineNumbers
analytics: {
  vercel: true,
}
```

Es werden keine Schlüssel benötigt — das Skript meldet an das Projekt, unter dem es deployt ist. Daten werden nur bei Vercel-Deployments erfasst, wo der Endpunkt `/_vercel/insights` existiert.

## PostHog

Gib deinen **Projekt-API-Schlüssel** an, um [PostHog](https://posthog.com) hinzuzufügen. Der Host ist standardmäßig PostHog Cloud US; setze `host` für EU Cloud (`https://eu.i.posthog.com`) oder eine selbst gehostete Instanz.

```ts blume.config.ts lineNumbers
analytics: {
  posthog: {
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // optional, this is the default
  },
}
```

Der Projekt-API-Schlüssel kann gefahrlos an den Browser ausgeliefert werden — er ist ein öffentlicher, ausschließlich schreibender Schlüssel.

## Eigene Skripte

Verwende `scripts`, um einen beliebigen anderen Analytics-Anbieter zu laden. Jeder Eintrag rendert ein `<script>`-Tag und muss **genau eines** von `src` (extern) oder `content` (inline) setzen.

```ts blume.config.ts lineNumbers
analytics: {
  scripts: [
    // Plausible
    {
      src: "https://plausible.io/js/script.js",
      strategy: "defer",
      attributes: { "data-domain": "example.com" },
    },
    // Fathom
    {
      src: "https://cdn.usefathom.com/script.js",
      strategy: "defer",
      attributes: { "data-site": "ABCDEFG" },
    },
    // An inline snippet
    {
      content: "console.log('analytics ready')",
    },
  ],
}
```

`attributes` ist eine Zuordnung zusätzlicher HTML-Attribute (`data-*`, `id`, …), die auf das Tag verteilt werden, und `strategy` fügt externen Skripten `async` oder `defer` hinzu.

## Optionen

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `vercel` | `false` | Vercel Web Analytics hinzufügen (nur bei Vercel-Deployments). |
| `posthog.key` | — | PostHog-Projekt-API-Schlüssel. Aktiviert PostHog, wenn gesetzt. |
| `posthog.host` | `https://us.i.posthog.com` | PostHog-Ingestion-Host (EU Cloud oder selbst gehostet). |
| `scripts[].src` | — | URL des externen Skripts. Schließt sich mit `content` gegenseitig aus. |
| `scripts[].content` | — | Inline-Skriptinhalt. Schließt sich mit `src` gegenseitig aus. |
| `scripts[].strategy` | — | `async` oder `defer` für ein externes Skript. |
| `scripts[].attributes` | — | Zusätzliche HTML-Attribute, die auf das `<script>`-Tag verteilt werden. |

Alle drei lassen sich kombinieren — aktiviere Vercel, PostHog und eigene Skripte gemeinsam. Zum Deployen deiner gebauten Website siehe [Deployment](/docs/deployment).

---

# Anpassung
Source: https://useblume.dev/de/docs/configuration/customization

## Komponenten-Overrides

Füge eine `components.ts` (oder `components.tsx`) im Stammverzeichnis deines Projekts hinzu und exportiere `defineComponents`. Die `mdx`-Map **ersetzt** entweder eine eingebaute Komponente oder **fügt** eine neue hinzu — verfügbar in jeder `.mdx`-Seite ohne Import.

```ts components.ts lineNumbers
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";
import Pricing from "./components/Pricing.astro";

export default defineComponents({
  mdx: {
    Callout, // replace the built-in Callout
    Pricing, // add a new <Pricing /> component
  },
});
```

Die Schlüssel sind die Namen, die du in MDX schreibst (`<Callout>`, `<Pricing>`). Verwende den Dateinamen mit `.tsx`, wenn du React-Komponenten importierst.

### Referenzformen

Jedes Override — in `mdx`, `layout` oder `islands` — akzeptiert drei Formen:

```ts components.ts
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";

export default defineComponents({
  mdx: {
    Callout, // 1. an imported component
    Note: "./components/Note.astro", // 2. a path string (resolved from the project root)
    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. a descriptor
  },
});
```

Die **Descriptor**-Form ergänzt einen Hydration-Modus, damit eine interaktive React-/Vue-/Svelte-Komponente ihr JavaScript ausliefert und auf dem Client zum Leben erwacht. Ohne einen `client`-Modus wird eine Framework-Komponente als statisches HTML gerendert — Blume gibt eine Build-Warnung aus, wenn es so einen Fall entdeckt, da das meist ein Versehen ist.

| `client` | Hydratisiert |
| --- | --- |
| `"load"` | Sofort beim Laden der Seite |
| `"idle"` | Wenn der Main Thread im Leerlauf ist |
| `"visible"` | Wenn sie in den sichtbaren Bereich gescrollt wird |
| `"media"` | Wenn eine `media`-Query zutrifft (ergänze `media: "(min-width: 40rem)"`) |
| `"only"` | Nur auf dem Client, niemals serverseitig gerendert |

Für interaktive Komponenten, die du auf vielen Seiten einsetzt, ist die [`islands`-Gruppe](/docs/content/islands#registering-islands-in-componentsts) eine Kurzschreibweise für die Descriptor-Form mit `client: "visible"`.

### Ein Override typisieren

Wenn du eine eingebaute Komponente ersetzt, importiere ihren Prop-Typ aus `blume/components`, damit deine Komponente dem Vertrag entspricht — die Typen werden aus den Komponenten selbst abgeleitet, laufen also nie auseinander:

```tsx components/Callout.tsx
import type { CalloutProps } from "blume/components";

export default function Callout(props: CalloutProps) {
  // …your own callout, same props as the built-in
}
```

Prop-Typen werden für die Content-Komponenten exportiert (`CalloutProps`, `CardProps`, `TabsProps`, `StepsProps`, `BadgeProps` und weitere).

## Layout-Slots

Die `layout`-Map ersetzt einen Teil von Blumes Rahmen durch deine eigene Komponente. Jedes Override erhält dieselben Props wie die eingebaute Komponente, die es ersetzt, sodass du die Standardvariante umhüllen oder bei null anfangen kannst.

```ts components.ts
import { defineComponents } from "blume";
import Footer from "./components/Footer.astro";
import Logo from "./components/Logo.astro";

export default defineComponents({
  layout: {
    Logo, // brand mark + title in the header
    Footer, // site-wide footer (no built-in — renders only when set)
  },
});
```

Verdrahtete Slots:

| Slot | Ersetzt | Props |
| --- | --- | --- |
| `Layout` | Die gesamte Seitenhülle (`RootLayout`) | Alles, was das eingebaute Layout erhält, plus die `layout`-Map |
| `Header` | Die obere Navigationsleiste | `site`, `logo`, `navigation`, `route`, `searchEnabled`, … |
| `Logo` | Der Marken-Link (Bildmarke + Titel) im Header | `site`, `logo` |
| `Search` | Der Suchauslöser im Header + Modal | `navigation`, `strings`, `locale`, `askEnabled` |
| `Sidebar` | Der primäre Navigationsbaum | `items`, `currentRoute` |
| `MobileNav` | Die Navigation in der mobilen Schublade (standardmäßig `Sidebar`) | `items`, `currentRoute` |
| `Breadcrumbs` | Der Breadcrumb-Pfad | `crumbs` |
| `TableOfContents` | Die Gliederung „Auf dieser Seite“ | `headings`, `title`, `variant` |
| `Pagination` | Die Zurück-/Weiter-Links im Fußbereich | `prev`, `next`, `strings` |
| `PageHeader` | Ein Einfügepunkt über dem Artikel (keine eingebaute Komponente) | `page`, `headings`, `route` |
| `PageFooter` | Ein Einfügepunkt unter dem Artikel (keine eingebaute Komponente) | `page`, `headings`, `route` |
| `Footer` | Ein seitenweiter Footer nach dem Content-Grid (keine eingebaute Komponente) | `site`, `navigation`, `ui` |

`PageHeader`, `PageFooter` und `Footer` haben keine eingebaute Komponente — sie rendern nichts, bis du sie setzt, was sie zu praktischen Einfügepunkten für ein Werbebanner, einen „Zuletzt aktualisiert“-Hinweis oder einen Marketing-Footer macht.

Layout-Slots akzeptieren dieselben [drei Referenzformen](#reference-form) wie MDX-Overrides, sodass ein Slot ein Pfad-String oder ein hydratisierter Descriptor (`{ component, client }`) sein kann, wenn du einen interaktiven Header oder Footer möchtest.

## Interaktive Islands

Für interaktive UI (React, Vue oder Svelte) legst du eine Komponente in einen `islands/`-Ordner und verwendest sie in jeder MDX-Seite — Blume hydratisiert sie für dich, ohne Wrapper oder Registrierung:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}
```

```mdx page.mdx
Use it anywhere: <Counter />
```

Siehe [Islands](/docs/content/islands) für Hydration-Strategien und Framework-Setup.

## Eigene Seiten

Füge `.astro`-Dateien in deinem `pages/`-Ordner hinzu, um vollständig eigene Routen neben deiner Dokumentation einzubinden — eine Landingpage, eine Preisseite oder einen handgebauten Index. Sie behalten ihren Ort, sodass relative Importe und `getStaticPaths` wie gewohnt funktionieren, und sie können deine Konfiguration, Navigation und Routen aus dem Modul `blume:data` lesen.

Siehe [Eigene Seiten](/docs/advanced/custom-pages) für die vollständige Anleitung.

## Registry

`blume add` kopiert eine von Blume gepflegte Komponente als **Quellcode** in dein Projekt — sie gehört dir und du kannst sie frei bearbeiten. Führe den Befehl ohne Argumente aus, um aufzulisten, was verfügbar ist:

```bash
blume add
```

Installiere einen Layout-Slot (Header, Sidebar, Breadcrumbs, Inhaltsverzeichnis, Pagination oder Feedback) oder eine beliebige Content-Komponente (Callout, Card, Tabs, Steps, Accordion und weitere):

```bash
blume add callout
blume add pagination
```

Die Kopie importiert den Rest des Frameworks aus `blume/*`, sodass sie exakt wie die eingebaute Komponente rendert, bis du sie änderst. `blume add` gibt das `defineComponents`-Snippet aus, um sie zu registrieren — Content-Komponenten unter `mdx`, Layout-Teile unter `layout`.

## Astro-Integrationen

Füge eine beliebige Astro-Integration über das Array `integrations` auf oberster Ebene in `blume.config.ts` hinzu. Installiere die Integration zuerst in deiner Site; Blume fügt sie nicht zu den Abhängigkeiten der generierten Runtime hinzu und verwaltet auch nicht ihre Astro-Kompatibilität.

```bash
npm install @astrojs/sitemap
```

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  integrations: [
    sitemap({
      filter: (page) => !page.includes("/drafts/"),
    }),
  ],
});
```

Blume behält seine eingebauten Integrationen in ihrer bestehenden Reihenfolge und hängt anschließend deine Einträge in Deklarationsreihenfolge an. Sie werden weder sortiert noch dedupliziert, sodass zwei Integrationen mit demselben `name` beide laufen. Blume validiert, dass `integrations` ein Array ist, während Astro jeden Eintrag validiert und ungültige Integrationen meldet.

Da Blume deine Integrationen lädt, indem es `blume.config.ts` aus der generierten Astro-Konfiguration erneut importiert, statt die Instanzen zu kopieren, wird das Konfigurationsmodul pro Lauf zweimal ausgewertet — einmal, wenn Blume deine Konfiguration liest, und einmal, wenn Astro sie lädt. Halte Integrations-Factories frei von Seiteneffekten (gib die Integration zurück; schreibe keine Dateien und öffne keine Verbindungen bei der Konstruktion), damit die zweite Auswertung harmlos bleibt.

Dieselben Integrationen laufen in `blume dev` und `blume build`. Wenn du `blume.config.ts` während `blume dev` bearbeitest, wird die versteckte Astro-Konfiguration neu generiert und ein Konfigurationsneustart ausgelöst; falls eine bearbeitete Integration keine Wirkung zeigt, starte `blume dev` neu. Blume kann nicht erkennen, welche Konfigurationsänderungen Integrationen betreffen, daher löst jede Änderung an `blume.config.ts` — selbst an einem nicht zusammenhängenden Feld — einen Neustart des Dev-Servers aus statt einer Hot-Anwendung, sobald `integrations` nicht leer ist. Blume verfolgt nur den Inhalt von `blume.config.ts`, sodass das Bearbeiten einer separaten Datei, die davon importiert wird, diese Neugenerierung nicht von selbst auslöst — starte `blume dev` nach solchen Änderungen neu. Wenn du ejectest, behält die dir gehörende `astro.config.mjs` eine relative Brücke zu `blume.config.ts`, sodass die konfigurierten Integrationen weiterhin laufen; du kannst sie später direkt in die Astro-Konfiguration verschieben, als Teil der vollständigen Übernahme.

## Eject

Wenn du volle Kontrolle möchtest, ejecte die generierte Runtime in ein eigenständiges Astro-Projekt:

```bash
blume eject --yes
```

Eject ist ein einseitiger Schritt: Die versteckte `.blume/`-Runtime wird zu einer normalen Astro-App, die dir gehört und die du direkt verändern kannst. Das Paket `blume` bleibt importierbar, sodass du seine Komponenten, sein Theme und seine Markdown-Prozessoren behältst.

### Was Eject zurücklässt

Nach dem Eject führt dein `build`-Skript einfach `astro build` aus — die Site selbst wird gleich gebaut, aber die Artefakte, die `blume build` obendrauf gelegt hat, werden nicht mehr erzeugt. Der Eject-Befehl warnt vor denen, die deine Konfiguration tatsächlich nutzt. Um sie zu behalten:

- **Pagefind-Suchindex** — mit `search.provider: "pagefind"` lädt die Such-UI den Index von der gebauten Site, sodass die Suche in Produktion nicht funktioniert, bis du selbst indexierst. Installiere `pagefind` als devDependency und indexiere nach jedem Build: `"build": "astro build && pagefind --site dist"`.
- **Synchronisierung der gehosteten Suche** — der Index eines gehosteten Anbieters wird beim Build nicht mehr hochgeladen; lade deine Suchdatensätze nach jedem Build erneut über die API oder CLI des Anbieters hoch.
- **sitemap.xml** — erstelle sie neu mit der Standard-Integration [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/).
- **robots.txt** — liefere deine eigene als `public/robots.txt` aus.
- **llms.txt / llms-full.txt und agent-readability.json** — schreibe sie von Hand (oder generiere sie in einem eigenen Build-Schritt) und liefere sie aus `public/` aus.
- **Plattform-Weiterleitungsdateien** — `_redirects` und `vercel.json` werden für statische Builds nicht mehr ausgegeben. Deine Weiterleitungen funktionieren weiterhin als von Astro generierte Meta-Refresh-Seiten, oder du kannst sie in die Konfiguration deines Hosters übernehmen.

---

# Export
Source: https://useblume.dev/de/docs/configuration/export

Blume kann eine **Export**-Aktion zu den [Seitenaktionen](/docs/content/navigation#page-actions) unterhalb des Inhaltsverzeichnisses hinzufügen, sodass Leser die Seite, auf der sie sich befinden, als **PDF** oder **EPUB** speichern können. Die Funktion ist standardmäßig deaktiviert und läuft vollständig clientseitig — kein Server, und [statische](/docs/deployment) Builds bleiben statisch.

## Aktivieren

Schalten Sie beide Formate mit einem einzigen Schalter ein:

```ts blume.config.ts
export: true,
```

Um nur ein Format anzubieten, übergeben Sie stattdessen ein Objekt:

```ts blume.config.ts
export: {
  pdf: true,
  epub: false,
},
```

Jedes Format, das Sie weglassen (oder auf `false` setzen), wird aus dem Menü ausgeschlossen. Sind beide deaktiviert — die Standardeinstellung —, erscheint die **Export**-Aktion überhaupt nicht.

## PDF

**Als PDF exportieren** öffnet den Druckdialog Ihres Browsers mit einem Druck-Stylesheet, das die Website-Umgebung — Kopfzeile, Seitenleisten, Navigation — entfernt und nur den Artikel übrig lässt. Wählen Sie **Als PDF speichern**, um den Vorgang abzuschließen.

Da die live dargestellte, vollständig gestaltete Seite gedruckt wird, behält das Ergebnis gestochen scharfen, markierbaren Text, echte Schriftarten und syntaxhervorgehobenen Code. Es sind keine Abhängigkeiten erforderlich, und es funktioniert in der Entwicklung, in der Produktion und auf statischen Hosts gleichermaßen.

:::note
Der PDF-Export läuft über den nativen Druckdialog des Browsers, daher hängen die genaue Formulierung „Als PDF speichern“ und die Optionen vom Browser ab. Aktivieren Sie im Dialog **Hintergrundgrafiken**, damit die Hintergründe von Codeblöcken und Hinweisen erhalten bleiben.
:::

## EPUB

**Als EPUB exportieren** erzeugt im Browser eine eigenständige `.epub`-Datei der aktuellen Seite und lädt sie herunter — bereit für Apple Books, Calibre oder jeden E-Reader. Der Generator wird erst geladen, wenn ein Leser auf Export klickt, sodass er den Rest Ihrer Website nie belastet.

Damit die Datei auf einem Gerät ohne eigenes Stylesheet oder JavaScript lesbar bleibt, schreibt Blume die Seite in sauberes, eigenständiges HTML um: syntaxhervorgehobener Code wird zu einfacher Monospace-Schrift, dekorative Symbole und Kopieren-Schaltflächen entfallen, und ein integriertes E-Reader-Stylesheet kümmert sich um Abstände, Codeblöcke und Tabellen.

## Was exportiert wird

Beide Formate exportieren die **einzelne Seite**, die ein Leser gerade betrachtet — nicht die gesamte Website —, was dazu passt, wo die Aktion angesiedelt ist: unterhalb des Inhaltsverzeichnisses dieser Seite.

:::note
In einem EPUB gibt es kein JavaScript, um Tabs zu wechseln, daher werden Inhalte mit Tabs — wie [package-install](/docs/content/syntax)-Blöcke und Codegruppen — so erweitert, dass alle Panels gleichzeitig angezeigt werden. Clientseitig gerenderte Einbettungen wie Mermaid-Diagramme sind nicht enthalten.
:::

---

# Suche
Source: https://useblume.dev/de/docs/configuration/search

Blume liefert lokale Suche ohne gehostete Infrastruktur und ohne API-Schlüssel. Sie läuft im Browser, funktioniert sowohl in `blume dev` als auch in `blume build` und indexiert nur deine echten Inhalte — Navigationselemente und ausgeschlossene Seiten werden übersprungen. Wenn du sie irgendwann überwachsen hast, kannst du zu einem gehosteten oder semantischen Backend wechseln, ohne dass sich Aussehen oder Verhalten der Suche ändern — nur der `search.provider`, den du konfigurierst, ändert sich.

Blume erreicht Parität mit dem Anbieterangebot von Fumadocs: **Orama**, **FlexSearch**, **Algolia**, **Orama Cloud**, **Typesense** und **Mixedbread** (dazu **Pagefind**). In dein Projekt wird nur das SDK des konfigurierten Anbieters installiert, sodass die Wahl eines Backends nie die anderen mitzieht.

## Suche verwenden

Öffne die Suche mit <Badge variant="accent">⌘K</Badge> (oder `Ctrl K`), oder drücke `/`, wenn du gerade nicht in einem Feld tippst. `Esc` schließt sie, und `⌘J` (oder `Ctrl J`) blendet die Ergebnisvorschau ein und aus.

Suchanfragen treffen auf **Titel**, **Beschreibungen** und **Fließtext** von Seiten, wobei Titeltreffer am höchsten und Beschreibungen über dem Fließtext bewertet werden.

## Beliebte Seiten

Bevor ein Leser eine Suchanfrage tippt, zeigt der Suchdialog eine **Beliebt**-Liste. Standardmäßig sind das die ersten sechs Seiten der Seitenleiste — was auf Websites mit mehreren Tabs oft den falschen Bereich hervorhebt. Hefte stattdessen die gewünschten Links an:

```ts blume.config.ts lineNumbers
search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},
```

Jeder Eintrag benötigt ein `href` (interne Route oder externe URL) und ein `label`, dazu optional ein `icon` — der Name eines [integrierten Icons](/docs/content/components#icon), ein Bildpfad bzw. eine Bild-URL oder ein Inline-SVG (dieselben _Eingaben_ wie bei Nav-Icons), standardmäßig ein Datei-Symbol. Lass `popular` weg oder leer, um den Fallback auf die Seitenleiste beizubehalten.

Schreibe `href` so, als wäre die Website im Stammverzeichnis eingehängt — ein `basePath` wird für dich angewendet, genau wie bei `navigation.featured`. Externe URLs werden unverändert durchgereicht.

> **Warning**
>
> Eine kuratierte Liste ist ein einziger Satz von Links, den alle Sprachen
> gemeinsam nutzen. Auf einer Website mit konfiguriertem `i18n` folgt der
> Seitenleisten-Fallback der Sprache des Lesers, aber `popular`-Einträge zeigen
> dorthin, wohin ihr `href` verweist — hefte also nur dann Routen mit
> Sprachpräfix an, wenn du wirklich jeden Leser in diese eine Sprache schicken
> willst.

## Was indexiert wird

Für Orama, FlexSearch, Algolia, Orama Cloud und Typesense — sowie für das `search_docs`-Tool des MCP-Servers — indexiert Blume den Titel, die Beschreibung und den auf reinen Text reduzierten Fließtext jeder Seite: Codeblöcke, Bilder und Markup werden entfernt, damit die Ergebnisse relevant bleiben. Diese Indizes werden aus deinen Quelldateien erstellt und sind daher in der Entwicklung und in der Produktion identisch. Pagefind indexiert stattdessen das gebaute HTML, und Mixedbread synchronisiert dein rohes Markdown, sodass beide immer auch Code durchsuchen.

Wenn deine Doku bei durchsuchbaren Begriffen wie Optionen, Methoden oder Fehlernamen auf Codebeispiele setzt, nimm eingefassten Code ausdrücklich in die quellbasierten Indizes auf:

```ts blume.config.ts lineNumbers
search: {
  indexing: {
    includeCodeBlocks: true,
  },
},
```

Der Inhalt und der Titel jedes Code-Fences (`blume.config.ts` oben) werden durchsuchbar; die Sprache und die Fence-Marker nicht. Auf `.mdx`-Seiten liest der Index Komponenten als den Text, den sie anzeigen — den Titel einer Card, das Label eines Tab, die Beschreibungen einer TypeTable — und nutzt dabei dieselben Serializer wie die [Agent-Oberflächen](/docs/configuration/ai), sodass ein `ai.markdownComponents`-Eintrag auch deine eigenen Komponenten abdeckt. Auf Pagefind oder Mixedbread hat die Option keine Wirkung. Rechne damit, dass der Index mit deinen eingefassten Inhalten wächst — der Client-Index wird an jeden Leser ausgeliefert, gehostete Anbieter begrenzen die Datensatzgröße (Algolia weist den Synchronisierungs-Batch zurück, wenn der Datensatz einer Seite das Limit deines Tarifs überschreitet, und der bisherige Index bleibt aktiv), und ein Treffer innerhalb eines Fences zeigt im Ergebnisauszug flach dargestellten Code.

Auf einer [versionierten](/docs/content/versioning) Website beziehen sich die Ergebnisse standardmäßig auf die gerade angesehene Version, mit einem „Alle Versionen“-Schalter in der Fußzeile des Dialogs (der pro Leser gemerkt wird). Treffer aus anderen Versionen nennen ihre Version in der Zeile. Orama, FlexSearch, Algolia und Typesense berücksichtigen diese Eingrenzung — gehostete Datensätze tragen eine `version`-Facette, wobei die aktuelle Doku als `"current"` hochgeladen wird —, während Pagefind ohne Eingrenzung bleibt, passend zu seinem Verhalten bei Sprachen.

## Tags

Füge `search.tags` zum Frontmatter einer Seite hinzu, um sie im Suchdialog unter einem Filter zu gruppieren — Leser können Ergebnisse mit einem Klick auf ein Tag eingrenzen. Tags werden bei den gehosteten Anbietern außerdem zu einer Facette.

```yaml
search:
  tags: [api, reference]
```

## Anbieter

Die clientseitigen Anbieter kommen ohne Schlüssel aus und benötigen keine zusätzliche Konfiguration. Die gehosteten nehmen **öffentliche** Zugangsdaten in `blume.config.ts` entgegen (die gefahrlos an den Browser ausgeliefert werden können) und lesen ihren **geheimen** Admin-Schlüssel zur Buildzeit aus einer Umgebungsvariablen — das Geheimnis landet nie in der Konfiguration oder im Client-Bundle.

### Orama (Standard)

Blumes Standard-Engine. Sie erstellt einen JSON-Index, der unter `/blume-search.json` ausgeliefert wird, und fragt ihn im Browser ab — sofort, clientseitig und in `blume dev` live beim Bearbeiten. Keine Schlüssel, kein Dienst.

```ts blume.config.ts lineNumbers
search: {
  provider: "orama", // default
}
```

#### Nicht-lateinische Schriften

Oramas Standard-Tokenizer behält nur lateinische Grundbuchstaben, Ziffern und eine Handvoll akzentuierter Vokale, sodass Text in jeder anderen Schrift — Japanisch, Chinesisch, Koreanisch und Thai, aber ebenso Russisch, Griechisch, Hebräisch und Hindi — sonst überhaupt keine Treffer liefern würde. Blume erledigt das für dich: Wenn [`i18n.defaultLocale`](/docs/content/i18n) auf eine nicht-lateinische Schrift verweist, wechselt der Index zu einem wortsegmentierenden Tokenizer (aufgebaut auf dem in Browser und Node nativ verfügbaren `Intl.Segmenter`). Die Sprache deiner Website zu deklarieren, ist alles, was nötig ist:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}
```

Derselbe Tokenizer bedient den Suchdialog, das `search_docs`-Tool des MCP-Servers und die Fundierung von Ask AI. Entscheidend ist die Schrift, nicht der Sprachname — `az-Cyrl` wird segmentiert, `sr-Latn` nicht — und für den gesamten Index entscheidet die Standardsprache: Auf einer mehrsprachigen Website teilen sich alle Seiten den Tokenizer der Standardsprache. Bei einer nicht-lateinischen Standardsprache ist das unbedenklich, denn lateinische Wörter überstehen die Segmentierung unverändert, sodass Seiten auf Englisch neben der Standardsprache durchsuchbar bleiben. Umgekehrt gilt das nicht: Nicht-lateinische Übersetzungen auf einer Website mit lateinischer Standardsprache sind nicht durchsuchbar. Auch Sprachen in lateinischer Schrift, die stark auf Diakritika setzen (Vietnamesisch oder Serbisch in lateinischer Schrift), schneiden beim Standard-Tokenizer schlechter ab, der nur wenige akzentuierte Vokale zusammenfasst und Wörter an allen übrigen trennt.

Bei Japanisch und Chinesisch geht es noch einen Schritt weiter. Segmentierung allein indexiert einen zusammengesetzten Begriff als seine Bestandteile — 資金決済法 als 資金, 決済 und 法 — wodurch eine Seite, die jeden Bestandteil irgendwo erwähnt, die Seite überflügeln kann, um die es beim Begriff eigentlich geht. Han, Hiragana und Katakana werden deshalb als überlappende Zeichenpaare indexiert, und Abfragen auf diesen Indizes bevorzugen Seiten, die die Paare eines Begriffs gemeinsam tragen, und lockern auf Treffer mit beliebigen Paaren, wenn keine Seite alle trägt — so liefert auch das Tippen eines ganzen Satzes noch die passendsten Seiten. Koreanisch und Thai behalten ihre segmentierten Wörter.

### FlexSearch

Eine zweite schlüssellose, clientseitige Option. Sie verwendet denselben `/blume-search.json`-Index wieder, den Orama ausliefert, und baut im Browser einen [FlexSearch](https://github.com/nextapps-de/flexsearch)-Dokumentindex auf. Funktioniert in `blume dev` und `blume build`.

FlexSearch hat keinen vergleichbaren Segmentierungs-Hook, daher solltest du für Websites in nicht-lateinischer Schrift Orama (den Standard) oder [Pagefind](#pagefind) bevorzugen, dessen `pagefind_extended`-Binary eine breite Palette von Sprachen indexiert und Chinesisch, Japanisch und Koreanisch nativ segmentiert.

```ts blume.config.ts lineNumbers
search: {
  provider: "flexsearch",
}
```

### Pagefind

Für sehr große Dokumentationen kannst du dich für [Pagefind](https://pagefind.app) entscheiden. Es indexiert dein gebautes HTML und lädt den Index bei Bedarf in Shards, sodass die anfängliche Nutzlast winzig bleibt, egal wie groß die Website wird.

```ts blume.config.ts lineNumbers
search: {
  provider: "pagefind",
}
```

Pagefind läuft nur während `blume build`, daher ist die Suche mit diesem Anbieter in `blume dev` nicht verfügbar.

### Algolia

Der Browser fragt [Algolia](https://www.algolia.com) direkt mit deinem reinen Suchschlüssel ab. Jedes `blume build` ersetzt den Index mithilfe des Admin-Schlüssels aus `ALGOLIA_ADMIN_API_KEY` (der Build warnt und überspringt den Upload, wenn er nicht gesetzt ist). Bei jeder Synchronisierung wird der gesamte Index ersetzt, sodass gelöschte oder umbenannte Seiten nicht als veraltete Ergebnisse zurückbleiben.

```ts blume.config.ts lineNumbers
search: {
  provider: "algolia",
  algolia: {
    appId: "YOUR_APP_ID",
    indexName: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
  },
}
```

### Orama Cloud

Gehostetes Orama. Der Browser fragt deinen Index-Endpunkt mit dem öffentlichen API-Schlüssel ab; `blume build` schiebt Datensätze mit `ORAMA_PRIVATE_API_KEY` in den Index. Setze `indexId`, um die Synchronisierung zu aktivieren.

```ts blume.config.ts lineNumbers
search: {
  provider: "orama-cloud",
  oramaCloud: {
    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
    apiKey: "YOUR_PUBLIC_API_KEY",
    indexId: "your-index-id", // for the build-time sync
  },
}
```

### Typesense

Selbst gehostetes oder Cloud-[Typesense](https://typesense.org). Der Browser fragt die Collection mit dem reinen Suchschlüssel ab; `blume build` erstellt die Collection neu und importiert Dokumente mit `TYPESENSE_ADMIN_API_KEY`. Die Collection wird bei jeder Synchronisierung verworfen und neu aufgebaut, damit gelöschte oder umbenannte Seiten nicht als veraltete Ergebnisse zurückbleiben — wenn du die Einstellungen der Collection von Hand feinabstimmst, wende sie nach einem Build erneut an.

```ts blume.config.ts lineNumbers
search: {
  provider: "typesense",
  typesense: {
    host: "xyz.a1.typesense.net",
    collection: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
    // port + protocol default to 443 / https
  },
}
```

### Mixedbread

Semantische Suche über [Mixedbread](https://www.mixedbread.com). Anfragen werden über einen generierten `/api/search`-Endpunkt geleitet, der deinen Schlüssel hält, weshalb dieser Anbieter **Server-Output erfordert** (`deployment.output: "server"`). Der Endpunkt liest `MIXEDBREAD_API_KEY`. Synchronisiere deine Inhalte im Build mit der Mixedbread-CLI in den Store, z. B. `mxbai vs sync <STORE_ID> ./content --ci`.

```ts blume.config.ts lineNumbers
search: {
  provider: "mixedbread",
  mixedbread: {
    storeId: "YOUR_STORE_ID",
  },
}
```

### Suche deaktivieren

```ts blume.config.ts lineNumbers
search: {
  provider: "none",
}
```

## Seiten ausschließen

Es werden nur indexierbare Seiten durchsucht. Eine Seite bleibt aus dem Index heraus, wenn sie `search.exclude` im Frontmatter setzt:

```yaml
search:
  exclude: true
```

[Versteckte Seiten](/docs/content/navigation#hidden-pages) sind ebenfalls standardmäßig ausgeschlossen. Um sie trotzdem zu indexieren, aktiviere es ausdrücklich:

```ts blume.config.ts lineNumbers
search: {
  indexing: { includeHiddenPages: true },
}
```

---

# SEO
Source: https://useblume.dev/de/docs/configuration/seo

Blume übernimmt die Auffindbarkeitsebene für dich: Seiten-Metadaten, Bilder zum Teilen in sozialen Netzwerken, Feeds und strukturierte Daten. Die konfigurierbaren Funktionen liegen unter dem Schlüssel `seo` in `blume.config.ts`; die Metadaten ergeben sich aus deinen Inhalten.

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
  x: { handle: "@acme" },
}
```

Das meiste davon wird mit einer absoluten Site-URL noch besser – setze [`deployment.site`](/docs/deployment), damit Feeds, OG-Bilder, Canonicals, die Sitemap und JSON-LD vollständige URLs ausgeben können.

## Metadaten

Jede Seite rendert die standardmäßigen `<head>`-Tags aus deiner Konfiguration und deinem Frontmatter:

- `<title>` – der Seitentitel plus der `title` deiner Site.
- `<meta name="description">` und `og:description` – die `description` der Seite, ersatzweise die `description` der Site.
- `og:title` und `og:site_name` – der Seitentitel und der `title` deiner Site.
- `<link rel="canonical">` und `og:url` – die absolute URL der Seite (wenn `deployment.site` gesetzt ist).
- `og:type` – `article` bei Blogbeiträgen und Changelog-Einträgen, `website` sonst. Artikelseiten geben außerdem `article:published_time` und `article:modified_time` aus dem `date` der Seite und dem Zeitstempel der letzten Änderung aus.
- `og:image` – das [OG-Bild](#open-graph-images) für die Seite. Eine generierte Karte deklariert zusätzlich ihre `og:image:width`, `og:image:height`, `og:image:type` und `og:image:alt`, sodass ein Crawler die Karte anordnen kann, ohne sie zuvor abzurufen; ein `seo.image`, das du selbst angibst, deklariert nichts davon, da Größe und Format unbekannt sind.
- `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` – die X-Karte. Seiten mit einem Bild erhalten die breite Variante `summary_large_image`; Seiten ohne Bild erhalten weiterhin die kompakte `summary`-Karte, statt als nackter Link dargestellt zu werden.

### X-Zuschreibung

X liest alles Übrige auf der Karte aus den `og:*`-Tags, sodass die einzigen Werte, die es nicht ableiten kann, die zu nennenden Konten sind. Setze sie unter `seo.x`, und Blume gibt `twitter:site` (das Konto deiner Site) und `twitter:creator` (das der Autorenschaft) aus. Das `@` ist optional – `acme` und `@acme` funktionieren beide.

```ts blume.config.ts lineNumbers
seo: {
  x: { handle: "@acme", creator: "@jane" },
}
```

Eine Seite kann ihre eigene Autorenschaft angeben, was bei einem Gastbeitrag genau das ist, was du willst:

```yaml lineNumbers
---
title: How we shipped it
seo:
  x:
    creator: "@guestauthor"
---
```

Überschreibe jedes der anderen Tags pro Seite mit `seo`-Frontmatter:

```yaml lineNumbers
---
title: Pricing
description: Plans and pricing for every team size.
seo:
  title: Pricing — Acme
  canonical: https://acme.com/pricing
  noindex: false
---
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.title?` | `string` | - | Override the <title> and og:title for this page. |
| `seo.description?` | `string` | - | Override the meta + og:description. |
| `seo.image?` | `string` | - | Custom social image (see Open Graph). |
| `seo.canonical?` | `string` | - | Override the canonical URL. |
| `seo.noindex?` | `boolean` | - | Emit robots noindex and skip structured data. |
| `seo.x.creator?` | `string` | - | Credit this page to an X account (twitter:creator), overriding seo.x.creator from your config. |

## Open-Graph-Bilder

Blume kann für jede Seite zur Build-Zeit eine Social-Karte in 1200×630 rendern – dank [Takumi](https://takumi.kane.tw) ohne Headless-Browser, sodass Builds schnell bleiben. Standardmäßig aktiviert, sobald [`deployment.site`](/docs/deployment) gesetzt oder automatisch erkannt wurde (die `og:image`-URL muss absolut sein, um für Crawler nützlich zu sein), andernfalls deaktiviert. Setze `enabled`, um das in beide Richtungen zu überschreiben:

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}
```

### Die generierte Karte mit deiner Marke versehen

Setze ein lokales SVG und eine Farbpalette, um die generierte Karte an deine Marke anzupassen. Das Logo kann in `public/` oder im Projektstammverzeichnis liegen. Lasse einen Palettenwert weg, um dessen Standard beizubehalten.

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

Standardmäßig leitet sich jede Karte aus deinen Inhalten und deinem Theme ab – der **Seitentitel** als Überschrift, die **Seitenbeschreibung** als Untertitel (derselbe Text wie ihre `og:description`, sodass `seo.description` Vorrang vor `description` hat), der **Titel deiner Site** als Kopfzeile und der **Akzent** deines Themes für die Marke. Bilder werden unter `/og/<slug>.png` ausgeliefert, spiegeln also jede Route, und werden selbst im Server-Modus als statische Dateien vorgerendert:

| Seitenroute         | Bild-URL                   |
| ------------------- | -------------------------- |
| `/`                 | `/og/index.png`            |
| `/quickstart`       | `/og/quickstart.png`       |
| `/configuration/ai` | `/og/configuration/ai.png` |

Überschreibe die generierte Karte für eine beliebige Seite mit `seo.image` – eine Datei in `public/` oder eine externe URL. Sie hat Vorrang vor der generierten Karte und funktioniert auch dann, wenn `og` deaktiviert ist, sodass du eigene Bilder mit generierten mischen kannst:

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
Jede Palettenfarbe akzeptiert jede CSS-Farbe – Hex, `oklch(…)`, `rgb(…)` und so weiter. Der Akzent akzeptiert außerdem eine benannte Voreinstellung (`blue`, `teal`, …), passend zu [`theme.accent`](/docs/configuration/theming#accent). Eine Farbe, die der Renderer nicht parsen kann, lässt den Build fehlschlagen, statt stillschweigend eine Karte in der Standardfarbe auszuliefern.
:::

Emojis in einem Seitentitel oder Site-Titel werden als [Twemoji](https://github.com/jdecked/twemoji)-Glyphen gerendert, die während des Renderns der Karte von einem CDN abgerufen werden – ein Build, dessen Titel Emojis enthalten, benötigt also Netzwerkzugriff. Jede Glyphe wird einmal pro Build abgerufen, egal wie viele Seiten sie verwenden.

### Kartenebenen anzeigen, ausblenden oder überschreiben

Über die Überschrift hinaus trägt die Karte drei optionale Ebenen: die **Markenkennzeichnung** oben links (dein Logo oder eine Akzentkachel mit dem Anfangsbuchstaben des Site-Titels), den **Untertitel** unter der Überschrift (die `description` der Seite oder die `description` deiner Site bei Seiten ohne eigene) und eine **Fußzeile** mit deinem Repo-Slug (aus `github`) und der URL der Site – dem Host der Deployment-Site plus [`deployment.base`](/docs/deployment#subpath-deploys), sodass eine GitHub-Pages-Projektseite als `user.github.io/repo` erscheint. Überschreibe jede davon mit einer eigenen Zeichenkette oder blende eine mit `false` aus:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}
```

### Kartenschriften

Standardmäßig wird die Karte in der integrierten Schriftart von Takumi gerendert, die nur lateinische Glyphen abdeckt – ein Titel in einer anderen Schrift (Japanisch, Chinesisch, Koreanisch, Arabisch, …) würde als Tofu erscheinen, also als leere Kästchen.

**Setze [`theme.fonts`](/docs/configuration/theming#fonts), und die Karte folgt dem.** Wenn deine Konfiguration eigene Schriften wählt, rendern die generierten Karten die Überschrift automatisch in deiner Display-Schrift und die Beschreibung sowie die Fußzeile in deiner Fließtextschrift, sodass geteilte Links zur Site passen – einschließlich nicht-lateinischer Abdeckung, ohne dass hier etwas zu konfigurieren wäre. (Familien von Anbietern außer Google werden übersprungen – der Karten-Renderer kann nur von Google Fonts laden –, lokale Schriftdateien funktionieren jedoch.)

Um auf Karten andere Schriften als auf der Site zu verwenden oder Schriftsystem-Abdeckung hinzuzufügen, ohne das Theme anzufassen, setze `og.fonts` explizit – es hat immer Vorrang vor den aus dem Theme abgeleiteten Schriften:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

Jeder Eintrag ist ein Google-Fonts-Familienname, ein Objekt, das dessen `weight` (eine Zahl, eine Liste oder ein variabler Bereich wie `"100..900"`) und `style` (`"normal"`, `"italic"` oder beides) festlegt, oder eine lokale Schriftdatei – `src` wird relativ zum Projektstammverzeichnis aufgelöst, mit optionalem `weight` und `style`, wenn nicht die Metadaten der Datei selbst entscheiden sollen.

Google-Familien werden beim Build abgerufen – ein Build, der sie verwendet, benötigt also Netzwerkzugriff – und der Renderer lädt nur die Glyphen-Subsets, die die Titel tatsächlich verwenden. Der Fallback erfolgt pro Glyphe, sodass das Hinzufügen einer Familie nur Glyphen betrifft, die die anderen Schriften nicht darstellen können.

Ein explizites `og.fonts: []` deaktiviert das Ganze: Karten behalten die integrierte Schrift, selbst wenn `theme.fonts` gesetzt ist.

### Eigene Seitentitel

Eine benutzerdefinierte [`.astro`-Seite](/docs/advanced/custom-pages) hat kein Frontmatter zum Auslesen, daher wird ihre generierte Karte betitelt, indem das letzte URL-Segment ihrer Route lesbar gemacht wird – aus `/getting-started` wird „Getting Started“, aus `/cli` aber „Cli“. Benenne diese Karten explizit mit `og.titles`, gekennzeichnet nach Route (`"/"` adressiert die Startseite, deren Karte sonst den Site-Titel trägt):

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

Einträge gelten nur für benutzerdefinierte Seiten – die Karte einer Inhaltsseite übernimmt ihre Überschrift immer aus dem Seitentitel, ändere diese also stattdessen im Frontmatter.

`seo.image` ist Frontmatter und deckt daher nur Markdown- und MDX-Inhalte ab. Um einer benutzerdefinierten [`.astro`-Seite](/docs/advanced/custom-pages) ein eigenes Social-Bild zu geben – etwa einer Marketing-Startseite oder Landingpage, und das ist auch der Weg, allein der Startseite ein maßgeschneidertes Teilen-Bild zu geben – übergib die Prop `ogImage` an `PageLayout`.

## RSS-Feeds

Blume erstellt einen RSS-Feed für jeden Inhaltstyp in `rss.types` – standardmäßig `blog` und `changelog` –, der Seiten enthält, ausgeliefert unter `/<type>/rss.xml`. Siehe [Feeds](/docs/content#feeds) zum Verfassen von Blog- und Changelog-Einträgen mit Datumsangaben.

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `enabled` | `true` | Feeds erzeugen. |
| `types` | `["blog", "changelog"]` | Inhaltstypen, die jeweils einen Feed erhalten. |
| `limit` | `50` | Maximale Anzahl Einträge pro Feed, neueste zuerst. |

Blume fügt `<link rel="alternate">`-Tags ein, damit Browser und Feed-Reader die Feeds automatisch finden.

## Strukturierte Daten

Blume gibt [schema.org](https://schema.org)-JSON-LD im `<head>` jeder Seite aus, damit Suchmaschinen deine Inhalte verstehen. Standardmäßig aktiviert:

```ts blume.config.ts lineNumbers
seo: {
  structuredData: true,
}
```

Jede Seite enthält:

- einen **WebSite**-Knoten für die Identität der Site,
- die Seite als **Artikel** – `BlogPosting` für Blogbeiträge, `TechArticle` für Changelog und Doku – mit ihrer Beschreibung und ihrem Veröffentlichungsdatum,
- eine **BreadcrumbList**, aufgebaut aus dem Navigationspfad.

URLs sind absolut, wenn `deployment.site` gesetzt ist. Seiten, die mit `seo.noindex` markiert sind, werden übersprungen.

### Identität der Site

Der WebSite-Knoten sagt, dass eine Site existiert; er sagt nicht, _was_ sie ist oder _wer_ sie betreibt – und genau dafür lesen KI-Agents JSON-LD, bevor sie dich empfehlen oder zitieren. Zwei optionale Blöcke füllen das aus, beide benötigen `deployment.site` (die Knoten tragen absolute Bezeichner):

```ts blume.config.ts lineNumbers
seo: {
  organization: {
    name: "Acme", // defaults to the site title
    email: "hello@acme.com",
    telephone: "+1 555 0100",
    address: { addressLocality: "Sydney", addressCountry: "AU" },
    logo: "/logo.svg",
    sameAs: ["https://github.com/acme", "https://x.com/acme"],
  },
  software: {
    license: "MIT",
    operatingSystem: "Node.js 22+",
    price: 0, // emitted as an Offer; 0 marks it free
    sameAs: ["https://www.npmjs.com/package/acme"],
  },
}
```

`organization` fügt jeder Seite einen **Organization**-Knoten hinzu – der WebSite-Knoten und die Artikel-Knoten führen ihn als `publisher` – mit E-Mail und Telefonnummer als `ContactPoint` (`contactType` ist standardmäßig `"customer support"`) und der Adresse als `PostalAddress`, den beiden Feldern, nach denen Prüfungen zur Unternehmensverifizierung suchen. `name` und `url` übernehmen standardmäßig die Werte der Site; ein wurzelrelatives `logo` wird wie jede Seiten-URL absolut gemacht.

`software` fügt der Startseite einen **SoftwareApplication**-Knoten hinzu: Name und Beschreibung des Produkts (ersatzweise die der Site), `applicationCategory` (Standard `"DeveloperApplication"`), Betriebssystem, Lizenz, ein `Offer`, wenn `price` gesetzt ist, und die Registry- oder Repository-URLs in `sameAs`. Übergib `software: true`, um alle Standardwerte zu übernehmen. Die Organisation wird, sofern konfiguriert, als dessen `publisher` geführt.

## Sitemap

Blume schreibt zur Build-Zeit eine `sitemap.xml` mit jeder indexierbaren Seite. Sie benötigt ein absolutes [`deployment.site`](/docs/deployment) und listet jede Seite auf, außer Entwürfen, versteckten und `noindex`-Seiten. Auf einer [versionierten](/docs/content/versioning) Site bleiben außerdem archivierte Seiten außen vor, deren Canonical auf ihre aktuelle Entsprechung zeigt – die aktuelle Seite ist die, die indexiert werden soll. Standardmäßig aktiviert:

```ts blume.config.ts lineNumbers
seo: {
  sitemap: true,
}
```

Liefere deine eigene `public/sitemap.xml` aus, um die Kontrolle zu übernehmen – Blume überschreibt niemals eine Datei, die du in `public/` ablegst.

## Robots

Blume schreibt eine `robots.txt`, die alle Crawler zulässt, deine [Content-Signale](#content-signals) deklariert und eine `Sitemap:`-Zeile hinzufügt, die auf die Sitemap verweist, sofern eine verfügbar ist. Standardmäßig aktiviert:

```ts blume.config.ts lineNumbers
seo: {
  robots: true,
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://docs.example.com/sitemap.xml
```

### Content-Signale

Die `Content-Signal`-Zeile – die sich etablierende Konvention zur Inhaltsnutzung – deklariert, wie KI-Crawler deine Doku weiterverwenden dürfen. Blume gibt sie **standardmäßig aus, mit jedem Signal auf `yes`**, passend zu seiner Haltung, dass Doku für Menschen und Agents gleichermaßen offen ist:

- `search` – klassische und KI-gestützte Suchindexierung
- `aiInput` – Grounding / RAG zum Antwortzeitpunkt
- `aiTrain` – Modelltraining

Schränke ein beliebiges Signal ein, indem du es auf `false` setzt; die von dir ausgelassenen bleiben auf `yes`:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: {
    aiTrain: false, // opt out of training, keep search + grounding
  },
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /
```

Setze `contentSignals: false`, um die Deklaration vollständig wegzulassen:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: false,
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.contentSignals?` | `boolean \| object` | - | Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually. |
| `contentSignals.search?` | `boolean` | - | Allow use for search indexing (search). Default true. |
| `contentSignals.aiInput?` | `boolean` | - | Allow use for AI grounding / RAG at answer time (ai-input). Default true. |
| `contentSignals.aiTrain?` | `boolean` | - | Allow use for AI model training (ai-train). Default true. |

Content-Signale drücken eine Präferenz aus, keine Zugriffskontrolle: Sie teilen wohlerzogenen Crawlern mit, wie du deine Inhalte genutzt sehen möchtest, und es liegt am Crawler, sie zu respektieren.

Liefere deine eigene `public/robots.txt` aus, um die Kontrolle zu übernehmen.

---

# Theming
Source: https://useblume.dev/de/docs/configuration/theming

Blumes Theme ist Token-gesteuert und funktioniert von Haus aus im hellen und dunklen Modus. Nutze so wenig oder so viel davon, wie du brauchst: ein paar Konfigurations-Tokens für die gängigen Fälle, eine `theme.css`, um beliebige Design-Tokens zu überschreiben, oder Tailwind-Utilities für eigene Komponenten.

## Konfigurations-Tokens

Die alltäglichen Stellschrauben findest du unter `theme` in deiner Konfiguration:

```ts blume.config.ts lineNumbers
theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}
```

### Akzentfarbe

Die Akzentfarbe färbt interaktive und hervorgehobene Elemente ein — Schrittmarkierungen, aktive Tabs, Badges, Karten-Hover und mehr. Verwende eine benannte Voreinstellung oder eine beliebige CSS-Farbe:

```ts blume.config.ts lineNumbers
theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}
```

Benannte Voreinstellungen: `blue` (Standard), `green`, `orange`, `pink`, `purple`, `red` und `teal`.

Ein String gilt für beide Farbmodi; übergib ein Objekt für [eine unterschiedliche Akzentfarbe je Modus](#dark-mode-colors).

### Eckenradius

`radius` legt die Eckenrundung fest, die Karten, Codeblöcke, Callouts und Eingabefelder gemeinsam nutzen — `none`, `sm`, `md` (Standard) oder `lg`.

### Farbmodus

`mode` legt das anfängliche Farbschema fest:

- **`system`** (Standard) — folgt der Betriebssystem-Einstellung der Leserin oder des Lesers
- **`light`** / **`dark`** — verwendet standardmäßig ein bestimmtes Schema

Ein Umschalter im Header erlaubt Lesenden jederzeit den Wechsel, und ihre Wahl wird über Besuche hinweg gespeichert. Der dunkle Modus wird über ein Attribut `data-theme="dark"` am `<html>`-Element angewendet.

### Schriften

`fonts` legt die Schriftarten für drei Rollen fest:

- **`display`** — Überschriften (`h1`–`h6`)
- **`body`** — Fließtext, UI und Prosa
- **`mono`** — Codeblöcke und Inline-Code

Überschriften bekommen ihre Display-Laufweite (`-0.05em`) direkt vom Theme. Egal, was du für `display` wählst — auch Textschriften wie der Inter-Standard — Überschriften wirken in großen Größen richtig gesetzt, ohne dass die Laufweite in der Schrift selbst stecken muss.

Für jede Rolle ist standardmäßig eine kuratierte Google-Schrift hinterlegt, damit Blume von Anfang an durchdacht aussieht:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}
```

Lege nur die Rollen fest, die du ändern möchtest — der Rest behält seine Standardwerte:

```ts blume.config.ts lineNumbers
theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}
```

Schriften werden **selbst gehostet**: Blume lädt sie zur Build-Zeit herunter und liefert sie von deiner eigenen Website aus, sodass es keine Laufzeitanfrage an Google und kein Layout-Shift gibt (Astro erzeugt automatisch Fallback-Schriften mit passenden Metriken).

Ein einfacher String ist ein Google-Fonts-Slug aus der folgenden kuratierten Auswahl:

| Kategorie | Slugs |
| --- | --- |
| Sans | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
| Serif | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4` |
| Mono | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono` |

#### Beliebige Schriftfamilie eines Anbieters

Du brauchst eine Familie, die nicht in der kuratierten Auswahl enthalten ist — etwa eine, die ein nicht-lateinisches Schriftsystem abdeckt? Übergib ein Objekt mit dem exakten Namen der Familie. Sie wird genauso selbst gehostet und optimiert:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}
```

- **`name`** — der Familienname exakt so, wie der Anbieter ihn führt.
- **`provider`** — woher die Familie stammt: `google` (Standard), `fontsource`, `bunny` oder `fontshare`.
- **`weights`** — die zu ladenden Schriftschnitte, als Zahlen oder als variabler Bereich wie `"100..900"`. Standard ist `[400, 500, 600, 700]`.
- **`subsets`** — die zu ladenden Zeichen-Subsets, mit den Namen des Anbieters (`latin`, `latin-ext`, `vietnamese`, `cyrillic`, `greek`, …). Standard ist `latin` plus alles, was deine konfigurierten Locales brauchen — siehe unten.
- **`fallback`** — der System-Stack, der während des Ladens der Schrift und für fehlende Glyphen angezeigt wird: `sans`, `serif` oder `mono`. Standard ist `mono` für die Mono-Rolle und andernfalls `sans`.

#### Subsets und Locales

Google, Bunny und Fontsource teilen jede Familie in Subsets je Schriftsystem auf, und nur die Subsets, die du lädst, bekommen eine `@font-face`. Blume leitet die Liste aus deinen [`i18n.locales`](/docs/content/i18n) ab: Eine Website mit vietnamesischen, polnischen, russischen oder griechischen Locales lädt `vietnamese`, `latin-ext`, `cyrillic` oder `greek` zusätzlich zu `latin`, sodass diakritische Zeichen und nicht-lateinische Buchstaben in deiner gewählten Schrift statt im System-Fallback erscheinen. Websites ohne `i18n`-Block oder mit ausschließlich Latin-1-Sprachen laden nur `latin`. Browser laden ein Subset erst herunter, wenn eine Seite dessen Zeichen verwendet, und Preloads folgen derselben Liste.

Setze `subsets` bei einer Familie, um die abgeleitete Liste zu überschreiben — etwa bei einer Website mit nur einer Locale, deren Inhalt trotzdem ein Schriftsystem braucht, das ihre Locale nicht nahelegt:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}
```

Kuratierte Slugs wie `inter` folgen der aus den Locales abgeleiteten Liste; verwende die Objektform, um auch für diese Familien Subsets festzulegen.

#### Lokale Schriftdateien

Für eine Schrift, die dir gehört (oder die kein Anbieter ausliefert), verweist du eine Rolle auf Schriftdateien in deinem Projekt. Jede Variante wird zu einer `@font-face`:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}
```

Pfade werden relativ zum Projektstammverzeichnis aufgelöst. `weight` und `style` (`normal`, `italic`, `oblique`) sind optional — wenn sie fehlen, liest Astro sie aus der Schriftdatei.

:::note
Wenn du `theme.fonts` explizit setzt, gestalten deine Display- und Body-Schriften automatisch auch die generierten [Open-Graph-Karten](/docs/configuration/seo#card-fonts), sodass geteilte Links zur Website passen. Familien von Anbietern außerhalb von Google werden dort übersprungen (der Karten-Renderer kann nur von Google Fonts laden); lokale Dateien funktionieren überall.
:::

Du möchtest zum System-Stack zurückkehren? Überschreibe die `--blume-font-*`-Tokens direkt in [`theme.css`](#themecss).

### Farben im dunklen Modus

`accent` und `background` folgen einer Regel: Ein String gilt für beide Farbmodi, und ein Objekt `{ light, dark }` legt jeden Modus einzeln fest:

```ts blume.config.ts lineNumbers
theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}
```

Jede Farbe akzeptiert eine benannte Voreinstellung oder eine beliebige CSS-Farbe. Bei `background` (und `backgroundImage`) kann jeder Schlüssel weggelassen werden, um nur einen Modus zu überschreiben — `background: { dark: "#0a0a0a" }` behält den standardmäßigen hellen Hintergrund bei.

### Aktionsfarbe

`action` ist eine sekundäre Akzentfarbe für primäre Handlungsaufforderungen und die `action`-Tailwind-Utilities (`bg-action`, `text-action`). Standardmäßig entspricht sie deiner `accent`-Farbe:

```ts blume.config.ts
theme: {
  action: "#ff0066",
}
```

### Hintergrundbild

Lege mit `backgroundImage` ein Hintergrundbild hinter deinen Inhalt — eine URL oder ein Pfad unterhalb von `public/`. Wie bei den Farben gilt ein String für beide Modi, und ein Objekt `{ light, dark }` legt das Bild je Modus fest:

```ts blume.config.ts lineNumbers
theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}
```

## theme.css

Lege eine `theme.css` im Stammverzeichnis deines Projekts ab, um beliebige Design-Tokens zu überschreiben. Sie ist die letzte Ebene der Kaskade und setzt sich damit gegenüber den Standardwerten und den Konfigurations-Tokens durch:

```css theme.css lineNumbers
:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}
```

Setze ein Token unter `:root` für den hellen Modus und unter `:root[data-theme="dark"]` für den dunklen Modus. Farb-Tokens haben eigene integrierte Dunkelwerte, die mit der höheren Spezifität des Dunkel-Selektors deklariert sind — eine Überschreibung von `--blume-accent`, `--blume-background` und Konsorten allein unter `:root` gilt daher nur für den hellen Modus. Deklariere zusätzlich den Dunkel-Block, wenn sich beide Modi ändern sollen.

`theme.css` wird in den Tailwind-Einstiegspunkt der Website eingebunden, sodass darin auch Tailwind-Direktiven funktionieren. Die für ein Monorepo entscheidende ist `@source`: Blume durchsucht dein Projekt nach Utility-Klassen, und eine Seite, die Komponenten aus einem benachbarten Workspace-Paket importiert, braucht auch dieses Paket im Scan. Verweise relativ zu `theme.css` darauf — die übliche Tailwind-Regel — und Blume übernimmt den Pfad in das generierte Stylesheet:

```css theme.css lineNumbers
@source "../../packages/ui/src";
```

### Design-Tokens

| Token                       | Steuert                                       |
| --------------------------- | --------------------------------------------- |
| `--blume-background`        | Seitenhintergrund                             |
| `--blume-foreground`        | Fließtext                                     |
| `--blume-muted`             | Dezente Flächen — Callouts, Tabellenköpfe     |
| `--blume-muted-foreground`  | Sekundärer Text                               |
| `--blume-border`            | Rahmen und Trennlinien                        |
| `--blume-accent`            | Akzentfarbe                                   |
| `--blume-accent-foreground` | Text und Icons auf einem Akzenthintergrund    |
| `--blume-action`            | Sekundäre Akzentfarbe (Standard: Akzentfarbe) |
| `--blume-code-background`   | Fläche des Codeblocks                         |
| `--blume-radius`            | Eckenradius                                   |
| `--blume-font-display`      | Überschriftenschrift                          |
| `--blume-font-body`         | Body-/UI-Schrift                              |
| `--blume-font-mono`         | Code-Schrift                                  |

Setze ein `--blume-font-*`-Token auf einen beliebigen Font-Stack, um eine Schrift außerhalb der kuratierten Liste zu verwenden oder auf den System-Stack zurückzufallen:

```css theme.css lineNumbers
:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

## Tailwind-Utilities

Blumes Theme ist intern mit Tailwind v4 gebaut, und die `.astro`-, `.tsx`- und `.jsx`-Dateien deines Projekts werden ebenfalls gescannt — du kannst eigene Komponenten und Seiten also mit Utility-Klassen gestalten, ganz ohne Tailwind-Setup. Jedes Token ist als Utility verfügbar, sodass deine Komponenten dem Theme automatisch folgen:

| Token                       | Utilities                  |
| --------------------------- | -------------------------- |
| `--blume-background`        | `bg-background`            |
| `--blume-foreground`        | `text-foreground`          |
| `--blume-muted`             | `bg-muted`                 |
| `--blume-muted-foreground`  | `text-muted-foreground`    |
| `--blume-border`            | `border-border`            |
| `--blume-accent`            | `bg-accent`, `text-accent` |
| `--blume-accent-foreground` | `text-accent-foreground`   |
| `--blume-action`            | `bg-action`, `text-action` |
| `--blume-radius`            | `rounded-blume`            |
| `--blume-font-display`      | `font-display`             |
| `--blume-font-body`         | `font-sans`                |
| `--blume-font-mono`         | `font-mono`                |

## Reihenfolge der Kaskade

Styles werden in drei Ebenen aufgelöst, von denen jede die vorherige überschreibt:

1. **Basis**

    Blumes Reset, Standard-Tokens und Komponenten-Styles.

2. **Konfigurations-Tokens**

    `--blume-accent`, `--blume-radius` und die `--blume-font-*`-Tokens aus
    `theme`.

3. **theme.css**

    Deine Token-Überschreibungen — das letzte Wort.

---

# Seiten
Source: https://useblume.dev/de/docs/content

Deine Dokumentation ist einfach ein Ordner voller Markdown- und MDX-Dateien. Blume macht aus jeder Datei eine Seite — Routing, Navigation und Metadaten werden aus dem Dateisystem abgeleitet, es gibt also kein Manifest, das synchron gehalten werden muss.

Inhalte liegen unter deinem **Content-Root** (standardmäßig `docs/`; änderbar über `content.root` in [`blume.config.ts`](/docs/configuration)).

## Markdown und MDX

Blume rendert zwei Arten von Dateien:

- **`.md`** — Markdown für reinen Fließtext: GFM, Frontmatter, typografische Satzzeichen sowie Hoch- und Tiefstellung.
- **`.mdx`** — alles, was `.md` bietet, plus [Komponenten](/docs/content/components) und die nur in MDX verfügbaren [Direktiven, Paketinstallationen und Mathematik](/docs/content/syntax).

Greif zu `.md`, wenn eine Seite nur aus Fließtext besteht, und zu `.mdx`, wenn sie Komponenten oder Direktiven braucht. Der Wechsel ist so einfach wie das Umbenennen der Datei.

## Dateien und Routen

Jede Datei wird anhand ihres Pfads unterhalb des Content-Roots auf eine Route abgebildet:

| Datei                     | Route             |
| ------------------------- | ----------------- |
| `docs/index.mdx`          | `/`               |
| `docs/quickstart.mdx`     | `/quickstart`     |
| `docs/guides/theming.mdx` | `/guides/theming` |
| `docs/guides/index.mdx`   | `/guides`         |

Verschachtelte Ordner werden zu verschachtelten Routen, und eine `index.mdx` in einem Ordner wird zur eigenen Seite dieses Ordners.

## Sortierung mit numerischen Präfixen

Stelle einer Datei oder einem Ordner eine Zahl voran, um die Reihenfolge in der Seitenleiste zu steuern. Das Präfix wird aus der URL entfernt, sodass du Seiten neu anordnen kannst, ohne Links zu zerstören:

```txt
01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation
```

Die Sortierung hat mehrere Ebenen — die vollständigen Vorrangregeln findest du unter [Navigation](/docs/content/navigation).

## Gruppenordner

Setze einen Ordnernamen in Klammern, um dessen Seiten in der Seitenleiste zu gruppieren, **ohne** ein URL-Segment hinzuzufügen:

```txt
docs/(internal)/security.mdx  ->  /security
```

Die Seiten teilen sich eine Seitenleisten-Gruppe „Internal“, behalten aber flache URLs ohne Klammern.

## Entwürfe

Markiere eine Seite als Entwurf, um sie aus Produktions-Builds herauszuhalten, sie aber weiterhin in `blume dev` ansehen zu können:

```yaml lineNumbers
---
title: Work in progress
draft: true
---
```

`blume build` überspringt Entwürfe; `blume dev` rendert sie, damit du offen daran arbeiten kannst.

## Inhaltstypen

Jede Seite hat einen **Typ**, festgelegt über das Frontmatter-Feld `type` (Standard `doc`). Typen ermöglichen es Blume, Gruppen von Seiten unterschiedlich zu behandeln — vor allem werden `blog`- und `changelog`-Seiten in [Feeds](#feeds) gesammelt.

```yaml lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---
```

Der Typ ist unabhängig davon, wo die Datei liegt, aber per Konvention gehören Blogbeiträge unter `blog/` und Changelog-Einträge unter `changelog/`. Beide erhalten automatisch einen RSS-Feed, und Changelog-Einträge werden zusätzlich in einer generierten [`/changelog`-Timeline](/docs/advanced/changelog) gesammelt. Wie du sie jeweils schreibst, erfährst du unter [Blog](/docs/advanced/blog) und [Changelog](/docs/advanced/changelog).

## Feeds

Blume erzeugt automatisch einen RSS-Feed für jeden Inhaltstyp, der in [`rss.types`](/docs/configuration/seo#rss-feeds) aufgeführt ist — standardmäßig `blog` und `changelog` — sofern er mindestens eine Seite enthält. Feeds werden unter `/<type>/rss.xml` ausgeliefert:

| Typ         | Feed                 |
| ----------- | -------------------- |
| `blog`      | `/blog/rss.xml`      |
| `changelog` | `/changelog/rss.xml` |

Gib jedem Eintrag ein `date`, damit die Einträge nach Aktualität sortiert werden und ein `pubDate` tragen. Ein YAML-Datum ohne Anführungszeichen ist in Ordnung — Blume normalisiert es:

```yaml lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---
```

Feeds benötigen eine absolute Website-URL, setze also [`deployment.site`](/docs/deployment). Blume fügt jeder Seite `<link rel="alternate">`-Tags hinzu, damit Browser und Feedreader sie automatisch finden. Wie du die jeweiligen Inhaltstypen schreibst, erfährst du unter [Blog](/docs/advanced/blog) und [Changelog](/docs/advanced/changelog).

## Auf dieser Seite

Jede Seite erhält automatisch ein Inhaltsverzeichnis, das aus ihren Überschriften erstellt wird. Auf breiten Bildschirmen sitzt es in einer haftenden Seitenleiste neben deinem Inhalt; auf schmaleren Bildschirmen klappt es in ein Panel **Auf dieser Seite** oberhalb der Seite zusammen. Beim Scrollen wird der Eintrag des Abschnitts hervorgehoben, den du gerade liest, sodass du auf einer langen Seite immer weißt, wo du dich befindest.

Blume wandelt jede Überschrift in einen Anker-Slug um, sodass jeder Eintrag direkt auf seinen Abschnitt verlinkt — und du kannst auf jede Überschrift per Deeplink verweisen, indem du ihren Slug an die URL anhängst (`.../my-page#getting-started`).

Das Inhaltsverzeichnis listet deine `##`- und `###`-Überschriften (H2 und H3) auf. Eine Seite ohne Überschriften auf dieser Ebene hat schlicht kein Inhaltsverzeichnis.

## Wie geht es weiter

**[Frontmatter](/docs/reference/frontmatter)**

Seiten-Metadaten: Titel, Beschreibung, Seitenleiste, SEO und Suche.

**[Syntax](/docs/content/syntax)**

Jede Markdown- und MDX-Funktion, die du schreiben kannst.

**[Komponenten](/docs/content/components)**

Die JSX-Komponenten, die in jeder MDX-Seite verfügbar sind.

**[Navigation](/docs/content/navigation)**

Gestalte Seitenleiste, Sortierung und Tabs.

**[Ordner-Meta](/docs/content/meta)**

Konfiguriere eine Seitenleisten-Gruppe mit einer `meta.ts`-Datei.

---

# Komponenten
Source: https://useblume.dev/de/docs/content/components

Blume liefert einen barrierefreien, themenfähigen Komponentensatz, der auf jeder `.mdx`-Seite **ohne Imports** verfügbar ist. Jede Komponente wird unten mit einer Live-Vorschau und ihrem Quellcode gezeigt. Die Komponenten sind Vanilla und React-frei; React wird nur aktiviert, wenn du deine eigene Island hinzufügst.

## Card and CardGroup

Karten verlinken mit Icon, Titel und kurzem Text auf ein Ziel. Gruppiere sie mit `CardGroup` zu einem responsiven Raster. Setze sie auf Landingpages, in Abschnittsübersichten und bei „nächsten Schritten“ ein – überall dort, wo du die Leserschaft weiterführst.

**[Quickstart](/docs/quickstart)**

Installiere Blume und veröffentliche deine erste Seite.

**[Components](/docs/content/components)**

Durchstöbere die Komponentenbibliothek.

```astro lineNumbers
<CardGroup cols={2}>
  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
    Install Blume and ship your first page.
  </Card>
  <Card title="Components" href="/docs/content/components" icon="folder">
    Browse the component library.
  </Card>
</CardGroup>
```

`Card` nimmt `title`, ein optionales `href` (weglassen für eine nicht klickbare Karte) und ein `icon` aus Blumes integriertem Icon-Set entgegen. `CardGroup` nimmt `cols` entgegen (Standard `2`).

## Steps

Eine nummerierte vertikale Abfolge für geordnete Anleitungen – Installationen, Einrichtungsabläufe und Tutorials, bei denen die Reihenfolge zählt. Jeder `Step` nimmt einen `title` entgegen.

1. **Install Blume**

    Füge das Paket zu deinem Projekt hinzu.

2. **Write a page**

    Lege eine `.mdx`-Datei in deinen Inhaltsordner.

3. **Ship it**

    Führe `blume build` aus und deploye `dist/`.

```astro lineNumbers
<Steps>
  <Step title="Install Blume">Add the package to your project.</Step>
  <Step title="Write a page">
    Drop an `.mdx` file into your content folder.
  </Step>
  <Step title="Ship it">Run `blume build` and deploy `dist/`.</Step>
</Steps>
```

## Tabs

Wechsle an Ort und Stelle zwischen gleichwertigen Inhalten – Sprachvarianten, betriebssystemspezifischen Befehlen oder alternativen Vorgehensweisen – ohne alles untereinander auf der Seite zu stapeln. Jeder `Tab` nimmt einen `title` entgegen.

**macOS**

Nutze Homebrew, um die Toolchain zu installieren.

**Windows**

Nutze winget, um die Toolchain zu installieren.

```astro lineNumbers
<Tabs>
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

Füge `inline` hinzu, um randlos zu rendern – eine Tab-Leiste auf einer Linie über die volle Breite, mit dem Inhalt, der darunter als Fließtext folgt – statt der umrandeten Box. Füge `param` hinzu, um den aktiven Tab statt mit dem Hash mit einem URL-Query-Parameter zu synchronisieren; das macht die Auswahl teilbar: Ein Link, der auf `?install=windows` endet, öffnet den Windows-Tab. Jede Gruppe synchronisiert sich mit ihrem eigenen `param`, sodass du mehrere unabhängige, direkt verlinkbare Gruppen auf einer Seite verwenden kannst.

Gruppen mit gleichnamigen Tabs wechseln gemeinsam – wähle in einer „macOS“, und jede Gruppe mit einem macOS-Tab zieht nach. Füge `syncKey` hinzu, um diese Synchronisierung einzugrenzen: Nur Gruppen mit demselben Schlüssel wechseln gemeinsam, sodass unabhängige Gruppen, die zufällig einen Tab-Titel teilen, eigenständig bleiben.

**macOS**

Nutze Homebrew, um die Toolchain zu installieren.

**Windows**

Nutze winget, um die Toolchain zu installieren.

```astro lineNumbers
<Tabs inline param="install">
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

## Badge

Ein kleines Inline-Label für Status oder Metadaten – Versionskennzeichen, „new“- oder „beta“-Markierungen, Stabilitätsstufen. Die `variant` stimmt die Farbe auf die Bedeutung ab.

### Default

Neutrale Metadaten ohne besondere Betonung.

<Badge>Stabil</Badge>

```astro
<Badge>Stable</Badge>
```

### Accent

Zieht mit deiner Theme-Akzentfarbe den Blick auf sich – gut für „neu“- oder Hervorhebungs-Markierungen.

<Badge variant="accent">Neu</Badge>

```astro
<Badge variant="accent">New</Badge>
```

### Success

Ein positiver oder bestandener Zustand.

<Badge variant="success">Bestanden</Badge>

```astro
<Badge variant="success">Passing</Badge>
```

### Warning

Etwas, das mit Vorsicht zu verwenden ist, etwa ein experimentelles Feature.

<Badge variant="warning">Beta</Badge>

```astro
<Badge variant="warning">Beta</Badge>
```

### Danger

Ein negativer oder brechender Zustand, etwa eine Veraltung.

<Badge variant="danger">Veraltet</Badge>

```astro
<Badge variant="danger">Deprecated</Badge>
```

## Icon

Rendere ein Icon anhand seines Namens – dieselbe `icon`-Prop treibt Karten, Schritte, Tabs und Sidebar-Einträge an. Die Namen stammen von [Lucide](https://lucide.dev/icons), in Kleinschreibung und Kebab-Case (`rocket`, `gauge`, `book-open`).

<Icon icon="rocket" size={20} />

```astro
<Icon icon="rocket" size={20} />
```

Blume unterstützt ausschließlich Lucide – ein reiner Name wird gegen Lucide aufgelöst, und du kannst einem Namen zur Symmetrie mit anderen Icon-Eingaben `lucide:` voranstellen (`lucide:rocket`). `size` legt die Pixelgröße fest (Standard `16`) und `color` färbt es ein (jede CSS-Farbe; Standard ist `currentColor`). Übergib anstelle eines Namens einen rohen `<svg>`-String, eine Bild-URL oder einen lokalen Bildpfad, um eigene Grafiken zu rendern, und ergänze ein `label`, um es assistiven Technologien zugänglich zu machen – ohne ein solches gilt das Icon als dekorativ.

Icons werden zur Build-Zeit aufgelöst und als SVG ohne JavaScript eingebettet – zur Laufzeit wird nichts nachgeladen.

## File tree

Veranschauliche ein Projekt- oder Ordnerlayout. Umschließe eine gewöhnliche Markdown-Liste, und Blume stylt sie als Baum – praktisch, um Strukturen in Einrichtungs- und Konfigurationsanleitungen zu erklären.

<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>

```astro lineNumbers
<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>
```

## Accordion

Staple zusammengehörige Aufklappbereiche in einem einzigen umrandeten Container mit Trennlinien dazwischen – FAQs, optionale Schritte oder lange Beispiele. Jedes Kind ist ein `AccordionItem` (`title`, optional `icon`, `description`, `defaultOpen`). Für einen einzelnen eigenständigen Aufklappbereich verwende [Expandable](#expandable).

<Accordion>
  <AccordionItem title="Does it support MDX?">
    Ja – jede Seite kann `.md` oder `.mdx` sein.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Ja, über Tailwind-v4-Tokens und dein eigenes `theme.css`.
  </AccordionItem>
</Accordion>

```astro lineNumbers
<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>
```

## Expandable

Ein leichtgewichtiger Inline-Aufklappbereich für verschachtelte Details – etwa die Unterattribute eines Feldes oder eine optionale Randbemerkung. `title` beschriftet den Umschalter (Standard „Show more“); setze `defaultOpen`, damit er aufgeklappt startet.

<Expandable title="Show advanced options">
  Diese Einstellungen sind optional und müssen selten geändert werden.
</Expandable>

```astro
<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>
```

## Columns

Ordne Karten oder Blöcke in einem responsiven Raster aus gleich breiten Spalten an, das auf Mobilgeräten umbricht. `Columns` nimmt `cols` entgegen; umschließe jede Zelle mit einem `Column`.

<Columns cols={2}>
  <Column>
    **Fast**

    Gebaut auf Astro und Vite.
  </Column>
  <Column>
    **Themeable**

    Tailwind-v4-Design-Tokens.
  </Column>
</Columns>

```astro lineNumbers
<Columns cols={2}>
  <Column>
    <Card title="Fast" icon="rocket">
      Built on Astro and Vite.
    </Card>
  </Column>
  <Column>
    <Card title="Themeable" icon="sun">
      Tailwind v4 design tokens.
    </Card>
  </Column>
</Columns>
```

## CodeGroup

Fasse mehrere Codeblöcke zu einem einzigen Tab-Umschalter zusammen – ein Tab pro Sprache oder Datei. Die Tab-Beschriftung ist der Titel des jeweiligen Blocks (der Text nach der Sprache), und der Kopier-Button der Gruppe sitzt in der Tab-Leiste und kopiert den gerade angezeigten Block. Füge `dropdown` hinzu, um statt über eine Tab-Leiste über ein Menü zu wechseln.

<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>

````astro
<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>
````

## Frame

Umschließe ein Bild oder eine beliebige Grafik mit einem zentrierten, umrandeten Rahmen samt optionaler `caption` (wird als Markdown gerendert) und `hint`.

<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <svg
    width="160"
    height="72"
    viewBox="0 0 160 72"
    role="img"
    aria-label="Sample frame"
  >
    <rect width="160" height="72" rx="8" fill="#3b82f6" />
  </svg>
</Frame>

```astro lineNumbers
<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <img src="/screenshot.png" alt="Product screenshot" />
</Frame>
```

## YouTube

Bette ein YouTube-Video in einen responsiven, datenschutzfreundlichen (`youtube-nocookie.com`) 16:9-Rahmen ein, der kein Client-JavaScript ausliefert. Übergib eine Video-`id` oder eine vollständige `url` sowie optional einen `title` (für Barrierefreiheit) und eine `start`-Zeit in Sekunden.

[Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

```astro lineNumbers
<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
<YouTube url="https://youtu.be/aqz-KE-bpKQ" start={30} />
```

## Color

Zeige Farbfelder mit kopierbaren Hex-Werten – nützlich, um eine Palette oder Markenfarben zu dokumentieren. Verwende `variant="compact"` für eine Liste von Farbfeldern oder `variant="table"` mit `Color.Row`, um sie zu gruppieren. Jedes `Color.Item` nimmt einen `name` und einen `value` entgegen (einen Hex-String oder `{ light, dark }` für themenabhängige Farben).

<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>

```astro lineNumbers
<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>
```

## Tree

Rendere eine hierarchische Datei-/Ordnerstruktur mit ausklappbaren Ordnern. (Für eine schnelle, listenbasierte Variante siehe [File tree](#file-tree); `Tree` bietet Kontrolle pro Ordner.) Verwende `Tree.Folder` (`name`, optional `defaultOpen`, `openable`) und `Tree.File` (`name`).

<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>

```astro lineNumbers
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>
```

## Panel

Ein betitelter Container für ergänzende, beiseitegestellte Inhalte. `title` ist optional.

<Panel title="Good to know">
  Panels nehmen ergänzende Details auf, ohne den Lesefluss zu unterbrechen.
</Panel>

```astro
<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>
```

## Tooltip

Zeige beim Überfahren eines Inline-Begriffs eine Definition oder einen Hinweis. `tip` ist der Hover-Text; ergänze optional eine `headline` sowie ein `cta` + `href` für einen weiterführenden Link.

Fahre über den Begriff <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip>, um mehr zu erfahren.

```astro
Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term.
```

## Tile

Eine klickbare Vorschau, die mit einer Grafik – einem Icon oder Bild – über Titel und Beschreibung eröffnet. Gut für Galerien und Showcases. Nimmt `title`, `description` und `href` entgegen; das Kind ist die Grafik.

<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>

```astro
<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>
```

## Prompt

Eine einzelne Zeile mit einer Beschriftung und einem Kopier-Button. Die `description` (Markdown) ist die sichtbare Beschriftung; der Body ist der Prompt selbst – ausgeblendet und beim Drücken des Buttons **Copy prompt** in die Zwischenablage kopiert. `actions` steuert die Buttons (z. B. `["copy", "cursor"]`).

<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Schreibe eine Referenzdokumentation für den Endpunkt POST /v1/pets.
</Prompt>

```astro
<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>
```

## Visibility

Zeige oder verbirg Inhalte je nach Zielgruppe. `for="web"` rendert nur auf der Website; `for="agents"` zielt auf das an Agenten gerichtete Markdown, das KI-Agenten lesen (`llms-full.txt` und die `.md`-Spiegelung jeder Seite).

```astro
<Visibility for="web">Shown on the site only.</Visibility>
<Visibility for="agents">Shown only in the generated Markdown.</Visibility>
```

## Type tables

Tabellen zur Dokumentation der Eigenschaften eines Objekts – seiner Props, Typen und Standardwerte. Schreibe die Zeilen mit `TypeTable` von Hand oder erzeuge sie direkt aus einem TypeScript-Interface oder Typ-Alias mit `AutoTypeTable`.

### Type table

Ein **Prop / Type**-Raster, in dem sich jede Zeile ausklappen lässt, um ihre Beschreibung und Details zu zeigen. Übergib eine `type`-Map mit den Eigenschaftsnamen als Schlüssel; jeder Eintrag nimmt einen `type` entgegen, dazu optional eine `description`, ein `default`, ein `required`-Flag, `typeDescription` und `typeDescriptionLink`. Optionale Props (`required` nicht gesetzt) zeigen ein `?` nach dem Namen.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | - | The button's visible label. |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | Visual style. |
| `disabled?` | `boolean` | - | |

```astro lineNumbers
<TypeTable
  type={{
    label: {
      type: "string",
      required: true,
      description: "The button's visible label.",
    },
    variant: {
      type: '"primary" | "ghost"',
      default: '"primary"',
      description: "Visual style.",
    },
    disabled: { type: "boolean" },
  }}
/>
```

### Auto type table

Erzeuge eine Typtabelle aus einem TypeScript-Typ, damit die Dokumentation mit dem Quellcode synchron bleibt. Richte `AutoTypeTable` mit `path` (relativ zum Projektstammverzeichnis aufgelöst) und einem Typ-`name` auf eine Datei aus. Beschreibungen stammen aus JSDoc-Kommentaren, Standardwerte aus `@default`-Tags, und optionale Eigenschaften (`?`) werden entsprechend markiert.

```astro
<AutoTypeTable path="./src/button.ts" name="ButtonProps" />
```

Du kannst den Typ statt eines `path` auch inline über `type` übergeben – praktisch für kleine Beispiele:

<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>

```astro lineNumbers
<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>
```

## GitHub info

Eine Karte, die auf ein GitHub-Repository verlinkt und dessen aktuelle Stern- und Fork-Zahlen anzeigt. Die Zahlen werden zur Build-Zeit abgerufen – kein Client-JavaScript – und die Karte wird auch dann gerendert, wenn die API nicht erreichbar ist. Übergib `owner` und `repo` oder lass beides weg, um das Repository aus deiner `blume.config` zu verwenden. Setze eine Umgebungsvariable `GITHUB_TOKEN`, um das API-Ratenlimit anzuheben.

Die Karte liest die Instanz aus [`github.host`](/docs/configuration#github-enterprise), sodass auf einer Enterprise-gehosteten Website auch explizite `owner`/`repo` diese Instanz adressieren. Übergib `host`, um eine einzelne Karte woanders hinzurichten – etwa auf ein öffentliches Projekt von einer Enterprise-Website aus; die REST-Basis wird davon genauso abgeleitet wie von `github.host`.

<GithubInfo owner="haydenbleasel" repo="blume" />

```astro lineNumbers
<!-- Uses the repo from blume.config -->
<GithubInfo />

<!-- Or point it at any repository -->
<GithubInfo owner="haydenbleasel" repo="blume" />

<!-- Or at a repository on another instance -->
<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
```

## Component

`Component` rendert eine Beispieldatei aus dem Verzeichnis `examples/` deines Projekts als Live-Vorschau neben ihrem hervorgehobenen Quellcode, in Tabs. Richte es mit `path` auf eine Datei aus – ihr Ort unterhalb von `examples/`, ohne Erweiterung (aus `examples/counter.tsx` wird also `path="counter"`). React-, Vue-, Svelte- und Astro-Beispiele werden alle unterstützt; Framework-Beispiele hydrieren, Astro-Beispiele werden statisch gerendert. So bleiben Vorschau und Code aus einer einzigen Datei synchron.

Die Vorschau rendert in einem isolierten Rahmen, den die Doku-Styles nie erreichen – keine Fließtext-Abstände, Typografie oder Theme-Elemente sickern in deine Komponente. Der Rahmen erhält Tailwind (Preflight + Utilities, die aus deinem Projekt und deinem Beispielverzeichnis gescannt werden), Blumes Design-Tokens, sodass Klassen wie `bg-background` standardmäßig der Website-Palette folgen, und er folgt der Hell-/Dunkel-Umschaltung der Website in Echtzeit. Der Bereich passt seine Größe an das gerenderte Beispiel an – und verfolgt das weiter, falls das Beispiel nach dem Laden wächst oder schrumpft – wobei die Tabs „Preview“ und „Code“ dieselbe Höhe teilen, sodass das Umschalten die Seite nie verschiebt.

Um Vorschauen mit deinem eigenen Designsystem zu gestalten – etwa mit shadcn-Variablen – richte `examples.css` auf ein Stylesheet aus. Es wird nach Blumes Standardwerten in jeden Vorschaurahmen eingefügt, sodass deine Tokens gewinnen. Verwende darin kein `@import "tailwindcss"`; der Rahmen stellt Tailwind bereits bereit. Sowohl `.dark` als auch `[data-theme="dark"]` funktionieren für Dark-Mode-Overrides:

```ts
// blume.config.ts
export default defineConfig({
  examples: { css: "examples/theme.css" },
});
```

```css
/* examples/theme.css */
:root {
  --primary: oklch(0.6 0.2 260);
}

.dark {
  --primary: oklch(0.75 0.15 260);
}

@theme inline {
  --color-primary: var(--primary);
}
```

Auch das Verzeichnis ist konfigurierbar – setze `source` (oder nutze die Kurzschreibweise als String, `examples: "..."`), wenn deine Beispiele anderswo liegen (z. B. in einem Registry-Layout). `path` ist immer relativ dazu:

```ts
// blume.config.ts
export default defineConfig({
  examples: "registry/files-sdk",
});
```

```astro
<!-- registry/files-sdk/file-list/basic.tsx -->
<Component path="file-list/basic" />
```

`examples` kann auch ein Glob sein (alles mit `*`, `?`, `[]`, `{}` oder `!`). Es werden nur passende Dateien erfasst, und `path` ist relativ zum statischen Präfix des Globs (dem Teil vor dem ersten Platzhalter). Das ist für eine Registry gedacht, die den Quellcode jeder Komponente neben ihrem Beispiel ablegt – richte es nur auf die Beispiele aus, damit die Quelldateien, die keinen Default-Export für eine Vorschau haben, nicht mit eingesammelt werden:

```ts
// blume.config.ts
export default defineConfig({
  // registry/files-sdk/file-list/file-list.tsx — source, left out
  // registry/files-sdk/file-list/examples/basic.tsx — discovered
  examples: "registry/files-sdk/**/examples/*",
});
```

```astro
<!-- keyed relative to registry/files-sdk -->
<Component path="file-list/examples/basic" />
```

In einem Monorepo liegen die Komponenten, die deine Beispiele importieren, meist in einem benachbarten Workspace-Paket. Tailwinds `@source` scannt Dateien, keine Importe: Blume scannt dein Projekt und das `examples`-Verzeichnis (wohin auch immer `source` zeigt, auch außerhalb des Projekts), sodass eine Klasse, die nur innerhalb dieses benachbarten Pakets verwendet wird, erst erzeugt wird, wenn du das Paket zum Scan hinzufügst. Das machst du mit einer `@source`-Direktive in `examples.css` (für die Vorschaurahmen) oder `theme.css` (für die Website), relativ zu der Datei geschrieben, in der sie steht – die übliche Tailwind-Regel – und Blume übernimmt sie in das erzeugte Stylesheet:

```css
/* examples/theme.css */
@source "../../../packages/ui/src";
```

```tsx
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <button
      className="rounded-blume border-border bg-background text-foreground hover:bg-muted border px-4 py-2 text-sm font-medium transition-colors"
      onClick={() => setCount((value) => value + 1)}
      type="button"
    >
      Clicked {count} {count === 1 ? "time" : "times"}
    </button>
  );
};

export default Counter;
```

```astro
<!-- examples/counter.tsx -->
<Component path="counter" />
```

Ein Astro-Beispiel rendert live und ohne Client-JavaScript:

```astro
---
interface Props {
  title?: string;
}

const { title = "Hello from Astro" } = Astro.props;
---

<div class="rounded-blume border border-border bg-muted/30 px-5 py-4">
  <p class="m-0 font-semibold text-foreground text-sm">{title}</p>
  <p class="m-0 mt-1 text-muted-foreground text-sm">
    A static, server-rendered example — no client JavaScript ships.
  </p>
</div>
```

## CodeBlock

`CodeBlock` hebt einen Code-String mit demselben Shiki-Theme und denselben Transformern hervor wie deine eingezäunten Codeblöcke – einschließlich des Hell-/Dunkel-Wechsels – für Stellen, an die kein Code-Fence passt, etwa eine Landingpage oder eine eigene Komponente. Übergib `code` und ein `lang`:

<CodeBlock
  lang="ts"
  code={`export const greet = (name: string): string =>
  \`Hello, \${name}!\`;`}
/>

```astro
---
import CodeBlock from "blume/components/content/CodeBlock.astro";
---

<CodeBlock lang="ts" code={source} />
```

Um selbst zu einem HTML-String hervorzuheben (z. B. innerhalb deiner eigenen Komponente), importiere den zugrunde liegenden Helfer aus `blume/markdown`:

```ts
import { highlightCode } from "blume/markdown";

const html = await highlightCode(source, "ts");
```

## Diff

`Diff` rendert einen Diff im Git-Stil, hervorgehoben mit demselben Shiki-Theme wie deine Codeblöcke und vollständig zur Build-Zeit erzeugt – kein Client-JavaScript. Übergib zwei Inline-Strings (`old` / `new`), zwei Dateipfade (`before` / `after`) oder einen Unified Patch (einen Inline-`patch`-String oder eine `src`-Datei).

<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>

```astro
<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>
```

Vergleiche zwei Dateien in deinem Projekt, relativ zu dessen Stammverzeichnis:

<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />

```astro
<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />
```

Oder rendere einen Unified Patch – entweder aus einer Datei mit `src` oder inline mit `patch`:

<Diff src="diffs/greet.patch" />

```astro
<Diff src="diffs/greet.patch" />
```

```astro
<Diff
  patch={`--- a/greet.ts
+++ b/greet.ts
@@ -1,3 +1,4 @@
-export function greet(name) {
-  return "Hi, " + name;
+export function greet(name: string): string {
+  const greeting = "Hi, " + name + "!";
+  return greeting;
 }`}
/>
```

---

# Internationalisierung
Source: https://useblume.dev/de/docs/content/i18n

Blume stellt ein Projekt in vielen Sprachen bereit. Lege übersetzte Dateien an der richtigen Stelle ab, und Blume verdrahtet Routing, den Sprachumschalter, die Navigation pro Locale und SEO für dich – es gibt keine separate Routing-Ebene zu pflegen. Es ist optional: Ohne einen `i18n`-Block bleibt deine Website genau wie zuvor einsprachig. Es lässt sich außerdem mit [Versionierung](/docs/content/versioning) kombinieren – ein eingefrorener Snapshot behält seine Übersetzungen, und der Locale-Fallback funktioniert innerhalb jeder Version.

## Aktivieren

Füge einen `i18n`-Block hinzu, der deine Locales auflistet und angibt, welche die Standard-Locale ist:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}
```

Jede Locale hat einen `code` (wird in URLs verwendet), ein `label` (wird im Sprachumschalter angezeigt) und ein optionales `dir` für Rechts-nach-links-Schriften (standardmäßig `"ltr"`). Ein optionales `style` gibt [`blume translate`](/docs/reference/translate) freie Hinweise für die Locale – Register, Dialekt, Terminologie, z. B. `"Brazilian Portuguese, informal você"` – sodass die Wahl von der allerersten Übersetzung an festgelegt ist, statt vom Agenten entschieden zu werden.

## Übersetzte Inhalte organisieren

Die Standard-Locale liegt im Stammverzeichnis deiner Inhalte. Jede weitere Locale ist ein Ordner der obersten Ebene, benannt nach ihrem `code`, der die Standardstruktur spiegelt:

```txt
docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar
```

| Datei                           | Route                   |
| ------------------------------- | ----------------------- |
| `docs/index.mdx`                | `/`                     |
| `docs/guides/quickstart.mdx`    | `/guides/quickstart`    |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

Du übersetzt nur die Dateien, die du möchtest – alles andere greift automatisch auf einen Fallback zurück (siehe [Fallbacks](#fallbacks)).

### Dateinamen-Suffixe

Du möchtest Übersetzungen lieber neben dem Original behalten? Setze `parser: "dot"` und benenne Dateien mit einem Locale-Suffix, statt Ordner zu verwenden:

```txt
docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)
```

Gut geeignet für spärliche Übersetzungen – lege die wenigen übersetzten Seiten daneben ab, ohne den gesamten Baum zu spiegeln.

### Gemeinsame Dateien

Für Inhalte, die in jeder Sprache gleich sind – ein Changelog, eine Statusseite – füge einen `$`-Marker hinzu, damit eine Datei alle Locales ohne Duplikate bedient:

```txt
docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

Eine locale-spezifische `meta.ts` überschreibt die gemeinsame für diese Sprache weiterhin.

## URLs der Standard-Locale

Standardmäßig hat die Standard-Locale kein URL-Präfix (`/`, `/guides/quickstart`), während andere Locales ein Präfix erhalten (`/fr/…`). So bleiben die URLs deiner Hauptsprache sauber. Um jeder Locale ein Präfix zu geben, einschließlich der Standard-Locale:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## Navigation pro Locale

Jede Sprache erhält ihre eigene Seitenleiste, aufgebaut aus den Dateien dieser Locale – so können Übersetzungen in Struktur, Reihenfolge oder Beschriftungen abweichen. Auch [`meta.ts`](/docs/content/meta)-Dateien von Ordnern werden pro Locale aufgelöst: Lege unter dem Standard-Parser `dir` eine `meta.ts` in `fr/guides/` ab, um die französische Gruppe unabhängig zu sortieren. Unter dem `dot`-Parser liegen Übersetzungen neben den Originalen, sodass die `meta.ts` eines Ordners für jede Locale gilt. Alles andere zur [Navigation](/docs/content/navigation) funktioniert genauso, pro Sprache.

Header-Tabs werden konfiguriert und nicht aus dem Inhalt abgeleitet, daher werden ihre Beschriftungen in `blume.config.ts` lokalisiert: Ein Tab-`label` akzeptiert neben der einfachen String-Form auch eine Zuordnung pro Locale (`{ en: "Docs", fr: "Documentation" }`) und greift für Locales, die du nicht ausgefüllt hast, auf den Eintrag der Standard-Locale zurück. Siehe [Tabs](/docs/content/navigation#tabs).

## Fallbacks

Wenn eine Seite noch nicht übersetzt ist, rendert Blume den Inhalt der Fallback-Locale unter der lokalisierten URL – so funktioniert der Link, die Seite wird vollständig vorgerendert, und Suchmaschinen landen nicht in einer Sackgasse. Der Fallback ist standardmäßig deine `defaultLocale`:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}
```

Fallback-Seiten werden vom Suchindex ausgeschlossen und in `hreflang` nicht als echte Übersetzungen ausgewiesen, sodass unübersetzte Inhalte nicht um das Ranking konkurrieren. Sie erscheinen weiterhin in der Seitenleiste dieser Locale, sodass die Navigation vollständig bleibt – eine Leserin oder ein Leser erreicht jede Seite in jeder Sprache.

:::tip
Beginne damit, deine wichtigsten Seiten zu übersetzen – die Startseite, den Schnellstart und die wichtigsten Anleitungen – und lass den Rest auf den Fallback zurückgreifen. Du kannst Übersetzungen mit der Zeit ergänzen, ohne Links zu beschädigen.
:::

## Übersetzen mit einem Agenten

Du musst die Locales nicht von Hand ausfüllen. [`blume translate`](/docs/reference/translate) findet jede Seite, die in einer Locale fehlt oder veraltet ist, und übersetzt sie mit einer lokalen Agenten-CLI ([Claude Code](https://claude.com/claude-code) oder [Codex](https://developers.openai.com/codex/cli)):

```bash
blume translate --claude
```

Blume validiert die Struktur jedes Ergebnisses – Frontmatter, Code-Fences, Links – und schreibt die Dateien selbst; der Agent übersetzt nur Text. Ein eingecheckter Ledger (`blume.translations.json`) verfolgt, aus welcher Quellrevision jede Übersetzung stammt, sodass erneute Läufe nur ändern, was sich geändert hat, und von Hand geschriebene Übersetzungen unverändert übernommen und nie überschrieben werden. In der CI schlägt `blume translate --check` fehl, wenn eine Quellseite ihren Übersetzungen vorausgeeilt ist.

## Der Sprachumschalter

Wenn i18n aktiviert ist, erscheint automatisch ein Sprachumschalter im Header, generiert aus deinen `locales`. Für jede Seite verlinkt er die passende Übersetzung in jeder Sprache; wo eine Übersetzung fehlt, verlinkt er die Fallback-Seite und kennzeichnet sie als nicht übersetzt. Es gibt nichts zu konfigurieren.

## Übersetzte Benutzeroberfläche

Blume liefert integrierte Übersetzungen für seine eigene Oberfläche mit – „Auf dieser Seite“, „Suchen“, „Auf GitHub bearbeiten“ und den Rest – sodass eine Locale mit integriertem Paket von Haus aus eine übersetzte Oberfläche erhält. **Du übersetzt nur deine Inhalte.**

Pakete gibt es für über 30 Sprachen – Arabisch, Bengalisch, Bulgarisch, Katalanisch, Chinesisch (vereinfacht und traditionell), Kroatisch, Tschechisch, Dänisch, Niederländisch, Finnisch, Französisch, Deutsch, Griechisch, Hebräisch, Hindi, Ungarisch, Indonesisch, Italienisch, Japanisch, Koreanisch, Norwegisch, Persisch, Polnisch, Portugiesisch (und brasilianisches Portugiesisch), Rumänisch, Russisch, Serbisch, Slowakisch, Spanisch, Schwedisch, Thailändisch, Türkisch, Ukrainisch und Vietnamesisch. Sie werden von der Community gepflegt – öffne einen PR, um eine Locale hinzuzufügen oder eine Übersetzung zu verbessern.

Fehlende oder nicht mitgelieferte Strings greifen auf die Standard-Locale zurück, dann auf Englisch. Um einen String zu überschreiben oder deine eigene Sprache bereitzustellen, setze `i18n.ui`, aufgeschlüsselt nach Locale:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}
```

## SEO

Lokalisiertes SEO wird für dich erledigt – keine Metadaten pro Seite zu schreiben:

- `<html lang>` und `dir` werden anhand der aktiven Locale gesetzt.
- `hreflang`-Alternates verlinken jede echte Übersetzung einer Seite, plus ein `x-default`, das auf die Standard-Locale zeigt.
- Kanonische URLs sind locale-korrekt, und JSON-LD führt `inLanguage`.

Setze [`deployment.site`](/docs/deployment), damit diese als absolute URLs ausgegeben werden können.

## Suche

Die Suche ist auf die aktive Sprache beschränkt: Auf einer `/fr/…`-Seite liefert der Dialog französische Ergebnisse, mit einem Umschalter **Alle Sprachen**, um auf einmal über alle Locales zu suchen. Der Standardindex (Orama) und der FlexSearch-Index filtern im Browser; gehostete Anbieter führen eine `locale`-Facette auf jedem Datensatz.

## Rechts-nach-links

Setze `dir: "rtl"` auf einer Locale, und Blume spiegelt die gesamte Oberfläche – die Seitenleiste, den Header, das Inhaltsverzeichnis, die Seitennavigation, die Suche und die Menüs – und setzt `<html dir>` entsprechend. Zwei Dinge bleiben bewusst von links nach rechts: **Code-Blöcke** (Code liest sich in jeder Sprache LTR) und **Fallback-Inhalte** – eine unübersetzte Seite behält die Richtung der Sprache, in der sie tatsächlich geschrieben ist, sodass unter einer RTL-Locale angezeigtes Englisch weiterhin korrekt lesbar ist, während die umgebende Oberfläche gespiegelt wird.

## Wie geht es weiter

**[Navigation](/docs/content/navigation)**

Gestalte Seitenleiste, Reihenfolge und Tabs für jede Locale.

**[SEO](/docs/configuration/seo)**

Sitemaps, Open Graph und strukturierte Daten.

---

# Includes
Source: https://useblume.dev/de/docs/content/includes

Schreibe ein Snippet einmal und füge es in jede beliebige Seite ein. Eine `<include>`-Anweisung in einer eigenen Zeile bettet zur Build-Zeit eine andere Datei ein, so als wäre deren Inhalt direkt dort geschrieben worden — Überschriften werden Teil des Inhaltsverzeichnisses der Seite, Text wird von der Suche indexiert, und der Inhalt erscheint im `.md`-Spiegel der Seite sowie in llms-full.txt.

```mdx
<include>./_snippets/prerequisites.mdx</include>
```

Der Pfad wird relativ zur einbindenden Datei aufgelöst. Pfade, die mit `/` beginnen, werden ab deinem Content-Root aufgelöst, sodass tief verschachtelte Seiten gemeinsame Snippets ohne `../../..`-Ketten referenzieren können:

```mdx
<include>/_snippets/prerequisites.mdx</include>
```

Die Syntax entspricht der Include-Syntax von Fumadocs, sodass migrierte Inhalte unverändert funktionieren.

Hier siehst du es live — der folgende Hinweis stammt aus einem gemeinsam genutzten Snippet:

:::tip
Dieser Hinweis lebt in `_snippets/include-demo.mdx` — er wird hier gerendert, weil die Seite ihn per `<include>`-Anweisung einfügt.
:::

## Partials

Jede Datei, deren Name (oder Ordner) mit einem Unterstrich beginnt, ist standardmäßig von Routing, Navigation, Suche und Sitemaps ausgeschlossen — diese Konvention ist der natürliche Ort für gemeinsam genutzte Snippets:

```text
docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx
```

Ein Partial ist eine ganz normale Markdown- oder MDX-Datei. Sein Frontmatter wird beim Einfügen entfernt (das Frontmatter der einbindenden Seite gewinnt), und alles andere — Hinweise, Code-Blöcke, Komponenten, Mathematik — wird genau so gerendert wie inline. Partials können andere Partials einbinden; ein zirkulärer Include wird als Fehler gemeldet.

Relative Bildreferenzen innerhalb eines Partials funktionieren weiterhin: Sie werden auf die einbindende Seite umgerechnet, sodass ein neben dem Partial liegendes `![diagram](./diagram.png)` überall aufgelöst wird, wo das Partial eingefügt wird.

Wenn du ein Partial bearbeitest, während `blume dev` läuft, wird jede Seite neu geladen, die es einbindet.

## Code-Dateien einbinden

Ein Ziel, das nicht `.md`/`.mdx` ist, wird als umschlossener Code-Block eingebettet, wobei die Sprache aus der Dateiendung abgeleitet wird. Verwende `lang`, um die Sprache zu überschreiben (oder um eine Markdown-Datei als Quelltext anzuzeigen, statt sie einzufügen), und `meta`, um einen Fence-Meta-String wie einen Titel zu übergeben:

```mdx
<include>./examples/config.ts</include>

<include lang="ts" meta='title="blume.config.ts"'>
  ../blume.config.ts
</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>
```

## Regeln und Diagnosen

Include-Anweisungen müssen in einer eigenen Zeile stehen — sie sind block-level, nicht inline. Anweisungen innerhalb von umschlossenen Code-Blöcken bleiben unangetastet, sodass du die Syntax selbst dokumentieren kannst (so wie diese Seite es tut).

Ziele müssen innerhalb deines Content-Roots liegen: Eine Datei außerhalb davon würde in Versions-Snapshots und ausgeworfenen Projekten stillschweigend fehlen, deshalb meldet `blume` `BLUME_INCLUDE_OUTSIDE_ROOT`, statt sie einzufügen. Ein nicht existierendes Ziel ergibt `BLUME_INCLUDE_NOT_FOUND`, und eine Schleife von Includes ergibt `BLUME_INCLUDE_CYCLE` — alle drei lassen `blume build` fehlschlagen (übergib `--no-strict`, um trotzdem zu bauen) und tauchen in `blume validate` auf.

Defekte Links innerhalb eines Partials werden der Partial-Datei zugeordnet, nicht den Seiten, die sie einfügen — so behebst du sie dort, wo sie leben.

:::note
Partials werden über alle Sprachen hinweg gemeinsam genutzt und nicht von `blume translate` übersetzt — halte Partials sprachneutral (Code, Tabellen, Diagramme), oder erstelle Partials pro Sprache und binde sie aus den Seiten der jeweiligen Sprache ein.
:::

---

# Islands
Source: https://useblume.dev/de/docs/content/islands

Blume rendert deine Dokumentation standardmäßig als statisches HTML mit **null JavaScript**. Wenn du etwas Interaktives brauchst — eine Live-Demo, ein Diagramm, einen Playground — fügst du eine **Island** hinzu: eine Framework-Komponente, die JS nur für sich selbst ausliefert, und nur auf den Seiten, die sie verwenden.

## Die `islands/`-Konvention

Lege eine Komponente in einen `islands/`-Ordner im Stammverzeichnis deines Projekts. Ihr Dateiname wird zu einer Komponente, die du in **jeder** `.mdx`-Seite verwenden kannst, ganz ohne Import:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Clicked {count}</button>;
}
```

```mdx page.mdx
Here's a live counter: <Counter />
```

Der Dateiname ist der Komponentenname, er **muss also ein PascalCase-Bezeichner sein** — nur Buchstaben, Ziffern und Unterstriche (`Counter.tsx` → `<Counter />`). Kleingeschriebene Dateinamen, Namen mit Bindestrichen/Punkten/Leerzeichen (wie `Time-Picker.tsx`) und zwei Islands, die zum selben Namen aufgelöst werden, werden mit einer Build-Warnung übersprungen.

:::note
Islands sind für **interaktive** UI gedacht. Für eine statische Komponente, die du seitenübergreifend wiederverwendest (ein gestalteter Hinweis, eine Preistabelle), nutze stattdessen ein [MDX-Override](/docs/configuration/customization) — es liefert kein JavaScript aus.
:::

## Islands in `components.ts` registrieren

Wenn du Islands lieber bei deinen übrigen Komponenten aufbewahren möchtest — oder ihnen einen anderen Namen als der Datei geben willst — registriere sie mit `defineComponents`. Die Gruppe `islands` verhält sich genau wie der `islands/`-Ordner: Jeder Eintrag steht in jeder MDX-Seite zur Verfügung und wird hydriert (standardmäßig mit `client: "visible"`).

```ts components.ts
import { defineComponents } from "blume";
import Counter from "./widgets/Counter.tsx";

export default defineComponents({
  islands: {
    Counter, // <Counter /> in any MDX page, hydrated
  },
});
```

Referenziere die Komponente per Import oder über einen Pfad-String und lege mit der Deskriptor-Form einen Hydrierungsmodus pro Island fest:

```ts components.ts
export default defineComponents({
  islands: {
    Chart: { component: "./widgets/Chart.tsx", client: "only" },
  },
});
```

## Hydrierung

Standardmäßig nutzt eine Island `client:visible`: Sie hydriert, sobald die lesende Person sie in den sichtbaren Bereich scrollt, sodass auch eine Seite voller Islands sofort lädt. Entscheide dich mit einem `export const client` in der Island-Datei für eine andere Strategie:

```tsx islands/Chart.tsx lineNumbers
// Skip server rendering entirely — for components that touch the DOM/window.
export const client = "only";

export default function Chart() {
  /* ... */
}
```

| `client`-Wert | Hydriert | Verwende es für |
| --- | --- | --- |
| `"visible"` _(Standard)_ | Beim Scrollen in den sichtbaren Bereich | Die meisten Islands |
| `"load"` | Sofort beim Laden der Seite | UI oberhalb der Falz, die sofort da sein muss |
| `"idle"` | Wenn der Haupt-Thread untätig ist | Nicht dringende Interaktivität |
| `"only"` | Nur clientseitig, nie serverseitig gerendert | Bibliotheken, die `window`/`document` brauchen (Diagramme, Editoren) |

## Frameworks

**React funktioniert sofort** — Blume aktiviert es automatisch, sobald dein Projekt eine `.tsx`/`.jsx`-Island enthält.

Der [React Compiler](https://react.dev/learn/react-compiler) ist standardmäßig aktiv, sobald React aktiviert ist, sodass deine Islands automatisch memoisiert werden — handgeschriebene `useMemo`/`useCallback` sind nicht nötig. Er wird mit Blume ausgeliefert; es gibt nichts zu installieren. Deaktivieren kannst du ihn in `blume.config.ts`:

```ts blume.config.ts
export default defineConfig({
  react: { compiler: false },
});
```

**Vue und Svelte** werden ebenfalls unterstützt; installiere die passende Astro-Integration, und Blume verdrahtet den Renderer, sobald es eine `.vue`- oder `.svelte`-Island sieht:

```bash
# Vue
npm install @astrojs/vue vue

# Svelte
npm install @astrojs/svelte svelte
```

```vue islands/Toggle.vue lineNumbers
<script setup>
import { ref } from "vue";
const on = ref(false);
</script>

<template>
  <button @click="on = !on">{{ on ? "On" : "Off" }}</button>
</template>
```

Props, die du in MDX übergibst (`<Counter start={5} />`), werden an die Komponente weitergereicht, und Kindelemente (`<Counter>label</Counter>`) kommen als Standard-Slot an.

:::tip
Islands hydrieren auf dem Client, daher muss alles, was du als Prop übergibst, serialisierbar sein — Strings, Zahlen, einfache Objekte, keine Funktionen.
:::

## Hooks

Islands hydrieren eigenständig, es gibt also keinen React-Context, durch den sich Projektdaten durchreichen ließen. Stattdessen liest `blume/hooks` einen kleinen Snapshot, den das Layout in die Seite serialisiert — kein Prop-Drilling nötig:

```tsx islands/PageInfo.tsx lineNumbers
import { useBlume, usePage } from "blume/hooks";

export default function PageInfo() {
  const blume = useBlume();
  const page = usePage();
  if (!(blume && page)) {
    return null;
  }
  return (
    <p>
      You're reading <strong>{page.title}</strong> on {blume.config.title}.
    </p>
  );
}
```

| Hook | Gibt zurück |
| --- | --- |
| `useBlume()` | `{ config, navigation }` für die Website, oder `null` vor dem Mount |
| `usePage()` | `{ route, title }` für die aktuelle Seite, oder `null` vor dem Mount |
| `useSearch()` | `{ search, results, loading }` — den konfigurierten Suchanbieter abfragen |
| `useAskAI()` | `{ ask, messages, loading, reset }` — vom Ask-AI-Endpunkt streamen |

`useBlume()` und `usePage()` geben `null` zurück, bis die Island mountet (damit Server und Client denselben ersten Frame rendern) — sichere das ab. Der Snapshot wird nur auf Seiten ausgegeben, die React ausliefern, eine vollständig statische Website zahlt also nichts dafür.

Auf [benutzerdefinierten Seiten](/docs/advanced/custom-pages), die mit `PageLayout` gebaut sind, übergib `clientData`, damit Islands dort darauf zugreifen können:

```astro
<PageLayout
  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
  {/* …other props… */}
/>
```

---

# Ordner-Meta
Source: https://useblume.dev/de/docs/content/meta

Jeder Ordner in deinem Content-Baum wird zu einer Sidebar-Gruppe. Lege eine `meta.ts` neben die Seiten, um zu steuern, wie diese Gruppe aussieht und wie ihre Kinder sortiert werden. Das ist völlig optional: ohne eine solche Datei ist die Bezeichnung der Gruppe der lesbar aufbereitete Ordnername, und ihre Seiten werden [nach Index, numerischem Präfix und dann alphabetisch](/docs/content/navigation#ordering) sortiert.

## Meta definieren

Exportiere ein `defineMeta`-Objekt für eine vollständig typisierte Konfiguration. Lege die Datei im Wurzelverzeichnis des Ordners ab, den sie konfiguriert — `guides/meta.ts` konfiguriert die Gruppe **Guides**:

```ts meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});
```

Jedes Feld ist optional — setze nur das, was du überschreiben möchtest.

## Felder

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `title` | `string` | Die Bezeichnung der Gruppe. Standardmäßig der lesbar aufbereitete Ordnername. |
| `icon` | `string` | Icon, das neben der Bezeichnung angezeigt wird. |
| `order` | `number` | Position unter gleichrangigen Gruppen und Seiten. Niedrigere Zahlen werden zuerst einsortiert. |
| `collapsed` | `boolean` | Legt im [Anzeigemodus `group`](/docs/content/navigation#display-modes) fest, ob die Gruppe eingeklappt startet. |
| `display` | `"flat" \| "group" \| "page"` | Darstellungsmodus für diese Gruppe; überschreibt das globale [`navigation.sidebar.display`](/docs/content/navigation#display-modes). |
| `pages` | `string[]` | Explizite Reihenfolge der Kinder der Gruppe, nach Slug. |

Das `pages`-Array listet die Kinder nach Slug auf — dem Ordner- oder Dateinamen ohne numerisches Präfix und ohne Klammern (aus `01-quickstart.mdx` wird also `"quickstart"`). Kinder, die du weglässt, erscheinen trotzdem, und zwar nach den aufgeführten.

Wie Gruppen dargestellt werden — als flache Überschriften, aufklappbare Bereiche oder Drill-in-Panels — richtet sich standardmäßig nach dem sidebarweiten `navigation.sidebar.display`; setze hier `display`, um das nur für diese Gruppe zu überschreiben. Die `index`-Seite eines Ordners kann es zudem im Frontmatter setzen, was Vorrang vor `meta.ts` hat — siehe [Overrides pro Gruppe](/docs/content/navigation#per-group-overrides).

## Berechnetes Meta

Da `meta.ts` ein echtes Modul ist, kannst du das Meta berechnen — übergib statt eines Objekts eine Funktion (synchron oder `async`), um es beim Scan aufzubauen. Praktisch, um Seiten anhand einer externen Quelle zu sortieren:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));
```

## Reihenfolge innerhalb einer Gruppe

Das `pages`-Array legt die Reihenfolge der Kinder einer Gruppe fest. Alles, was es auslässt, fällt auf das `sidebar.order` im Frontmatter der jeweiligen Seite zurück und danach auf das Dateisystem (zuerst eine `index`-Seite, dann numerische Präfixe, dann alphabetisch). Die vollständige Sidebar-Rangfolge — einschließlich einer expliziten Sidebar-Konfiguration — findest du unter [Navigation › Reihenfolge](/docs/content/navigation#ordering).

Um Seiten zu gruppieren, _ohne_ ein URL-Segment hinzuzufügen, brauchst du überhaupt keine `meta.ts`: verwende einen geklammerten Ordnernamen — siehe [Seiten › Gruppenordner](/docs/content#group-folders).

## Internationalisierung

Unter [i18n](/docs/content/i18n) wird Ordner-Meta pro Locale aufgelöst: lege eine `meta.ts` unter `fr/guides/` ab, um die französische Gruppe unabhängig zu sortieren.

Für Ordner-Meta, das in jeder Sprache identisch ist, füge eine `$`-Markierung hinzu, damit eine Datei ohne Duplizierung alle Locales bedient:

```txt
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

Eine locale-spezifische `meta.ts` überschreibt die gemeinsame `meta.$.ts` für diese Sprache weiterhin.

## Wie geht es weiter

**[Navigation](/docs/content/navigation)**

Wie Sidebar, Breadcrumbs und Tabs aufgebaut werden.

**[Frontmatter](/docs/reference/frontmatter)**

Metadaten pro Seite, einschließlich der `sidebar`-Overrides.

---

# Navigation
Source: https://useblume.dev/de/docs/content/navigation

Blume erstellt deine Seitenleiste aus dem Dateisystem und lässt dich sie dann so weit verfeinern, wie du möchtest – Seite für Seite, Ordner für Ordner oder mit einer einzigen expliziten Konfiguration. Breadcrumbs, Zurück-/Weiter-Links und die Gliederung auf der Seite ergeben sich alle aus demselben Modell, ganz ohne Verkabelung.

## Die generierte Seitenleiste

Standardmäßig spiegelt die Seitenleiste deinen Inhaltsbaum wider:

- Ordner werden zu **Gruppen**, Dateien werden zu **Seiten**
- Die Beschriftung einer Seite ist ihr Frontmatter-`title`; die Beschriftung einer Gruppe ist der lesbar gemachte Ordnername
- Einträge werden nach [numerischem Präfix](/docs/content) sortiert, dann alphabetisch, und die `index`-Seite eines Ordners steht an erster Stelle

Für viele Websites reicht das bereits – alles Weitere ist optional.

## Seitenbeschriftung, Symbol und Badge

Passe im Frontmatter unter `sidebar` an, wie eine einzelne Seite in der Seitenleiste erscheint:

```yaml lineNumbers
sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group
```

Das vollständige Seitenschema findest du unter [Frontmatter](/docs/reference/frontmatter).

## Ordnergruppen

Jeder Ordner wird zu einer Gruppe in der Seitenleiste. Lege eine [`meta.ts`](/docs/content/meta) neben die Seiten, um Titel, Symbol und Reihenfolge der Gruppe sowie die Reihenfolge ihrer untergeordneten Einträge festzulegen:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

Unter [Ordner-Meta](/docs/content/meta) findest du alle Felder sowie Informationen zur Berechnung von Meta-Daten während des Scans.

Das `meta.title` eines Ordners und das Frontmatter-`title` seiner eigenen `index`-Seite werden unabhängig voneinander aufgelöst – übersetzt du unter i18n das eine und vergisst das andere, entsteht eine korrekte Seitenleiste mit einem veralteten `<title>` bzw. einer veralteten Überschrift auf der Landing-Page selbst. Blume meldet eine `BLUME_NAV_INDEX_TITLE_MISMATCH`-Warnung, wenn beide voneinander abweichen. Nicht übersetzte Seiten, die aus der Fallback-Sprache ergänzt werden, sind davon ausgenommen – ihr Titel gehört zur Fallback-Sprache, und die Lösung besteht darin, die Seite zu übersetzen, nicht ihr Frontmatter zu bearbeiten.

Um Seiten zu gruppieren, _ohne_ ein URL-Segment hinzuzufügen, verwende einen in Klammern gesetzten Ordnernamen – siehe [Seiten](/docs/content#group-folders).

## Anzeigemodi

`navigation.sidebar.display` legt fest, wie jede Gruppe in der Seitenleiste dargestellt wird:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`** (Standard) – eine nicht einklappbare Überschrift mit den darunter aufgelisteten Seiten. Seiten, die zu keiner Gruppe gehören, stehen immer zuerst, oberhalb der Gruppenabschnitte, damit sie nicht für untergeordnete Einträge einer Gruppe gehalten werden.
- **`group`** – ein einklappbares `<details>`-Element pro Gruppe. Gruppen sind standardmäßig zunächst eingeklappt; eine Gruppe, welche die aktuelle Seite enthält, ist immer aufgeklappt, sodass nur der Abschnitt geöffnet ist, in dem du dich befindest. Setze `collapsed: false` im [Ordner-Meta](/docs/content/meta), um eine Gruppe unabhängig davon offen zu erzwingen.
- **`page`** – jede Gruppe ist eine einzelne Zeile, die beim Anklicken die Seitenleiste in ein Unterpanel schiebt, das nur die Einträge dieser Gruppe zeigt, mit einem Zurück-Pfeil oben. Das Panel ist routen-bewusst, sodass beim direkten Aufruf einer Seite innerhalb der Gruppe sofort dorthin geöffnet wird.

:::tip
Der `page`-Modus hält tiefe Abschnitte aufgeräumt – greif darauf zurück, wenn Gruppen viele untergeordnete Einträge haben und du lieber in sie hineinnavigieren möchtest, als an ihnen vorbeizuscrollen.
:::

### Überschreibungen pro Gruppe

Jede generierte Gruppe kann sich vom globalen Modus abmelden – ganz ohne explizite Seitenleiste. Setze `display` in der [`meta.ts`](/docs/content/meta) des Ordners oder – wenn der Ordner eine `index`-Seite hat – unter `sidebar` im Frontmatter dieser Seite, und nur diese eine Gruppe ändert sich:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

Der effektive Modus einer generierten Gruppe wird nach absteigender Priorität aufgelöst:

1. `sidebar.display` im Frontmatter der eigenen `index`-Seite der Gruppe
2. `display` in der `meta.ts` des Ordners
3. Das globale `navigation.sidebar.display`
4. Der Blume-Standard (`flat`)

Das `display` einer Gruppe gilt nur für diese Gruppe – verschachtelte Untergruppen lösen ihren eigenen Wert über dieselbe Kette auf. Eine Gruppe im `page`-Modus mit einer Index-Seite navigiert weiterhin in ihr Unterpanel: Die Index-Seite wird als erster Eintrag des Panels aufgeführt, und beim Aufruf ihrer URL öffnet sich das Panel direkt.

`sidebar.display` bedeutet an allen anderen Stellen nichts – auf einer Nicht-Index-Seite, auf der eigenen `index`-Seite des Inhalts-Roots (der Root ist keine Gruppe; verwende `navigation.sidebar.display`) oder auf jeder Seite, wenn eine [explizite Seitenleiste](#explicit-sidebar) konfiguriert ist (deren Einträge bestimmen den Modus jeder Gruppe) –, daher meldet Blume eine `BLUME_SIDEBAR_DISPLAY_IGNORED`-Warnung, statt es stillschweigend zu verwerfen. `collapsed` bleibt spezifisch für den `group`-Modus; es ist wirkungslos, wenn eine Gruppe zu `flat` oder `page` aufgelöst wird.

Eine Gruppe in einer [expliziten Seitenleiste](#explicit-sidebar) überschreibt den globalen Modus mit einem eigenen `display`, genau wie zuvor.

## Reihenfolge

Wenn die Seitenleiste generiert wird, wird die Reihenfolge nach absteigender Priorität aufgelöst:

1. **Konfigurierte Seitenleiste**

    Eine explizite `navigation.sidebar` ersetzt den generierten Baum
    vollständig.

2. **Ordner-Meta**

    Das `pages`-Array in `meta.ts` bestimmt die Reihenfolge einer Gruppe.

3. **Frontmatter**

    `sidebar.order` auf einer Seite.

4. **Dateisystem**

    Zuerst eine `index`-Seite, dann numerische Präfixe, dann alphabetisch nach
    Beschriftung.

Zwei gleichrangige Einträge mit derselben expliziten oder numerischen Reihenfolge werden untereinander alphabetisch sortiert – Blume meldet eine `BLUME_DUPLICATE_SIDEBAR_ORDER`-Warnung, damit der Gleichstand nicht unbemerkt bleibt.

## Ausgeblendete Seiten

Blende eine Seite aus der Seitenleiste – und aus der Zurück-/Weiter-Navigation – aus, während sie weiterhin gebaut und über ihre URL erreichbar bleibt:

```yaml
sidebar:
  hidden: true
```

## Tabs

Stelle Abschnitte der obersten Ebene als Tabs im Header dar – nützlich, um eine große Website in eigenständige Bereiche zu unterteilen, etwa Adapter, eine API und KI-Leitfäden. Ein Tab wird hervorgehoben, wenn die aktuelle Route unter seinen `path` fällt:

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

Eine aktivierte [OpenAPI- oder AsyncAPI-Referenz](/docs/advanced/api-reference) wird unter ihrer Route eingebunden, fügt aber nicht von sich aus einen Tab hinzu – richte einen Tab auf diese Route, um sie im Header sichtbar zu machen (und, beim nativen Renderer, um ihre Operations-Seitenleiste einzugrenzen), mit einer Beschriftung deiner Wahl:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

Der `path` eines Tabs ist sein Abschnittspräfix und dient zugleich als Linkziel. Ein Abschnitt, dessen `path` keine eigene Seite ist – ein Ordner ohne `index.mdx` –, würde auf einen 404 verweisen, daher greift der Tab stattdessen auf die erste Seite im Abschnitt zurück. Setze `href`, wenn er woanders landen soll:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

Das ist wichtig für Routen, die nicht Teil des Inhaltsbaums sind, da der Fallback sie nicht sehen kann: der generierte [Changelog](/docs/advanced/changelog)-Index oder eine [benutzerdefinierte Seite](/docs/advanced/custom-pages), die du unter `pages/` hinzugefügt hast. Ohne `href` landet ein `/changelog`-Tab auf dem neuesten Eintrag statt auf dem Index. Tabs, die kein `href` setzen, sind nicht betroffen.

Auf einer [i18n](/docs/content/i18n)-Website kann die `label` eines Tabs (und die eines Dropdown-Eintrags) statt einer Zeichenkette eine Zuordnung pro Sprache sein – der Eintrag der aktiven Sprache gewinnt, danach der der Standardsprache:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}
```

Tabs **grenzen außerdem die Seitenleiste ein**: Wenn die aktuelle Route unter den `path` eines Tabs fällt, zeigt die Seitenleiste nur die Seiten dieses Abschnitts – `/adapters/*` listet also die Adapter und sonst nichts. Der Ordner am `path` eines Tabs wird zum Abschnitt, sodass dafür über die Tabs hinaus keine zusätzliche Konfiguration nötig ist; strukturiere deine Inhalte in einen Ordner pro Tab und richte jeden Tab darauf aus.

Auf einer Route, die unter keinem Tab liegt (oder unter einem Tab, dessen `path` `/` ist), zeigt die Seitenleiste die Seiten, die _nicht_ zu einem Tab gehören – der Ordner jedes Tabs wird darin ausgeblendet, da dieser Abschnitt bereits einen eigenen Tab im Header hat. Eine Root-Landing-Page listet also deine losen Seiten der obersten Ebene, während die in Abschnitte gegliederten Inhalte hinter ihrem Tab bleiben – analog zu den Root-Ordnern von Fumadocs. Hat eine Route auf diese Weise keine eigenen Seiten anzuzeigen, wird stattdessen der vollständige Baum gezeigt, damit die Seitenleiste nie leer bleibt.

## Selektoren

Zum Wechseln zwischen ganzen Partitionen einer Website – einem Produkt, einer Version oder einer beliebigen gruppierten Menge von Zielen – füge einen `selector` hinzu. Jeder wird als Dropdown im Header dargestellt und zeigt die Option, deren `path` zur aktuellen Route passt:

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

Jeder Eintrag nimmt ein `label`, einen `path` sowie optional `icon`, `description` und `tag` entgegen. `kind` (`dropdown`, `product`, `version` oder `language`) ist ein Hinweis darauf, wie der Selektor verwendet wird; alle stellen dasselbe Dropdown dar.

Ist [Versionierung](/docs/content/versioning) konfiguriert, stellt Blume automatisch einen Versions-Selektor dar – deklarierst du hier einen eigenen `kind: "version"`-Selektor, ersetzt er den automatischen, sodass selbstgebaute Setups weiterhin funktionieren.

## Hervorgehobene Links

Hefte Links an den oberen Rand der Seitenleiste, über alle Abschnitte – ein Blog, ein Changelog, eine Kontakt- oder Supportseite, die immer nur einen Klick entfernt sein sollte. Anders als der generierte Baum sind hervorgehobene Links **nicht nach Tab eingegrenzt**: Sie erscheinen auf jeder Route und bei jedem Breakpoint.

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

Jeder Link nimmt ein `label`, ein `href` und optional ein `icon` entgegen (ein Name eines [eingebauten Symbols](/docs/content/components#icon), ein Bildpfad bzw. eine Bild-URL oder ein Inline-SVG – wie überall sonst auch). Ein `href` kann überallhin verweisen: Eine externe URL öffnet sich in einem neuen Tab, während eine interne Route (`/contact`) zur Build-Zeit gegen deine Seiten geprüft wird und dich warnt, wenn nichts übereinstimmt.

## Explizite Seitenleiste

Für volle Kontrolle listest du explizite Einträge in `navigation.sidebar` auf – ein bloßes Array ist eine Kurzform für `sidebar.items`, und die Objektform kombiniert sie mit einem globalen [`display`](#display-modes). Sind Einträge gesetzt, verwendet Blume sie unverändert und überspringt die Generierung aus dem Dateisystem:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}
```

Jeder Eintrag ist eine Seitenroute (eine Zeichenkette), eine Gruppe (`label` + `items`) oder ein Link (`label` + `href`). Gruppen können verschachtelt werden, den globalen [`display`-Modus](#display-modes) überschreiben und `collapsed` starten.

## Header-Aktionen

`navigation.actions` platziert schlichte Links im Header, links neben den Symbol-Buttons, und `navigation.cta` ist der eine gefüllte Button:

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

`cta` ist mit Absicht Singular – ein Doku-Header hat Platz für genau eine Sache, zu der Lesende aufgefordert werden, und eine Reihe von Buttons fordert zu gar nichts auf. Sekundäre Links gehören in `actions` – oder in [`featured`](#featured-links), wenn sie stattdessen bei der Seitenleiste sitzen sollen.

Ein `http(s)`- oder protokollrelatives href öffnet sich in einem neuen Tab; eine Route bleibt im Tab und wird – wie ein `featured`-Link – zur Build-Zeit gegen deine Seiten geprüft. Eine Seite, die von einer anderen App auf demselben Host ausgeliefert wird (etwa `/signup` auf dem Produkt), solltest du daher als absolute URL schreiben. `actions` werden unterhalb des `sm`-Breakpoints ausgeblendet, wo der Header nur noch Platz für das Logo und den Navigations-Umschalter hat. `cta` wird dort ebenfalls ausgeblendet – außer auf einer Seite ohne Navigations-Umschalter, etwa einer Landing-Page mit `PageLayout` ohne Tabs, wo er bleibt, da ihn auf einem Smartphone sonst nichts sichtbar machen kann.

## Repository-Link

Wenn du [`github`](/docs/configuration) in deiner Konfiguration setzt, zeigt Blume ein GitHub-Symbol im Header – neben dem Theme-Umschalter –, das auf dein Repository verlinkt. Es ist standardmäßig aktiviert; blende es mit `navigation.repo` aus:

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // hide the header GitHub link (default: true)
}
```

Der Link erscheint nur, wenn `github` konfiguriert ist, sodass Projekte ohne Repository so oder so nicht betroffen sind.

`repo` nimmt außerdem eine absolute URL entgegen, die das Zeichen im Header auf einen beliebigen Ort auf GitHub verweisen lässt:

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

Das ist für ein Projekt gedacht, dessen Doku-Repository privat ist. `github` steuert den Bearbeiten-Link pro Seite, das Zeichen im Header und das Repository im [Agenten-Manifest](/docs/configuration/ai) gemeinsam, sodass ein solches Projekt `github` ungesetzt lassen muss – und eine URL sorgt dafür, dass trotzdem ein Zeichen angezeigt wird, das auf etwas Öffentliches verweist. Das Symbol bleibt das GitHub-Zeichen, ein Link auf einen anderen Host gehört daher in [`actions`](#header-actions).

## Breadcrumbs und Seitennavigation

Diese ergeben sich kostenlos aus dem Seitenleistenbaum – ohne Konfiguration:

- **Breadcrumbs** zeigen die übergeordnete Gruppe der aktuellen Seite über dem Titel.
- **Zurück- und Weiter-Links** am Fuß jeder Seite folgen der Reihenfolge in der Seitenleiste und überspringen ausgeblendete Seiten.

## Auf dieser Seite

Aus den `##`- und `###`-Überschriften jeder Seite wird automatisch eine Gliederung in der rechten Spalte erzeugt, damit lange Seiten überschaubar bleiben. Auf schmaleren Bildschirmen, wo die rechte Spalte ausgeblendet ist, klappt sie zu einem „Auf dieser Seite“-Dropdown über dem Inhalt zusammen.

## Seitenaktionen

Unter dem Inhaltsverzeichnis zeigt jede Seite eine Reihe von Schnellaktionen:

- **Auf GitHub bearbeiten** – verlinkt direkt auf die Quelldatei. Erscheint, sobald du [`github`](/docs/configuration) in deiner Konfiguration setzt.
- **Nach oben scrollen** – kehrt sanft an den Anfang langer Seiten zurück.
- **Feedback geben** – öffnet ein vorausgefülltes GitHub-Issue mit optionaler Reaktion und Notiz (benötigt ebenfalls `github`).

Andere übergeben die Seite an KI-Tools – **Als Markdown kopieren** und **Im Chat öffnen** – beschrieben unter [KI](/docs/configuration/ai#copy-as-markdown).

Mit aktiviertem [`export`](/docs/configuration/export) ermöglicht eine **Export**-Aktion Lesenden zusätzlich, die Seite als PDF oder EPUB herunterzuladen.

---

# Inhaltsquellen
Source: https://useblume.dev/de/docs/content/sources

Standardmäßig liest Blume einen Ordner mit `.md`/`.mdx`-Dateien. **Inhaltsquellen** ermöglichen es dir, Seiten von woanders zu beziehen – aus einem entfernten Repository, einem CMS oder einem beliebigen eigenen Backend – und mehrere Quellen zu einer einzigen Website zu kombinieren. Quellen werden zur Build-Zeit gelesen; Blume bleibt static-first.

## Die Voreinstellung

Ohne Konfiguration durchsucht Blume dein Inhaltsverzeichnis (standardmäßig `docs`) als eine implizite Dateisystemquelle. Die Optionen `content.root`/`include`/`exclude` auf oberster Ebene funktionieren weiterhin genau wie zuvor – es muss nichts geändert werden.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: { root: "docs" },
});
```

## Mehrere Quellen

Füge ein `content.sources`-Array hinzu, um Quellen zusammenzustellen. Jeder Eintrag erhält über ein optionales `prefix` einen eigenen Namensraum, sodass seine Routen unter `/<prefix>/…` liegen. Wenn `sources` vorhanden ist, ersetzt es die implizite Voreinstellung – nimm daher einen `filesystem`-Eintrag für deine lokale Dokumentation auf.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      // Local docs at the site root
      { type: "filesystem", root: "docs" },

      // Remote MDX from a GitHub repo, mounted under /sdk
      {
        type: "mdx-remote",
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      },
    ],
  },
});
```

Wenn zwei Quellen dieselbe Route auflösen, meldet Blume den Build-Fehler `BLUME_DUPLICATE_ROUTE` – gib jeder Quelle ein eigenes `prefix`.

## Obsidian

Die eingebaute Quelle `obsidian` liest einen [Obsidian](https://obsidian.md)-Vault direkt an Ort und Stelle. Es gibt keinen Exportschritt, und es wird nichts in dein Repository generiert: Der Vault bleibt die Quelle der Wahrheit, und Blume überführt Obsidians Dialekt beim Laden nach Markdown.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "obsidian",
        prefix: "notes",
        vault: "vault",
        // Vault folder names to skip at any depth, on top of dot-folders
        exclude: ["Templates", "Daily"],
      },
    ],
  },
});
```

`[[Wikilinks]]` werden zu Route-Links, die – so wie Obsidian Notizen adressiert – über den Notiznamen im gesamten Vault statt über einen Pfad aufgelöst werden. Eigener Linktext (`[[Note|label]]`), Überschriften-Anker (`[[Note#Install]]`), vollständige Pfade (`[[folder/Note]]` und `[[folder/Note.md]]`), die Teilpfade, die Obsidians Standardeinstellung „Kürzester Pfad, wenn möglich“ schreibt (`[[guides/Note]]`), und die Form `[[Note\|label]]`, die Obsidian innerhalb einer Tabellenzelle schreibt, funktionieren alle; und eine Notiz, die `slug` in ihrem Frontmatter setzt, wird unter der Route verlinkt, die dieser Slug veröffentlicht. Wenn zwei Notizen denselben Namen haben, gewinnt eine Notiz, deren vollständiger Vault-Pfad genau diesem Namen entspricht – Obsidian löst einen Link zuerst als Pfad und dann als Namen auf –, danach die erste in Vault-Reihenfolge (Ordner vor Notizen, ohne Beachtung der Groß-/Kleinschreibung, wie in Obsidians Dateiexplorer). Blume warnt nur, wenn ein Wikilink tatsächlich über eine solche Kollision aufgelöst wird; schreibe einen längeren Pfad, um die Mehrdeutigkeit aufzulösen. Eine Blockreferenz (`[[Note#^id]]`) verlinkt auf ihre Notiz ohne Anker: Blöcke werden ohne id gerendert, auf der man landen könnte. Ein Überschriften-Anker wird gegen die echten Überschriften der Zielnotiz aufgelöst, abgeglichen so, wie Obsidians Autovervollständigung sie schreibt (ohne `**bold**`, `` `code` `` und Link-Syntax), und mit demselben `extractHeadings`-Durchlauf zu einem Slug gemacht, der auch das Seiten-Manifest füllt – ein Link auf `#Install` landet also auf der Überschrift statt auf einer id, die keine Seite ausgibt. `[[#Install]]` adressiert eine Überschrift in der Notiz, die du gerade schreibst. Ein Link auf eine Überschrift, die nicht existiert, behält den Seitenlink, verwirft den Anker und warnt.

Das Frontmatter behält, was Blumes [Seitenschema](/docs/reference/frontmatter) akzeptiert, plus jeden Schlüssel, den du in [`frontmatter.extend`](/docs/reference/frontmatter#custom-keys) deklarierst (oder, für Notizen dieses `type`, im `frontmatter` eines Inhaltstyps); jede andere Obsidian-Eigenschaft – Dataview-Felder, Templater-Daten, `publish` sowie Obsidians eigene `tags`, `aliases` und `cssclasses` – wird beim Überführen einer Notiz verworfen, sodass ein mit der Properties-Oberfläche geschriebener Vault ohne Frontmatter-Fehler baut. `aliases` wird verworfen statt aufgelöst – Alias-Linkziele werden noch nicht unterstützt. Ein relatives Markdown-Bild neben einer Notiz (`![chart](./chart.png)`) wird aus dem Vault ausgeliefert, und wenn der Vault innerhalb deines Git-Repositorys liegt, erhalten Vault-Seiten wie jede andere Seite aus Git abgeleitete [„Zuletzt aktualisiert“-Daten](/docs/configuration#last-modified). „Diese Seite bearbeiten“-Links werden über `github.dir` aufgelöst, sodass ein Vault, der in einem Monorepo neben der Dokumentations-App liegt, weiterhin auf seine Datei verlinkt; ein Vault außerhalb des Repositorys bekommt keinen Link.

Locale-Verzeichnisse und Versions-Snapshots innerhalb des Vaults werden genauso gelesen, wie die Dateisystemquelle sie liest: `fr/Note.md` wird bei konfiguriertem [i18n](/docs/content/i18n) unter `/fr/` veröffentlicht, `v1.0/Note.md` bei [Versionen](/docs/content/versioning) unter `/v1.0/`, und Wikilinks auf diese Notizen zeigen auf die Route, die die jeweilige Notiz veröffentlicht.

:::note
Eine Überschrift, die selbst einen Link enthält, erhält ihren Manifest-Anker aus dem Markdown der Überschrift und ihre gerenderte `id` aus ihrem Textinhalt. Für diese Überschrift unterscheiden sich beide, sodass ein Wikilink darauf eventuell auf der Seite statt im Abschnitt landet.
:::

Ein Link auf eine `index`-Notiz landet auf der Route ihres Ordners statt auf einem Phantom-`/index`. **Ein nicht auflösbarer Wikilink wird zu einfachem Text mit einer Build-Warnung abgestuft, statt den Build fehlschlagen zu lassen**, sodass ein Vault mitten im Refactoring weiterhin veröffentlicht wird. Einzeilige `%%comments%%` werden entfernt, ein Wikilink innerhalb eines HTML-Kommentars (`<!-- [[Draft]] -->`) bleibt unangetastet, da Obsidian ihn ebenfalls verbirgt, und eine Notiz ohne `title` im Frontmatter erhält ihren Dateinamen als Titel – dieselbe Regel, die auch Obsidian selbst anwendet. Eine `index`-Notiz ist die einzige Ausnahme: Sie benennt eine Route statt einer Notiz, daher fällt ihr Titel auf Blumes übliche Herleitung zurück (erste Überschrift, dann das lesbar gemachte Segment). Code in Fences, eingerückter Code und Inline-Code werden wortwörtlich durchgereicht, sodass eine Notiz, die die Syntax dokumentiert, erhalten bleibt.

Punkt-Ordner werden übersprungen, einschließlich Obsidians eigenem Konfigurationsverzeichnis `.obsidian` und `.trash` – das der Dev-Watcher ebenfalls ignoriert, sodass das Verschieben eines Panels in der App oder das Löschen einer Notiz in den Papierkorb deine Website nicht neu baut. Das Bearbeiten einer Notiz schon. Die Verzeichnisse, die kein Inhaltsscan liest (`node_modules`, `dist`, `.git`, …), werden ebenfalls übersprungen, sodass ein Vault, der im Projekt selbst wurzelt, keine READMEs von Abhängigkeiten veröffentlicht. Symlinks innerhalb des Vaults werden verfolgt, so wie die Dateisystemquelle sie verfolgt, sodass ein in den Vault verlinkter geteilter Ordner mit ihm veröffentlicht wird. Ein Vault, der innerhalb von `content.root` liegt, muss von der Dateisystemquelle ausgeschlossen werden (`exclude: ["vault/**"]`); `blume version cut` lässt ihn dann aus dem Snapshot heraus, da der Vault seine eigenen Notizen weiterhin als aktuell veröffentlicht.

Noch nicht überführt: Callouts (`> [!note]`) werden als einfache Blockzitate gerendert, Einbettungen (`![[image.png]]`) werden unverändert durchgereicht, mehrzeilige `%%comments%%` bleiben stehen, und es gibt keinen Backlink-Graphen.

## Entferntes MDX

Die eingebaute Quelle `mdx-remote` lädt rohe `.md`/`.mdx`-Dateien über HTTP. Zähle die Dateien entweder über einen Teilbaum eines GitHub-Repositorys (`github`) oder explizit gegenüber einer Raw-Basis-URL (`url` + `files`) auf:

```ts blume.config.ts
{
  type: "mdx-remote",
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
}
```

Das Token eines privaten Repositorys wird aus der Umgebungsvariable `GITHUB_TOKEN` gelesen – es wird niemals in deine Konfiguration oder die generierte Ausgabe eingebettet und ausschließlich an GitHubs eigene Hosts (`api.github.com`, `raw.githubusercontent.com`) gesendet, niemals an eine eigene `url`-Basis.

Entfernte Seiten werden mit voller MDX-plus-Komponenten-Treue gerendert: Ihre Inhalte werden in einem versteckten Staging-Verzeichnis materialisiert und zusammen mit deiner lokalen Dokumentation über Astro gerendert, sodass Callouts, Tabs und alle anderen Blume-Komponenten weiterhin funktionieren.

### Caching und Offline-Builds

Jede entfernte Quelle hält einen Snapshot unter `.blume/cache/<source>/` vor. Wenn ein Abruf fehlschlägt – eine Netzwerkstörung oder ein CMS-Ausfall –, liefert Blume den letzten funktionierenden Snapshot mit einer Warnung aus, anstatt den Build fehlschlagen zu lassen. Der Cache liegt innerhalb von `.blume/` und wird neu erzeugt, niemals eingecheckt.

In der Entwicklung werden entfernte Inhalte einmal abgerufen und für die Sitzung eingefroren; starte den Dev-Server neu, um sie zu aktualisieren. Lokale Dateisystemquellen laden wie gewohnt per Hot-Reload neu. Um eine entfernte Quelle stattdessen auf Änderungen abzufragen, setze bei ihr `pollInterval` (in Sekunden) – der Dev-Server ruft in diesem Intervall erneut ab und lädt nur dann neu, wenn sich der Inhalt tatsächlich geändert hat. Lass die Option ungesetzt, um die API während der Arbeit nicht zu belasten.

## GitHub Releases

Die eingebaute Quelle `github-releases` verwandelt die Releases eines Repositorys in ein Changelog: Jedes Release wird zu einem Eintrag mit `type: changelog`, sodass deine Release Notes _dein_ Changelog sind – nichts muss doppelt geschrieben werden. In Kombination mit der generierten [Changelog-Timeline](/docs/advanced/changelog) liefert die Veröffentlichung eines GitHub-Releases direkt einen Changelog-Eintrag.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // include prereleases (default off)
        // drafts: false,       // include drafts (needs a write token)
        // limit: 100,          // cap releases, newest-first
      },
    ],
  },
});
```

Jedes Release wird automatisch auf die Changelog-Felder abgebildet: Sein Name (oder Tag) wird zum Titel, sein Veröffentlichungsdatum bestimmt die Reihenfolge in der Timeline, der Tag wird zu `changelog.version`, und Prereleases werden mit `Prerelease` gekennzeichnet (alle anderen mit `Release`). Die Notes werden als Inhalt des Eintrags gerendert. Gib der Quelle ein `prefix`, damit ihre Release-Seiten unter einer Route wie `/changelog/v1-2-0` liegen.

Ein privates Repository authentifiziert sich über die Umgebungsvariable `GITHUB_TOKEN` – dasselbe Token, das auch die anderen GitHub-Funktionen verwenden, und es wird niemals in deine Konfiguration eingebettet. Wie jede entfernte Quelle wird sie unter `.blume/cache/<source>/` zwischengespeichert und offline ausgeliefert, falls die API nicht erreichbar ist. Da ein Changelog ergänzend ist, führt ein fehlgeschlagener Abruf ohne Cache (etwa ein CI-Build ohne Token) zu einem leeren Changelog mit einer Warnung, statt den Build fehlschlagen zu lassen – setze `GITHUB_TOKEN` in deinen CI- und Deploy-Umgebungen, um es zu befüllen.

## Sanity

Die eingebaute Quelle `sanity` führt eine GROQ-Abfrage aus und bildet die Felder jedes Dokuments auf Frontmatter sowie seinen Portable-Text-Inhalt auf Markdown ab. Das Paket `@sanity/client` ist eine optionale Peer-Abhängigkeit – installiere es nur, wenn du diese Quelle verwendest.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "sanity",
        prefix: "guides",
        projectId: "abc123",
        dataset: "production",
        query: `*[_type == "guide"]`,
        // Field paths default to title / slug.current / body / _updatedAt
        fields: { slug: "slug.current", body: "content" },
      },
    ],
  },
});
```

Ein Lesetoken für ein privates Dataset stammt aus der Umgebungsvariable `SANITY_TOKEN`. Eigene Portable-Text-Blocktypen werden über die Option `serializers` des Adapters auf Blume-Komponenten abgebildet; sie steht zur Verfügung, wenn du `sanitySource` direkt über eine [eigene Quelle](#custom-sources) konstruierst.

## Notion

Die eingebaute Quelle `notion` verwandelt eine Notion-Datenbank in eine Sammlung: Jede Zeile wird zu einer Seite, ihre Eigenschaften werden zu Frontmatter und ihr Blockbaum wird zu MDX. Callouts, Toggles, Spalten und Codeblöcke werden auf die passenden Blume-Komponenten abgebildet. `@notionhq/client` (v5 oder neuer) ist eine optionale Peer-Abhängigkeit; Blume liest die Datenbank über ihre erste Datenquelle.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "notion",
        prefix: "handbook",
        database: process.env.NOTION_DB_ID,
        // Property names default to the title-typed prop / Description / Slug / Order
        // Set publishedValue to treat Status as a publish gate (opt-in)
        publishedValue: "Published",
      },
    ],
  },
});
```

Das Integrationstoken stammt aus der Umgebungsvariable `NOTION_TOKEN` (teile die Datenbank mit deiner Integration). Standardmäßig wird jede Seite importiert; setze `publishedValue`, um die Eigenschaft `Status` zu einer Veröffentlichungssperre zu machen – jeder andere Wert wird dann auf `draft: true` abgebildet, was Produktions-Builds verwerfen. **Notion-Bild-URLs sind signiert und laufen ab**, daher lädt der Adapter sie zur Build-Zeit in die Assets der Website herunter und schreibt die Verweise um – so verdirbt ein CMS-Bild niemals einen statischen Build. API-Aufrufe werden über einen kleinen Request-Pool getaktet (3 gleichzeitig, passend zum Rate-Limit pro Integration bei Notion), sodass sich Datenbanken mit Hunderten von Seiten importieren lassen, ohne `429`-Antworten auszulösen; setze `concurrency` an der Quelle, um das anzupassen.

## Preview und Sync

Zwei Flags steuern, wie entfernte Inhalte abgerufen werden und was enthalten ist:

- **`--preview`** bei `blume dev` oder `blume build` rendert Entwürfe und lädt unveröffentlichte CMS-Inhalte – Sanity wechselt in seine `previewDrafts`-Perspektive, und Notion filtert nicht mehr nach `Status`. Produktions-Builds ohne das Flag schließen Entwürfe wie gewohnt aus, sodass ein Preview-Build eine sichere Möglichkeit ist, unveröffentlichte Arbeit vor der Auslieferung zu prüfen.
- **`blume sync`** ruft jede entfernte Quelle erneut ab und generiert die Runtime neu. Die Entwicklung ist cache-first – eine entfernte Quelle wird einmal abgerufen und beim Neustart aus `.blume/cache` ausgeliefert (schnell und offline-tolerant), daher ist `blume sync` der Weg, die neuesten CMS-Inhalte zu holen, ohne den Dev-Server neu zu starten (ein laufender Server lädt per Hot-Reload neu). Ergänze `--force`, um zuerst den Cache zu verwerfen, oder setze `pollInterval` an einer Quelle, um automatisch zu aktualisieren.

```sh
blume dev --preview      # author workflow: see drafts live
blume build --preview    # render a full preview build
blume sync               # refresh remote content now
blume sync --force       # ...ignoring any cached snapshot
```

## Eigene Quellen

Jedes Objekt, das die `ContentSource`-Schnittstelle implementiert, kann direkt übergeben werden. So lässt sich ein Adapter mit eigenen Serializern – oder ein beliebiges nicht eingebautes Backend – einbinden, ohne dass dessen SDK die Kerninstallation berührt:

```ts blume.config.ts
import { defineConfig } from "blume";
import { sanitySource } from "blume/sources/sanity.ts";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "custom",
        source: sanitySource({
          name: "guides",
          prefix: "guides",
          projectId: "abc123",
          dataset: "production",
          query: `*[_type == "guide"]`,
          // Map custom Portable Text blocks to Blume components
          serializers: {
            callout: (block) => `<Callout>${block.text}</Callout>`,
          },
        }),
      },
    ],
  },
});
```

Eine Quelle normalisiert ihre native Form (Portable Text, Notion-Blöcke, entferntes HTML) zu Markdown-/MDX-Text, sodass dieselben Komponenten und Markdown-Funktionen gelten, ganz gleich, woher eine Seite stammt.

Eine eigene Quelle, die lokale Dateien liest, sollte an jedem Eintrag `sourcePath` und an der Quelle selbst `contentRoot` setzen. `sourcePath` benennt die Datei in Diagnosemeldungen und löst relative Bilder daneben auf; `contentRoot` grenzt das `log` von Git ein, das Seiten datiert – ohne die Option erhalten die Seiten der Quelle also kein aus Git abgeleitetes [„Zuletzt aktualisiert“-Datum](/docs/configuration#last-modified).

---

# Syntax
Source: https://useblume.dev/de/docs/content/syntax

Blume rendert standardmäßiges Markdown und MDX mit einem kuratierten, GitHub-Flavored-Funktionsumfang — keine Imports, keine Konfiguration. Schreibe Inhalte so, wie du es ohnehin tust; diese Seite zeigt alles, was unterstützt wird, mit einer Live-Vorschau und dem Quelltext für jedes Element.

## Überschriften

Gliedere eine Seite mit Überschriften. Blume rendert den `title` aus deinem Frontmatter als Seitenüberschrift, beginne deinen Inhalt also bei `##` — `##` und `###` werden zu Einträgen im Inhaltsverzeichnis. Jede Überschrift von `##` bis `######` wird außerdem in einen Link auf ihren eigenen Anker eingefasst, sodass Leser eine Überschrift anklicken können, um einen Permalink direkt zu diesem Abschnitt zu kopieren, als Lesezeichen zu speichern oder zu teilen (mit dem Mauszeiger darüberfahren, um das `#` einzublenden). Schalte das mit `markdown: { headingAnchors: false }` in `blume.config.ts` ab.

```md
## Section

### Subsection

#### Detail
```

### Eigene Anker

Anker-IDs werden aus dem Überschriftentext erzeugt, eine umformulierte Überschrift bekommt also einen neuen Anker. Hänge stattdessen `[#custom-id]` an, um den Anker festzunageln — der Marker wird nie gerendert, und Links funktionieren weiter, egal wie die Überschrift lautet. Festgenagelte Anker bleiben außerdem über [übersetzte Locales](/docs/content/i18n) hinweg identisch, wo automatisch erzeugte IDs sonst je Sprache abweichen würden.

```md
## Getting started [#setup]
```

Verlinke darauf als `/page#setup`. Die Syntax entspricht der von Fumadocs, migrierte Inhalte funktionieren also wortwörtlich.

Die von Pandoc, kramdown und Markdown-basierten Spezifikations-Toolchains verwendete Form `{#custom-id}` wird in `.md`-Dateien als gleichwertig akzeptiert. In `.mdx` ist ein nacktes `{…}` ein JSX-Ausdruck und die Seite lässt sich nicht kompilieren — `blume check` meldet den Marker als `BLUME_MDX_CURLY_ANCHOR` —, schreibe dort also `[#custom-id]` oder escape die geschweiften Klammern. Die escapte Form nagelt in beiden Formaten denselben Anker fest, was sie zur richtigen Schreibweise für ein Partial macht, das `.mdx`-Seiten [einbinden](/docs/content/includes):

```md
## Getting started \{#setup\}
```

Fragment-Links können auch auf ein rohes HTML-Element mit einer `id` zeigen (`<a id="setup"></a>`); `blume validate` akzeptiert diese neben Überschriften-Ankern.

### Inhaltsverzeichnis-Marker

Zwei weitere nachgestellte Marker steuern, wie eine Überschrift im Inhaltsverzeichnis erscheint. `[!toc]` behält eine Überschrift auf der Seite, hält sie aber aus dem Inhaltsverzeichnis heraus; `[toc]` macht das Gegenteil — die Überschrift erscheint nur im Inhaltsverzeichnis, als unsichtbares Ankerziel, was nützlich ist, um Abschnitte zu beschriften, die aus Komponenten statt aus Fließtext aufgebaut sind. Marker lassen sich in beliebiger Reihenfolge aneinanderreihen. Eine Ausnahme, geerbt von CommonMark: Eine nachgestellte Klammer, deren Label irgendwo auf der Seite eine Link-Referenzdefinition besitzt (`[toc]: /url`), ist ein Shortcut-Referenzlink und kein Marker — sie bleibt im Überschriftentext stehen.

```md
## Appears on the page only [!toc]

## Appears in the TOC only [toc]

## Both markers together [toc] [#custom-id]
```

Marker werden immer geparst — eine Überschrift, die wörtlich auf markerförmigen Text endet, würde als markiert behandelt. Escapen mit Backslash hilft nicht (Markdown löst `\[` zu `[` auf, bevor der Marker-Parse läuft); um wörtlichen Marker-Text am Ende einer Überschrift zu zeigen, packe ihn in Inline-Code: `` ## Using `[toc]` ``.

## Betonung

Inline-Formatierung, um Wörter hervorzuheben, Löschungen zu kennzeichnen und Code oder Tastenanschläge mitten im Satz zu zeigen.

**Fett**, _kursiv_, ~~durchgestrichen~~ und `Inline-Code`.

```md
**Bold**, _italic_, ~~strikethrough~~, and `inline code`.
```

## Hoch- und Tiefstellung

Für Fußnotenzeichen, Ordnungszahlen sowie wissenschaftliche oder chemische Notation im Fließtext.

E = mc^2^ und H~2~O.

{/* prettier-ignore */}
```md
E = mc^2^ and H~2~O.
```

## Blockzitate

Hebe ein Zitat, einen beiläufigen Hinweis oder eine redaktionelle Anmerkung vom umgebenden Text ab.

> Dokumentation, die schnell, KI-bereit und ohne Konfiguration auskommt — bis hin zum Template.

```md
> Documentation that's fast, AI-ready, and zero-config — down to the template.
```

## Listen

Verwende ungeordnete Listen für ungeordnete Mengen, geordnete Listen für Abfolgen und Aufgabenlisten für Checklisten und Roadmaps.

- Markdown-first schreiben
- Standardmäßig statisch
  - Server-Funktionen optional aktivieren
- Deine Ausgabe gehört dir

1. Blume installieren
2. Eine Seite schreiben
3. Veröffentlichen

- [x] Projekt aufsetzen
- [ ] Erste Anleitung schreiben

```md
- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide
```

## Tabellen

Stelle strukturierte Daten tabellarisch dar — Konfigurationsoptionen, Vergleichsmatrizen, Parameterlisten. Verwende Doppelpunkte in der Trennzeile, um Spalten auszurichten.

| Befehl        | Beschreibung             | Ausgabe |
| ------------- | ------------------------ | :-----: |
| `blume dev`   | Den Dev-Server starten   |    —    |
| `blume build` | Die statische Site bauen | `dist/` |

```md
| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |
```

Für eine Tabelle ohne Kopfzeile — zum Beispiel Schlüssel-Wert-Paare — lässt du die Kopfzellen leer. Markdown verlangt die Kopf- und Trennzeile syntaktisch, aber Blume entfernt den leeren Kopf aus der gerenderten Tabelle.

```md
|                |          |
| -------------- | -------- |
| Current status | E-3 visa |
```

## Links und Bilder

Verlinke auf andere Seiten oder externe Websites. Bilder akzeptieren einen relativen Pfad zu einer Datei neben deinem Inhalt, jeden Pfad unter `public/` (wird im Site-Root ausgeliefert) oder eine entfernte URL.

Lies den [Schnellstart](/docs/quickstart), um loszulegen.

```md
Read the [quickstart](/docs/quickstart) to get started.

![Alt text](./screenshot.png)
```

**Bevorzuge relative Pfade für lokale Bilder** — sie werden beim Build optimiert: komprimiert, nach WebP konvertiert und mit intrinsischer `width`/`height` versehen, damit die Seite beim Laden nicht springt. Lege das Bild neben die Seite, die es verwendet (oder in einen gemeinsamen Ordner innerhalb deines Content-Verzeichnisses) und referenziere es relativ:

```md
![Build output](./images/build-output.png)
```

Absolute Pfade unter `public/` (`![Alt text](/screenshot.png)`) werden unverändert ausgeliefert, ohne Optimierung — nutze sie für Dateien, die ihre exakten Bytes und ihre URL behalten müssen, etwa ein Logo, das von außerhalb deiner Doku referenziert wird. Auch entfernte Bilder werden unangetastet durchgereicht, sofern ihr Host nicht in der [`image`-Konfiguration](/docs/configuration#images) autorisiert ist.

Inhaltsbilder sind standardmäßig per Klick zoombar — Leser können jedes Bild anklicken, um es in einer Lightbox zu öffnen. Schalte das mit `markdown: { imageZoom: false }` in `blume.config.ts` ab oder nimm ein einzelnes Bild mit `data-no-zoom` aus.

## Horizontale Linie

Trenne größere Themenwechsel innerhalb einer langen Seite.

---

```md
---
```

## Codeblöcke

Eingezäunte Codeblöcke werden syntaxhervorgehoben und erhalten eine Kopfzeile mit der Sprache — samt Markensymbol für erkannte Sprachen — sowie einen Kopieren-Button. Füge nach der Sprache einen **Titel** hinzu — typischerweise einen Dateinamen — und er ersetzt die Sprachbezeichnung in der Kopfzeile.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```

````md
```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```
````

Auch Inline-Code lässt sich hervorheben: Setze einen `{:lang}`-Marker in eine Backtick-Spanne, und sie wird wie ein winziger Codeblock eingefärbt — `useState(){:js}` oder `T extends object{:ts}`. Das greift nur, wenn du den Marker hinzufügst, sodass einfacher Inline-Code unberührt bleibt — nichts, was aktiviert werden müsste.

Die Hervorhebung nutzt standardmäßig die Themes `github-light`/`github-dark`. Tausche pro Farbmodus jedes [mitgelieferte Shiki-Theme](https://shiki.style/themes) über `markdown.codeBlocks.theme` ein — es färbt alle Code-Oberflächen auf einmal (Fences, Inline-Snippets, `<CodeBlock>` und `<Diff>`):

```ts blume.config.ts
export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: "vesper" },
    },
  },
});
```

Du kannst auch direkt eine eigene [Shiki-Theme-Definition](https://shiki.style/guide/load-theme) bereitstellen. Importiere eine VS-Code-kompatible Theme-JSON-Datei (mit einem Import-Attribut, falls deine Laufzeitumgebung eines verlangt) und weise sie einem der beiden Farbmodi zu; mitgelieferte Namen und eigene Definitionen lassen sich mischen:

```ts blume.config.ts
import darkTheme from "./themes/acme-dark.json" with { type: "json" };

export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: darkTheme },
    },
  },
});
```

### Zeilennummern

Hänge `lineNumbers` an, um eine Zeilennummernspalte zu rendern — allein oder zusammen mit einem Titel:

```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```

````md
```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```
````

### Hervorhebung

Versieh Code mit Kommentaren im GitHub-Stil, um Aufmerksamkeit auf Zeilen, Wörter und Änderungen zu lenken. Die Kommentare werden aus der gerenderten Ausgabe entfernt, sodass der Code sauber kopierbar bleibt. Alle vier sind standardmäßig aktiv — keine Konfiguration nötig.

Markiere eine Zeile mit `// [!code highlight]`, um ihr einen hervorgehobenen Hintergrund zu geben:

```ts
const config = defineConfig({
  title: "My docs", // [!code highlight]
});
```

Zeige Änderungen mit `// [!code ++]` für Ergänzungen und `// [!code --]` für Entfernungen, gerendert als grün/rotes Diff:

```ts
export default defineConfig({
  title: "My docs", // [!code --]
  title: "Blume docs", // [!code ++]
});
```

Hebe jedes Vorkommen eines Begriffs in einer Zeile mit `// [!code word:serve]` hervor:

```ts
import { serve } from "blume"; // [!code word:serve]

serve({ port: 3000 });
```

Blende alles außer den mit `// [!code focus]` markierten Zeilen ab (der Rest wird beim Überfahren mit der Maus wieder scharf):

```ts
export default defineConfig({
  title: "My docs", // [!code focus]
  description: "Built with Blume",
});
```

Oder hebe Zeilen per **Nummer** statt per Kommentar hervor — nützlich, wenn du den Code nicht bearbeiten kannst. Setze einen Bereich in geschweiften Klammern hinter die Sprache; einzelne Zeilen, Kommalisten und `start-end`-Spannen funktionieren alle:

```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```

````md
```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```
````

### Anzeigetypen

Markiere einen TypeScript-Block mit `twoslash`, um echte Typen direkt aus dem Compiler anzuzeigen — ermöglicht durch [Twoslash](https://shiki.style/packages/twoslash). Fahre über ein beliebiges Token, um seinen abgeleiteten Typ zu sehen, und füge eine Inline-Abfrage `^?` hinzu, um einen Typ unter der Zeile anzuheften.

```ts twoslash
const config = {
  title: "My docs",
  version: 1,
};

config.title;
//     ^?
```

````md
```ts twoslash
const config = { title: "My docs", version: 1 };

config.title;
//     ^?
```
````

### TypeScript- und JavaScript-Tabs

Markiere einen `ts`- oder `tsx`-Block mit `ts2js`, um ihn als Tab-Paar zu rendern: dein TypeScript neben einer automatisch erzeugten JavaScript-Variante — so pflegst du ein einziges Snippet und Leser wählen ihren Dialekt. Die Umwandlung entfernt Typ-Syntax und reine Typ-Imports, behält deine Formatierung, Kommentare und JSX aber exakt so bei, wie du sie geschrieben hast — und die Tabs sind synchronisiert, sodass eine einmalige Wahl von JavaScript jedes Paar auf der Seite umschaltet. Wie Diagramme und Mathematik ist dies eine reine MDX-Funktion — in einer `.md`-Datei rendert der Block als schlichter TypeScript-Fence.

```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```

````md
```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```
````

Weitere Fence-Metaangaben lassen sich kombinieren: Ein `title="..."` erscheint auf beiden Tabs, während `{1,4-5}`-Zeilenbereiche nur für den TypeScript-Tab gelten (die Zeilennummern verschieben sich, sobald die Typen weg sind). Die einzige Ausnahme ist `twoslash` — Hover-Typen lassen sich nicht auf generierten Code übertragen, daher bleibt ein Fence, der beides trägt, ein schlichter Twoslash-Block.

:::note
Blende die Sprachsymbole aus oder lasse lange Zeilen umbrechen statt scrollen — mit `markdown: { code: { icons: false, wrap: true } }` in `blume.config.ts`.
:::

## Paketinstallation

Ein `package-install`-Block macht aus einem einzelnen Installationsbefehl ein Snippet mit Tabs für npm, pnpm, yarn und bun — so kopieren Leser genau den, der zu ihrem Setup passt. Wie Diagramme und Mathematik ist dies eine reine MDX-Funktion — in einer `.md`-Datei rendert der Block als schlichter Code-Fence.

```package-install
npm i blume
```

````md
```package-install
npm i blume
```
````

## Diagramme

Ein `mermaid`-Block rendert ein [Mermaid](https://mermaid.js.org)-Diagramm direkt aus Text. Der Inhalt des Fences wird unverändert an Mermaid übergeben, sodass jeder von Mermaid unterstützte Diagrammtyp hier funktioniert. Diagramme folgen dem aktiven Farbthema und werden bei einem Wechsel neu gerendert. Erstelle eines, indem du den Quelltext mit `mermaid` einzäunst:

````md
```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```
````

Diagramme werden im Client gerendert, daher ist dies eine reine MDX-Funktion, und die Mermaid-Bibliothek wird nur auf Seiten geladen, die eines enthalten. Der Rest dieses Abschnitts ist eine Galerie gängiger Typen — die vollständige Liste findest du in der [Mermaid-Dokumentation](https://mermaid.js.org/intro/).

### Flussdiagramm

```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```

### Sequenzdiagramm

```mermaid
sequenceDiagram
  participant R as Reader
  participant B as Blume
  R->>B: Request /docs
  B-->>R: Prerendered HTML
```

### Klassendiagramm

```mermaid
classDiagram
  class Page {
    +string title
    +string route
    +render()
  }
  Page <|-- Doc
  Page <|-- Changelog
```

### Zustandsdiagramm

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: build
  Published --> [*]
```

### Entity-Relationship

```mermaid
erDiagram
  PAGE ||--o{ HEADING : contains
  PAGE {
    string title
    string route
  }
```

### User Journey

```mermaid
journey
  title Publishing a page
  section Write
    Draft MDX: 5: Author
  section Ship
    blume build: 4: Author
    Deploy: 3: Author
```

### Gantt

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Docs
    Draft   :a1, 2026-01-01, 7d
    Review  :after a1, 3d
```

### Git-Graph

```mermaid
gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit
```

### Kreisdiagramm

```mermaid
pie title Content types
  "Docs" : 70
  "Blog" : 20
  "Changelog" : 10
```

### Mindmap

```mermaid
mindmap
  root((Blume))
    Content
      MDX
      Markdown
    Build
      Static HTML
      llms.txt
```

### Zeitstrahl

```mermaid
timeline
  title Blume milestones
  2025 : Prototype
  2026 : 1.0 release
```

## Callouts

Callouts lenken die Aufmerksamkeit der Leser auf Kontext, Ratschläge oder Risiken. Schreibe sie als `:::type`-Direktiven; einen Titel fügst du in eckigen Klammern hinzu, etwa `:::warning[Achtung]`. Direktiven sind eine reine MDX-Funktion — in einer `.md`-Datei bleibt eine `:::note`-Zeile wörtlicher Text.

### Note

Neutraler, unterstützender Kontext, den der Leser im Hinterkopf behalten sollte.

:::note
Blume erzeugt `.blume/` bei jedem Lauf neu — bearbeite es niemals von Hand.
:::

```md
:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::
```

### Tip

Eine hilfreiche Abkürzung oder Best Practice, die nicht erforderlich ist, das Leben aber leichter macht.

:::tip
Setze `deployment.site`, damit Sitemaps und Open-Graph-Bilder absolute URLs verwenden.
:::

```md
:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::
```

### Success

Bestätige ein positives Ergebnis oder dass ein Schritt wie erwartet abgeschlossen wurde.

:::success
Deine Doku wurde erfolgreich gebaut und ist bereit zum Deployment.
:::

```md
:::success
Your docs built successfully and are ready to deploy.
:::
```

### Warning

Weise auf etwas hin, das Sorgfalt erfordert, um einen Fehler oder überraschendes Verhalten zu vermeiden.

:::warning[Achtung]
Der Wechsel zu `output: "server"` erfordert einen Adapter, bevor du deployen kannst.
:::

```md
:::warning[Heads up]
Switching to `output: "server"` requires an adapter before you can deploy.
:::
```

### Danger

Mache auf eine zerstörerische oder brechende Aktion aufmerksam, die sich nicht leicht rückgängig machen lässt.

:::danger
`blume eject` ist ein Einbahnstraßen-Schritt — das generierte Astro-Projekt gehört danach dir.
:::

```md
:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::
```

### Info

Ein informativer Einschub; ein alias-freundlicher Standard, der neutral wirkt.

:::info
Das Kern-Theme liefert kein Client-Framework-JS aus.
:::

```md
:::info
The core theme ships no client framework JS.
:::
```

Die Namen `caution`, `error`, `important` und `warn` werden als Aliase für `warning`, `danger`, `note` beziehungsweise `warning` akzeptiert.

## Mathematik

Rendere LaTeX mit KaTeX als zentrierte Blöcke — nützlich für mathematik- oder naturwissenschaftslastige Dokumentation. Setze eine Formel in `$$…$$`:

$$
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

```md
$$
a^2 + b^2 = c^2
$$
```

:::note
Mathematik gibt es nur als Block und sie ist automatisch aktiv — schreibe `$$…$$` und es wird gerendert; schreibst du keine, wird das Stylesheet von KaTeX nie ausgeliefert. Inline-Mathematik mit `$…$` gibt es nicht: Ein einzelnes `$` (Währung, Shell-Variablen, Code) bleibt immer wörtlicher Text, es gibt also kein Trennzeichen zu escapen und keine Einstellung zum Umschalten. Mathematik ist eine reine MDX-Funktion. Die Klassennamen im gerenderten Markup (`.katex-html`, `.katex-base`, …) sind KaTeX-eigene Interna und kein Styling-Vertrag, den Blume pflegt — sie können sich bei einem KaTeX-Upgrade ändern, ziele für eigene Styles also auf den `.katex-display`-Wrapper.
:::

## Intelligente Interpunktion

Blume wandelt gerade Anführungszeichen und Bindestriche schon beim Schreiben in typografische Entsprechungen um, sodass Fließtext wirkt, als wäre er gesetzt worden — ohne Sonderzeichen.

"Anführungszeichen" werden typografisch, -- wird zu einem Halbgeviertstrich, --- zu einem Geviertstrich und ... zu Auslassungspunkten.

```md
"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
```

---

# Versionierung
Source: https://useblume.dev/de/docs/content/versioning

Blume versioniert deine Docs so, wie Releases tatsächlich funktionieren: Die aktuelle Dokumentation liegt im Wurzelverzeichnis deiner Inhalte mit sauberen, präfixfreien URLs, und jede vergangene Version ist ein eingefrorener Snapshot in einem eigenen Ordner. Erstelle einen Snapshot, wenn du auslieferst, und Blume verkabelt den Umschalter, den Hinweis auf die „alte Version“, das Scoping der Suche, SEO und die Agent-Oberfläche für dich. Es ist opt-in: Ohne einen `versions`-Block ändert sich nichts.

## Aktivieren

Füge einen `versions`-Block hinzu, der die aktuellen Docs und alle archivierten Snapshots benennt:

```ts blume.config.ts lineNumbers
versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}
```

`current` beschriftet den präfixfreien Baum im Umschalter (mit einem optionalen `badge`). Die `id` jedes archivierten Eintrags ist zugleich der Verzeichnisname des Snapshots und sein URL-Segment – IDs müssen mit einem Buchstaben beginnen (`v1.0`, nicht `1.0`), damit sie niemals mit [numerischen Sortierpräfixen](/docs/content/navigation#ordering) kollidieren können. Liste archivierte Versionen mit der neuesten zuerst; diese Reihenfolge ist die Reihenfolge im Umschalter.

## Eine Version einfrieren

Wenn du ein Release veröffentlichst, friere die aktuellen Docs mit einem Befehl ein:

```bash
blume version v1.0
```

Das kopiert deinen Inhaltsbaum nach `docs/v1.0/` (bestehende Snapshots ausgenommen), schreibt wurzelabsolute Links innerhalb der Kopie so um, dass sie im Snapshot bleiben (`/guides/x` wird zu `/v1.0/guides/x`, umzäunter und Inline-Code bleiben unberührt), und registriert die ID in `blume.config.ts` – oder gibt den Eintrag zum Einfügen aus, wenn deine Konfiguration so aufgebaut ist, dass sie nicht angetastet wird. Links auf Seiten, die nicht Teil des kopierten Baums sind – generierte API-Referenzen, entfernte Quellen wie ein Changelog –, zeigen weiterhin auf die aktuellen Seiten, da der Snapshot keine Kopie davon enthält. Führe `blume version` ohne ID aus, um die konfigurierten Versionen aufzulisten.

Prüfe und committe das neue Verzeichnis wie jeden anderen Inhalt. Starte `blume dev` neu, damit es übernommen wird.

```txt
docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart
```

**Archiviert heißt eingefroren.** Künftige Änderungen gehören in den lebenden Baum; ein Snapshot ist die Doku so, wie sie war. Blume stützt sich darauf: Snapshots behalten ihre eigenen Ordner-Metadaten und Übersetzungen, [`blume translate`](/docs/reference/translate) übersetzt sie nie erneut, und eine konfigurierte explizite Sidebar gilt nur für die aktuellen Docs – die Sidebar eines Snapshots stammt immer aus seinen eigenen Dateien.

## Der Umschalter und der Hinweis

Mit konfigurierten Versionen erhält der Header automatisch ein Versions-Dropdown. Beim Wechseln landest du auf derselben Seite in der Zielversion, sofern sie existiert, und andernfalls im Wurzelverzeichnis dieser Version (setze `switcher.redirect: "root"`, um immer im Wurzelverzeichnis zu landen). Wenn du in [`navigation.selectors`](/docs/content/navigation#selectors) einen eigenen Selektor mit `kind: "version"` deklarierst, ersetzt dieser den automatischen.

Jede archivierte Seite zeigt außerdem einen nicht ausblendbaren Hinweis mit einem „Zur neuesten Version“-Link, der auf das aktuelle Gegenstück der Seite verweist. Passe ihn pro Version an oder deaktiviere ihn:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0", banner: "These docs cover the 1.x SDK." },
    { id: "v0.9", banner: false },
  ],
}
```

## SEO

Alte Docs sind die Lieblingsfalle von Suchmaschinen: Die veraltete Seite rankt besser als die aktuelle, oder beide konkurrieren miteinander. Blume setzt standardmäßig auf die Lösung, die SEO-Leitfäden empfehlen und die kein anderes Docs-Framework automatisiert: Archivierte Seiten bleiben indexierbar, deklarieren aber das **aktuelle Gegenstück als ihr Canonical**, sodass die aktuelle Seite maßgeblich ist, während versionsspezifische Inhalte (eine Seite, die in den aktuellen Docs nicht mehr existiert) mit einem Self-Canonical auffindbar bleiben.

Pro Version kannst du eine andere Behandlung wählen:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0" }, // canonical → latest (default)
    { id: "v0.9", canonical: "self" }, // every page authoritative
    { id: "v0.8", noindex: true }, // deindexed entirely
  ],
}
```

Die Sitemap zieht mit: Archivierte Seiten, deren Canonical auf ein aktuelles Gegenstück zeigt, werden weggelassen, `noindex`-Versionen fallen vollständig weg, und versionsspezifische Seiten bleiben gelistet. Das eigene `seo.canonical`-Frontmatter einer Seite gewinnt immer.

## Suche

Der Suchdialog begrenzt die Ergebnisse auf die gerade betrachtete Version, mit einem „Alle Versionen“-Umschalter (pro Leser gespeichert) neben dem für die Sprache. Versionsübergreifende Treffer nennen ihre Version in der Ergebniszeile. Orama (die Standardoption), FlexSearch, Algolia und Typesense berücksichtigen das Scoping alle – gehostete Datensätze tragen eine `version`-Facette, wobei die aktuellen Docs als `"current"` hochgeladen werden –, während Pagefind ungescopt bleibt, passend zu seinem Verhalten bei Sprachen.

## Agents

Die Agent-Oberfläche ist versionsbewusst – etwas, das kein anderes Docs-Framework bietet:

- Die MCP-Tools `search_docs` und `list_pages` verwenden standardmäßig die aktuellen Docs und akzeptieren `version`: eine archivierte ID (`"v1.0"`) oder `"all"`. `get_navigation` gibt auf Anfrage den Baum eines archivierten Snapshots zurück.
- `llms.txt` ordnet archivierte Versionen nach den aktuellen Docs ein, beschriftet als `1.0 (archived)`, sodass ein Agent beim Lesen des Index weiß, welche Docs eingefroren sind.
- `llms-full.txt` bleibt ausschließlich aktuell – der flache Dump vermischt nie eingefrorene Kopien derselben Seite.
- Rohe Markdown-Spiegel (`.md`-URLs) existieren für die Seiten jeder Version, wie für jede andere Route auch.

## Zusammen mit i18n

Versionierung lässt sich mit [Internationalisierung](/docs/content/i18n) kombinieren. Auf der Festplatte liegt der Versionsordner außen – ein Snapshot enthält naturgemäß seine Sprachordner –, während in den URLs die Sprache außen bleibt, passend zum Rest der Website:

```txt
docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
```

Der Sprach-Fallback funktioniert innerhalb jeder Version: Eine nicht übersetzte Snapshot-Seite rendert den Inhalt der Fallback-Sprache unter der lokalisierten URL, und `hreflang`-Alternativen werden pro Version gruppiert. Eine Versions-ID darf nicht mit einem konfigurierten Sprachcode kollidieren – Blume weist eine solche Konfiguration rundweg zurück.

## Was unversioniert bleibt

Die Versionierung umfasst den Inhaltsbaum der Docs. Der Blog, das Changelog, aus OpenAPI-Spezifikationen generierte API-Referenzen und benutzerdefinierte Seiten sind immer aktuell. Zwei weitere Verhaltensweisen solltest du kennen: Header-Tabs werden gegen die aktuellen Docs definiert, sodass die Sidebar innerhalb eines archivierten Baums ohne Tab-Scoping gerendert wird; und bei großen Websites solltest du bedenken, dass jeder Snapshot eine vollständige Kopie ist – Inhalte, Suchindex-Einträge und Navigationsdaten wachsen alle pro Version.

---

# Deployment
Source: https://useblume.dev/de/docs/deployment

## Überall bereitstellen (statisch)

`blume build` kompiliert deine Dokumentation zu reinem HTML, CSS und einem lokalen Suchindex in `dist/`. Es muss kein Server betrieben werden — richte einfach einen beliebigen statischen Host auf den Ordner aus.

| Einstellung        | Wert             |
| ------------------ | ---------------- |
| Build-Befehl       | `blume build`    |
| Ausgabeverzeichnis | `dist`           |
| Node-Version       | 22.12 oder neuer |

Diese Einstellungen funktionieren auf Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront oder in jedem Bucket bzw. CDN. Stelle sicher, dass `blume` eine Abhängigkeit ist, damit der Host den Build ausführen kann.

Ein statischer Build enthält:

- jede Dokumentations- und benutzerdefinierte Seite als statisches HTML
- einen lokalen Suchindex (standardmäßig Orama, Pagefind optional)
- eine [`sitemap.xml`](/docs/configuration/seo#sitemap) und [`robots.txt`](/docs/configuration/seo#robots), wenn `deployment.site` gesetzt ist
- `llms.txt` und `llms-full.txt` für KI-Tools
- Weiterleitungsseiten
- vorgerenderte [Open-Graph-Bilder](/docs/configuration/seo#open-graph-images), wenn `seo.og.enabled` aktiviert ist

### Deine Site-URL festlegen

Sitemaps, Canonical-Tags, RSS und Open-Graph-Bilder benötigen einen absoluten Origin. Auf **Vercel**, **Netlify** und **Cloudflare Pages** erkennt Blume ihn zur Build-Zeit aus der Umgebung der Plattform — keine Konfiguration erforderlich.

Setze `deployment.site`, um den erkannten Wert zu überschreiben oder um auf Hosts, die ihn nicht bereitstellen (GitHub Pages, S3, ein eigenes CDN), einen Wert anzugeben:

```ts blume.config.ts lineNumbers
deployment: {
  site: "https://docs.example.com",
}
```

Bei der automatischen Erkennung bevorzugt Blume deine stabile Produktionsdomain gegenüber Preview-URLs einzelner Deployments, sodass der kanonische Origin über Deployments hinweg gleich bleibt.

Während `blume dev` fällt die Site-URL auf deinen lokalen Dev-Server zurück (z. B. `http://localhost:4321`), wenn keine gesetzt ist, damit Site-abhängige Funktionen — Open-Graph-Bilder, Canonicals, die Sitemap — sofort funktionieren. Builds verwenden diesen Fallback nie, sodass die Produktionsausgabe niemals auf localhost verweist.

## Lokale Vorschau

Bevor du veröffentlichst, kannst du den Produktions-Build genau so in der Vorschau ansehen, wie ihn ein statischer Host ausliefern würde:

```bash
blume build
blume preview
```

## Deployments unter einem Unterpfad

Du lieferst deine Dokumentation unter einem Pfad wie `example.com/docs` aus? Setze `deployment.base` — üblich für GitHub-Pages-Projektseiten. Die gesamte Site, einschließlich der Wurzel, wird unter die Basis verschoben, und interne Links sowie Assets werden so umgeschrieben, dass sie die Basis enthalten.

```ts blume.config.ts lineNumbers
deployment: {
  base: "/docs",
}
```

## Die Dokumentation unter einem Pfad einhängen

`basePath` hängt jede generierte Route unter ein Segment (`/docs/getting-started`), lässt die Seitenleiste dabei aber unverändert — die oberste Ebene sind deine Abschnitte, keine umschließende Gruppe. Verwende es, wenn die Dokumentation unter `/docs/*` liegt, die Site-Wurzel aber dir gehört (wie `routeBasePath` bei Docusaurus oder `baseUrl` bei Fumadocs).

```ts blume.config.ts lineNumbers
basePath: "/docs",
```

Schreibe Links so, als wären sie an der Wurzel eingehängt (`/getting-started`); Blume schreibt sie um — ebenso Weiterleitungen, die Sitemap, kanonische URLs, Open-Graph-Bilder, `llms.txt` und den Suchindex. Öffentliche Assets (Bilder, Dateien unter `public/`) bleiben an der Site-Wurzel.

Dies ist ein anderes Konzept als die beiden obigen Pfade:

- Ein quellenspezifisches [`prefix`](/docs/content/sources#multiple-sources) versieht **eine** Quelle mit einem Namensraum und fügt **sehr wohl** eine Seitenleistengruppe hinzu.
- `deployment.base` ist das Unterverzeichnis des Hosts, aus dem die **gesamte** App ausgeliefert wird. Beide lassen sich kombinieren — sind beide gesetzt, landet eine Seite unter `{deployment.base}/{basePath}/page`.

## Server-Rendering

Statische Ausgabe deckt die meisten Dokumentationen ab. Wechsle zur Server-Ausgabe, wenn du Funktionen zur Anfragezeit benötigst — insbesondere den [Ask AI](/docs/configuration/ai)-Endpunkt:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

Die Adapter `vercel` und `node` sind in Blume enthalten — die Auswahl eines der beiden funktioniert einfach. Die Adapter `netlify` und `cloudflare` müssen in deinem Projekt installiert werden (z. B. `bun add -d @astrojs/netlify`); die CLI warnt dich, wenn das Paket fehlt:

| Adapter | Paket | Verwendung für |
| --- | --- | --- |
| `vercel` | `@astrojs/vercel` | Vercel — der ausgereifteste Weg |
| `netlify` | `@astrojs/netlify` | Netlify Functions |
| `node` | `@astrojs/node` | Selbst gehostete Node-Server, Container |
| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers und Pages |

Auf **Vercel**, **Netlify** und **Cloudflare Pages** wählt Blume den passenden Adapter für die Server-Ausgabe automatisch aus — setze `output: "server"` und deploye (bei Netlify und Cloudflare musst du zusätzlich das Adapterpaket installieren). Setze `adapter` explizit, um den erkannten Wert zu überschreiben oder wenn du mit `node` selbst hostest.

Ein Server-Build enthält alles, was ein statischer Build enthält, sowie alle Astro-Endpunkte oder Middleware, die du hinzufügst. Der `node`-Adapter erzeugt einen eigenständigen Server, den du direkt ausführen kannst.

Auf Vercel und Cloudflare aktiviert ein Server-Build außerdem die [Content Negotiation über `Accept: text/markdown`](/docs/configuration/ai#content-negotiation), sodass ein Agent, der eine beliebige Inhaltsseite mit diesem Header anfragt, unter derselben URL deren Roh-Markdown-Spiegelung erhält. Auf Vercel fügt Blume header-abhängige Rewrites in die Routing-Konfiguration des Deployments ein; auf Cloudflare erzeugt es einen kleinen Worker vor dem Astro-Worker und beschränkt `assets.run_worker_first` auf die Inhaltsrouten, da die Plattform andernfalls die vorgerenderten Seiten ausliefern würde, bevor Servercode ausgeführt wird — andere Assets behalten ihren schnellen Pfad ohne Worker.

:::note
Serverfunktionen haben ihre eigene Konfiguration — Ask AI benötigt beispielsweise einen API-Schlüssel für ein Modell. Zur Einrichtung siehe den [KI-Leitfaden](/docs/configuration/ai).
:::

## Weiterleitungen

Ordne alte URLs in `blume.config.ts` neuen zu:

```ts blume.config.ts
redirects: [{ from: "/old", to: "/new", status: 301 }];
```

`status` akzeptiert `301`, `302`, `307` oder `308` (Standard `301`). Server-Builds verarbeiten Weiterleitungen zur Anfragezeit. Statische Builds erzeugen Weiterleitungsseiten **und** Plattformdateien, damit dein Host eine echte HTTP-Weiterleitung ausgibt: `_redirects` (Netlify, Cloudflare Pages), `vercel.json` (Vercel) und `blume-redirects.json` — ein strukturiertes Manifest für alles Übrige (nginx-/Apache-Regeln, ein Edge Worker). Eine `_redirects` oder `vercel.json`, die du in `public/` mitlieferst, bleibt unangetastet.

:::note
`from` wird als exakter Pfad abgeglichen — Platzhalter und Musterabgleich (z. B. `/blog/:slug` oder `/old/*`) werden nicht unterstützt. Wenn du musterbasierte Regeln brauchst, behandle sie stattdessen in einer Infrastrukturdatei wie `vercel.json` (die Platzhalter-`source`-Muster unterstützt) oder in der Weiterleitungskonfiguration deines Hosts. Eine `vercel.json`, die du in `public/` mitlieferst, bleibt unverändert erhalten.
:::

:::note
Schreibe sowohl `from` als auch `to` so, als wären sie an der Wurzel eingehängt — sowohl unter [`deployment.base`](#subpath-deploys) als auch unter [`basePath`](#mount-the-docs-under-a-path) schreibt Blume beide Seiten für dich um, sodass eine Weiterleitung innerhalb der Basis landet. Eine Basis, die du bereits von Hand in `to` geschrieben hast, bleibt erhalten und wird nicht verdoppelt.
:::

## Inhaltstypen

Ein statischer Build erzeugt außerdem eine `_headers`-Datei, die `charset=utf-8` an die rohen, KI-tauglichen Endpunkte heftet — `/<route>.md`, `/<route>.mdx` und die `.txt`-Dateien (`llms.txt`, `llms-full.txt`). Diese Antworten sind gültiges UTF-8, doch viele statische Hosts liefern sie als `text/markdown` / `text/plain` **ohne** Charset aus, und Browser fallen dann auf Windows-1252 zurück — sodass Dokumentation mit Nicht-ASCII-Zeichen (Japanisch, akzentuiertes Latein, …) beim direkten Öffnen der Roh-URL als Zeichensalat dargestellt wird. HTML-Seiten sind davon nicht betroffen, da sie `<meta charset>` mitführen. Netlify und Cloudflare (statische Assets von Pages/Workers) lesen `_headers`; Hosts, die das nicht tun (Vercel, S3), ignorieren die Datei folgenlos. Eine `_headers`-Datei, die du in `public/` mitlieferst, bleibt unangetastet.

## Umgebungsvariablen

Wenn eine Funktion ein Laufzeit-Secret benötigt, warnt Blume bei `blume dev`/`build`, falls es fehlt — so tritt das Problem früh zutage statt erst bei der ersten Anfrage:

| Funktion | Variable |
| --- | --- |
| Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (oder Vercel OIDC) |
| Ask AI (andere Anbieter) | die Standard-Schlüssel-Umgebungsvariable des Anbieters (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`) oder dein konfiguriertes `apiKeyEnv` |
| Mixedbread-Suche | `MIXEDBREAD_API_KEY` |

Setze sie in `.env.local` für die lokale Entwicklung und in der Umgebung deines Hosts für die Produktion. Vor fehlenden Build-Zeit-Secrets für die Synchronisierung des Suchindex (Algolia, Orama Cloud, Typesense) wird separat während des Sync-Schritts gewarnt.

## Build-Zusammenfassung

Jeder Build gibt eine Zusammenfassung aus — Ausgabemodus, Adapter, aufgelöste Site-URL, Suchanbieter, Anzahl der Weiterleitungen, Status von Sitemap und `llms.txt` sowie alle aktivierten Serverfunktionen — damit du vor dem Deployment prüfen kannst, was ausgeliefert wurde (einschließlich aller automatisch erkannten Werte).

---

# FAQ
Source: https://useblume.dev/de/docs/faq

Antworten auf häufig gestellte Fragen. Fehlt eine? [Öffne ein Issue](https://github.com/haydenbleasel/blume/issues) oder frage den Assistenten auf der Seite.

## Wie unterscheidet sich Blume von Mintlify, Fumadocs und anderen?

Die meisten Dokumentationswerkzeuge liegen an einem von zwei Extremen. **Verwaltete Plattformen** wie Mintlify liefern dir schnell ein poliertes Ergebnis, aber Build und Hosting sind ihr Service — du verfasst innerhalb ihres Systems und veröffentlichst auf ihrer Infrastruktur. **Komponentenbibliotheken und Starter** wie Fumadocs, Nextra oder Docusaurus sind Open Source und flexibel, aber sie übergeben dir eine Anwendung (ein Next.js- oder React-Projekt), die du aufsetzt, verkabelst und pflegst, bevor und nachdem du ein einziges Wort geschrieben hast.

Blume geht einen dritten Weg: **Das Framework ist die Vorlage.** Du richtest es auf einen Ordner mit Markdown, und es erzeugt und steuert die gesamte Website — Navigation, Suche, Theming, Open-Graph-Bilder, SEO und KI-Endpunkte — ohne dass du eine App besitzen musst. Es ist vollständig Open Source und selbst hostbar, es gibt also keinen verwalteten Dienst und keine Anbieterbindung, aber auch keinen Boilerplate-Code zu pflegen.

|  | Blume | Mintlify | Fumadocs / Nextra / Docusaurus |
| --- | --- | --- | --- |
| **Modell** | Zero-Config-Framework; nur Inhalte | Gehostete Plattform | Bibliothek + App, die du aufsetzt |
| **Quelle** | Open Source (MIT) | Geschlossener Kern | Open Source |
| **Hosting** | Überall — statisch oder als Serverfunktion | Ihre verwaltete Infrastruktur | Überall; du baust und veröffentlichst |
| **Du pflegst** | Dein Markdown | Dein Markdown + Plattformkonfiguration | Dein Markdown + die App darum herum |
| **Rendering** | Astro; das Kern-Theme liefert null Client-JS aus | Ihre Runtime | React-/Next.js-Runtime |
| **KI-Funktionen** | `llms.txt`, rohes Markdown, Ask AI, MCP — eingebaut, ohne gehosteten Dienst | Eingebaut (gehostet) | Bring dein eigenes mit |

Ein paar Konsequenzen, die es hervorzuheben lohnt:

- **Dir gehört das Ergebnis.** `blume build` erzeugt eine schlichte Website, die du auf Vercel, Netlify, Cloudflare, S3 oder deinem eigenen Rechner hostest. Nichts funkt nach Hause.
- **Keine Bindung, zwei Auswege.** Deine Inhalte sind portables Markdown, und `blume eject` verwandelt das Projekt in eine eigenständige Astro-App, die weiterhin das `blume`-Paket nutzt, wenn du volle Kontrolle willst.
- **Standardmäßig schnell.** Das Kern-Theme kommt ohne React aus und rendert statisches HTML, sodass Seiten ohne Feintuning bei den Core Web Vitals gut abschneiden. Serverfunktionen (Ask AI, MCP) schaltest du nur dann dazu, wenn du sie brauchst.
- **Typsichere Konfiguration.** `blume.config.ts` und jede `meta.ts` sind echtes TypeScript, validiert durch ein Schema — kein lose typisiertes YAML.

:::note
Das ist kein „besser als alles andere“ — verwaltete Plattformen und vollwertige Frameworks sind die richtige Wahl, wenn du ein gehostetes Produkt oder maximale Kontrolle über die App möchtest. Blume ist für Teams, die eine produktionsreife Dokumentationsseite wollen, ohne weder die Plattform noch die Infrastruktur dahinter zu besitzen.
:::

Siehe [Warum es Blume gibt](/docs) für die ausführliche Fassung.

## Ist Blume kostenlos und quelloffen?

Ja — Blume steht unter der MIT-Lizenz und ist kostenlos. Du installierst das `blume`-Paket, hältst deine Inhalte in deinem eigenen Repository und hostest den Build, wo du möchtest. Es gibt keine kostenpflichtige Stufe, keine Preise pro Nutzer und kein Konto, für das du dich registrieren musst. Der Quellcode liegt auf [GitHub](https://github.com/haydenbleasel/blume).

## Muss ich Astro, React oder Tailwind kennen?

Nein. Ein Ordner mit Markdown ist eine vollständige Website — Navigation, Suche und Theming werden abgeleitet oder mit einer Handvoll Tokens festgelegt. Zum darunterliegenden Stack greifst du nur, wenn du anpassen willst: [interaktive Islands](/docs/content/islands) (React), [Komponenten-Overrides](/docs/configuration/customization) oder [Theme-Tokens](/docs/configuration/theming) (Tailwind). Und selbst dann ist [`blume.config.ts`](/docs/configuration) typisiert, sodass dich dein Editor führt.

## Kann ich React-Komponenten und MDX verwenden?

Ja. Jede Seite kann `.md` oder `.mdx` sein, und mit MDX kannst du die [eingebauten Komponenten](/docs/content/components) ohne Importe einfügen. Du kannst auch eigene `.tsx`/`.jsx`-[Islands](/docs/content/islands) hinzufügen — Blume aktiviert React automatisch nur für die Seiten, die sie nutzen, sodass das Kern-Theme überall sonst frei von JavaScript bleibt.

## Wo kann ich es veröffentlichen?

Überall. `blume build` gibt standardmäßig statisches HTML aus, das du von jedem statischen Host oder CDN ausliefern kannst — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3 oder deinem eigenen Server. Reine Serverfunktionen (Ask AI, der MCP-Server, On-Demand-Rendering) stellen den Build über einen Adapter für Vercel, Node, Netlify oder Cloudflare auf eine Serverfunktion um. Siehe [Deployment](/docs/deployment).

## Braucht die Suche einen gehosteten Dienst?

Nein. [Orama](/docs/configuration/search) erstellt einen lokalen Index, der sowohl in der Entwicklung als auch in der Produktion funktioniert, ohne dass etwas gehostet oder bezahlt werden muss. Für sehr große Websites ist [Pagefind](/docs/configuration/search) nur ein Flag entfernt. So oder so wird der Index als Teil deiner Website ausgeliefert.

## Wie passe ich das Erscheinungsbild an?

Beginne mit [Theme-Tokens](/docs/configuration/theming) — Akzentfarbe, Schriften, Radius und eine `theme.css` für alles andere, was Tailwind ausdrücken kann. Geh weiter, indem du [eingebaute Komponenten überschreibst](/docs/configuration/customization) oder [eigene Seiten](/docs/configuration/customization#custom-pages) hinzufügst. Wenn du das Astro-Projekt selbst haben möchtest, übergibt dir [`blume eject`](/docs/reference/cli) eine eigenständige App, die weiterhin das `blume`-Paket nutzt.

## Warum faltet oxfmt / Ultracite meine Direktiven zusammen?

Wenn du dein Markdown mit [Ultracite](https://www.ultracite.ai) formatierst (das oxlint + [oxfmt](https://oxc.rs) ausführt) — so wie Blume es selbst tut — fällt dir vielleicht auf, dass Container-Direktiven nach einem Formatierungsdurchlauf auf eine einzige Zeile zusammengedrückt werden:

```md
:::note
Regenerate the project with blume dev.
:::
```

wird zu

```md
:::note Regenerate the project with blume dev. :::
```

Sobald die öffnende `:::note`-Auszeichnung mit dem Fließtext verbunden ist, ist sie keine Direktive mehr und wird als wörtlicher Text statt als [Callout](/docs/content/syntax#callouts) dargestellt.

### Warum das passiert

Das ist ein Fehler im Markdown-Formatierer von oxfmt (geerbt von Prettiers Markdown-Printer — siehe [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). Beim Umbrechen von Fließtext behandelt er die `:::`-Zeilen als gewöhnlichen Text und verbindet sie mit der angrenzenden Zeile, was die Direktive zerstört. Betroffen sind alle Typen von Container-Direktiven — `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::success`.

Wir haben das upstream unter [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096) gemeldet; bis es dort behoben ist, ist der untenstehende Patch die Behelfslösung.

### Die Lösung

Patche oxfmt so, dass es den Zeilenumbruch erhält, der direkt an einer `:::`-Auszeichnung sitzt. Blume liefert dieselbe Korrektur in seinem eigenen Repository aus, und du kannst sie in jedem Projekt anwenden.

1. Speichere den Patch als `patches/oxfmt@0.66.0.patch`:

   ```diff patches/oxfmt@0.66.0.patch
   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
   --- a/dist/markdown-BgZGxhM2.js
   +++ b/dist/markdown-BgZGxhM2.js
   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
    		case "sentence": return Oh(e, r);
    		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
    		case "whitespace": {
   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   +			let { next: a, 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(":::");
   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
   +			// linkReference between two sentence nodes at the paragraph level: the
   +			// fence word ends the sentence before the reference, and the body's
   +			// leading newline opens the sentence after it. So when this whitespace
   +			// starts its sentence, climb to the paragraph and check whether the two
   +			// preceding siblings are a (link) reference and a sentence ending in a
   +			// `:::` fence word.
   +			let oxfmtPrevIsTitledFence = !1;
   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
   +				if (oxfmtSentIdx >= 2) {
   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
   +				}
   +			}
   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
   +			// words, so the whole directive is one sentence. For a newline
   +			// whitespace, walk back to the start of its visual line within the
   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
   +				let oxfmtLineFirst = null;
   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
   +					let oxfmtSib = e.parent.children[oxfmtJ];
   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
   +					oxfmtLineFirst = oxfmtSib;
   +				}
   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
   +			}
   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
    			return ou(e, n.value, u, !1, t);
    		}
    		case "emphasis": {
   ```

2. Registriere ihn über die `patchedDependencies` deines Paketmanagers. Mit Bun oder pnpm fügst du in `package.json` hinzu:

   ```json package.json
   {
     "patchedDependencies": {
       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
     }
   }
   ```

3. Installiere neu, damit der Patch angewendet wird:

   ```package-install
   bun install
   ```

:::warning[An eine Version gebunden]
Der Patch zielt auf einen bestimmten oxfmt-Build ab — sein Diff verweist auf eine Datei, deren Name pro Release gehasht wird (`dist/markdown-*.js`). Wenn du oxfmt aktualisierst, erzeuge den Patch neu (z. B. mit `bun patch oxfmt`) oder prüfe, ob die Korrektur upstream gelandet ist und der Patch nicht mehr nötig ist.
:::

---

# Schnellstart
Source: https://useblume.dev/de/docs/quickstart

Von einem leeren Ordner zu einer laufenden Doku-Website in wenigen Befehlen. Blume benötigt **Node.js 22.12 oder neuer** und einen `docs/`-Ordner mit mindestens einer `.md`- oder `.mdx`-Datei – mehr ist nicht einzurichten.

## Installieren und ausführen

1. **Blume installieren**

    Füge das Paket zu einem neuen oder bestehenden Projekt hinzu.

    ```package-install
    npm i blume
    ```

2. **Ein Projekt erstellen**

    `blume init` stellt ein paar Fragen – wo das Projekt erstellt werden soll, wie deine
    Doku-Website heißt, welches Template verwendet wird und wo deine Inhalte liegen – und
    erzeugt dann das Nötigste: einen Inhaltsordner und eine Konfigurationsdatei. Übergib
    `--yes`, um die Abfragen zu überspringen und die Standardwerte zu übernehmen.

    ```bash
    blume init
    ```

    ```txt
    docs/
      index.mdx
    blume.config.ts
    ```

3. **Den Entwicklungsserver starten**

    Blume generiert die Laufzeitumgebung und stellt deine Doku mit Hot Reload bereit.

    ```bash
    blume dev
    ```

4. **Für die Produktion bauen**

    Statisches HTML wird nach `dist/` geschrieben, mit einem darauf aufgebauten lokalen Suchindex.

    ```bash
    blume build
    ```

:::tip
Blume funktioniert mit jedem Paketmanager und verlangt nie, dass du Astro oder Tailwind selbst einrichtest.
:::

## Schreibe deine erste Seite

Jede Seite ist Markdown oder MDX mit ein wenig Frontmatter – `title` und `description` werden automatisch als Seitenüberschrift und Einleitung gerendert. Füge dies in `docs/index.mdx` ein:

```mdx docs/index.mdx lineNumbers
---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::
```

Speichere sie, und der Entwicklungsserver lädt sofort neu. Navigation, Suche und Seiten-Metadaten werden aus deinen Dateien abgeleitet, sobald du sie hinzufügst – schreib einfach weiter, und die Website zieht mit.

## Nächste Schritte

**[Konfiguration](/docs/configuration)**

Passe Titel, Theme, Suche und Deployment an.

**[Komponenten](/docs/content/components)**

Entdecke die integrierte Komponentenbibliothek.

**[KI](/docs/configuration/ai)**

Liefere `llms.txt` und einen Ask-AI-Assistenten aus.

**[Deployment](/docs/deployment)**

Geh auf jedem statischen Host live.

---

# CLI
Source: https://useblume.dev/de/docs/reference/cli

```bash
blume <command> [options]
```

## Befehle

| Befehl | Beschreibung |
| --- | --- |
| `blume init [dir]` | Ein Projekt aufsetzen (standardmäßig interaktiv). |
| `blume dev` | Den Dev-Server mit Hot Reload starten. |
| `blume build` | Die statische Site (oder Server-Site) bauen. |
| `blume preview` | Den letzten Build in der Vorschau ansehen. |
| `blume add <item>` | Eine Quellkomponente aus der Registry installieren. |
| `blume sync` | Entfernte Inhaltsquellen erneut abrufen und neu generieren. |
| `blume eject` | Die Laufzeitumgebung in eine eigenständige Astro-App überführen. |
| `blume check` | Die Site mit `astro check` typprüfen. |
| `blume doctor` | Konfigurations- und Inhaltsprobleme diagnostizieren. |
| `blume validate` | Links in deinen Inhalten validieren. |
| `blume audit` | Die gebaute Site auf SEO- und Gesundheitsprobleme prüfen. |
| `blume eval` | Die Dokumentation testen: Ein Agent beantwortet deine Fragen ausschließlich anhand der Dokumentation. |
| `blume translate` | Die Dokumentation mit einer lokalen Agent-CLI in die konfigurierten Sprachen übersetzen. |
| `blume version [id]` | Die aktuelle Dokumentation als [archivierte Version](/docs/content/versioning) einfrieren (ohne id werden die konfigurierten Versionen aufgelistet). |

## Gängige Flags

- `blume init` — führt dich im Terminal durch einige Fragen (wo das Projekt erstellt werden soll, Site-Name, Vorlage, Inhaltsquellen); jedes der folgenden Flags beantwortet seine Frage vorab.
- `blume init --yes` — die Abfragen überspringen und mit Standardwerten aufsetzen (auch das Verhalten in CI oder wenn stdin kein Terminal ist).
- `blume init --content-dir <dir>` — den Inhaltsordner festlegen (Standard `docs`).
- `blume init --template docs|api|sdk|changelog` — aus einer Startvorlage aufsetzen (API-Referenz, SDK oder Changelog statt des einfachen Docs-Grundgerüsts).
- `blume init --package-manager npm|pnpm|yarn|bun` — die ausgegebenen nächsten Schritte auf deinen Paketmanager zuschneiden.
- `blume init --eject` — aufsetzen und anschließend zu einem eigenständigen Astro-Projekt ejecten (führt dich ersatzweise durch `blume eject`, wenn die Abhängigkeiten noch nicht installiert sind).
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — einen anderen Inhaltsordner einlesen, ohne `blume.config.ts` zu bearbeiten.
- `blume dev --debug` — ausführliches Astro-/Vite-Logging zur Fehlersuche.
- `blume dev --preview` / `blume build --preview` — Entwürfe und unveröffentlichte CMS-Inhalte einbeziehen.
- `blume build --no-strict` — trotz Diagnosefehlern bauen. Standardmäßig schlägt `blume build` bei jeder Fehlerdiagnose fehl (Exit 1), da Seiten, die die Frontmatter-Validierung nicht bestehen, aus der Ausgabe entfernt werden; mit `--no-strict` gelingt der Build und meldet, wie viele Seiten fehlen. `blume dev --strict` aktiviert dasselbe Fail-Fast-Verhalten für den Dev-Modus.
- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — die Deployment-Ausgabe, den Adapter und den Basispfad aus `blume.config.ts` überschreiben.
- `blume build --analyze` — nach dem Build die Größen der Client-JavaScript-Bundles ausgeben (größte zuerst).
- `blume build --budget-js <kb> --budget-css <kb>` — den Build fehlschlagen lassen, wenn das gesamte Client-JavaScript/CSS das Budget überschreitet, und so ein Performance-Ziel in ein CI-Gate verwandeln.
- `blume build --isolated` — in eine wegwerfbare `.blume-verify/`-Laufzeitumgebung (mit eigenem `dist/`) statt nach `.blume/` bauen, sodass ein laufender `blume dev`-Server und dein echtes `dist/` unangetastet bleiben. Siehe [Verifizieren, während der Dev-Server läuft](#verifying-while-the-dev-server-runs).
- `blume preview --host --port <n>` — den Vorschauserver binden.
- `blume sync --force` — entfernte Quellen erneut abrufen und dabei zuerst den zwischengespeicherten Snapshot verwerfen.
- `blume add <item> --force` — bereits vorhandene Dateien überschreiben.
- `blume check --preview` — beim Prüfen Entwürfe und unveröffentlichte CMS-Inhalte einbeziehen.
- `blume check --strict` — auch bei Inhaltsdiagnosen fehlschlagen, nicht nur bei Typfehlern.
- `blume check --isolated` — in einer wegwerfbaren `.blume-verify/`-Laufzeitumgebung typprüfen, sodass ein laufender `blume dev`-Server unangetastet bleibt. Siehe [Verifizieren, während der Dev-Server läuft](#verifying-while-the-dev-server-runs).
- `blume eject --yes` — die Bestätigungsabfrage überspringen.
- `blume validate --external` — zusätzlich externe Links über das Netzwerk prüfen.
- `blume validate --strict` — auch bei Warnungen mit einem Exit-Code ungleich null beenden.
- `blume validate --json` / `blume doctor --json` — Diagnosen als JSON auf stdout ausgeben (mit `code`, `severity`, `file`, `line`/`column` und `docsUrl`) für CI- und Editor-Integrationen.
- `blume audit --fail-on error|warning|info` — das CI-Gate; Standard ist `error`. `--strict` ist ein Alias für `--fail-on warning`.
- `blume audit --url <origin>` — zusätzlich ein laufendes Deployment auf Statuscodes, Response-Header und Redirect-Ketten prüfen.
- `blume audit --external` — ausgehende Links über das Netzwerk prüfen.
- `blume audit --only <check|category>` / `--skip <check|category>` — den Bericht eingrenzen, während du ihn abarbeitest (kommagetrennt).
- `blume audit --list-checks` — jede Prüfung ausgeben, die das Audit melden kann.
- `blume audit --verbose` — jede betroffene Seite mit allen Details zum jeweiligen Befund auflisten, etwa welches Linkziel defekt ist.
- `blume audit --json` — den Bericht als JSON auf stdout ausgeben.
- `blume audit --claude` / `--codex` — die Befunde an Claude Code oder Codex übergeben, um sie interaktiv zu beheben.
- `blume eval` — die Fragen in `evals.yaml` durch einen Agenten laufen lassen, der ausschließlich deine Dokumentation liest; siehe [Evals](/docs/reference/eval).
- `blume eval init` — den Agenten eine erste `evals.yaml` aus deiner Dokumentation entwerfen lassen.
- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — siehe [Evals](/docs/reference/eval) für die einzelnen Flags.
- `blume translate --claude` / `--codex` — fehlende und veraltete Seiten in deine konfigurierten Sprachen übersetzen; siehe [Translate](/docs/reference/translate).
- `blume translate --check` — Übersetzungsdrift melden und mit einem Exit-Code ungleich null beenden (das CI-Gate), ohne einen Agenten auszuführen.
- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — siehe [Translate](/docs/reference/translate) für die einzelnen Flags.

## Verifizieren, während der Dev-Server läuft

`blume dev` betreibt einen Live-Astro-Server, der in der generierten `.blume/`-Laufzeitumgebung verwurzelt ist, und regeneriert sie bei jeder Änderung. `blume build` und `blume check` regenerieren _dieselbe_ `.blume/`, sodass beide sie beschädigen würden, wenn sie bei laufendem Dev-Server ausgeführt werden — beide verweigern die Ausführung mit einem Fehler und beenden sich mit einem Exit-Code ungleich null:

```
A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

Das Flag `--isolated` ist der Notausgang. Es verlagert die gesamte generierte Laufzeitumgebung (und bei `build` auch deren Ausgabe `dist/`) in ein benachbartes Verzeichnis `.blume-verify/`, sodass die Verifizierung nie etwas schreibt, worauf der Dev-Server — oder dein echtes `dist/` — angewiesen ist:

```bash
# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist
```

`check --isolated` ist der schnelle Weg (Astro-Typ- und Template-Diagnosen, kein `dist/`); `build --isolated` ist der aufwendigere, der auch Renderfehler zur Laufzeit erkennt. Isolierte Builds überspringen die Deploy-Nachbearbeitungsschritte (Suchindex, Sync mit gehosteten Anbietern, `llms.txt`, Sitemap/robots, Weiterleitungen) — eine Verifizierung muss nur bestätigen, dass die Site kompiliert und rendert, nicht sie veröffentlichen. `--analyze` sowie die Gates `--budget-js`/`--budget-css` laufen weiterhin und werden gegen die isolierte Ausgabe gemessen. Blume fügt `.blume-verify/` automatisch zu deiner `.gitignore` hinzu.

Das ist besonders nützlich, wenn ein Coding-Agent Änderungen verifizieren muss, während du den Dev-Server geöffnet lässt. Damit einfaches `blume build`/`blume check` auch ohne das Flag isoliert — zum Beispiel in der Shell eines Agenten — setze `BLUME_RUNTIME_DIR` auf das zu verwendende Laufzeitverzeichnis:

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## Typprüfung

`blume check` führt [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) über dein Projekt aus. Es regeneriert die `.blume`-Laufzeitumgebung, synchronisiert die Inhaltstypen von Astro und meldet dann alle TypeScript-Fehler — in deiner `blume.config.ts`, in eigenen `.astro`-Seiten und in den Komponenten, die diese importieren. Es beendet sich mit einem Exit-Code ungleich null, wenn Fehler vorliegen, und eignet sich damit als `typecheck`-Schritt in CI:

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

Füge deinem Projektstammverzeichnis eine `tsconfig.json` hinzu, die Astros Konfiguration erweitert, damit verfasste Seiten `blume/*`-Importe und virtuelle Module wie `blume:data` auflösen:

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}
```

Ohne eine `tsconfig.json` im Projekt wird nur die generierte Laufzeitumgebung geprüft.

## Links validieren

`blume validate` prüft jeden in deinen Inhalten gefundenen Link:

- **Interne Seitenlinks** (`/guides/intro`, `./sibling`) müssen auf eine echte Seite verweisen — defekte werden als Fehler gemeldet.
- **Ankerlinks** (`#section`, `/guides/intro#setup`) müssen einem Anker auf der Zielseite entsprechen — der id einer Überschrift (generiert oder [festgelegt](/docs/content/syntax#custom-anchors)) oder dem `id`-Attribut eines reinen HTML-Elements —, wobei Fehlschläge als Warnungen gemeldet werden. Ids in Codeblöcken, Inline-Code, HTML-Kommentaren und `<Prompt>`-Blöcken zählen nicht.

- **Asset-Links** werden dort geprüft, wo die Datei liegt: ein absoluter Pfad (`/logo.png`) gegen das Verzeichnis `public/`, eine relative Bildeinbindung (`![](./diagram.png)`) gegen den Ordner der Seite selbst. Ein einfacher Link auf einen relativen Pfad wird weiterhin als Site-Route aufgelöst — nur Bildeinbindungen durchlaufen die Bildpipeline.
- **Externe Links** werden nur mit `--external` geprüft (standardmäßig aus, da dies das Netzwerk erfordert); tote Links (404/410/nicht erreichbar) sind Fehler, während ratenbegrenzte oder vorübergehende Antworten (403/429/5xx/Timeout) Warnungen sind.

## Die gebaute Site auditieren

`blume validate` liest deine _Inhalte_; `blume audit` liest die _gebaute Site_. Es crawlt nach einem Build das HTML in `dist/` und meldet SEO- und Site-Gesundheitsprobleme — Titel, Meta-Beschreibungen, Canonicals, Open-Graph- und X-Cards, Überschriften, hreflang, Bilder, die Sitemap, `robots.txt` und strukturierte Daten.

Da Blume die Site gebaut hat, nennt jeder Befund die Quelldatei **und die Frontmatter-Zeile**, die ihn behebt, nicht nur die URL, die ein Crawler sehen würde:

```
⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.
```

Führe es nach einem Build aus:

```bash
blume build
blume audit
```

Befunde werden nach Prüfung gruppiert statt pro Seite aufgelistet, sodass sich der Bericht wie eine To-do-Liste liest. Verwende `--verbose`, um jede betroffene Seite mit allen Details aufzuklappen, und `--only`/`--skip`, um eine Kategorie nach der anderen abzuarbeiten. `blume audit --list-checks` gibt den vollständigen Katalog aus.

### CI fehlschlagen lassen

Der Exit-Code ist der Vertrag. Standardmäßig schlägt `blume audit` nur bei Fehlern fehl — Dinge, die definitiv kaputt sind, etwa ein Link auf eine nie gebaute Seite, eine Weiterleitungsschleife oder eine ungültige Sitemap. Hinweisende Befunde (eine kurze Beschreibung, ein doppelter Titel) sind Warnungen und lassen den Build nicht fehlschlagen:

```bash
blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings
```

### Ein laufendes Deployment prüfen

Manches kann dir nur der echte Server sagen: ob eine Seite, die in `dist/` existiert, hinter einem fehlerhaften Rewrite tatsächlich einen 404 liefert, ob Antworten komprimiert werden und ob ein `X-Robots-Tag`-Header stillschweigend eine Seite deindexiert, deren HTML völlig einwandfrei aussieht. Richte das Audit auf ein Deployment, um diese Prüfungen hinzuzufügen:

```bash
blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links
```

Ausgehende Links werden abgestuft bewertet statt pauschal als Fehler gewertet: Ein 404 ist ein defekter Link, den du beheben kannst, während ein 403 oder 5xx meist auf Ratenbegrenzung oder eine fremde Störung zurückgeht und als Warnung gemeldet wird.

### Die Befunde mit einem Agenten beheben

Wenn du [Claude Code](https://claude.com/claude-code) oder [Codex](https://developers.openai.com/codex/cli) verwendest, kann das Audit seine Befunde direkt daran übergeben:

```bash
blume audit --claude   # or --codex
```

Dabei wird der vollständige JSON-Bericht — jede betroffene Seite, nicht die Drei-Seiten-Vorschau des Terminals — in eine Datei geschrieben und der Agent interaktiv mit einem Prompt geöffnet, der ihn durch die Befunde führt: die von jedem Befund genannte Quelldatei bearbeiten, den vorgeschlagenen Fix anwenden und dann `blume build` und `blume audit` erneut ausführen, bis der Bericht sauber ist. Die Sitzung ist bewusst interaktiv: Du prüfst die Änderungen über den eigenen Berechtigungsablauf des Agenten, und dem Agenten wird gesagt, dass er einen Befund niemals durch Löschen von Inhalten beheben darf.

`--only` und `--skip` grenzen die Übergabe genauso ein, wie sie den Bericht eingrenzen, sodass du eine Kategorie nach der anderen schicken kannst.

### Was es prüft und was nicht

Der Prüfumfang ist bewusst enger als der eines allgemeinen SEO-Crawlers. Vieles, was ein solcher Crawler meldet, kann einer Blume-Site gar nicht passieren — sie gibt nie `rel=nofollow` aus, und Vites inhaltsgehashte Bundles fehlen nie und leiten nie um — und das als dauerhafte Nullwerte zu melden, würde dir nur beibringen, den Bericht zu ignorieren.

Zwei Grenzen, die es klar zu benennen gilt:

- **Strukturierte Daten** werden auf Wohlgeformtheit geprüft (gültiges JSON, ein `@context`, ein `@type` an jedem Knoten). Blume validiert nicht gegen das gesamte schema.org-Vokabular oder Googles Rich-Results-Regeln.
- **Core Web Vitals** werden nicht geprüft. Sie brauchen einen echten Browser, und ein Flag, das stillschweigend nichts misst, wäre schlimmer, als keines zu haben — daher meldet `blume audit` die Ursachen für Layout-Verschiebungen, die es offline sehen _kann_ (Bilder ohne `width`/`height`, überdimensionierte Assets), und lässt den Rest vorerst außen vor.

Alles, was das Audit nicht ausgeführt hat, wird als übersprungen gemeldet, statt stillschweigend zu bestehen:

```
⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)
```

---

# Evals
Source: https://useblume.dev/de/docs/reference/eval

`blume audit` sagt dir, ob Crawler deine Dokumentation finden können. `blume eval` sagt dir, ob überhaupt jemand sie _nutzen_ kann: Ein KI-Agent liest deine Dokumentation so, wie es eine fremde Person tun würde, und versucht, daraus echte Nutzerfragen zu beantworten. Wenn die Dokumentation die Antwort nicht enthält, schlägt der Lauf fehl und benennt die Seite, die sie enthalten sollte.

```bash
blume eval
```

```
blume eval  3 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: the adapter is auto-detected
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
```

## Funktionsweise

Jede Frage durchläuft zwei Agent-Sitzungen und nutzt dabei eine Agent-CLI, die du bereits installiert hast – standardmäßig [Claude Code](https://claude.com/claude-code) oder [Codex](https://developers.openai.com/codex/cli) mit `--agent codex`. Blume hält keine API-Schlüssel vor und ruft selbst kein Modell auf.

1. **Der Reader** beantwortet die Frage _ausschließlich_ anhand deiner Dokumentation. Er läuft in einem leeren Verzeichnis, seine Datei-, Shell- und Web-Tools sind deaktiviert, und er ist mit einem privaten [MCP-Server](/docs/configuration/ai) verbunden, der deine Dokumentation bereitstellt – dieselben `search_docs`/`get_page`-Tools, die ein echter Agent gegen deine veröffentlichte Website verwendet. Er kann dein Repository nicht lesen und erlebt die Dokumentation daher genau wie ein neuer Nutzer: Was nicht geschrieben steht, existiert nicht.
2. **Der Judge** bewertet die Antwort anhand der von dir aufgeführten Fakten, ganz ohne Tools. Umschreibungen bestehen; ein fehlender oder widersprochener Fakt fällt durch – und ebenso „die Dokumentation sagt dazu nichts“.

Der MCP-Snapshot wird direkt aus deinen Content-Quellen erstellt, sodass du `blume build` nicht vorher ausführen musst und nichts irgendwohin deployed oder hochgeladen wird.

Eine Antwort, die die Dokumentation _nicht_ stützen kann, fällt selbst dann durch, wenn das Vorwissen des Agenten zufällig richtig ist – genau darum geht es. Deine Dokumentation ist die einzige Quelle, die ausgeliefert wird.

## Evals schreiben

Die Fragen liegen in `evals.yaml` im Projektstammverzeichnis. Damit ein Agent aus deiner bestehenden Dokumentation eine Startdatei entwirft:

```bash
blume eval init
```

Oder schreibe sie von Hand:

```yaml
questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - the output directory is dist
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - pagefind is the default
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped
```

- `expected` listet die Fakten auf, die eine korrekte Antwort inhaltlich nennen muss – der Judge akzeptiert Umschreibungen und weist Widersprüche zurück.
- `routes` benennt die Seite(n), die die Frage beantworten sollten. Ein Fehlschlag wird im Bericht dann der Quelldatei dieser Seite zugeordnet; ein Hinweis, der zu keiner Seite mehr passt, wird gemeldet statt stillschweigend verworfen.
- `severity: warning` behält eine Frage im Bericht, ohne die CI fehlschlagen zu lassen; `skip: true` lässt eine Frage komplett aussetzen.

Schreibe Fragen, die deine Nutzer tatsächlich stellen – die aus Support-Threads, GitHub-Issues und Onboarding-Gesprächen. Die besten Evals codieren ein Versprechen deiner Dokumentation („Deployments ohne Konfiguration“) als Frage, die bricht, sobald ein PR das Versprechen bricht.

## CI zum Fehlschlagen bringen

Der Exit-Code ist der Vertrag: Jede fehlgeschlagene Frage führt zu einem Exit-Code ungleich null. `--threshold` lockert die Schranke auf einen bestandenen Anteil, wenn du dich aus einem Rückstand herausarbeitest:

```bash
blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout
```

Der JSON-Bericht hat dieselbe Struktur aus `diagnostics` + `summary` wie `blume validate --json` und `blume audit --json`, ergänzt um die Ergebnisse pro Frage (Antwort, Score, fehlende Fakten, Kosten).

Da jede Frage zwei Modellsitzungen bedeutet, kostet ein Eval-Lauf echtes Geld und echte Minuten – die Ausgaben pro Frage werden während des Laufs ausgegeben. Ein sinnvolles CI-Setup führt `blume eval` bei Änderungen an der Dokumentation aus statt bei jedem Push.

## Die Befunde beheben

Jeder Fehlschlag benennt die fehlenden Fakten und die Seite, die sie nennen sollte. Um stattdessen den gesamten Bericht an den Agenten zu übergeben:

```bash
blume eval --fix
```

Dies schreibt den vollständigen JSON-Bericht in eine Datei und öffnet den Agenten interaktiv mit einem Prompt, der ihn durch jede fehlgeschlagene Frage führt: die benannte Seite lesen, die fehlenden Fakten im Stil der Seite ergänzen und `blume eval` erneut ausführen, bis alles besteht. Die Sitzung ist bewusst interaktiv – du prüfst die Änderungen über den Berechtigungsablauf des Agenten – und dem Agenten wird ausdrücklich untersagt, Fragen zu löschen oder erwartete Fakten abzuschwächen, um auf Grün zu kommen.

## Flags

- `--agent claude|codex` – welche Agent-CLI Reader und Judge ausführt. Standardwert: `claude`.
- `--file <path>` – die Evals-Datei. Standardwert: `evals.yaml`.
- `--threshold <0..1>` – der Mindestanteil bestandener Fragen, bevor der Lauf mit einem Exit-Code ungleich null endet. Standardwert: `1`.
- `--timeout <seconds>` – Zeitlimit des Readers pro Frage. Standardwert: `180`.
- `--json` – gibt den Bericht als JSON auf stdout aus.
- `--fix` – übergibt den Bericht nach einem fehlgeschlagenen Lauf an den Agenten, um die Dokumentation interaktiv zu korrigieren.
- `--verbose` – nimmt die vollständige Antwort des Readers unter jeden Fehlschlag auf.

---

# Frontmatter
Source: https://useblume.dev/de/docs/reference/frontmatter

Jede Seite akzeptiert das folgende Frontmatter. Alle Felder sind optional.

| Prop | Type | Default | Description |
| - | - | - | - |
| `title?` | `string` | - | Seitentitel. |
| `description?` | `string` | - | Seitenzusammenfassung. |
| `type?` | `string` | `doc` | Inhaltstyp. blog/changelog steuern Feeds. |
| `date?` | `string` | - | Veröffentlichungsdatum für Blog-/Changelog-Feeds (ISO- oder YAML-Datum). |
| `authors?` | `string \| string[] \| object[]` | - | Autor(en) des Beitrags für Blog- oder Changelog-Inhalte — ein Name oder Objekte mit einem Namen plus optionalem avatar/url und beliebigen zusätzlichen Feldern. Werden unverändert übernommen. |
| `slug?` | `string` | - | Überschreibt den generierten Slug. |
| `draft?` | `boolean` | `false` | Von Produktions-Builds ausschließen. |
| `lastModified?` | `string` | - | Legt das Datum der letzten Aktualisierung der Seite fest (ISO- oder YAML-Datum); überschreibt das aus Git abgeleitete Datum. |

## Sidebar

```yaml lineNumbers
sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page
```

`display` legt den Rendermodus der Ordnergruppe der Seite fest ([Overrides pro Gruppe](/docs/content/navigation#per-group-overrides)) und ist nur auf der `index`-Seite eines Ordners unter der generierten Sidebar sinnvoll — überall sonst (auf einer Nicht-Index-Seite, auf der `index`-Seite des Content-Roots selbst oder auf einer beliebigen Seite unter einer expliziten `navigation.sidebar`) gibt es keine Gruppe zu konfigurieren, und Blume warnt mit `BLUME_SIDEBAR_DISPLAY_IGNORED`.

## SEO

```yaml lineNumbers
seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
```

## Suche

```yaml lineNumbers
search:
  exclude: false
  tags: [api]
```

## Changelog

Changelog-Einträge (`type: changelog`) akzeptieren ein optionales `changelog`-Objekt für umfangreichere Feed- und Anzeige-Metadaten:

```yaml lineNumbers
type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features
```

`date` kann hier oder auf der obersten Ebene stehen — beide speisen den [Changelog-RSS-Feed](/docs/content#feeds). Siehe [Changelog](/docs/advanced/changelog) für die generierte Timeline-Seite und den Feed.

## Eigene Schlüssel

Jeder Schlüssel außerhalb dieser Referenz lässt den Build fehlschlagen, sodass Tippfehler früh auffallen. Projekte mit eigenen Metadaten können zusätzliche Schlüssel über [`frontmatter.extend`](/docs/configuration#frontmatter) in `blume.config.ts` zulassen, jeweils validiert durch ein Schema, das das Projekt bereitstellt:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

```yaml page.mdx
---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---
```

Schemas werden über die [Standard-Schema](https://standardschema.dev)-Schnittstelle akzeptiert, sodass Zod (in der Version, die Ihr Projekt installiert), Valibot und ArkType allesamt funktionieren. Jeder deklarierte Schlüssel wird auf jeder Seite validiert — auch fehlende —, sodass ein erforderliches Schema den Schlüssel site-weit erzwingt; markieren Sie ihn mit `.optional()`, um nur dort zu validieren, wo er vorhanden ist. Alle übrigen Schlüssel bleiben streng validiert, und eingebaute Felder können nicht neu deklariert werden.

### Schlüssel pro Typ

Um Schlüssel nur für einen Inhaltstyp zu verlangen — den `status` eines RFC, die `severity` eines Incident-Reports — deklariere sie stattdessen unter [`content.types`](/docs/configuration#content), geschlüsselt nach dem Frontmatter-`type`, für den sie gelten:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

```yaml rfcs/openapi-request-schemas.mdx
---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---
```

Schlüssel pro Typ folgen denselben Validierungsregeln wie `extend`, beschränkt auf Seiten, deren aufgelöster `type` passt — einschließlich Seiten ohne `type`, wenn die Deklaration für [`content.defaultType`](/docs/configuration#content) gilt. Ein Schlüssel gehört zu einer Deklaration, site-weit oder pro Typ, nicht zu beiden. Und ein Schlüssel, der nur für einen anderen Typ deklariert ist, bleibt anderswo unbekannt, sodass ein versehentliches `status` auf einer gewöhnlichen Doc-Seite den Build weiterhin fehlschlagen lässt.

Eine Seite, die die Validierung nicht besteht, lässt `blume build` mit einer Diagnose fehlschlagen, die Datei und Schlüssel benennt. Mit [`--no-strict`](/docs/reference/cli#common-flags) läuft der Build dennoch erfolgreich durch und die fehlerhaften Seiten werden aus der Ausgabe entfernt — die Build-Zusammenfassung meldet, wie viele.

Schemas werden aus `blume/schema` für Editor- und Migrations-Tooling exportiert.

---

# Übersetzen
Source: https://useblume.dev/de/docs/reference/translate

Sobald [i18n](/docs/content/i18n) aktiviert ist, veraltet jede Änderung an einer Quellseite stillschweigend deren Übersetzungen. `blume translate` schließt diesen Kreis: Es berechnet exakt, welche Seiten in jeder Locale fehlen oder veraltet sind, übersetzt sie headless mit einer lokalen Agent-CLI und hält in einem eingecheckten Ledger fest, was es getan hat, damit der nächste Lauf – und CI – weiß, was aktuell ist.

```bash
blume translate --claude
```

```
blume translate  3 item(s) · 2 locale(s) · Claude Code

  ✔ docs/guides/install.mdx → fr 24.2s $0.11
  ✔ docs/guides/install.mdx → de 22.8s $0.10
  ✔ meta titles (2) → de 4.1s $0.01

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
```

## Funktionsweise

Blume besitzt die Pipeline; der Agent übersetzt nur Text. Für jede Datei, die Arbeit erfordert, baut Blume einen Übersetzungs-Prompt, führt die Agent-CLI headless mit deaktivierten Datei-, Shell- und Web-Tools aus, validiert die Struktur der Antwort und schreibt die Zieldatei selbst – [Claude Code](https://claude.com/claude-code) mit `--claude` oder [Codex](https://developers.openai.com/codex/cli) mit `--codex`. Blume hält keine API-Schlüssel und ruft selbst kein Modell auf.

Jeder validierte Schreibvorgang wird in `blume.translations.json` im Projektstammverzeichnis festgehalten: für jede Quelldatei und Locale ein Hash der Quelle zum Zeitpunkt der Übersetzung. **Committe diese Datei.** So erkennt ein erneuter Lauf den Unterschied zwischen „bereits übersetzt“ und „übersetzt, aber die Quelle hat sich seitdem geändert“ – und genau das macht die CI-Schranke möglich.

Das Ledger wird nach jeder fertiggestellten Datei geschrieben, sodass beim Abbrechen eines langen Laufs (Strg+C) höchstens die gerade laufenden Übersetzungen verloren gehen – der nächste Lauf macht dort weiter, wo du aufgehört hast. Standardmäßig laufen 4 Dateien gleichzeitig; erhöhe den Wert mit `--concurrency`, wenn deine Maschine und die Rate Limits des Agenten es zulassen.

Erneute Läufe sind inkrementell: Eine Quelle, die sich seit ihrer letzten Übersetzung nicht geändert hat, wird übersprungen – wenn du also `blume translate` nach der Bearbeitung einer Seite ausführst, wird eine Seite pro Locale übersetzt. Wird eine veraltete Seite erneut übersetzt, bekommt der Agent die vorhandene Übersetzung gezeigt und wird angewiesen, deren Register, Dialekt und Terminologie zu übernehmen – eine Quelländerung von einem Absatz erzeugt einen Übersetzungs-Diff von einem Absatz, keine komplette Neuübersetzung.

Eine Erstübersetzung hat keinen Präzedenzfall, an dem sie sich orientieren könnte – lege die Wahl deshalb vorab mit [`style` auf der Locale](/docs/content/i18n) fest (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`). Die Vorgabe wandert in jeden Übersetzungs-Prompt mit, und wo eine vorhandene Übersetzung ihr widerspricht, gewinnt `style` – eine Neuübersetzung schiebt ältere Seiten also ebenfalls in Richtung des konfigurierten Stils.

## Was übersetzt wird

- **Seiten** – `.md`/`.mdx`-Dateien in der Standard-Locale. Der Agent übersetzt die Prosa und nur die für Menschen sichtbaren Frontmatter-Werte (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`). Die Ziele richten sich nach deinem Parser: `fr/guides/install.mdx` bei `dir`, `guides/install.fr.mdx` bei `dot`.
- **Navigationstitel von Ordnern** – beim `dir`-Parser werden die benötigten [`meta.ts`](/docs/content/meta)-Titel jeder Locale in einem gebündelten Aufruf übersetzt, und die generierte `meta.ts` pro Locale übernimmt jeden anderen Schlüssel (`order`, `pages`, `icon`, `collapsed`) wortwörtlich, damit die Sidebar der Locale ihre Reihenfolge behält.

Übersetzungen, die du von Hand geschrieben hast, werden **übernommen, niemals überschrieben**: Eine Übersetzung, die existiert, aber keinen Ledger-Eintrag hat, wird als aktuell gestempelt und unangetastet gelassen. Nur `--force` übersetzt sie erneut.

## Validierung

Dem Agenten wird bei der Struktur nie vertraut. Vor dem Schreiben prüft Blume jede Antwort und baut die Datei aus der Quelle neu auf:

- Das Frontmatter wird aus den Daten der Quelldatei rekonstruiert, wobei nur die sechs übersetzbaren Werte überlagert werden – vom Agenten erfundene Schlüssel werden verworfen, von ihm gelöschte Schlüssel werden wiederhergestellt, und `slug`, `icon`, `order` sowie Datumsangaben stammen konstruktionsbedingt wortwörtlich aus der Quelle.
- Die Anzahl der Code-Fences muss mit der Quelle übereinstimmen, der Textkörper darf nicht leer sein, und das Frontmatter muss parsebar sein.

Eine Antwort, die die Validierung nicht besteht, schreibt nichts – das Element wird als fehlgeschlagen gemeldet und der Lauf fährt fort. Alles Erfolgreiche bleibt im Ledger gestempelt, sodass ein erneuter Lauf nur die Fehlschläge wiederholt.

## CI zum Fehlschlagen bringen

`blume translate --check` ist die schreibgeschützte Schranke: Sie meldet jedes fehlende und veraltete Paar und beendet sich mit einem Exit-Code ungleich null, wenn es Abweichungen gibt – ohne einen Agenten auszuführen oder irgendetwas zu schreiben.

```bash
blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

Der JSON-Bericht trägt dieselbe `diagnostics`- + `summary`-Struktur wie `blume validate --json`, `blume audit --json` und `blume eval --json`, wobei die Abweichungen pro Locale gruppiert sind. Von Hand verfasste (nicht erfasste) Übersetzungen lassen die Schranke nie fehlschlagen.

## Einschränkungen

- Die Übersetzung von Meta-Titeln gibt es nur beim `dir`-Parser – der `dot`-Parser hat keinen Mechanismus für `meta.ts` pro Locale. Eine `meta.ts`, die per Default eine Funktion exportiert, wird mit einer Warnung übersprungen; verfasse die Kopie für diese Locale von Hand.
- Remote- und CMS-gestützte Quellen werden übersprungen: Es gibt keine lokale Datei, in die die Übersetzung geschrieben werden könnte.
- Die Beschriftungen der Header-Tabs liegen in `blume.config.ts`, nicht im Content – lokalisiere sie dort mit [Label-Maps pro Locale](/docs/content/navigation#tabs).
- Die Übersetzungsqualität ist die des Agenten. Prüfe die Ausgabe wie jeden anderen Beitrag – das Ledger garantiert nur Aktualität, nicht Sprachfluss.

## Flags

- `--claude` / `--codex` – welche Agent-CLI übersetzt. Genau eines ist erforderlich (außer bei `--check`).
- `--check` – Abweichungen melden und mit einem Exit-Code ungleich null beenden, ohne etwas zu schreiben.
- `--concurrency <n>` – parallele Agent-Sitzungen. Standardwert `4`, Maximum `16`.
- `--locale <codes>` – kommagetrennte Ziel-Locales (standardmäßig jede Locale außer der Standard-Locale).
- `--force` – alles neu übersetzen, einschließlich aktueller und von Hand verfasster Dateien.
- `--timeout <seconds>` – Zeitlimit des Agenten pro Datei. Standardwert `600`; die Obergrenze existiert, um hängende Agenten abzufangen, sodass große Seiten genug Zeit zum Fertigwerden haben.
- `--json` – den Bericht als JSON auf stdout ausgeben, in beiden Modi.

---

# Introduction
Source: https://useblume.dev/docs

Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade docs site — navigation, search, theming, Open Graph images, and a rich component library — with no app boilerplate to write or maintain.

**[Quickstart](/docs/quickstart)**

Install Blume and ship your first page in minutes.

**[Configuration](/docs/configuration)**

Tune the title, theme, search, and deployment.

## Why Blume exists

Docs should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.

Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start by replacing the built-in components, modifying the single configuration file, or even ejecting if you want the Astro site directly. The [FAQ](/docs/faq) walks through how that compares to Mintlify, Fumadocs, and the rest.

## What makes Blume different

### Fast by default

Blume builds on Astro and Vite and renders static HTML by default — fast, cacheable, and cheap to host. The core theme ships no client framework JS so pages score well on Core Web Vitals out of the box. Dev startup and hot reload feel Vite-native, and you opt into server features only when you need them.

### AI-ready out of the box

Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/configuration/ai), serves any page's raw Markdown by appending `.md` to its URL, exposes a [JSON API described by OpenAPI](/docs/configuration/ai#json-api), and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/configuration/ai#mcp-server) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.

### Zero configuration — even the template

A folder of docs is a complete project. There's no starter to clone, no Astro or Tailwind to set up, and no template to maintain. Navigation is inferred from your files, [search](/docs/configuration/search) works in dev and production without a hosted service, and theming is a handful of tokens. Everything has a sensible default; configuration is something you reach for, not something you start with.

### Type-safe to the core

Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/content/meta) are real TypeScript — validated by a schema and authored with `defineConfig` and `defineMeta`. Your editor autocompletes every option and catches typos, invalid values, and missing fields as you type, long before a build. Configuration is code you can refactor, compute, and trust — not loosely-typed YAML.

## Everything included

- **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with [no imports](/docs/content/components).
- **Local search** — Orama works in dev and production; Pagefind is one flag away for large sites. No hosted index.
- **AI** — [`llms.txt`, raw Markdown URLs, a JSON API with an OpenAPI description, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server](/docs/configuration/ai).
- **Navigation** — inferred from files, refined with `meta.ts` or config.
- **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
- **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.
- **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.

## How it works

The Blume CLI discovers your content, builds a content graph, and generates a hidden Astro project under `.blume/` that it drives for dev and build. The generated runtime is an implementation detail — you write Markdown, Blume handles the rest — until you choose to eject and own it.

## Next steps

**[Configuration](/docs/configuration)**

Tune the title, theme, search, and deployment.

**[Components](/docs/content/components)**

Explore the built-in component library.

**[AI](/docs/configuration/ai)**

Ship `llms.txt` and an Ask AI assistant.

**[CLI](/docs/reference/cli)**

Every `blume` command and flag.

---

# OpenAPI / AsyncAPI
Source: https://useblume.dev/docs/advanced/api-reference

Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, generated code samples, and an interactive [Try it](#try-it-playground) panel. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc. The config below points Blume at the public Petstore spec as an example.

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}
```

That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically. Documenting a GraphQL API instead? See the [GraphQL reference](/docs/advanced/graphql).

The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the operations sidebar for the native renderer:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
Operations are indexed for search by their **summary and tag**. The rendered schema tables and code samples aren't full-text indexed; search matches an operation's title and section, then links to its own page.
:::

## A local spec

A relative path is resolved from your project root and read at build time. Both JSON and YAML work:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}
```

## Route

`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the route you point a navigation tab at):

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}
```

## Code samples and schemas

`codeSamples` picks which languages render per operation (built in: `curl`, `js`, `python`); `expandSchemas` starts nested schema rows expanded rather than collapsed:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}
```

## Try it playground

Operation pages rendered natively ship an interactive **Try it** panel by default. Blume generates the form from the operation itself: an input per path, query, and header parameter, a body editor built from the request-body schema, everything prefilled from the spec's examples. A server picker lists the spec's `servers`, with a free-text field for any other base URL, and auth inputs match the operation's [resolved security](#authorization) — bearer token, API key, and basic credentials, with OAuth2 as a token paste field (bring an access token; Blume doesn't run the flow).

The panel and the code samples stay in lockstep: values typed into the form update the generated samples live, so a copied curl command always matches exactly what **Send** would do. And it stays out of the way — the panel is server-rendered collapsed, and its JavaScript loads only when a reader first opens it. Readers who never touch it download none of it.

`playground: false` is the entire off switch:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}
```

### Credentials

Credentials typed into the auth inputs stay in memory and vanish on reload. Checking **Remember on this device** persists them in `localStorage`, scoped to the docs origin — they're never sent anywhere except the API being called. Code samples keep showing placeholders (`YOUR_TOKEN` and friends) whatever's typed, unless the reader toggles **Include my values in samples**.

### CORS and the proxy

As with the [Scalar renderer](#the-scalar-renderer), requests go **directly from the browser** to the target API, so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). For APIs that can't, set `playground.proxy`: a URL routes requests through a proxy you host, and `true` enables the built-in `/_api-proxy` route — which needs a server build, so it requires [`deployment.output: "server"`](/docs/deployment#server-rendering):

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}
```

The built-in proxy only forwards requests to the origins your specs declare in `servers` — including across redirects — so a public docs deployment can't be aimed at other hosts on its network. A **Custom base URL** typed into the panel isn't a documented server: with the proxy enabled, requests to it are refused with a 403.

## Multiple specs

Use `sources` to publish more than one spec. Each source gets its own overview route, operation pages, and header tab. Give each a `label` (used for the tab and to derive its route), or set an explicit `route`:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}
```

`spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.

### Per-source indexing

Generated pages participate in search, `llms.txt`, and crawler indexing by default. A secondary or overlapping spec can opt out of any surface without hiding its pages or removing it from navigation:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}
```

- `includeInSearch: false` keeps the source's overview and operations out of site search.
- `includeInLlms: false` keeps them out of both `llms.txt` files.
- `noindex: true` adds crawler noindex metadata and removes the pages from the sitemap.

Each operation page's meta description is the operation's own `description` (or `summary`), followed by a generated sentence naming the endpoint — "Reference for the `GET /pets` endpoint in the Petstore API." — so a spec of terse one-line summaries still ships a distinct, snippet-length description per page. That sentence is English. On a site whose spec prose is written in another language, set `seoDescriptionSuffix: false` on the source to drop it and describe each page with the authored prose alone; an operation with neither a `description` nor a `summary` falls back to its title (`GET /pets`), so no page ships an empty description:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}
```

With the [Scalar renderer](#the-scalar-renderer), only `noindex` applies — a Scalar-rendered reference already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.

## Authorization

Operations that declare [security requirements](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) render an **Authorization** section above their parameters, and the generated code samples send a placeholder credential (`Authorization: Bearer YOUR_TOKEN`, an API-key header, or a query key — whatever the scheme calls for). There's nothing to configure: Blume reads `security` from the spec, so the reference always matches what the API actually enforces.

The OpenAPI semantics carry over as written:

- An operation's own `security` overrides the document's root default; `security: []` marks it **public** and renders no Authorization section.
- Multiple requirement entries are alternatives — rendered as "or" groups; every scheme inside one entry is required together. The first alternative feeds the code samples.
- An empty `{}` entry means auth is **optional** for that operation, and the section says so.
- OAuth2 scopes are listed per scheme; scheme `description`s from `components.securitySchemes` render inline.

## The Scalar renderer

The native renderer is the default — operation pages, search integration, and the [Try it playground](#try-it-playground) above are all its work. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference UI — its own sidebar, search, theme, and request client on a single route — set `renderer: "scalar"`:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}
```

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`, and Blume's [`playground`](#try-it-playground) config doesn't apply to it. It does follow Blume's light/dark toggle: the embed is pinned to the page's theme when it mounts and switches with it, so Scalar's own theme switch is hidden (set `scalar.forceDarkModeState` or `scalar.darkMode` to hand color mode back to Scalar). Scalar brings its own request client, which calls your **target API directly from the browser** (the `playground.proxy` route isn't available here), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` applies 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 — and the same native renderer. Each `send`/`receive` operation becomes a real page with message payload and header schema tables, channel parameters, protocol bindings, an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups), and a [Try it](#try-it-for-events) message composer. Only the default route differs (`/events`):

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}
```

AsyncAPI **2.x specs are normalized to 3.x automatically** with the official AsyncAPI converter, so `publish`/`subscribe` channels map onto `send`/`receive` operation pages with stable URLs — later upgrading the spec file itself through the converter moves nothing. Operations group by tag; untagged operations group under their channel address.

Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on the `openapi` block; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.

Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags (`seoDescriptionSuffix` too — the generated sentence names the channel and action instead of an endpoint), and search indexing by operation summary and tag.

Setting `renderer: "scalar"` opts back into the embedded Scalar SPA, where — as with OpenAPI — only `noindex` applies. Scalar has no AsyncAPI playground of its own; its embed auto-detects the document type and renders channels, operations, messages, and a Models section, so that swap trades the composer away.

### Try it for events

Operation pages rendered natively ship a **Try it** panel here too, on the same terms as the [OpenAPI panel](#try-it-playground): server-rendered collapsed, with its JavaScript loaded only when a reader first opens it.

Whatever the protocol, the panel opens with a payload editor prefilled from the message's `examples` — or, when the message declares none, from a value sampled out of the payload schema — validated against the message payload schema as you type. Under it sit an input per channel parameter and a server picker fed by the channel's `servers`, with a free-text field for any other URL. The protocol-aware code samples stay in lockstep with the form exactly as curl, js, and python do on an HTTP operation: the channel address template is filled in with the parameter values you type, so a copied `wscat`, `WebSocket`, `kcat`, or `mosquitto_pub` snippet matches what the form says.

Live connect is WebSocket-only. On a `ws` or `wss` binding the panel connects to the resolved channel URL, shows the connection state, and logs every frame with a timestamp. AsyncAPI 3 states an action from the API's side, and the panel follows it: a `receive` operation is one the API receives from you, so it gets a **Send** button that publishes the composed payload; a `send` operation only streams messages at you, so it connects and logs. There's no reconnect logic — once a socket closes, it stays closed until you connect again. Kafka, MQTT, AMQP, and every other protocol get the composer and the copyable CLI samples, and the panel says as much on the page: Blume doesn't fake broker connectivity from a browser tab.

`asyncapi.playground` mirrors `openapi.playground` — on by default with the native renderer, and `false` is the entire off switch:

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}
```

:::note
`playground.proxy` doesn't apply to event operations. It forwards HTTP requests, and a WebSocket connect goes straight from the browser to the server named in the URL, so there's nothing for a proxy to sit in front of.
:::

The event composer collects no broker credentials. Each operation page's **Authorization** section documents what the broker expects, and a WebSocket connect carries only what's already in the URL. Nothing is persisted for event operations.

---

# Blog
Source: https://useblume.dev/docs/advanced/blog

A blog in Blume is just content with a type. Mark a page `type: blog` and Blume gives it an RSS feed and richer article metadata automatically. Unlike the [changelog](/docs/advanced/changelog), there's no generated index page — you compose the landing page yourself, which keeps the design entirely in your hands.

## Write a post

A post is a regular `.md` or `.mdx` page with `type: blog` in its frontmatter. By convention posts live under `blog/`, but the type — not the folder — is what matters:

```mdx blog/introducing-blume.mdx lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
```

Give every post a `date` so feed items sort newest-first and carry a `pubDate`, and a `description` — it's used for both the feed summary and SEO.

## The RSS feed

Blume builds a blog feed at **`/blog/rss.xml`**, sorted newest-first by `date`. Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">` tag on every page so readers discover it automatically.

The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

Remove `"blog"` from `rss.types` to skip the feed.

## Structured data

When [structured data](/docs/configuration/seo#structured-data) is on, each post is emitted as a schema.org **`BlogPosting`** with its description and publish date — the richer article type search engines expect for blog content.

## Building an index

Blume doesn't generate a `/blog` landing page, so you build one. The simplest option is a content page that links to each post by hand:

```mdx blog/index.mdx lineNumbers
---
title: Blog
description: News and writing from the team.
---

<CardGroup cols={2}>
  <Card title="Introducing Blume" href="/blog/introducing-blume">
    Why we built a markdown-first docs framework.
  </Card>
</CardGroup>
```

To list posts automatically instead, add a [custom page](/docs/advanced/custom-pages) at `pages/blog/index.astro` that reads from Astro's `docs` content collection and pairs each entry with its route from `blume:data`:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    date: entry.data.date,
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }))
  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

See [Custom Pages](/docs/advanced/custom-pages#using-the-site-layout) for wrapping this in the full site layout.

**[Custom Pages](/docs/advanced/custom-pages)**

Mount the blog index and read from blume:data.

**[SEO](/docs/configuration/seo)**

Feeds, Open Graph images, and structured data.

---

# Changelog
Source: https://useblume.dev/docs/advanced/changelog

Blume ships a changelog out of the box. Write each release as a normal content file, mark it `type: changelog`, and Blume collects every entry into a generated timeline page and an RSS feed — no layout to build, no list to maintain. Or skip the files entirely and [source your changelog from GitHub Releases](#from-github-releases).

## Write an entry

A changelog entry is a regular `.md` or `.mdx` page with `type: changelog` in its frontmatter. By convention they live under `changelog/`, but the type — not the folder — is what matters:

```mdx changelog/v1-2-0.mdx lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks
```

Give every entry a `date` so the timeline and feed sort newest-first. An unquoted YAML date is fine — Blume normalizes it.

### The `changelog` object

The optional `changelog` object adds richer metadata for the timeline and feed:

| Prop | Type | Default | Description |
| - | - | - | - |
| `changelog.version?` | `string` | - | Release version. Falls back to a v-prefixed label when there's no title. |
| `changelog.category?` | `string` | - | Shown as a tag beside the entry, e.g. Release, Features, Fixes. |
| `changelog.date?` | `string` | - | Publish date. May live here or at the top level — both feed the timeline and RSS feed. |

## The timeline page

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. 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.

Because this page is generated rather than authored, it isn't part of the content tree — so a header [tab](/docs/content/navigation#tabs) pointing at `/changelog` resolves to the newest entry instead. Give the tab an `href` to land on the index itself:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

### 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. Blume's own [changelog](/changelog) is built this way:

```ts blume.config.ts
content: {
  sources: [
    { type: "filesystem", root: "content" },
    {
      type: "github-releases",
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    },
  ],
}
```

The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. Each release page also gets a unique meta description summarized from its notes — markdown stripped, section headings and changeset commit-hash prefixes dropped, trimmed to the search-snippet length [`blume audit`](/docs/reference/cli#auditing-the-built-site) checks for — instead of falling back to the site description. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.

## The RSS feed

Blume also builds a changelog feed at **`/changelog/rss.xml`**, sorted newest-first by `date`. Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">` tag on every page so readers discover it automatically.

The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

Remove `"changelog"` from `rss.types` to skip the feed while keeping the timeline.

## Structured data

When [structured data](/docs/configuration/seo#structured-data) is on, each changelog entry is emitted as a schema.org **`TechArticle`** with its description and publish date, so search engines can index releases as dated articles.

**[Frontmatter](/docs/reference/frontmatter#changelog)**

The full changelog frontmatter schema.

**[Custom Pages](/docs/advanced/custom-pages)**

Replace the generated timeline with your own layout.

---

# Custom Pages
Source: https://useblume.dev/docs/advanced/custom-pages

Most of a Blume site is Markdown, but sometimes you need a route that _isn't_ a doc — a landing page, a pricing page, a hand-built blog or changelog index, or an interactive dashboard. Drop an `.astro` file under your **pages** folder and Blume mounts it as a real route, right alongside your content.

## Add a page

Create a `pages/` folder at your project root and add an `.astro` file:

```astro pages/pricing.astro lineNumbers
---
import data from "blume:data";
---

<h1>Pricing for {data.config.title}</h1>
```

`blume dev` picks it up immediately and `blume build` prerenders it to static HTML. The folder name is configurable with [`content.pages`](/docs/configuration#content) (default `"pages"`).

Custom pages keep their original location on disk, so relative imports, component imports, and [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) all work exactly as they do in a plain Astro project — Blume mounts each file where it sits rather than copying it.

## Files and routes

Each file's path under the pages folder becomes its route. `index` maps to the parent folder, and dynamic `[param]` segments are preserved:

| File                      | Route         |
| ------------------------- | ------------- |
| `pages/pricing.astro`     | `/pricing`    |
| `pages/blog/index.astro`  | `/blog`       |
| `pages/blog/[slug].astro` | `/blog/:slug` |
| `pages/changelog.astro`   | `/changelog`  |

A custom page **wins** over a generated route at the same path. Adding `pages/changelog.astro`, for example, replaces Blume's [generated changelog timeline](/docs/advanced/changelog) with your own.

## Reading site data

Import `blume:data` to read the same resolved config, navigation, routes, and feeds the rest of the site uses:

```astro pages/all-pages.astro lineNumbers
---
import data from "blume:data";
---

<h1>All pages</h1>
<ul>
  {
    data.routes
      .filter((route) => route.indexable)
      .map((route) => (
        <li>
          <a href={route.path}>{route.title}</a>
        </li>
      ))
  }
</ul>
```

Inside a Blume project the module is typed automatically. You can also pull the shape in explicitly — for typed helpers, props, or your own tsconfig — with `import type { BlumeData } from "blume"`:

```ts
import type { BlumeData, BlumeRoute } from "blume";

const indexable = (data: BlumeData): BlumeRoute[] =>
  data.routes.filter((route) => route.indexable);
```

The module exposes:

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `BlumeDataConfig` | - | Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host, and the REST api base — null when unset), search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom. |
| `navigation` | `Navigation` | - | The sidebar, tabs, and selectors inferred from your content (default locale). |
| `navigationByLocale` | `Record<string, Navigation>` | - | Per-locale navigation trees, keyed by locale code. Empty unless i18n is configured. |
| `routes` | `BlumeRoute[]` | - | Every content page: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }. |
| `feeds` | `BlumeFeed[]` | - | Generated RSS feeds: { href, title }. |
| `fontCssVars` | `string[]` | - | CSS variable names for the configured fonts (Astro <Font> integration). |
| `ui` | `UIStrings` | - | Resolved UI chrome strings for the default locale (search, sidebar, and footer labels). |
| `uiByLocale` | `Record<string, UIStrings>` | - | Per-locale UI strings, keyed by locale code. Empty unless i18n is configured. |

`routes` carries page metadata but not frontmatter like `type` or `date`. To build a list filtered by content type — a blog or changelog index — pair it with Astro's `docs` content collection, which holds the frontmatter:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

// Each route's id matches its collection entry id.
const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

## Runtime helpers

`blume/runtime` bundles the common data patterns so you don't reach into `blume:data` internals.

**`getBlumeCollection(data, query?)`** selects content routes — filtered by collection, locale, or path prefix, with drafts and hidden pages excluded and the result sorted by path — which is exactly what a custom index needs:

```astro pages/blog/index.astro lineNumbers
---
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const posts = getBlumeCollection(data, { prefix: "/blog" });
---

<ul>
  {posts.map((post) => (
    <li><a href={post.path}>{post.title}</a></li>
  ))}
</ul>
```

**`<BlumePage>`** renders a content entry's body inside a custom page, with Blume's built-in MDX components (callouts, cards, steps…) already wired in — for featuring a doc on a landing page or building a bespoke index that shows real content:

```astro pages/index.astro lineNumbers
---
import BlumePage from "blume/components/BlumePage.astro";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const [intro] = getBlumeCollection(data, { prefix: "/docs" });
---

{intro && <BlumePage id={intro.entryId} />}
```

Pass `components` to add your own overrides or islands (which live in the generated runtime and aren't imported by default), and `collection` to read from a collection other than `"docs"`.

## Using the site layout

`RootLayout` gives a custom page the full docs chrome — header, sidebar, search, TOC, and theme — by wrapping it in the same 3-column grid the generated pages use. For a landing or marketing page that grid is in the way, so reach for **`PageLayout`** instead: it provides the document shell, header, theme, and fonts, then a single full-width `<slot />` (no sidebar, no prose, no TOC). An optional `footer` slot renders after `<main>`:

```astro pages/index.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
import Footer from "./_home/Footer.astro";

const { config } = data;
---

<PageLayout
  site={{ title: config.title, description: config.description }}
  logo={config.logo}
  banner={config.banner}
  analytics={config.analytics}
  navigation={data.navigation}
  favicon={config.favicon}
  fontCssVars={data.fontCssVars}
  themeMode={config.theme.mode}
  searchEnabled={config.search.enabled}
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  page={{ title: "Acme — the fastest docs", description: config.description }}
>
  <section class="mx-auto max-w-5xl px-6 py-24">
    <h1>Build docs that fly</h1>
  </section>
  <Footer slot="footer" />
</PageLayout>
```

The header a custom page gets is the same one the docs pages get, so the chrome that lives in it comes along: search, the theme toggle, the language switcher, and — when [Ask AI](/docs/configuration/ai) is configured — the Ask AI trigger. None of it needs wiring up per page. Pass `askEnabled={false}` to leave the Ask trigger off one page while keeping it everywhere else.

Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generated `og:image` automatically: Blume renders an Open Graph card for every static custom page — the home included, the most-shared URL — served at `/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title with the description as its eyebrow; a deeper page is titled from its last path segment. Set `ogImage` or `canonical` explicitly to override either. `ogImage` takes a root-relative path — a file in `public/`, resolved against [`deployment.site`](/docs/deployment) to the absolute URL crawlers need — or an external URL, which passes through untouched:

```astro pages/index.astro lineNumbers
<PageLayout
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  ogImage="/opengraph-image.png"
  ogImageAlt="Acme — the fastest docs"
  ogImageSize={{ width: 1200, height: 630 }}
  page={{ title: config.title }}
>
  <!-- page content -->
</PageLayout>
```

Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image. The generated card declares its size and alt text to crawlers on its own; for your own `ogImage`, pass `ogImageAlt` and `ogImageSize` alongside so the share card gets the same treatment.

The page also emits schema.org JSON-LD — the same `WebSite` graph the docs pages carry, so the home page (usually a custom page) isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with the [`structuredData`](/docs/configuration/seo) config, or `structuredDataEnabled={false}` to turn it off for one page.

`page.title` is used verbatim as the document title (no `- siteTitle` suffix), since marketing pages usually set their own. To give a custom page the full docs chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the layout the generated pages use. Pull the required props straight from `blume:data`:

```astro pages/pricing.astro lineNumbers
---
import RootLayout from "blume/components/layout/RootLayout.astro";
import data from "blume:data";
---

<RootLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  banner={data.config.banner}
  navigation={data.navigation}
  page={{ title: "Pricing", route: "/pricing" }}
  headings={[]}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  indexable={true}
>
  <h1>Pricing</h1>
</RootLayout>
```

:::note
`RootLayout` is part of the generated runtime, so its props can change between releases. When you want a layout that's fully yours, [`blume eject`](/docs/configuration/customization#eject) turns `.blume/` into a standard Astro project you own outright.
:::

## 404 page

Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes. Under the message, a **Where to look next** list links every top-level section plus the `sitemap.xml` and [`llms.txt`](/docs/configuration/ai#llmstxt) indexes when they exist, so a reader — or an agent that followed a stale URL — has a way back.

The page also has a Markdown twin at `/404.md` and a JSON twin at `/404.json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details) with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set), plus the [`openapi.json`](/docs/configuration/ai#json-api) description when the JSON API is on. On a [Vercel server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation), or asks for a `.md` URL no page backs, gets the Markdown body with the `404` status instead of the HTML shell; one that sends `Accept: application/json`, or asks for a `.json` URL no file backs, gets the problem document — so an agent never has to parse a page of chrome to learn where to go next.

To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped. Build it like any other custom page, in `PageLayout` or `RootLayout`:

```astro pages/404.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
---

<PageLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  navigation={data.navigation}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  page={{ title: "Page not found", route: "/404" }}
  noindex={true}
>
  <section class="mx-auto max-w-2xl px-6 py-24 text-center">
    <h1>This page took a wrong turn</h1>
    <a href="/">Back to home</a>
  </section>
</PageLayout>
```

To keep the default design but change its wording — including for other languages — override the `notFound` [UI strings](/docs/content/i18n) (`title`, `description`, `home`) via `i18n.ui`.

## Interactive pages

Custom pages are ordinary Astro, so you can drop in React (or any framework) [islands](/docs/configuration/customization#interactive-islands) with a hydration directive. React switches on automatically the moment your project contains a `.tsx` or `.jsx` file.

**[Customization](/docs/configuration/customization)**

Component overrides, React islands, the registry, and eject.

**[Blog](/docs/advanced/blog)**

Author posts and build a custom blog index.

---

# GraphQL
Source: https://useblume.dev/docs/advanced/graphql

Point Blume at a GraphQL schema and it generates a native API reference: one **real page per root field** — queries, mutations, and subscriptions — plus one **page per named type** (objects, input objects, enums, interfaces, unions, and custom scalars). Every page shows arguments, defaults, deprecations, and usage backlinks, alongside a generated example operation, code samples, and an interactive [Try it](#try-it-playground) panel. Because each page is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
}
```

That mounts the reference at `/graphql` (an overview page), with root fields at `/graphql/queries/<field>`, `/graphql/mutations/<field>`, and `/graphql/subscriptions/<field>`, and types grouped by kind at `/graphql/objects/<type>`, `/graphql/enums/<type>`, and so on.

The `spec` is either a path to a local file in your project or an `http(s)` URL, and accepts two formats:

- **SDL text** — a `.graphql` file with type definitions.
- **An introspection result** — the JSON produced by running the standard introspection query, either the raw `{ "__schema": … }` shape or the full `{ "data": { "__schema": … } }` response envelope.

The `endpoint` is the live GraphQL API URL. A schema, unlike an OpenAPI document, names no server — so the endpoint is what the Try it panel and the generated code samples target. Leave it off and the samples render with a placeholder URL readers replace.

The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the reference sidebar:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}
```

## Generated examples

Every operation page carries a complete, valid example operation — one variable per argument, typed off the schema, with a bounded-depth selection set over the return type — plus matching example variables and an example response that mirrors the same selection. Code samples show the exact HTTP request (a JSON `POST` of `{ query, variables }`) in each configured language:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  codeSamples: ["curl", "js"],   // built in: curl, js, python
}
```

## Type pages

Named types get their own deep-linkable pages, grouped by kind in the sidebar: fields and input fields with their types linked, enum values, union members, interface implementations, and a **Used by** section listing the operations that return or accept the type and the other types that reference it. Spec-defined scalars (`String`, `Int`, …) don't get pages; custom scalars do, including their `specifiedBy` URL.

## Multiple schemas

Each entry in `sources` renders one schema on its own route. A per-source `endpoint` overrides the block-level one:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  endpoint: "https://api.example.com/graphql",
  sources: [
    { label: "Public API", spec: "./schema.graphql" },
    {
      label: "Admin API",
      route: "/graphql-admin",
      spec: "./admin.graphql",
      endpoint: "https://admin.example.com/graphql",
    },
  ],
}
```

Each source takes the same [per-source controls](/docs/advanced/api-reference#per-source-indexing) as the OpenAPI block: `includeInSearch`, `includeInLlms`, `noindex`, and `seoDescriptionSuffix` (here the generated sentence names the query, mutation, or type — "Reference for the `pets` query in the GraphQL API.").

## Try it playground

Query and mutation pages render an interactive panel: edit the request body (the query and variables), point it at your endpoint or a custom URL, and send — the code samples update live so what you copy is byte-for-byte what was sent. Disable it with `playground: false`. Subscription pages show the generated operation and an example event instead: subscriptions run over a stateful transport (WebSocket or SSE) that the playground's single HTTP `POST` can't speak.

If your GraphQL API doesn't allow cross-origin requests from the docs site, route sends through a CORS proxy — a URL of your own, or `true` for the built-in `/_api-proxy` endpoint (which requires `deployment.output: "server"`). The built-in proxy only forwards to origins your documented specs declare — each configured GraphQL `endpoint`, plus any absolute `servers[].url` from a documented [OpenAPI spec](/docs/advanced/api-reference) — so a public docs deployment can't be aimed at other hosts. That makes `endpoint` required for a working proxy: without one, the proxy has no origin to allow for this reference and refuses every send (the build warns about this).

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
  playground: { proxy: true },
}
```

---

# Skills
Source: https://useblume.dev/docs/advanced/skills

Blume ships [agent skills](https://docs.claude.com/en/docs/claude-code/skills) — playbooks that teach a coding agent (Claude Code, Codex, Cursor) how to do a Blume-shaped job without you explaining it. They live on GitHub in the repo's `skills/` folder and are bundled in the installed package under `skills/`, so any agent can be pointed at a `SKILL.md` directly.

## Blume

The core skill. It teaches the agent what Blume is and how to scaffold, write, and configure a site — filesystem-derived navigation, the config schema, content components — and points it at the full docs bundled in the installed package (the `docs/` directory inside `blume`, resolved from wherever your package manager installs it — in a pnpm monorepo that's the depending workspace's `node_modules`, not the repo root). Install it in any project where an agent helps you build your docs:

```bash
npx skills add haydenbleasel/blume
```

## Self-updating docs

`blume-update-docs` keeps your docs in sync with the product they document. On each run — typically from a schedule you configure in your agent runner — it audits recently merged PRs, changelogs, config schemas, and CLI help against the docs content, updates only pages that are factually stale (feature-flagged work is ignored), verifies with `blume build`, and opens or updates a `blume/*` pull request. If nothing drifted, it reports a clean no-op instead of opening a noisy PR.

```bash
npx skills add haydenbleasel/blume --skill blume-update-docs
```

Blume doesn't host the automation — wire the skill into a scheduled task in Claude Code, a Codex or Cursor automation, or plain cron, with permission to read repo history and open PRs. A typical weekly prompt:

```text
Use the blume-update-docs skill. Review the PRs merged within the last 7 days and compare them to the docs content. Ignore work behind feature flags. If docs need updates, make them, verify the docs build, and open a blume/* PR. If not, report what you checked and do not open a PR.
```

---

# Configuration file
Source: https://useblume.dev/docs/configuration

Blume reads `blume.config.ts` from your project root. Wrap your config in `defineConfig` for autocomplete and type-checking — every field is optional, with a sensible default.

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});
```

## A complete example

A broader example touching the most common options (see each feature's guide for the rest):

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [sitemap()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — see the Search guide
  search: {
    provider: "orama",
  },

  // Markdown features
  markdown: {
    imageZoom: true,
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
    },
    codeBlocks: {
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // AI — see the AI guide
  ai: {
    llmsTxt: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — see the Deployment guide
  deployment: {
    output: "static",
    site: "https://docs.example.com",
  },
});
```

## Site

| Option | Default | Description |
| --- | --- | --- |
| `title` | `"Documentation"` | Site name — shown in the header, page titles, OG cards. |
| `description` | — | Default meta description, used for SEO and OG. |
| `logo` | — | Brand mark and/or wordmark shown in the header. |
| `banner` | — | Site-wide announcement bar above the header. |

### Logo

Point `logo` at an SVG and Blume inlines it, so a `currentColor` logo follows the light and dark theme automatically:

```ts blume.config.ts
logo: "/logo.svg",
```

The SVG can live at your project root or in `public/`. The brand is a mark (`image`) plus a wordmark (`text`); the object form lets you set them independently:

```ts blume.config.ts lineNumbers
logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},
```

`image` takes the same value as the shorthand — a single path, or `{ light, dark, alt }` for separate light/dark artwork (raster images must live in `public/`).

`text` controls the wordmark independently of the mark:

- **Omit `text`** and the brand uses your site `title` (the default).
- **Set `text: ""`** to show the mark alone — handy when the logo image already includes the wordmark.
- **Set `text` with no `image`** for a text-only logo.

### Favicon

There's no favicon option — Blume auto-detects one by filename, the way Next.js does. Drop an `icon` or `favicon` file (`.svg`, `.png`, or `.ico`) in your project root or `public/` directory and it becomes the browser tab icon:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/
```

SVG wins over PNG over ICO when several are present, and a file in `public/` is preferred over one at the root. If Blume finds no icon, it falls back to its own mark.

A dark mark disappears against dark browser chrome, so you can ship a second file for dark mode. Add a `-dark` sibling of your icon file — the same name and directory, with `-dark` before the extension (`icon.png` → `icon-dark.png`) — and Blume emits both icons behind a `prefers-color-scheme` media query, plus a plain light tag for browsers and crawlers that ignore media queries on icons:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/
```

Only the sibling of the icon Blume picked is used — a `-dark` file with a different name stays ignored, so an unrelated file can't pair with your mark by accident. The dark file is optional; with only one icon, Blume emits a single tag as before. Blume's own fallback mark ships both variants.

### Apple touch icon

The icon iOS uses when someone adds your site to their home screen is detected the same way. Drop an `apple-icon` file (`.png`, `.jpg`, or `.jpeg`) — or an `apple-touch-icon.png`, the name most favicon generators emit — in your project root or `public/` directory and Blume wires up `<link rel="apple-touch-icon">` for you. There's no default; if no file is found, no tag is emitted.

```
my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/
```

Put the file in `public/` rather than the project root: iOS ignores the inlined data URI Blume uses for a root-level icon, so only a `public/` file (served at `/apple-icon.png`) reliably reaches the home screen. Unlike the favicon, there's no `-dark` sibling here — iOS ignores media queries on home-screen icons, so a dark variant could never be served.

### Banner

Show a site-wide announcement bar above the header. Pass a string, or an object with a link and a dismiss button:

```ts blume.config.ts
banner: "Docs are in beta — expect changes.",
```

```ts blume.config.ts lineNumbers
banner: {
  content: "Blume v1 is here!",
  link: { text: "Read more", href: "/blog/v1" },
  dismissible: true,
  id: "v1",
},
```

When `dismissible` is on, the bar shows a close button and stays hidden for that visitor afterward. The dismissal key defaults to the content text, so editing the message brings the banner back; set a stable `id` to keep it dismissed across edits.

## Content

Where your content lives and how Blume discovers it. See [Pages](/docs/content) for how files become routes.

```ts blume.config.ts lineNumbers
content: {
  root: "docs",
}
```

| Option | Default | Description |
| --- | --- | --- |
| `root` | `"docs"` | Folder Blume scans for content. |
| `include` | `["**/*.{md,mdx}"]` | Globs that match content files. |
| `exclude` | `["**/_*", "**/.*"]` | Globs to ignore (underscore- and dot-files). |
| `pages` | `"pages"` | Folder for custom `.astro` pages. |
| `defaultType` | `"doc"` | Page `type` used when frontmatter omits it. |
| `types` | `{}` | Per-type content definitions — custom frontmatter keys scoped to pages of one `type`. See [Frontmatter](#frontmatter). |

Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`. Images referenced by **relative path** (`![](./diagram.png)`) live next to your content instead, and are [optimized at build time](/docs/content/syntax#links-and-images).

## Images

Local images referenced by relative path are optimized automatically at build time — compressed, converted to WebP, and given intrinsic `width`/`height` attributes so the layout doesn't shift while they load. There's nothing to configure; see [Links and images](/docs/content/syntax#links-and-images) for authoring guidance.

Remote images are served untouched by default. To have Blume download and optimize them at build time too, authorize their hosts:

```ts blume.config.ts lineNumbers
image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}
```

| Option | Default | Description |
| --- | --- | --- |
| `domains` | `[]` | Hostnames whose remote images may be optimized. |
| `remotePatterns` | `[]` | Pattern-based authorization (`protocol`, `hostname`, `port`, `pathname`); hostnames accept `*.` (one level) and `**.` (any depth) wildcards. |

## Frontmatter

Page frontmatter is strictly validated — an unknown key fails the build, so typos are caught early. To carry project-specific metadata (an owner, a review date), declare the extra keys under `frontmatter.extend`, each mapped to a schema you supply:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

Any [Standard Schema](https://standardschema.dev) library works — Zod (whichever version your project installs), Valibot, ArkType. Keys outside the extension stay strictly validated, so typo-catching is unchanged. See [Custom keys](/docs/reference/frontmatter#custom-keys) for the validation semantics.

Keys under `extend` apply site-wide. To require keys only on pages of one content type — an RFC's `status`, a runbook's `service` — declare them per type under `content.types` instead:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

A key can be declared site-wide or per-type, not both. See [Per-type keys](/docs/reference/frontmatter#per-type-keys) for how the scoping resolves.

`facets` names the custom keys whose values become filterable metadata: they ride along on search documents (`blume-search.json` and the MCP index), and the [MCP tools](/docs/configuration/ai#mcp-server) accept a `filters` input matching against them, so an agent can retrieve, say, only `enforced` RFCs in the `architecture` domain. Each facet must be a declared custom key — per-type or site-wide — and only string (or stringified number/boolean) values facet.

## GitHub

Point Blume at your repository with `github`. It powers the header [repository link](/docs/content/navigation#repository-link) and the **Edit on GitHub** and **Give feedback** [page actions](/docs/content/navigation#page-actions):

```ts blume.config.ts lineNumbers
github: {
  owner: "acme",
  repo: "docs",
}
```

| Option | Default | Description |
| --- | --- | --- |
| `owner` | — | GitHub account or organization that owns the repository. |
| `repo` | — | Repository name. |
| `branch` | `"main"` | Branch that edit links point at. |
| `dir` | — | Path from the repo root to the project root (for monorepos). |
| `host` | `"https://github.com"` | Origin of the GitHub instance, for Enterprise installations. Must be HTTP(S); normalized to its origin. |
| `api` | derived from `host` | REST API base, for `<GithubInfo>` against an Enterprise instance. Must be HTTP(S); normalized to an origin and path. |

### GitHub Enterprise

Docs whose repository lives on a GitHub Enterprise instance set `host`, and every repo-derived link — the header mark, edit links, the agent manifest — points at that instance instead of the public site:

```ts blume.config.ts lineNumbers
github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}
```

The REST API base that [`<GithubInfo>`](/docs/content/components) queries is derived from `host`: an Enterprise Cloud tenant with data residency (`acme.ghe.com`) is served from its `api.` subdomain, and any other host is treated as Enterprise Server (`/api/v3`). Set `api` explicitly when your instance sits somewhere else.

:::warning
An instance reachable only over plain HTTP still renders its counts, but `GITHUB_TOKEN` is withheld from the request rather than sent in cleartext — so a private repo's card comes back without them.
:::

:::note
`host` covers links Blume derives from `github`. To point only the header mark somewhere else — an organization, say, when the docs repo itself is private — use [`navigation.repo`](/docs/content/navigation#repository-link) with an absolute URL.
:::

## Last modified

Show a "Last updated on …" line at the bottom of each page. Off by default; set `lastModified` to `true` to derive each page's date from its git history:

```ts blume.config.ts
lastModified: true,
```

| Value | Description |
| --- | --- |
| `false` | Disabled (default). |
| `true` | Read the date from git history (commit dates). |
| `{ type: "git" }` | Same as `true`, written explicitly. |
| `{ type: "frontmatter" }` | Never run git — use only the `lastModified` frontmatter field. |

The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time. CI platforms usually check out a shallow clone, which silently drops most dates (the build warns with `BLUME_SHALLOW_GIT_HISTORY` when that happens): on Vercel, set the `VERCEL_DEEP_CLONE=true` environment variable; with `actions/checkout`, set `fetch-depth: 0`. A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:

```mdx page.mdx
---
title: My page
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.

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}
```

| Option | Default | Description |
| --- | --- | --- |
| `og.enabled` | auto | Per-page Open Graph images — on when a site URL is set. |
| `rss.enabled` | `true` | Build feeds for blog and changelog content. |
| `rss.types` | `["blog", "changelog"]` | Content types that each get a feed. |
| `rss.limit` | `50` | Maximum items per feed. |
| `sitemap` | `true` | Generate sitemap.xml (needs deployment.site). |
| `robots` | `true` | Generate robots.txt with a Sitemap link. |
| `structuredData` | `true` | Emit schema.org JSON-LD in each page's head. |

These work best with an absolute [`deployment.site`](/docs/deployment) for full URLs.

## Table of contents

The on-this-page outline is on by default and lists `H2`–`H3` headings. Turn it off, or change the heading range, with `toc`:

```ts blume.config.ts
export default defineConfig({
  toc: false, // hide it everywhere
});
```

Or narrow the heading range instead:

```ts blume.config.ts
export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});
```

## Feature options

Each of these has its own guide. The config field is the entry point:

| Field | What it configures | Guide |
| --- | --- | --- |
| `theme` | Accent color, corner radius, fonts, light/dark mode | [Theming](/docs/configuration/theming) |
| `navigation` | Explicit sidebar and header tabs | [Navigation](/docs/content/navigation) |
| `search` | Provider (Orama, Pagefind, Algolia, and more) and indexing | [Search](/docs/configuration/search) |
| `markdown` | Markdown rendering options — code blocks, heading anchors, image zoom | [Syntax](/docs/content/syntax) |
| `ai` | `llms.txt`, Ask AI, and the hosted MCP server for coding agents | [AI](/docs/configuration/ai) |
| `analytics` | Vercel, PostHog, and custom scripts | [Analytics](/docs/configuration/analytics) |
| `seo` | Metadata, OG images, feeds, structured data | [SEO](/docs/configuration/seo) |
| `deployment` | Output mode, adapter, and site URL | [Deployment](/docs/deployment) |
| `redirects` | Permanent and temporary redirects | [Deployment](/docs/deployment#redirects) |
| `integrations` | Astro integrations appended after Blume's built-ins | [Customization](/docs/configuration/customization#astro-integrations) |

## Precedence

Settings resolve from lowest to highest priority, so you only override what you need:

1. **Blume defaults**

    A sensible default for every field.

2. **blume.config.ts**

    Your project-wide configuration.

3. **Folder meta**

    [`meta.ts`](/docs/content/meta) for a section's title and ordering.

4. **Page frontmatter**

    Per-page overrides win.

---

# AI
Source: https://useblume.dev/docs/configuration/ai

Blume has a few AI features: machine-readable docs for external tools (`llms.txt` and a [JSON API](#json-api) with an OpenAPI description, both 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

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: false,
}
```

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, organized into sections that mirror your sidebar — folders and groups become headings, so an agent sees the docs' structure, not one flat blob.
- **`/llms-full.txt`** — the entire corpus: each page's full Markdown body, with its source URL, in one file.

Draft pages are excluded. Set [`deployment.site`](/docs/deployment) so the links and source URLs resolve to absolute addresses.

`llmsTxt` also takes an object form with knobs for what the files include. If your [API reference](/docs/advanced/api-reference) documents a placeholder or example spec, set `openapi: false` to keep its generated pages out of both files:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    enabled: true, // default
    openapi: false, // exclude generated API reference pages
  },
}
```

The object form also takes `details`: Markdown placed right after the title and summary in `llms.txt`, before the page sections — the [llms.txt spec](https://llmstxt.org)'s free-form "details" block. It's the place to tell agents _when_ to reach for your product and how to call it, which readiness scanners look for explicitly; an install command and the package name belong here too:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    details: [
      "## When to use Acme",
      "",
      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
    ].join("\n"),
  },
}
```

`llms.txt` closes with two generated sections that need no configuration. **Agent skills** lists each skill published through [`ai.skills`](#skills-discovery) with its description (where a skill says when to use it). **Agent resources** links every machine-readable artifact the build emits — `llms-full.txt`, the per-page [raw Markdown](#raw-markdown) mirror, the [MCP server](#mcp-server) and its discovery document, the skills index, the [API catalog](#api-catalog), [`agent-readability.json`](#agent-readability), and the [sitemap](/docs/configuration/seo#sitemap) — each only when it exists, so an agent that reads nothing but `llms.txt` still finds the whole surface.

To keep an individual page out of both files, set `ai.exclude` in its frontmatter:

```mdx
---
title: Internal notes
ai:
  exclude: true
---
```

The page still renders, stays in search, and keeps its place in the sitemap — only the `llms.txt` files skip it.

To take full control of either file, add your own `llms.txt` or `llms-full.txt` to your `public/` folder. Like a custom favicon, it's picked up automatically and ships in place of the generated file — override one and Blume still generates the other.

## Raw Markdown

Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — perfect for LLMs, coding agents, and "copy as Markdown" workflows. It's available for every page, in dev and production, with no configuration.

| URL               | Returns                                   |
| ----------------- | ----------------------------------------- |
| `/quickstart`     | The rendered page                         |
| `/quickstart.md`  | Plain Markdown, with components converted |
| `/quickstart.mdx` | The raw MDX source, exactly as written    |

Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.

The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, `<Card>` its title as a link over its body (and `<CardGroup>` the cards it holds), and `<YouTube>` a link. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.

### Content negotiation

Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel or Cloudflare server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy automatically — routing rules on Vercel, a generated Worker on Cloudflare — no configuration needed. The homepage always negotiates, even when it's a custom landing page rather than a content page: its Markdown mirror falls back to the [`llms.txt`](#llmstxt) index, so an agent asking the site root for Markdown gets the machine-readable map of the site. Markdown responses also carry an `x-markdown-tokens` header — an estimated token count (~4 characters per token), following the convention of [Cloudflare's Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — on every surface where Blume controls response headers: the dev server, server-rendered responses, and the negotiated homepage on Vercel and Cloudflare. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.

Missing pages negotiate too. Every build emits a Markdown [404 page](/docs/advanced/custom-pages#404-page) at `/404.md` — the not-found message followed by recovery links to every top-level section, the sitemap, and `llms.txt` — and on Vercel a request for a nonexistent URL that prefers Markdown, or any `.md` URL with no page behind it, gets that body with a real `404` status rather than the HTML shell.

### Custom component serializers

Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import type { ComponentMarkdown } from "blume";

const chart: ComponentMarkdown = ({ props }) =>
  `![${props.title}](/charts/${props.slug}.png)`;

export default defineConfig({
  ai: {
    markdownComponents: {
      Chart: chart,
    },
  },
});
```

For container components, `childComponents("Name")` extracts direct children by tag — the same way the built-in `<Steps>` serializer collects its `<Step>` items — and `childBlocks()` returns every direct child in order, components and prose alike, each already downleveled to a block of Markdown (the built-in `<CardGroup>` serializer is just those blocks joined by blank lines). A same-name entry replaces a built-in serializer, so you can restyle how `<Callout>` downlevels — or return `null` to opt one out entirely.

Serializers live in `blume.config.ts`, not `components.tsx`: the config file is executed at build time, while the components file is only statically analyzed (it may import `.astro` files, which can't run outside the site build). Your components themselves stay registered in `components.tsx` exactly as before — `markdownComponents` only adds their agent-facing Markdown form.

## Copy as Markdown

Every page carries a **Copy as Markdown** action — in the [page actions](/docs/content/navigation#page-actions) beneath the table of contents — that copies the page's raw Markdown to the clipboard. It's the same source served at the [`.md` URL](#raw-markdown) above, ready to paste into an LLM, an issue, or your notes. It's available on every page, in dev and production, with no configuration.

Where the Clipboard API is unavailable or the browser denies it — in-app browsers, WebViews, insecure origins — the action falls back to the legacy copy command, and if nothing lands on the clipboard the button reports **Copy failed** (localized via `actions.copyFailed`) rather than staying silent. The same fallback backs every copy button Blume renders.

## Open in chat

The **Open in chat** action opens the current page in an AI assistant — v0, ChatGPT, Claude, T3 Chat, Scira, or Cursor — pre-filled with a prompt that points it at the page's raw Markdown so it can answer questions about what you're reading:

> Read `https://your-site/this-page.md` so I can ask you questions about this page.

Like Copy as Markdown, it needs no setup. The assistant fetches the page over its public URL, so it works as soon as the page is deployed.

The prompt is part of the [UI dictionary](/docs/content/i18n#translated-ui) (`actions.openInChatPrompt`), so localized sites send it in their language, and `i18n.ui` can override the wording — keep the `{url}` placeholder, which is replaced with the page's raw-Markdown URL.

To tailor the action, set `ai.openInChat`. `false` hides it entirely, and an array of provider keys — `"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"` — shows just those providers, in the order you list them:

```ts blume.config.ts lineNumbers
ai: {
  openInChat: ["claude", "chatgpt", "cursor"],
}
```

To embed a ready-to-copy prompt inline in your content — rather than a whole-page action — use the [Prompt component](/docs/content/components#prompt), which renders a labeled row with a **Copy prompt** button and an optional open-in-Cursor link.

## Ask AI

Add an assistant that answers reader questions in an in-page chat panel, backed by a streaming server endpoint and the [AI SDK](https://ai-sdk.dev):

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "gateway", // default
    model: "openai/gpt-5.5",
  },
}
```

### Suggested questions

Seed the empty state with a few starter prompts. Each renders as a clickable suggestion — click one to send it — with an optional [Lucide icon](/docs/content/components#icon) beside the label:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    suggestions: [
      { label: "What is Blume?", icon: "rocket" },
      { label: "How do I write a docs page?", icon: "file-text" },
      { label: "How do I configure the theme?", icon: "settings" },
    ],
  },
}
```

`label` is the question that gets asked; `icon` is optional. Leave `suggestions` unset (or empty) and the panel opens to a plain input.

### Custom instructions

Add your own system-prompt text with `instructions` — identity, language, tone, or anything else the assistant should keep in mind:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    instructions:
      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
  },
}
```

Your text is **appended to** the built-in instructions rather than replacing them: the built-in part carries the [grounding](#grounding) contract — answer only from the retrieved pages, cite them as Markdown links — that the chat panel's citations depend on, so it stays intact whatever you add.

### Grounding

Ask AI is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.

The page the reader is currently on is added to the context first and used to scope retrieval to that page's language, so answers stay relevant to where they are in the docs. Retrieval runs at request time from a snapshot baked into the build, so it works regardless of your [search](/docs/configuration/search) provider — even when search is set to `none` — and needs no configuration.

Grounding is on for every backend except **[Inkeep](#backends)**, which runs its own retrieval over the content you've indexed in its dashboard.

### Retrieval size

How much documentation a question carries is the biggest lever on how long the reader waits for the first word: the model reads every injected character before it emits a token. On a hosted frontier model that's invisible, but on a self-hosted backend it dominates. `retrieval` sizes it:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    retrieval: {
      maxResults: 3, // fewer pages retrieved per question
      excerptChars: 1200, // shorter excerpt from each one
      contextBudget: 3000, // smaller total injection
    },
  },
}
```

| Option          | Default | Description                                     |
| --------------- | ------- | ----------------------------------------------- |
| `maxResults`    | `6`     | Documents retrieved per question.               |
| `excerptChars`  | `2000`  | Characters kept from each retrieved page.       |
| `contextBudget` | `10000` | Total injected characters, across all excerpts. |

The three aren't interchangeable. `contextBudget` caps the whole injection, `excerptChars` decides how deep into a single long page its excerpt reaches — raise it when one page holds the whole answer and the excerpt cuts it off — and `maxResults` caps how many pages retrieval adds. The page the reader is viewing is injected on top of the retrieved ones, so an answer can cite up to one page more than `maxResults`.

The defaults suit a hosted model. Lower them when you're serving from your own hardware and time-to-first-token matters more than recall; answers stay grounded either way, and the assistant is told to say when something isn't covered rather than fill the gap.

### External endpoint

Already have an API backend for AI? Point the panel at it and keep the docs build static:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}
```

Blume sends the same `POST` body as its built-in route:

```json
{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}
```

Return a successful response whose body is a plain UTF-8 text stream. If the endpoint is on another origin, allow the docs origin with CORS: accept `OPTIONS` and `POST`, permit the `content-type` request header, and return the CORS headers on both the preflight and streamed response. With `endpoint` set, Blume generates the chat UI but no server route, grounding snapshot, provider dependency, or provider-secret warning; your backend owns retrieval, authentication, rate limiting, model access, and citations.

### Server output required

Blume's built-in Ask AI backend is a server route (`POST /api/ask`), so it can't run on a static build. Switch to server output and pick an adapter:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

A static build with Ask AI enabled and no external `endpoint` fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.

### Backends

By default Ask AI routes through the **Vercel AI Gateway**: `model` is a `provider/model` string, so you switch models by changing it (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up automatically when you deploy on Vercel.

Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable and streams through a provider SDK you install in your project — only the one you use:

| `provider` | `model` | API key env var | SDK to install |
| --- | --- | --- | --- |
| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` | none — ships with Blume |
| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` | `@ai-sdk/openai-compatible` |

The SDKs are optional peer dependencies, so add the one your backend needs to your project (e.g. `npm install @openrouter/ai-sdk-provider`). If it's missing, the build warns with the exact package name before Vite would fail to resolve the import.

For example, to use OpenRouter:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openrouter",
    model: "anthropic/claude-sonnet-4-5",
  },
}
```

Any OpenAI-compatible endpoint works through `openai-compatible` — supply the `baseUrl` and the env var holding its key:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openai-compatible",
    baseUrl: "https://my-gateway.example.com/v1",
    apiKeyEnv: "MY_GATEWAY_API_KEY",
    model: "gpt-4o",
  },
}
```

Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point at a different env var or proxy.

:::note
**Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages.
:::

Keys are read with `process.env`, which covers the Node, Vercel, and Netlify adapters. On Cloudflare, expose the key through the platform's [runtime binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).

### Rate limiting

The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request — rejecting malformed bodies, capping it to 1–40 messages, and accepting only `user`/`assistant` roles so a caller can't inject their own system prompt and repurpose the route as a general LLM proxy — to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.

## MCP server

Host a [Model Context Protocol](https://modelcontextprotocol.io) server so coding agents (Claude Code, Cursor, VS Code, claude.ai connectors) can search and read your docs directly — no scraping:

```ts blume.config.ts lineNumbers
ai: {
  mcp: {
    enabled: true,
    route: "/mcp", // where the server is mounted
  },
}
```

| Option         | Default | Description                                       |
| -------------- | ------- | ------------------------------------------------- |
| `enabled`      | `false` | Generate and host the MCP server.                 |
| `route`        | `/mcp`  | Path the Streamable-HTTP endpoint is mounted on.  |
| `name`         | title   | Server name shown to clients (defaults to title). |
| `instructions` | —       | Optional system hint passed to connecting agents. |

The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and every page as an MCP resource (`resources/list` enumerates the pages at their served URLs with a `text/markdown` type; `resources/read` returns the page's agent Markdown, the same output as `get_page`), so clients that attach context by URI can browse the docs without calling a tool. It publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. The server card follows the [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card extension schema (reverse-DNS `name`, `remotes` transport endpoints), with initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set).

`search_docs` runs its own full-text index, so it works regardless of your [search](/docs/configuration/search) provider — and even when search is set to `none`. The MCP server is a separate feature from on-page search.

`search_docs` and `list_pages` both accept an optional `contentTypes` filter, narrowing results to pages of the given frontmatter [`type`s](/docs/reference/frontmatter) — `["rfc"]`, `["blog", "changelog"]` — so an agent working against a site that mixes docs with RFCs, runbooks, or policies can scope retrieval to the kind of page it needs. Every result names its content type, and `list_pages` output shows the types in use.

Both tools also accept a `filters` object matching against the facets a site declares per content type ([`content.types.<type>.facets`](/docs/configuration#frontmatter)) — custom frontmatter keys whose values become filterable metadata:

```json
{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}
```

Every `filters` entry must match (results carry their facet values, and `list_pages` shows each page's), so a knowledge base can drive progressive-disclosure agent workflows — enumerate the enforced standards, search only within them — without any server of its own.

### Server output required

The MCP server is a live endpoint (`/mcp`), so it can't run on a static build. Switch to server output and pick an adapter:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "node", // or "vercel" | "netlify" | "cloudflare"
  site: "https://docs.example.com",
}
```

A static build with `ai.mcp.enabled` fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters. Once deployed, connect from Claude Code with:

```bash
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

## JSON API

Every Blume site also serves its docs as a small read-only **JSON API** — the REST twin of the [MCP server](#mcp-server)'s tools, over the same page snapshot, for agents and function-calling frameworks that speak plain HTTP rather than MCP. It's on by default and needs no configuration:

| Endpoint | Returns |
| --- | --- |
| `/api/docs/pages.json` | Every page with its route, title, description, content type, locale, facets, and the URLs of its rendered, Markdown, and JSON forms. |
| `/api/docs/pages/{route}.json` | One page: its index entry plus the agent Markdown (the same body `get_page` returns). `{route}` is the page route without the leading slash, `index` for home. |
| `/api/docs/navigation.json` | The navigation tree — header tabs and the sidebar hierarchy. |
| `/api/docs/search?q=` | Full-text search, with the same `limit`, `contentTypes`, `locale`, `version`, and `filters[key]` scoping as `search_docs`. Server output only. |
| `/openapi.json` | The OpenAPI 3.1 description of the whole machine-readable surface. |

The page index, per-page documents, and navigation are prerendered, so a static site serves them as files from any host. Search is a live endpoint and exists only under [server output](/docs/deployment#server-rendering), where it runs the same index `search_docs` does. Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details (`application/problem+json`) with a stable `code`, a `detail`, and a `resolution` hint telling the agent where to go next — a missing page, a blank search query, or on server output any `/api/…` URL no endpoint answers:

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

The **OpenAPI document** at `/openapi.json` is generated per build from your config, so it describes only what the deployed site serves: every JSON endpoint with a unique `operationId`, typed parameters, and response schemas, plus the text surfaces alongside — the [`.md` mirrors](#raw-markdown), [`llms.txt`](#llmstxt) and `llms-full.txt`, [`agent-readability.json`](#agent-readability) — and the [MCP endpoint](#mcp-server) when it's enabled. Frameworks that build tools from an OpenAPI description get the same reach an MCP client has. The document is linked from the [API catalog](#api-catalog), the [readability manifest](#agent-readability), the homepage `Link` header as `rel="service-desc"`, and `llms.txt`.

None of this touches your own [API reference](/docs/advanced/api-reference): a documented spec is rendered into pages, never served at `/openapi.json`, and the catalog lists both. A `public/openapi.json` you ship yourself takes over that route (the JSON endpoints stay). The `/api/…` catch-all steps aside when a docs section is served from the `/api` namespace (`content/api/overview.md`) or a custom page owns a rest route under `/api/`, so those pages keep winning. Set `ai.api` to `false` to publish none of it:

```ts blume.config.ts lineNumbers
ai: {
  api: false,
}
```

## Agent readability

Blume writes an **`/agent-readability.json`** manifest at your site root that indexes the agent-facing surface described on this page — so an agent can discover it in a single fetch instead of guessing at conventions or scraping HTML. Like `llms.txt`, it's on by default:

```ts blume.config.ts lineNumbers
seo: {
  agentReadability: true,
}
```

The manifest lists only what you've enabled — the [raw Markdown](#raw-markdown) mirror pattern, the [JSON API](#json-api) and its OpenAPI description, [`llms.txt`](#llmstxt) and `llms-full.txt`, the [MCP server](#mcp-server) and its discovery document, the [Ask AI](#ask-ai) endpoint, the [sitemap](/docs/configuration/seo#sitemap), and [RSS feeds](/docs/configuration/seo#rss-feeds) — alongside your site name, description, source repository, and the [content-signal](/docs/configuration/seo#content-signals) usage policy. URLs are absolute when [`deployment.site`](/docs/deployment) is set and root-relative otherwise:

```json agent-readability.json
{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "https://docs.example.com/{route}.md"
    },
    "api": {
      "openapi": "https://docs.example.com/openapi.json",
      "pages": "https://docs.example.com/api/docs/pages.json",
      "search": "https://docs.example.com/api/docs/search"
    },
    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
    "llmsTxt": "https://docs.example.com/llms.txt",
    "mcp": {
      "discovery": "https://docs.example.com/.well-known/mcp.json",
      "url": "https://docs.example.com/mcp"
    }
  },
  "description": "Docs for the Acme API.",
  "generator": "blume@1.0.0",
  "name": "Acme Docs",
  "site": "https://docs.example.com",
  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
  "repository": "https://github.com/acme/docs"
}
```

The `contentNegotiation` field appears only when the deployed site actually honors the `Accept: text/markdown` header — see [content negotiation](#content-negotiation); on every other deployment the manifest advertises just the `.md` mirror pattern.

Set `seo.agentReadability` to `false` to skip it, or ship your own `public/agent-readability.json` to take over — Blume never overwrites a file you place in `public/`.

### Discovery Link header

Agents that probe a site don't know to look for the manifest — so Blume also advertises it in an [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` response header on the homepage, using IANA-registered relation types:

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
  </openapi.json>; rel="service-desc"; type="application/json",
  </agent-readability.json>; rel="describedby"; type="application/json",
  </llms.txt>; rel="describedby"; type="text/plain",
  </index.md>; rel="alternate"; type="text/markdown"
```

Each entry appears only when its feature is on. The `alternate` link points at the homepage's Markdown mirror — the page's own [raw Markdown](#raw-markdown) when the home route is a content page, or the synthesized `llms.txt` fallback when it's a landing page. The `service-desc` link ([RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)) points at the [JSON API](#json-api)'s OpenAPI description, and `api-catalog` at the [generated API catalog](#api-catalog). The header rides on every surface Blume controls: the dev server (check it with `curl -I localhost:4321`), static builds via the emitted `_headers` file (Netlify and Cloudflare), and Vercel server builds via the deploy's routing rules.

Not every agent enters through the root, though — one following a search result or a shared link lands on a deep page and never sees the homepage header. So every rendered page also carries the same discovery links in its HTML `<head>`, using the same IANA-registered relations:

```html
<link
  rel="describedby"
  href="/agent-readability.json"
  type="application/json"
/>
<link rel="describedby" href="/llms.txt" type="text/plain" />
<link rel="alternate" href="/docs/example.md" type="text/markdown" />
```

Here the `alternate` link points at _that page's own_ [raw-Markdown mirror](#raw-markdown), so an agent can jump straight from the HTML it landed on to the token-efficient version. Because the head links travel with the prerendered HTML, they also work on hosts that ignore `_headers` and can't send custom response headers at all (GitHub Pages, S3) — no matter which page the agent enters on.

### API catalog

When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog` — a [linkset](https://www.rfc-editor.org/rfc/rfc9264) that lets agents enumerate your APIs from the domain alone, served with its registered `application/linkset+json` media type on every build surface. There's nothing to configure: the catalog is derived from what's already in `blume.config.ts`. Each [OpenAPI or AsyncAPI reference](/docs/advanced/api-reference) becomes an entry anchored at its rendered docs route, with `service-doc` pointing at those docs and `service-desc` at the spec when it lives at a fetchable URL; the site's own [JSON API](#json-api) becomes an entry described by its `/openapi.json`; and the [MCP server](#mcp-server) becomes an entry with its discovery document as the service description:

```json .well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://docs.example.com/reference",
      "service-doc": [
        { "href": "https://docs.example.com/reference", "type": "text/html" }
      ],
      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
    },
    {
      "anchor": "https://docs.example.com/api/docs",
      "service-desc": [
        {
          "href": "https://docs.example.com/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://docs.example.com/mcp",
      "service-desc": [
        {
          "href": "https://docs.example.com/.well-known/mcp.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    }
  ]
}
```

A site with no API references, no MCP server, and the [JSON API](#json-api) turned off emits no catalog — there'd be nothing in it. As everywhere, a `public/.well-known/api-catalog` file you ship yourself wins over the generated one.

### WebMCP

[WebMCP](https://webmachinelearning.github.io/webmcp/) is an emerging browser API that lets a page register tools directly with an agentic browser — no separate server connection needed. Every Blume page registers the docs' read-only surface on the page's model context: `search_docs` (site search), `get_page` (a page's [raw Markdown](#raw-markdown)), and `list_pages` (the [`llms.txt`](#llmstxt) index). The script is tiny, loads no search machinery until a tool is actually called, and silently no-ops in every browser without the API — which today is all of them outside [Chrome's early preview](https://developer.chrome.com/blog/webmcp-epp). It registers on whichever surface the in-flux spec exposes (`navigator.modelContext` or `document.modelContext`), via `provideContext` or per-tool `registerTool`.

It's on by default; set `webmcp: false` to opt out:

```ts blume.config.ts lineNumbers
ai: {
  webmcp: false,
}
```

### Skills discovery

If your project ships [agent skills](https://agentskills.io) — the [Blume repo itself does](#agent-skill) — point `ai.skills` at the directory that holds them, and the build publishes them for discovery per the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc):

```ts blume.config.ts lineNumbers
ai: {
  skills: "./skills",
}
```

The path resolves against your project root, and each subdirectory with a `SKILL.md` becomes a published skill. A skill that's a lone `SKILL.md` is copied verbatim to `/.well-known/agent-skills/<name>/SKILL.md` (`type: "skill-md"`); a skill with supporting resources (`scripts/`, `references/`, `assets/`) is bundled into a deterministic `.tar.gz` (`type: "archive"`) so its relative references resolve after unpacking, with script execute bits preserved. The discovery index at `/.well-known/agent-skills/index.json` carries the v0.2.0 `$schema` and, per skill, its name, type, description (from the `SKILL.md` frontmatter), artifact URL, and the SHA-256 digest clients verify downloads against.

Skills with a missing or spec-invalid `name`/`description` are skipped with a build warning rather than published broken, and a `public/.well-known/agent-skills/index.json` you ship yourself takes over the whole surface.

### DNS-based discovery (DNS-AID)

[DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) is an emerging IETF draft that lets agents discover a site's AI surface before making a single HTTP request, by querying ServiceMode [SVCB/HTTPS records](https://www.rfc-editor.org/rfc/rfc9460) at a well-known DNS entrypoint. DNS records live in your zone, not in the build, so this is the one discovery surface Blume can't publish for you — instead, add a record with your DNS provider:

```txt
_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
```

Use the `HTTPS` record type if your provider offers it (Vercel DNS does; it doesn't support the plain `SVCB` type), or a ServiceMode `SVCB` record with `alpn` and `port` parameters otherwise. The draft also recommends signing the zone with DNSSEC so validating resolvers return authenticated answers — providers like Cloudflare enable it in one click, while some (including Vercel DNS) don't support it at all.

`blume audit --url <origin>` checks this for you: when [`deployment.site`](/docs/deployment) is set, the network tier queries the entrypoint over DNS-over-HTTPS and reports the exact record to publish if none exists, plus whether the answers are DNSSEC-authenticated. Set `BLUME_DOH_URL` to point the lookup at your own resolver if your network blocks the public ones (Google, Cloudflare).

### Web Bot Auth

[Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) works in the other direction: it's not about agents reading your docs, but about **your organization's agents identifying themselves** when they make requests elsewhere. Your agents sign their requests with [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421), and receiving sites verify them against a public-key directory published on your domain. If your org runs agents and your Blume site lives at the domain they identify as, publish their public keys:

```ts blume.config.ts lineNumbers
ai: {
  webBotAuth: {
    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
  },
}
```

Blume then serves the JWKS at `/.well-known/http-message-signatures-directory` with its registered media type on every build surface. The directory is public by definition, so the config only admits public keys — a JWK containing private material (`d`, `p`, `q`, …) fails validation with an error rather than shipping a leaked credential. Generate an Ed25519 pair with:

```bash
node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
```

The public JWK goes in the config above; the private one goes wherever your signing agent runs (a secret manager, never the repo). If your organization doesn't operate agents, skip this — an empty directory advertises nothing worth verifying.

Since `blume.config.ts` is executed at build time, the key doesn't have to be hardcoded — load it from a build-time environment variable to keep the config free of key blobs and rotate without a commit:

```ts blume.config.ts lineNumbers
const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;

export default defineConfig({
  ai: {
    webBotAuth: {
      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
    },
  },
});
```

Environments without the variable publish no directory, and a key loaded this way is validated exactly like an inline one — including the private-material check. (The public key isn't a secret, so committing it inline is equally fine; the env var is an ergonomic choice, not a security one.)

## Agent skill

Building a Blume site with the help of a coding agent? Install the Blume [agent skill](https://docs.claude.com/en/docs/claude-code/skills) so it knows how Blume works without you explaining it:

```bash
npx skills add haydenbleasel/blume
```

The skill teaches the agent what Blume is and how to scaffold, write, and configure a site, and points it at the full docs bundled in the installed package (the `docs/` directory inside `blume`, wherever your package manager installs it).

It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside a skill for keeping docs in sync with your product from a scheduled agent run.

---

# Analytics
Source: https://useblume.dev/docs/configuration/analytics

Blume injects analytics for you from a single `analytics` block in `blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a `scripts` escape hatch covers every other provider — Plausible, Fathom, Google Analytics, Umami, and the rest.

Analytics loads in **production builds only**. The scripts are emitted by `blume build`, never by `blume dev`, so local traffic never reaches your dashboards and you don't need a separate "development" project.

:::note
Analytics is opt-in. With no `analytics` block, Blume injects nothing.
:::

## Vercel Web Analytics

Set `vercel: true` to add [Vercel Web Analytics](https://vercel.com/docs/analytics). Blume injects Vercel's first-party script, which is served from your own domain once Web Analytics is enabled for the project in the Vercel dashboard.

```ts blume.config.ts lineNumbers
analytics: {
  vercel: true,
}
```

No keys are needed — the script reports to the project it's deployed under. This only collects data on Vercel deployments, where the `/_vercel/insights` endpoint exists.

## PostHog

Provide your **project API key** to add [PostHog](https://posthog.com). The host defaults to PostHog Cloud US; set `host` for EU Cloud (`https://eu.i.posthog.com`) or a self-hosted instance.

```ts blume.config.ts lineNumbers
analytics: {
  posthog: {
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // optional, this is the default
  },
}
```

The project API key is safe to ship to the browser — it's a public, write-only key.

## Custom scripts

Use `scripts` to load any other analytics provider. Each entry renders one `<script>` tag and must set **exactly one** of `src` (external) or `content` (inline).

```ts blume.config.ts lineNumbers
analytics: {
  scripts: [
    // Plausible
    {
      src: "https://plausible.io/js/script.js",
      strategy: "defer",
      attributes: { "data-domain": "example.com" },
    },
    // Fathom
    {
      src: "https://cdn.usefathom.com/script.js",
      strategy: "defer",
      attributes: { "data-site": "ABCDEFG" },
    },
    // An inline snippet
    {
      content: "console.log('analytics ready')",
    },
  ],
}
```

`attributes` is a map of extra HTML attributes (`data-*`, `id`, …) spread onto the tag, and `strategy` adds `async` or `defer` to external scripts.

## Options

| Option | Default | Description |
| --- | --- | --- |
| `vercel` | `false` | Add Vercel Web Analytics (Vercel deployments only). |
| `posthog.key` | — | PostHog project API key. Enables PostHog when set. |
| `posthog.host` | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted). |
| `scripts[].src` | — | External script URL. Mutually exclusive with `content`. |
| `scripts[].content` | — | Inline script body. Mutually exclusive with `src`. |
| `scripts[].strategy` | — | `async` or `defer` for an external script. |
| `scripts[].attributes` | — | Extra HTML attributes spread onto the `<script>` tag. |

All three can be combined — enable Vercel, PostHog, and custom scripts together. For deploying your built site, see [Deployment](/docs/deployment).

---

# Customization
Source: https://useblume.dev/docs/configuration/customization

## Component overrides

Add a `components.ts` (or `components.tsx`) to your project root and export `defineComponents`. The `mdx` map either **replaces** a built-in component or **adds** a new one — available in every `.mdx` page with no import.

```ts components.ts lineNumbers
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";
import Pricing from "./components/Pricing.astro";

export default defineComponents({
  mdx: {
    Callout, // replace the built-in Callout
    Pricing, // add a new <Pricing /> component
  },
});
```

Keys are the names you write in MDX (`<Callout>`, `<Pricing>`). Use the `.tsx` filename when you import React components.

### Reference form

Every override — in `mdx`, `layout`, or `islands` — accepts three forms:

```ts components.ts
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";

export default defineComponents({
  mdx: {
    Callout, // 1. an imported component
    Note: "./components/Note.astro", // 2. a path string (resolved from the project root)
    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. a descriptor
  },
});
```

The **descriptor** form adds a hydration mode so an interactive React/Vue/Svelte component ships its JavaScript and comes alive on the client. Without a `client` mode a framework component renders as static HTML — Blume prints a build warning when it spots one, since that's usually a mistake.

| `client` | Hydrates |
| --- | --- |
| `"load"` | Immediately on page load |
| `"idle"` | When the main thread is idle |
| `"visible"` | When scrolled into view |
| `"media"` | When a `media` query matches (add `media: "(min-width: 40rem)"`) |
| `"only"` | Client only, never server-rendered |

For interactive components you use across many pages, the [`islands` group](/docs/content/islands#registering-islands-in-componentsts) is a shorthand for the descriptor form with `client: "visible"`.

### Typing an override

When you replace a built-in, import its prop type from `blume/components` so your component matches the contract — the types are derived from the components themselves, so they never drift:

```tsx components/Callout.tsx
import type { CalloutProps } from "blume/components";

export default function Callout(props: CalloutProps) {
  // …your own callout, same props as the built-in
}
```

Prop types are exported for the content components (`CalloutProps`, `CardProps`, `TabsProps`, `StepsProps`, `BadgeProps`, and more).

## Layout slots

The `layout` map replaces a piece of Blume's chrome with your own component. Each override receives the same props as the built-in it replaces, so you can wrap the default or start from scratch.

```ts components.ts
import { defineComponents } from "blume";
import Footer from "./components/Footer.astro";
import Logo from "./components/Logo.astro";

export default defineComponents({
  layout: {
    Logo, // brand mark + title in the header
    Footer, // site-wide footer (no built-in — renders only when set)
  },
});
```

Wired slots:

| Slot | Replaces | Props |
| --- | --- | --- |
| `Layout` | The entire page shell (`RootLayout`) | Everything the built-in layout receives, plus the `layout` map |
| `Header` | The top navigation bar | `site`, `logo`, `navigation`, `route`, `searchEnabled`, … |
| `Logo` | The brand link (mark + title) in the header | `site`, `logo` |
| `Search` | The header search trigger + modal | `navigation`, `strings`, `locale`, `askEnabled` |
| `Sidebar` | The primary navigation tree | `items`, `currentRoute` |
| `MobileNav` | The nav inside the mobile drawer (defaults to `Sidebar`) | `items`, `currentRoute` |
| `Breadcrumbs` | The breadcrumb trail | `crumbs` |
| `TableOfContents` | The on-this-page outline | `headings`, `title`, `variant` |
| `Pagination` | The prev/next footer links | `prev`, `next`, `strings` |
| `PageHeader` | An injection point above the article (no built-in) | `page`, `headings`, `route` |
| `PageFooter` | An injection point below the article (no built-in) | `page`, `headings`, `route` |
| `Footer` | A site-wide footer after the content grid (no built-in) | `site`, `navigation`, `ui` |

`PageHeader`, `PageFooter`, and `Footer` have no built-in component — they render nothing until you set them, which makes them handy injection points for a promo banner, a "last updated" note, or a marketing footer.

Layout slots accept the same [three reference forms](#reference-form) as MDX overrides, so a slot can be a path string or a hydrated descriptor (`{ component, client }`) when you want an interactive header or footer.

## Interactive islands

For interactive UI (React, Vue, or Svelte), drop a component into an `islands/` folder and use it in any MDX page — Blume hydrates it for you, no wrapper or registration needed:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}
```

```mdx page.mdx
Use it anywhere: <Counter />
```

See [Islands](/docs/content/islands) for hydration strategies and framework setup.

## Custom pages

Add `.astro` files under your `pages/` folder to mount fully custom routes alongside your docs — a landing page, a pricing page, or a hand-built index. They keep their location, so relative imports and `getStaticPaths` work as usual, and they can read your config, navigation, and routes from the `blume:data` module.

See [Custom Pages](/docs/advanced/custom-pages) for the full guide.

## Registry

`blume add` copies a Blume-maintained component into your project as **source** — you own it and can edit it freely. Run it with no arguments to list what's available:

```bash
blume add
```

Install a layout slot (header, sidebar, breadcrumbs, table of contents, pagination, or feedback) or any content component (callout, card, tabs, steps, accordion, and more):

```bash
blume add callout
blume add pagination
```

The copy imports the rest of the framework from `blume/*`, so it renders exactly like the built-in until you change it. `blume add` prints the `defineComponents` snippet to register it — content components under `mdx`, layout pieces under `layout`.

## Astro integrations

Add any Astro integration from the top-level `integrations` array in `blume.config.ts`. Install the integration in your site first; Blume does not add it to the generated runtime's dependencies or manage its Astro compatibility.

```bash
npm install @astrojs/sitemap
```

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  integrations: [
    sitemap({
      filter: (page) => !page.includes("/drafts/"),
    }),
  ],
});
```

Blume keeps its built-in integrations in their existing order, then appends your entries in declaration order. It does not sort or deduplicate them, so two integrations with the same `name` both run. Blume validates that `integrations` is an array, while Astro validates each entry and reports invalid integrations.

Because Blume loads your integrations by re-importing `blume.config.ts` from the generated Astro config rather than copying the instances, the config module evaluates twice per run — once when Blume reads your config and once when Astro loads it. Keep integration factories side-effect free (return the integration; don't write files or open connections at construction) so the second evaluation is harmless.

The same integrations run in `blume dev` and `blume build`. Editing `blume.config.ts` during `blume dev` regenerates the hidden Astro config and triggers a config restart; if you don't see an edited integration take effect, restart `blume dev`. Blume can't tell which config edits affect integrations, so once `integrations` is non-empty, every edit to `blume.config.ts` — even to an unrelated field — restarts the dev server rather than hot-applying. Blume only tracks the contents of `blume.config.ts`, so editing a separate file it imports won't trigger that regeneration on its own — restart `blume dev` after such edits. If you eject, the owned `astro.config.mjs` keeps a relative bridge to `blume.config.ts`, so the configured integrations continue to run; you can later move them directly into the Astro config as part of taking full ownership.

## Eject

When you want full control, eject the generated runtime into a standalone Astro project:

```bash
blume eject --yes
```

Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app you own and can modify directly. The `blume` package stays importable, so you keep its components, theme, and Markdown processors.

### What eject leaves behind

After ejecting, your `build` script runs plain `astro build` — the site itself builds the same, but the artifacts `blume build` layered on top are no longer produced. The eject command warns about the ones your config actually uses. To keep them:

- **Pagefind search index** — with `search.provider: "pagefind"`, the search UI loads the index from the built site, so search breaks in production until you index it yourself. Install `pagefind` as a devDependency and index after each build: `"build": "astro build && pagefind --site dist"`.
- **Hosted search sync** — a hosted provider's index is no longer pushed on build; re-upload your search records after each build with the provider's API or CLI.
- **sitemap.xml** — recreate it with the standard [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) integration.
- **robots.txt** — ship your own as `public/robots.txt`.
- **llms.txt / llms-full.txt and agent-readability.json** — write them by hand (or generate them in a build step of your own) and serve them from `public/`.
- **Platform redirect files** — `_redirects` and `vercel.json` are no longer emitted for static builds. Your redirects still work as Astro-generated meta-refresh pages, or you can move them into your host's own config.

---

# Export
Source: https://useblume.dev/docs/configuration/export

Blume can add an **Export** action to the [page actions](/docs/content/navigation#page-actions) beneath the table of contents, letting readers save the page they're on as a **PDF** or an **EPUB**. It's off by default and entirely client-side — no server, and [static](/docs/deployment) builds stay static.

## Enable it

Turn on both formats with a single toggle:

```ts blume.config.ts
export: true,
```

To offer just one format, pass an object instead:

```ts blume.config.ts
export: {
  pdf: true,
  epub: false,
},
```

Any format you omit (or set to `false`) is left out of the menu. With both off — the default — the **Export** action doesn't appear at all.

## PDF

**Export to PDF** opens your browser's print dialog with a print stylesheet that strips the site chrome — header, sidebars, navigation — down to just the article. Choose **Save as PDF** to finish.

Because it prints the live, fully-styled page, the result keeps crisp, selectable text, real fonts, and syntax-highlighted code. It needs no dependencies and works the same in dev, in production, and on static hosts.

:::note
PDF export goes through the browser's native print dialog, so the exact "Save as PDF" wording and options depend on the browser. Enable **Background graphics** in the dialog to keep code-block and callout backgrounds.
:::

## EPUB

**Export to EPUB** generates a self-contained `.epub` of the current page in the browser and downloads it — ready for Apple Books, Calibre, or any e-reader. The generator is loaded only when a reader clicks Export, so it never weighs down the rest of your site.

To keep the file readable on a device with no stylesheet or JavaScript of its own, Blume rewrites the page into clean, standalone HTML: syntax-highlighted code becomes plain monospace, decorative icons and copy buttons are dropped, and a built-in e-reader stylesheet handles spacing, code blocks, and tables.

## What gets exported

Both formats export the **single page** a reader is viewing — not the whole site — which matches where the action lives, beneath that page's table of contents.

:::note
In an EPUB there's no JavaScript to switch tabs, so tabbed content — like [package-install](/docs/content/syntax) blocks and code groups — is expanded to show every panel at once. Client-rendered embeds such as Mermaid diagrams aren't included.
:::

---

# Search
Source: https://useblume.dev/docs/configuration/search

Blume ships local search with no hosted infrastructure and no API keys. It runs in the browser, works in both `blume dev` and `blume build`, and indexes only your real content — navigation chrome and excluded pages are skipped. When you outgrow it, you can switch to a hosted or semantic backend without changing how search looks or behaves — only the `search.provider` you configure changes.

Blume reaches parity with Fumadocs' provider set: **Orama**, **FlexSearch**, **Algolia**, **Orama Cloud**, **Typesense**, and **Mixedbread** (plus **Pagefind**). Only the configured provider's SDK is installed into your project, so picking one backend never pulls in the others.

## Using search

Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/` when you're not typing in a field. `Esc` closes it, and `⌘J` (or `Ctrl J`) toggles the result preview pane.

Queries match page **titles**, **descriptions**, and **body text**, with title matches ranked highest and descriptions above body.

## Popular pages

Before a reader types a query, the search dialog shows a **Popular** list. By default it is the first six sidebar pages — which on multi-tab sites often surfaces the wrong section. Pin the links you want instead:

```ts blume.config.ts lineNumbers
search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},
```

Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG (same _inputs_ as nav icons), defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback.

Write `href` as if the site were mounted at the root — a `basePath` is applied for you, the same as `navigation.featured`. External URLs pass through untouched.

> **Warning**
>
> A curated list is a single set of links shared by every language. On a site
> with `i18n` configured, the sidebar fallback follows the reader's locale, but
> `popular` entries point wherever their `href` says — so pin locale-prefixed
> routes only if you want every reader sent to that one language.

## What's indexed

For Orama, FlexSearch, Algolia, Orama Cloud, and Typesense — and the MCP server's `search_docs` tool — Blume indexes each page's title, description, and body reduced to plain text: code blocks, images, and markup are stripped, so results stay relevant. These indexes are built from your source files, so they're identical in dev and production. Pagefind indexes the built HTML instead, and Mixedbread syncs your raw Markdown, so both always search code.

If your docs rely on code examples for searchable terms like options, methods, or error names, opt fenced code into the source-built indexes:

```ts blume.config.ts lineNumbers
search: {
  indexing: {
    includeCodeBlocks: true,
  },
},
```

Each fence's body and title (`blume.config.ts` above) become searchable; the language and fence markers don't. On `.mdx` pages the index reads components as the text they show — a Card's title, a Tab's label, a TypeTable's descriptions — using the same serializers as the [agent surfaces](/docs/configuration/ai), so an `ai.markdownComponents` entry covers your own components too. The option has no effect on Pagefind or Mixedbread. Expect the index to grow with your fenced content — the client index ships to every reader, hosted providers cap record size (Algolia rejects the sync batch when one page's record exceeds its plan's limit, leaving the previous index live), and a hit inside a fence shows flattened code in the result excerpt.

On a [versioned](/docs/content/versioning) site, results default to the version being viewed, with an "All versions" toggle in the dialog footer (remembered per reader). Cross-version hits name their version on the row. Orama, FlexSearch, Algolia, and Typesense honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.

## Tags

Add `search.tags` to a page's frontmatter to group it under a filter in the search dialog — readers can narrow results to a tag with a click. Tags also become a facet on the hosted providers.

```yaml
search:
  tags: [api, reference]
```

## Providers

The client-side providers are keyless and need no extra config. The hosted ones take **public** credentials in `blume.config.ts` (safe to ship to the browser) and read their **secret** admin key from an environment variable at build time — the secret never lands in the config or the client bundle.

### Orama (default)

Blume's default engine. It builds a JSON index served at `/blume-search.json` and queries it in the browser — instant, client-side, and live in `blume dev` as you edit. No keys, no service.

```ts blume.config.ts lineNumbers
search: {
  provider: "orama", // default
}
```

#### Non-Latin scripts

Orama's standard tokenizer keeps only basic Latin letters, digits and a handful of accented vowels, so text in any other script — Japanese, Chinese, Korean and Thai, but equally Russian, Greek, Hebrew and Hindi — would otherwise produce no matches at all. Blume handles this for you: when [`i18n.defaultLocale`](/docs/content/i18n) resolves to a non-Latin script, the index switches to a word-segmenting tokenizer (built on the browser- and Node-native `Intl.Segmenter`). Declaring your site's language is all it takes:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}
```

The same tokenizer serves the search dialog, the MCP server's `search_docs` tool, and Ask AI grounding. The script is what decides, not the language name — `az-Cyrl` is segmented while `sr-Latn` is not — and it is the default locale that decides for the whole index: on a mixed-language site every page shares the default locale's tokenizer. With a non-Latin default that's safe, because Latin words survive segmentation intact, so pages in English stay searchable alongside the default language. The reverse doesn't hold: non-Latin translations on a Latin-default site aren't searchable. Latin-script languages that lean heavily on diacritics (Vietnamese, or Serbian in Latin script) also fare worse on the standard tokenizer, which folds only a few accented vowels and splits words on the rest.

Japanese and Chinese go one step further. Segmenting alone indexes a compound term as its parts — 資金決済法 as 資金, 決済 and 法 — which lets a page mentioning each part somewhere outrank the page the term is actually about. Han, Hiragana and Katakana are therefore indexed as overlapping character pairs, and queries on those indexes prefer pages carrying a term's pairs together, loosening to any-pair matching when no page carries them all, so typing a whole sentence still returns its closest pages. Korean and Thai keep their segmented words.

### FlexSearch

A second keyless, client-side option. It reuses the same `/blume-search.json` index Orama ships and builds a [FlexSearch](https://github.com/nextapps-de/flexsearch) document index in the browser. Works in `blume dev` and `blume build`.

FlexSearch has no equivalent segmentation hook, so for sites in a non-Latin script prefer Orama (the default) or [Pagefind](#pagefind), whose `pagefind_extended` binary indexes a broad set of languages and segments Chinese, Japanese and Korean natively.

```ts blume.config.ts lineNumbers
search: {
  provider: "flexsearch",
}
```

### Pagefind

For very large docs, opt into [Pagefind](https://pagefind.app). It indexes your built HTML and loads the index in shards on demand, keeping the initial payload tiny no matter how big the site grows.

```ts blume.config.ts lineNumbers
search: {
  provider: "pagefind",
}
```

Pagefind only runs during `blume build`, so search isn't available in `blume dev` with this provider.

### Algolia

The browser queries [Algolia](https://www.algolia.com) directly with your search-only key. Each `blume build` replaces the index using the admin key from `ALGOLIA_ADMIN_API_KEY` (the build warns and skips the upload if it's unset). The whole index is replaced on every sync, so pages you delete or rename don't linger as stale results.

```ts blume.config.ts lineNumbers
search: {
  provider: "algolia",
  algolia: {
    appId: "YOUR_APP_ID",
    indexName: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
  },
}
```

### Orama Cloud

Hosted Orama. The browser queries your index endpoint with the public API key; `blume build` pushes records to the index using `ORAMA_PRIVATE_API_KEY`. Set `indexId` to enable the sync.

```ts blume.config.ts lineNumbers
search: {
  provider: "orama-cloud",
  oramaCloud: {
    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
    apiKey: "YOUR_PUBLIC_API_KEY",
    indexId: "your-index-id", // for the build-time sync
  },
}
```

### Typesense

Self-hosted or cloud [Typesense](https://typesense.org). The browser queries the collection with the search-only key; `blume build` recreates the collection and imports documents using `TYPESENSE_ADMIN_API_KEY`. The collection is dropped and rebuilt on every sync so deleted or renamed pages don't linger as stale results — if you hand-tune the collection's settings, reapply them after a build.

```ts blume.config.ts lineNumbers
search: {
  provider: "typesense",
  typesense: {
    host: "xyz.a1.typesense.net",
    collection: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
    // port + protocol default to 443 / https
  },
}
```

### Mixedbread

Semantic search via [Mixedbread](https://www.mixedbread.com). Queries are proxied through a generated `/api/search` endpoint that holds your key, so this provider **requires server output** (`deployment.output: "server"`). The endpoint reads `MIXEDBREAD_API_KEY`. Sync your content to the store with the Mixedbread CLI in your build, e.g. `mxbai vs sync <STORE_ID> ./content --ci`.

```ts blume.config.ts lineNumbers
search: {
  provider: "mixedbread",
  mixedbread: {
    storeId: "YOUR_STORE_ID",
  },
}
```

### Disabling search

```ts blume.config.ts lineNumbers
search: {
  provider: "none",
}
```

## Excluding pages

Only indexable pages are searched. A page is left out of the index when it sets `search.exclude` in frontmatter:

```yaml
search:
  exclude: true
```

[Hidden pages](/docs/content/navigation#hidden-pages) are also excluded by default. To index them anyway, opt in:

```ts blume.config.ts lineNumbers
search: {
  indexing: { includeHiddenPages: true },
}
```

---

# SEO
Source: https://useblume.dev/docs/configuration/seo

Blume handles the discoverability layer for you: page metadata, social share images, feeds, and structured data. The configurable features live under the `seo` key in `blume.config.ts`; metadata is driven by your content.

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
  x: { handle: "@acme" },
}
```

Most of this is sharper with an absolute site URL — set [`deployment.site`](/docs/deployment) so feeds, OG images, canonicals, the sitemap, and JSON-LD can emit full URLs.

## Metadata

Every page renders the standard `<head>` tags from your config and frontmatter:

- `<title>` — the page title plus your site `title`.
- `<meta name="description">` and `og:description` — the page `description`, falling back to the site `description`.
- `og:title` and `og:site_name` — the page title and your site `title`.
- `<link rel="canonical">` and `og:url` — the page's absolute URL (when `deployment.site` is set).
- `og:type` — `article` on blog posts and changelog entries, `website` elsewhere. Article pages also emit `article:published_time` and `article:modified_time` from the page's `date` and last-modified timestamp.
- `og:image` — the [OG image](#open-graph-images) for the page. A generated card also declares its `og:image:width`, `og:image:height`, `og:image:type`, and `og:image:alt`, so a crawler can lay the card out without fetching it first; an `seo.image` you supply yourself declares none of these, since its size and format are unknown.
- `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` — the X card. Pages with an image get the wide `summary_large_image` variant; pages without one still get the compact `summary` card rather than rendering as a bare link.

### X attribution

X reads everything else on the card from the `og:*` tags, so the only values it can't infer are the accounts to credit. Set them under `seo.x` and Blume emits `twitter:site` (your site's account) and `twitter:creator` (the author's). The `@` is optional — `acme` and `@acme` both work.

```ts blume.config.ts lineNumbers
seo: {
  x: { handle: "@acme", creator: "@jane" },
}
```

A page can claim its own author, which is what you want for a guest post:

```yaml lineNumbers
---
title: How we shipped it
seo:
  x:
    creator: "@guestauthor"
---
```

Override any of the other tags per page with `seo` frontmatter:

```yaml lineNumbers
---
title: Pricing
description: Plans and pricing for every team size.
seo:
  title: Pricing — Acme
  canonical: https://acme.com/pricing
  noindex: false
---
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.title?` | `string` | - | Override the <title> and og:title for this page. |
| `seo.description?` | `string` | - | Override the meta + og:description. |
| `seo.image?` | `string` | - | Custom social image (see Open Graph). |
| `seo.canonical?` | `string` | - | Override the canonical URL. |
| `seo.noindex?` | `boolean` | - | Emit robots noindex and skip structured data. |
| `seo.x.creator?` | `string` | - | Credit this page to an X account (twitter:creator), overriding seo.x.creator from your config. |

## Open Graph images

Blume can render a 1200×630 social card for every page at build time — no headless browser, thanks to [Takumi](https://takumi.kane.tw), so builds stay fast. On by default once [`deployment.site`](/docs/deployment) is set or auto-detected (the `og:image` URL has to be absolute to be useful to crawlers), and off otherwise. Set `enabled` to override that either way:

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}
```

### Brand the generated card

Set a local SVG and color palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

By default, each card is derived from your content and theme — the **page title** as the headline, the **page description** as the subtitle (the same text as its `og:description`, so `seo.description` wins over `description`), your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:

| Page route          | Image URL                  |
| ------------------- | -------------------------- |
| `/`                 | `/og/index.png`            |
| `/quickstart`       | `/og/quickstart.png`       |
| `/configuration/ai` | `/og/configuration/ai.png` |

Override the generated card for any page with `seo.image` — a file in `public/` or an external URL. It takes precedence over the generated card and works even when `og` is off, so you can mix custom images with generated ones:

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
Every palette color accepts any CSS color — hex, `oklch(…)`, `rgb(…)`, and so on. The accent also accepts a named preset (`blue`, `teal`, …), matching [`theme.accent`](/docs/configuration/theming#accent). A color the renderer can't parse fails the build rather than silently shipping a default-colored card.
:::

Emoji in a page title or site title render as [Twemoji](https://github.com/jdecked/twemoji) glyphs, fetched from a CDN while the card renders — so a build whose titles contain emoji needs network access. Each glyph is fetched once per build, however many pages use it.

### Show, hide, or override card layers

Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (the page `description`, or your site `description` for pages without one), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}
```

### Card fonts

By default the card renders in Takumi's built-in font, which covers only Latin glyphs — a title in another script (Japanese, Chinese, Korean, Arabic, …) would render as tofu, empty boxes.

**Set [`theme.fonts`](/docs/configuration/theming#fonts) and the card follows it.** When your config picks its own fonts, the generated cards automatically render the headline in your display font and the description and footer in your body font, so shared links match the site — including non-Latin coverage, with nothing to configure here. (Families from non-Google providers are skipped — the card renderer can only fetch from Google Fonts — but local font files work.)

To use different fonts on cards than on the site, or to add script coverage without touching the theme, set `og.fonts` explicitly — it always wins over the theme-derived fonts:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

Each entry is a Google Fonts family name, an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both), or a local font file — `src` resolves from the project root, with optional `weight` and `style` when the file's own metadata shouldn't decide.

Google families are fetched at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the other fonts can't draw.

An explicit `og.fonts: []` opts out entirely: cards keep the built-in font even when `theme.fonts` is set.

### Custom page titles

A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

Entries only apply to custom pages — a content page's card always takes its headline from the page title, so retitle those in frontmatter instead.

`seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.

## RSS feeds

Blume builds an RSS feed for each content type in `rss.types` — `blog` and `changelog` by default — that has pages, served at `/<type>/rss.xml`. See [Feeds](/docs/content#feeds) for authoring blog and changelog entries with dates.

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

| Option    | Default                 | Description                           |
| --------- | ----------------------- | ------------------------------------- |
| `enabled` | `true`                  | Generate feeds.                       |
| `types`   | `["blog", "changelog"]` | Content types that each get a feed.   |
| `limit`   | `50`                    | Maximum items per feed, newest first. |

Blume injects `<link rel="alternate">` tags so browsers and feed readers discover the feeds automatically.

## Structured data

Blume emits [schema.org](https://schema.org) JSON-LD in every page's `<head>` so search engines understand your content. On by default:

```ts blume.config.ts lineNumbers
seo: {
  structuredData: true,
}
```

Each page includes:

- a **WebSite** node for site identity,
- the page as an **article** — `BlogPosting` for blog posts, `TechArticle` for changelog and docs — with its description and publish date,
- a **BreadcrumbList** built from the navigation trail.

URLs are absolute when `deployment.site` is set. Pages marked `seo.noindex` are skipped.

### Site identity

The WebSite node says a site exists; it doesn't say _what_ it is or _who_ runs it — which is what AI agents read JSON-LD for before they recommend or cite you. Two optional blocks fill that in, both needing `deployment.site` (the nodes carry absolute identifiers):

```ts blume.config.ts lineNumbers
seo: {
  organization: {
    name: "Acme", // defaults to the site title
    email: "hello@acme.com",
    telephone: "+1 555 0100",
    address: { addressLocality: "Sydney", addressCountry: "AU" },
    logo: "/logo.svg",
    sameAs: ["https://github.com/acme", "https://x.com/acme"],
  },
  software: {
    license: "MIT",
    operatingSystem: "Node.js 22+",
    price: 0, // emitted as an Offer; 0 marks it free
    sameAs: ["https://www.npmjs.com/package/acme"],
  },
}
```

`organization` adds an **Organization** node to every page — the WebSite and article nodes cite it as `publisher` — with the email and telephone as a `ContactPoint` (`contactType` defaults to `"customer support"`) and the address as a `PostalAddress`, the two fields business-verification checks look for. `name` and `url` default to the site's; a root-relative `logo` is absolutized like any page URL.

`software` adds a **SoftwareApplication** node to the homepage: the product's name and description (defaulting to the site's), `applicationCategory` (default `"DeveloperApplication"`), operating system, license, an `Offer` when `price` is set, and the registry or repository URLs in `sameAs`. Pass `software: true` to take every default. The organization, when configured, is cited as its `publisher`.

## Sitemap

Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and `noindex` pages. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:

```ts blume.config.ts lineNumbers
seo: {
  sitemap: true,
}
```

Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file you place in `public/`.

## Robots

Blume writes a `robots.txt` that allows all crawlers, declares your [content signals](#content-signals), and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:

```ts blume.config.ts lineNumbers
seo: {
  robots: true,
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://docs.example.com/sitemap.xml
```

### Content signals

The `Content-Signal` line — the emerging content-usage convention — declares how AI crawlers may reuse your docs. Blume emits it **on by default with every signal set to `yes`**, matching its stance that docs are open to humans and agents alike:

- `search` — traditional and AI search indexing
- `aiInput` — grounding / RAG at answer time
- `aiTrain` — model training

Restrict any signal by setting it to `false`; the ones you leave out stay `yes`:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: {
    aiTrain: false, // opt out of training, keep search + grounding
  },
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /
```

Set `contentSignals: false` to drop the declaration entirely:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: false,
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.contentSignals?` | `boolean \| object` | - | Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually. |
| `contentSignals.search?` | `boolean` | - | Allow use for search indexing (search). Default true. |
| `contentSignals.aiInput?` | `boolean` | - | Allow use for AI grounding / RAG at answer time (ai-input). Default true. |
| `contentSignals.aiTrain?` | `boolean` | - | Allow use for AI model training (ai-train). Default true. |

Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honor them.

Ship your own `public/robots.txt` to take over.

---

# Theming
Source: https://useblume.dev/docs/configuration/theming

Blume's theme is token-driven and works in light and dark mode out of the box. Reach for as little or as much as you need: a few config tokens for the common cases, a `theme.css` to override any design token, or Tailwind utilities for custom components.

## Config tokens

The everyday knobs live under `theme` in your config:

```ts blume.config.ts lineNumbers
theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}
```

### Accent

The accent color tints interactive and highlighted elements — step markers, active tabs, badges, card hovers, and more. Use a named preset or any CSS color:

```ts blume.config.ts lineNumbers
theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}
```

Named presets: `blue` (default), `green`, `orange`, `pink`, `purple`, `red`, and `teal`.

A string applies to both color modes; pass an object for [a different accent per mode](#dark-mode-colors).

### Radius

`radius` sets the corner rounding shared by cards, code blocks, callouts, and inputs — `none`, `sm`, `md` (default), or `lg`.

### Color mode

`mode` sets the initial color scheme:

- **`system`** (default) — follow the reader's OS preference
- **`light`** / **`dark`** — default to one scheme

A toggle in the header always lets readers switch, and their choice is remembered across visits. Dark mode is applied with a `data-theme="dark"` attribute on the `<html>` element.

### Fonts

`fonts` sets the typefaces for three roles:

- **`display`** — headings (`h1`–`h6`)
- **`body`** — body text, UI, and prose
- **`mono`** — code blocks and inline code

Headings get display-grade letter-spacing (`-0.05em`) from the theme itself, so whatever you pick for `display` — including text families like the Inter default — reads correctly at heading sizes instead of depending on tracking built into the font.

Each defaults to a curated Google Font, so Blume looks intentional out of the box:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}
```

Set only the roles you want to change — the rest keep their defaults:

```ts blume.config.ts lineNumbers
theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}
```

Fonts are **self-hosted**: Blume downloads them at build time and serves them from your own site, so there's no runtime request to Google and no layout shift (Astro generates fallback-metric faces automatically).

A bare string is a Google Fonts slug from the curated set below:

| Category | Slugs |
| --- | --- |
| Sans | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
| Serif | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4` |
| Mono | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono` |

#### Any provider family

Need a family that isn't in the curated set — say, one that covers a non-Latin script? Pass an object with the family's exact name. It's self-hosted and optimized the same way:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}
```

- **`name`** — the family name exactly as the provider lists it.
- **`provider`** — where the family comes from: `google` (default), `fontsource`, `bunny`, or `fontshare`.
- **`weights`** — the weights to load, as numbers or a variable range like `"100..900"`. Defaults to `[400, 500, 600, 700]`.
- **`subsets`** — the character subsets to load, by the provider's names (`latin`, `latin-ext`, `vietnamese`, `cyrillic`, `greek`, …). Defaults to `latin` plus whatever your configured locales need — see below.
- **`fallback`** — the system stack shown while the font loads and for missing glyphs: `sans`, `serif`, or `mono`. Defaults to `mono` for the mono role and `sans` otherwise.

#### Subsets and locales

Google, Bunny, and Fontsource split each family into per-script subsets, and only the subsets you load get a `@font-face`. Blume derives the list from your [`i18n.locales`](/docs/content/i18n): a site with Vietnamese, Polish, Russian, or Greek locales loads `vietnamese`, `latin-ext`, `cyrillic`, or `greek` alongside `latin`, so diacritics and non-Latin letters render in your chosen font instead of the system fallback. Sites without an `i18n` block, or with only Latin-1 languages, load `latin` alone. Browsers download a subset only when a page uses its characters, and preloads follow the same list.

Set `subsets` on a family to override the derived list — say, for a single-locale site whose content still needs a script its locale doesn't imply:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}
```

Curated slugs like `inter` follow the locale-derived list; use the object form to pin subsets for those families too.

#### Local font files

For a font you own (or one no provider serves), point a role at font files in your project. Each variant becomes one `@font-face`:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}
```

Paths resolve from the project root. `weight` and `style` (`normal`, `italic`, `oblique`) are optional — Astro reads them from the font file when omitted.

:::note
When you set `theme.fonts` explicitly, your display and body fonts also style the generated [Open Graph cards](/docs/configuration/seo#card-fonts) automatically, so shared links match the site. Non-Google provider families are skipped there (the card renderer can only fetch from Google Fonts); local files work everywhere.
:::

Want to drop back to the system stack? Override the `--blume-font-*` tokens directly in [`theme.css`](#themecss).

### Dark-mode colors

`accent` and `background` follow one rule: a string applies to both color modes, and a `{ light, dark }` object sets each mode individually:

```ts blume.config.ts lineNumbers
theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}
```

Each color takes a named preset or any CSS color. For `background` (and `backgroundImage`) either key can be omitted to override a single mode — `background: { dark: "#0a0a0a" }` keeps the default light background.

### Action color

`action` is a secondary accent for primary calls to action and the `action` Tailwind utilities (`bg-action`, `text-action`). It defaults to your `accent`:

```ts blume.config.ts
theme: {
  action: "#ff0066",
}
```

### Background image

Set a background image behind your content with `backgroundImage` — a URL or a path under `public/`. Like the colors, a string applies to both modes and a `{ light, dark }` object sets each mode's image:

```ts blume.config.ts lineNumbers
theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}
```

## theme.css

Drop a `theme.css` in your project root to override any design token. It's the last layer in the cascade, so it wins over the defaults and config tokens:

```css theme.css lineNumbers
:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}
```

Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode. Color tokens have distinct built-in dark values declared at the dark selector's higher specificity, so a `:root`-only override of `--blume-accent`, `--blume-background`, and friends applies to light mode only — declare the dark block too when both modes should change.

`theme.css` is inlined into the site's Tailwind entry, so Tailwind directives work in it too. The one to know for a monorepo is `@source`: Blume scans your project for utility classes, and a page that imports components from a sibling workspace package needs that package scanned as well. Point at it relative to `theme.css` — the standard Tailwind rule — and Blume carries the path into the generated sheet:

```css theme.css lineNumbers
@source "../../packages/ui/src";
```

### Design tokens

| Token                       | Controls                                  |
| --------------------------- | ----------------------------------------- |
| `--blume-background`        | Page background                           |
| `--blume-foreground`        | Body text                                 |
| `--blume-muted`             | Subtle surfaces — callouts, table headers |
| `--blume-muted-foreground`  | Secondary text                            |
| `--blume-border`            | Borders and dividers                      |
| `--blume-accent`            | Accent color                              |
| `--blume-accent-foreground` | Text and icons on an accent background    |
| `--blume-action`            | Secondary accent (defaults to accent)     |
| `--blume-code-background`   | Code block surface                        |
| `--blume-radius`            | Corner radius                             |
| `--blume-font-display`      | Heading font                              |
| `--blume-font-body`         | Body / UI font                            |
| `--blume-font-mono`         | Code font                                 |

Set a `--blume-font-*` token to any font stack to use a font outside the curated list, or to fall back to the system stack:

```css theme.css lineNumbers
:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

## Tailwind utilities

Blume's theme is built with Tailwind v4 internally, and your project's `.astro`, `.tsx`, and `.jsx` files are scanned too — so you can style custom components and pages with utility classes, no Tailwind setup required. Every token is exposed as a utility, so your components track the theme automatically:

| Token                       | Utilities                  |
| --------------------------- | -------------------------- |
| `--blume-background`        | `bg-background`            |
| `--blume-foreground`        | `text-foreground`          |
| `--blume-muted`             | `bg-muted`                 |
| `--blume-muted-foreground`  | `text-muted-foreground`    |
| `--blume-border`            | `border-border`            |
| `--blume-accent`            | `bg-accent`, `text-accent` |
| `--blume-accent-foreground` | `text-accent-foreground`   |
| `--blume-action`            | `bg-action`, `text-action` |
| `--blume-radius`            | `rounded-blume`            |
| `--blume-font-display`      | `font-display`             |
| `--blume-font-body`         | `font-sans`                |
| `--blume-font-mono`         | `font-mono`                |

## Cascade order

Styles resolve in three layers, each overriding the last:

1. **Base**

    Blume's reset, default tokens, and component styles.

2. **Config tokens**

    `--blume-accent`, `--blume-radius`, and the `--blume-font-*` tokens from
    `theme`.

3. **theme.css**

    Your token overrides — the final word.

---

# Pages
Source: https://useblume.dev/docs/content

Your docs are just a folder of Markdown and MDX files. Blume turns each file into a page — routing, navigation, and metadata are inferred from the file system, so there's no manifest to keep in sync.

Content lives under your **content root** (`docs/` by default; change it with `content.root` in [`blume.config.ts`](/docs/configuration)).

## Markdown and MDX

Blume renders two kinds of file:

- **`.md`** — Markdown for plain prose: GFM, frontmatter, smart punctuation, and super/subscript.
- **`.mdx`** — everything `.md` has, plus [components](/docs/content/components) and the MDX-only [directives, package installs, and math](/docs/content/syntax).

Reach for `.md` when a page is just prose, and `.mdx` when it needs components or directives. Switching is as simple as renaming the file.

## Files and routes

Each file maps to a route by its path under the content root:

| File                      | Route             |
| ------------------------- | ----------------- |
| `docs/index.mdx`          | `/`               |
| `docs/quickstart.mdx`     | `/quickstart`     |
| `docs/guides/theming.mdx` | `/guides/theming` |
| `docs/guides/index.mdx`   | `/guides`         |

Nested folders become nested routes, and an `index.mdx` inside a folder becomes that folder's own page.

## Ordering with numeric prefixes

Prefix a file or folder with a number to control its order in the sidebar. The prefix is stripped from the URL, so you can reorder pages without breaking links:

```txt
01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation
```

Ordering has several layers — see [Navigation](/docs/content/navigation) for the full precedence rules.

## Group folders

Wrap a folder name in parentheses to group its pages in the sidebar **without** adding a URL segment:

```txt
docs/(internal)/security.mdx  ->  /security
```

The pages share an “Internal” sidebar group but keep flat, parenthesis-free URLs.

## Drafts

Mark a page as a draft to keep it out of production builds while still previewing it in `blume dev`:

```yaml lineNumbers
---
title: Work in progress
draft: true
---
```

`blume build` skips drafts; `blume dev` renders them so you can work in the open.

## Content types

Every page has a **type**, set with the `type` frontmatter field (default `doc`). Types let Blume treat groups of pages differently — most importantly, `blog` and `changelog` pages are collected into [feeds](#feeds).

```yaml lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---
```

The type is independent of where the file lives, but by convention blog posts go under `blog/` and changelog entries under `changelog/`. Both get an RSS feed automatically, and changelog entries are also collected into a generated [`/changelog` timeline](/docs/advanced/changelog). See [Blog](/docs/advanced/blog) and [Changelog](/docs/advanced/changelog) for authoring each.

## Feeds

Blume generates an RSS feed automatically for each content type listed in [`rss.types`](/docs/configuration/seo#rss-feeds) — `blog` and `changelog` by default — as long as it has at least one page. Feeds are served at `/<type>/rss.xml`:

| Type        | Feed                 |
| ----------- | -------------------- |
| `blog`      | `/blog/rss.xml`      |
| `changelog` | `/changelog/rss.xml` |

Give each entry a `date` so items sort newest-first and carry a `pubDate`. An unquoted YAML date is fine — Blume normalizes it:

```yaml lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---
```

Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment). Blume adds `<link rel="alternate">` tags to every page so browsers and feed readers discover them automatically. See [Blog](/docs/advanced/blog) and [Changelog](/docs/advanced/changelog) for authoring each content type.

## On this page

Every page gets an automatic table of contents, built from its headings. On wide screens it sits in a sticky sidebar beside your content; on narrower screens it collapses into an **On this page** panel above the page. As you scroll, the entry for the section you're reading is highlighted, so you always know where you are in a long page.

Blume slugifies each heading into an anchor, so every entry links straight to its section — and you can deep-link to any heading by appending its slug to the URL (`.../my-page#getting-started`).

The contents list your `##` and `###` headings (H2 and H3). A page with no headings at that level simply has no table of contents.

## Where to next

**[Frontmatter](/docs/reference/frontmatter)**

Page metadata: title, description, sidebar, SEO, and search.

**[Syntax](/docs/content/syntax)**

Every Markdown and MDX feature you can write.

**[Components](/docs/content/components)**

The JSX components available in any MDX page.

**[Navigation](/docs/content/navigation)**

Shape the sidebar, ordering, and tabs.

**[Folder meta](/docs/content/meta)**

Configure a sidebar group with a `meta.ts` file.

---

# Components
Source: https://useblume.dev/docs/content/components

Blume ships an accessible, themeable component set available in any `.mdx` page with **no imports**. Each one is shown below with a live preview and its source. Components are vanilla and React-free; React only switches on if you add your own island.

## Card and CardGroup

Cards link to a destination with an icon, title, and short blurb. Group them with `CardGroup` for a responsive grid. Reach for them on landing pages, section indexes, and “next steps” — anywhere you’re guiding the reader onward.

**[Quickstart](/docs/quickstart)**

Install Blume and ship your first page.

**[Components](/docs/content/components)**

Browse the component library.

```astro lineNumbers
<CardGroup cols={2}>
  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
    Install Blume and ship your first page.
  </Card>
  <Card title="Components" href="/docs/content/components" icon="folder">
    Browse the component library.
  </Card>
</CardGroup>
```

`Card` takes `title`, an optional `href` (omit it for a non-clickable card), and an `icon` from Blume's built-in icon set. `CardGroup` takes `cols` (default `2`).

## Steps

A numbered vertical sequence for ordered instructions — installs, setup flows, and tutorials where the order matters. Each `Step` takes a `title`.

1. **Install Blume**

    Add the package to your project.

2. **Write a page**

    Drop an `.mdx` file into your content folder.

3. **Ship it**

    Run `blume build` and deploy `dist/`.

```astro lineNumbers
<Steps>
  <Step title="Install Blume">Add the package to your project.</Step>
  <Step title="Write a page">
    Drop an `.mdx` file into your content folder.
  </Step>
  <Step title="Ship it">Run `blume build` and deploy `dist/`.</Step>
</Steps>
```

## Tabs

Switch between equivalent content in place — language variants, OS-specific commands, or alternative approaches — without stacking everything on the page. Each `Tab` takes a `title`.

**macOS**

Use Homebrew to install the toolchain.

**Windows**

Use winget to install the toolchain.

```astro lineNumbers
<Tabs>
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

Add `inline` to render borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. Add `param` to sync the active tab to a URL query param instead of the hash, which makes the selection shareable: a link ending in `?install=windows` opens on the Windows tab. Each group syncs to its own `param`, so you can use several independent, deep-linkable groups on one page.

Groups with same-titled tabs switch together — pick "macOS" in one and every group with a macOS tab follows. Add `syncKey` to scope that syncing: only groups sharing the same key switch together, so unrelated groups that happen to share a tab title stay independent.

**macOS**

Use Homebrew to install the toolchain.

**Windows**

Use winget to install the toolchain.

```astro lineNumbers
<Tabs inline param="install">
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

## Badge

A small inline label for status or metadata — version tags, “new” or “beta” markers, stability levels. The `variant` tunes the color to the meaning.

### Default

Neutral metadata with no particular emphasis.

<Badge>Stable</Badge>

```astro
<Badge>Stable</Badge>
```

### Accent

Draws the eye using your theme accent — good for “new” or featured markers.

<Badge variant="accent">New</Badge>

```astro
<Badge variant="accent">New</Badge>
```

### Success

A positive or passing state.

<Badge variant="success">Passing</Badge>

```astro
<Badge variant="success">Passing</Badge>
```

### Warning

Something to use with caution, such as an experimental feature.

<Badge variant="warning">Beta</Badge>

```astro
<Badge variant="warning">Beta</Badge>
```

### Danger

A negative or breaking state, such as a deprecation.

<Badge variant="danger">Deprecated</Badge>

```astro
<Badge variant="danger">Deprecated</Badge>
```

## Icon

Render an icon by name — the same `icon` prop powers cards, steps, tabs, and sidebar entries. Names come from [Lucide](https://lucide.dev/icons), lowercase and kebab-cased (`rocket`, `gauge`, `book-open`).

<Icon icon="rocket" size={20} />

```astro
<Icon icon="rocket" size={20} />
```

Blume is Lucide-only — a bare name resolves against Lucide, and you can prefix a name with `lucide:` (`lucide:rocket`) for symmetry with other icon inputs. `size` sets the pixel size (default `16`) and `color` tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string, an image URL, or a local image path in place of a name to render your own art, and add a `label` to expose it to assistive tech — without one, the icon is decorative.

Icons resolve at build time and inline as zero-JS SVG — nothing is fetched at runtime.

## File tree

Illustrate a project or folder layout. Wrap a normal Markdown list and Blume styles it as a tree — handy for explaining structure in setup and config guides.

<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>

```astro lineNumbers
<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>
```

## Accordion

Stack related collapsibles in a single bordered container with dividers between them — FAQs, optional steps, or long examples. Each child is an `AccordionItem` (`title`, optional `icon`, `description`, `defaultOpen`). For a single standalone disclosure, use [Expandable](#expandable).

<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>

```astro lineNumbers
<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>
```

## Expandable

A lightweight inline disclosure for nested detail — expanding a field's sub-properties or an optional aside. `title` labels the toggle (defaults to “Show more”); set `defaultOpen` to start expanded.

<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>

```astro
<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>
```

## Columns

Lay cards or blocks out in a responsive grid of equal columns that reflows on mobile. `Columns` takes `cols`; wrap each cell in a `Column`.

<Columns cols={2}>
  <Column>
    **Fast**

    Built on Astro and Vite.
  </Column>
  <Column>
    **Themeable**

    Tailwind v4 design tokens.
  </Column>
</Columns>

```astro lineNumbers
<Columns cols={2}>
  <Column>
    <Card title="Fast" icon="rocket">
      Built on Astro and Vite.
    </Card>
  </Column>
  <Column>
    <Card title="Themeable" icon="sun">
      Tailwind v4 design tokens.
    </Card>
  </Column>
</Columns>
```

## CodeGroup

Group several code blocks into one tabbed switcher — a tab per language or file. The tab label is each block's title (the text after the language), and the group's copy button sits in the tab bar and copies the block that is showing. Add `dropdown` to switch with a menu instead of a tab bar.

<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>

````astro
<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>
````

## Frame

Wrap an image or any visual in a centered, bordered frame with an optional `caption` (rendered as Markdown) and `hint`.

<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <svg
    width="160"
    height="72"
    viewBox="0 0 160 72"
    role="img"
    aria-label="Sample frame"
  >
    <rect width="160" height="72" rx="8" fill="#3b82f6" />
  </svg>
</Frame>

```astro lineNumbers
<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <img src="/screenshot.png" alt="Product screenshot" />
</Frame>
```

## YouTube

Embed a YouTube video in a responsive, privacy-friendly (`youtube-nocookie.com`) 16:9 frame that ships no client JavaScript. Pass a video `id` or a full `url`, plus an optional `title` (for accessibility) and a `start` time in seconds.

[Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

```astro lineNumbers
<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
<YouTube url="https://youtu.be/aqz-KE-bpKQ" start={30} />
```

## Color

Show color swatches with copyable hex values — useful for documenting a palette or brand colors. Use `variant="compact"` for a swatch list, or `variant="table"` with `Color.Row` to group them. Each `Color.Item` takes a `name` and a `value` (a hex string, or `{ light, dark }` for theme-aware colors).

<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>

```astro lineNumbers
<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>
```

## Tree

Render a hierarchical file/folder structure with expandable folders. (For a quick, list-driven version see [File tree](#file-tree); `Tree` gives per-folder control.) Use `Tree.Folder` (`name`, optional `defaultOpen`, `openable`) and `Tree.File` (`name`).

<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>

```astro lineNumbers
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>
```

## Panel

A titled container for supplementary, set-aside content. `title` is optional.

<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>

```astro
<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>
```

## Tooltip

Reveal a definition or hint on hover for an inline term. `tip` is the hover text; add an optional `headline` and a `cta` + `href` for a follow-up link.

Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term to learn more.

```astro
Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term.
```

## Tile

A clickable preview that leads with a visual — an icon or image — above a title and description. Good for galleries and showcases. Takes `title`, `description`, and `href`; the child is the visual.

<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>

```astro
<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>
```

## Prompt

A single row with a label and a copy button. The `description` (Markdown) is the visible label; the body is the prompt itself — hidden, and copied to the clipboard when the **Copy prompt** button is pressed. `actions` controls the buttons (e.g. `["copy", "cursor"]`).

<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>

```astro
<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>
```

## Visibility

Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the agent-facing Markdown that AI agents read (`llms-full.txt` and each page's `.md` mirror).

```astro
<Visibility for="web">Shown on the site only.</Visibility>
<Visibility for="agents">Shown only in the generated Markdown.</Visibility>
```

## Type tables

Tables for documenting an object's properties — its props, types, and defaults. Write the rows by hand with `TypeTable`, or generate them straight from a TypeScript interface or type alias with `AutoTypeTable`.

### Type table

A **Prop / Type** grid where each row expands to reveal its description and details. Pass a `type` map keyed by property name; each entry takes a `type`, plus an optional `description`, `default`, `required` flag, `typeDescription`, and `typeDescriptionLink`. Optional props (`required` unset) show a `?` after the name.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | - | The button's visible label. |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | Visual style. |
| `disabled?` | `boolean` | - | |

```astro lineNumbers
<TypeTable
  type={{
    label: {
      type: "string",
      required: true,
      description: "The button's visible label.",
    },
    variant: {
      type: '"primary" | "ghost"',
      default: '"primary"',
      description: "Visual style.",
    },
    disabled: { type: "boolean" },
  }}
/>
```

### Auto type table

Generate a type table from a TypeScript type so the docs stay in sync with the source. Point `AutoTypeTable` at a file with `path` (resolved from your project root) and a type `name`. Descriptions come from JSDoc comments, defaults from `@default` tags, and optional properties (`?`) are marked accordingly.

```astro
<AutoTypeTable path="./src/button.ts" name="ButtonProps" />
```

You can also pass the type inline with `type` instead of a `path` — handy for small examples:

<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>

```astro lineNumbers
<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>
```

## GitHub info

A card linking to a GitHub repository with its live star and fork counts. Counts are fetched at build time — no client JavaScript — and the card still renders if the API is unreachable. Pass `owner` and `repo`, or omit them to use the repository from your `blume.config`. Set a `GITHUB_TOKEN` environment variable to lift the API rate limit.

The card reads the instance from [`github.host`](/docs/configuration#github-enterprise), so on an Enterprise-hosted site explicit `owner`/`repo` address that instance too. Pass `host` to point one card somewhere else — a public project from an Enterprise site, say; the REST base is derived from it the same way it is from `github.host`.

<GithubInfo owner="haydenbleasel" repo="blume" />

```astro lineNumbers
<!-- Uses the repo from blume.config -->
<GithubInfo />

<!-- Or point it at any repository -->
<GithubInfo owner="haydenbleasel" repo="blume" />

<!-- Or at a repository on another instance -->
<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
```

## Component

`Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.

The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your project and your examples directory), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.

To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:

```ts
// blume.config.ts
export default defineConfig({
  examples: { css: "examples/theme.css" },
});
```

```css
/* examples/theme.css */
:root {
  --primary: oklch(0.6 0.2 260);
}

.dark {
  --primary: oklch(0.75 0.15 260);
}

@theme inline {
  --color-primary: var(--primary);
}
```

The directory is configurable too — set `source` (or use the string shorthand, `examples: "..."`) when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it:

```ts
// blume.config.ts
export default defineConfig({
  examples: "registry/files-sdk",
});
```

```astro
<!-- registry/files-sdk/file-list/basic.tsx -->
<Component path="file-list/basic" />
```

`examples` can also be a glob (anything with `*`, `?`, `[]`, `{}`, or `!`). Only matching files are discovered, and `path` is relative to the glob's static prefix (the part before the first wildcard). This is for a registry that colocates each component's source with its example — point at just the examples so the sources, which have no default export to preview, aren't swept in:

```ts
// blume.config.ts
export default defineConfig({
  // registry/files-sdk/file-list/file-list.tsx — source, left out
  // registry/files-sdk/file-list/examples/basic.tsx — discovered
  examples: "registry/files-sdk/**/examples/*",
});
```

```astro
<!-- keyed relative to registry/files-sdk -->
<Component path="file-list/examples/basic" />
```

In a monorepo, the components your examples import usually live in a sibling workspace package. Tailwind's `@source` scans files, not imports: Blume scans your project and the `examples` directory (wherever `source` points, even outside the project), so a class used only inside that sibling package isn't generated until you add the package to the scan. Do that with an `@source` directive in `examples.css` (for the preview frames) or `theme.css` (for the site), written relative to the file it sits in — the standard Tailwind rule — and Blume carries it into the generated sheet:

```css
/* examples/theme.css */
@source "../../../packages/ui/src";
```

```tsx
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <button
      className="rounded-blume border-border bg-background text-foreground hover:bg-muted border px-4 py-2 text-sm font-medium transition-colors"
      onClick={() => setCount((value) => value + 1)}
      type="button"
    >
      Clicked {count} {count === 1 ? "time" : "times"}
    </button>
  );
};

export default Counter;
```

```astro
<!-- examples/counter.tsx -->
<Component path="counter" />
```

An Astro example renders live with no client JavaScript:

```astro
---
interface Props {
  title?: string;
}

const { title = "Hello from Astro" } = Astro.props;
---

<div class="rounded-blume border border-border bg-muted/30 px-5 py-4">
  <p class="m-0 font-semibold text-foreground text-sm">{title}</p>
  <p class="m-0 mt-1 text-muted-foreground text-sm">
    A static, server-rendered example — no client JavaScript ships.
  </p>
</div>
```

## CodeBlock

`CodeBlock` highlights a code string with the same Shiki theme and transformers as your fenced code — including the light/dark swap — for places a fence can't go, like a landing page or a custom component. Pass `code` and a `lang`:

<CodeBlock
  lang="ts"
  code={`export const greet = (name: string): string =>
  \`Hello, \${name}!\`;`}
/>

```astro
---
import CodeBlock from "blume/components/content/CodeBlock.astro";
---

<CodeBlock lang="ts" code={source} />
```

To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`:

```ts
import { highlightCode } from "blume/markdown";

const html = await highlightCode(source, "ts");
```

## Diff

`Diff` renders a git-style diff, highlighted with the same Shiki theme as your code blocks and produced entirely at build time — no client JavaScript. Give it two inline strings (`old` / `new`), two file paths (`before` / `after`), or a unified patch (an inline `patch` string or a `src` file).

<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>

```astro
<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>
```

Diff two files in your project, relative to its root:

<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />

```astro
<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />
```

Or render a unified patch — either from a file with `src`, or inline with `patch`:

<Diff src="diffs/greet.patch" />

```astro
<Diff src="diffs/greet.patch" />
```

```astro
<Diff
  patch={`--- a/greet.ts
+++ b/greet.ts
@@ -1,3 +1,4 @@
-export function greet(name) {
-  return "Hi, " + name;
+export function greet(name: string): string {
+  const greeting = "Hi, " + name + "!";
+  return greeting;
 }`}
/>
```

---

# Internationalization
Source: https://useblume.dev/docs/content/i18n

Blume serves one project in many languages. Drop translated files into the right place and Blume wires up routing, the language switcher, per-locale navigation, and SEO for you — there's no separate routing layer to maintain. It's opt-in: without an `i18n` block, your site stays single-language exactly as before. It also composes with [versioning](/docs/content/versioning) — a frozen snapshot keeps its translations, and locale fallback works within each version.

## Enable it

Add an `i18n` block listing your locales and which one is the default:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}
```

Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default). An optional `style` gives [`blume translate`](/docs/reference/translate) freeform guidance for the locale — register, dialect, terminology, e.g. `"Brazilian Portuguese, informal você"` — so the choice is pinned from the very first translation instead of decided by the agent.

## Organize translated content

The default locale lives at your content root. Every other locale is a top-level folder named by its `code`, mirroring the default structure:

```txt
docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar
```

| File                            | Route                   |
| ------------------------------- | ----------------------- |
| `docs/index.mdx`                | `/`                     |
| `docs/guides/quickstart.mdx`    | `/guides/quickstart`    |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

You only translate the files you want — everything else falls back automatically (see [Fallbacks](#fallbacks)).

### Filename suffixes

Prefer to keep translations next to the original? Set `parser: "dot"` and name files with a locale suffix instead of using folders:

```txt
docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)
```

Good for sparse translations — colocate the few pages you've translated without mirroring the whole tree.

### Shared files

For content that's the same in every language — a changelog, a status page — add a `$` marker so one file serves all locales without duplication:

```txt
docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

A locale-specific `meta.ts` still overrides the shared one for that language.

## Default-locale URLs

By default the default locale has no URL prefix (`/`, `/guides/quickstart`) while other locales are prefixed (`/fr/…`). This keeps your primary language's URLs clean. To prefix every locale, including the default:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## Per-locale navigation

Each language gets its own sidebar, built from that locale's files — so translations can diverge in structure, ordering, or labels. Folder [`meta.ts`](/docs/content/meta) files resolve per locale, too: under the default `dir` parser, put a `meta.ts` under `fr/guides/` to order the French group independently. Under the `dot` parser translations sit next to the originals, so a folder's `meta.ts` applies to every locale. Everything else about [navigation](/docs/content/navigation) works the same, per language.

Header tabs are configured, not derived from content, so their labels localize in `blume.config.ts`: a tab `label` accepts a per-locale map (`{ en: "Docs", fr: "Documentation" }`) alongside the plain-string form, falling back to the default locale's entry for locales you haven't filled in. See [Tabs](/docs/content/navigation#tabs).

## Fallbacks

When a page isn't translated yet, Blume renders the fallback locale's content at the localized URL — so the link works, the page is fully pre-rendered, and search engines aren't sent to a dead end. The fallback defaults to your `defaultLocale`:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}
```

Fallback pages are excluded from the search index and aren't advertised as real translations in `hreflang`, so untranslated content doesn't compete for ranking. They still appear in that locale's sidebar, so navigation stays complete — a reader can reach every page in any language.

:::tip
Start by translating your most important pages — the homepage, quickstart, and top guides — and let the rest fall back. You can fill in translations over time without breaking any links.
:::

## Translating with an agent

You don't have to fill in the locales by hand. [`blume translate`](/docs/reference/translate) finds every page that's missing or outdated in each locale and translates it with a local agent CLI ([Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli)):

```bash
blume translate --claude
```

Blume validates each result's structure — frontmatter, code fences, links — and writes the files itself; the agent only translates text. A committed ledger (`blume.translations.json`) tracks which source revision each translation came from, so reruns only touch what changed, and translations you wrote by hand are adopted as-is, never overwritten. In CI, `blume translate --check` fails when a source page has drifted ahead of its translations.

## The language switcher

When i18n is on, a language switcher appears in the header automatically, generated from your `locales`. For each page it links the matching translation in every language; where a translation is missing it links the fallback page and marks it as not translated. There's nothing to configure.

## Translated UI

Blume ships built-in translations for its own interface chrome — “On this page”, “Search”, “Edit on GitHub”, and the rest — so a locale with a built-in pack gets translated UI out of the box. **You only translate your content.**

Packs ship for over 30 languages — Arabic, Bengali, Bulgarian, Catalan, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (and Brazilian Portuguese), Romanian, Russian, Serbian, Slovak, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese. They're community-maintained — open a PR to add a locale or sharpen a translation.

Missing or unshipped strings fall back to the default locale, then to English. To override a string or supply your own language, set `i18n.ui`, keyed by locale:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}
```

## SEO

Localized SEO is handled for you — no per-page metadata to write:

- `<html lang>` and `dir` are set from the active locale.
- `hreflang` alternates link every real translation of a page, plus an `x-default` pointing at the default locale.
- Canonical URLs are locale-correct, and JSON-LD carries `inLanguage`.

Set [`deployment.site`](/docs/deployment) so these can be emitted as absolute URLs.

## Search

Search is scoped to the active language: on a `/fr/…` page the dialog returns French results, with an **All languages** toggle to search across every locale at once. The default (Orama) and FlexSearch indexes filter in the browser; hosted providers carry a `locale` facet on each record.

## Right-to-left

Set `dir: "rtl"` on a locale and Blume mirrors the whole interface — the sidebar, header, table of contents, pagination, search, and menus — and sets `<html dir>` to match. Two things deliberately stay left-to-right: **code blocks** (code reads LTR in any language) and **fallback content** — an untranslated page keeps the direction of the language it's actually written in, so English shown under an RTL locale still reads correctly while the surrounding chrome mirrors.

## Where to next

**[Navigation](/docs/content/navigation)**

Shape each locale's sidebar, ordering, and tabs.

**[SEO](/docs/configuration/seo)**

Sitemaps, Open Graph, and structured data.

---

# Includes
Source: https://useblume.dev/docs/content/includes

Write a snippet once and splice it into any page. An `<include>` statement on its own line embeds another file at build time, as if its content were written inline — headings join the page's table of contents, text is indexed by search, and the content appears in the page's `.md` mirror and llms-full.txt.

```mdx
<include>./_snippets/prerequisites.mdx</include>
```

The path is resolved relative to the including file. Paths starting with `/` resolve from your content root, so deeply nested pages can reference shared snippets without `../../..` chains:

```mdx
<include>/_snippets/prerequisites.mdx</include>
```

The syntax matches Fumadocs' include syntax, so migrated content works unchanged.

Here it is live — this next callout is spliced from a shared snippet:

:::tip
This callout lives in `_snippets/include-demo.mdx` — it renders here because the page splices it with an `<include>` statement.
:::

## Partials

Any file whose name (or folder) starts with an underscore is excluded from routing, navigation, search, and sitemaps by default — that convention is the natural home for shared snippets:

```text
docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx
```

A partial is a normal Markdown or MDX file. Its front matter is stripped when spliced (the including page's front matter wins), and everything else — callouts, code fences, components, math — renders exactly as it would inline. Partials can include other partials; a circular include is reported as an error.

Relative image references inside a partial keep working: they're rebased onto the including page, so a colocated `![diagram](./diagram.png)` next to the partial resolves wherever the partial is spliced.

Editing a partial while `blume dev` is running reloads every page that includes it.

## Including code files

A target that isn't `.md`/`.mdx` is embedded as a fenced code block, with the language inferred from the extension. Use `lang` to override the language (or to show a Markdown file as source rather than splicing it), and `meta` to pass a fence meta string such as a title:

```mdx
<include>./examples/config.ts</include>

<include lang="ts" meta='title="blume.config.ts"'>
  ../blume.config.ts
</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>
```

## Rules and diagnostics

Include statements must occupy their own line — they're block-level, not inline. Statements inside fenced code blocks are left alone, so you can document the syntax itself (like this page does).

Targets must live inside your content root: a file outside it would be silently missing from version snapshots and ejected projects, so `blume` reports `BLUME_INCLUDE_OUTSIDE_ROOT` instead of splicing it. A target that doesn't exist is `BLUME_INCLUDE_NOT_FOUND`, and a loop of includes is `BLUME_INCLUDE_CYCLE` — all three fail `blume build` (pass `--no-strict` to build anyway) and appear in `blume validate`.

Broken links inside a partial are reported against the partial file, not the pages that splice it, so you fix them where they live.

:::note
Partials are shared across locales and are not translated by `blume translate` — keep partials language-neutral (code, tables, diagrams), or create per-locale partials and include them from each locale's pages.
:::

---

# Islands
Source: https://useblume.dev/docs/content/islands

Blume renders your docs as static HTML with **zero JavaScript** by default. When you need something interactive — a live demo, a chart, a playground — you add an **island**: a framework component that ships JS only for itself, only on the pages that use it.

## The `islands/` convention

Drop a component into an `islands/` folder at your project root. Its filename becomes a component you can use in **any** `.mdx` page, with no import:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Clicked {count}</button>;
}
```

```mdx page.mdx
Here's a live counter: <Counter />
```

The filename is the component name, so it **must be a PascalCase identifier** — letters, digits, and underscores only (`Counter.tsx` → `<Counter />`). Lowercase filenames, names with dashes/dots/spaces (like `Time-Picker.tsx`), and two islands that resolve to the same name are skipped with a build warning.

:::note
Islands are for **interactive** UI. For a static component you reuse across pages (a styled callout, a pricing table), use an [MDX override](/docs/configuration/customization) instead — it ships no JavaScript.
:::

## Registering islands in `components.ts`

If you'd rather keep islands next to the rest of your components — or give them a different name than the file — register them with `defineComponents`. The `islands` group is exactly like the `islands/` folder: each entry is available in every MDX page and hydrates (defaulting to `client: "visible"`).

```ts components.ts
import { defineComponents } from "blume";
import Counter from "./widgets/Counter.tsx";

export default defineComponents({
  islands: {
    Counter, // <Counter /> in any MDX page, hydrated
  },
});
```

Reference the component by import or by a path string, and set a hydration mode per island with the descriptor form:

```ts components.ts
export default defineComponents({
  islands: {
    Chart: { component: "./widgets/Chart.tsx", client: "only" },
  },
});
```

## Hydration

By default an island uses `client:visible`: it hydrates when the reader scrolls it into view, so a page full of islands still loads instantly. Opt into a different strategy with an `export const client` in the island file:

```tsx islands/Chart.tsx lineNumbers
// Skip server rendering entirely — for components that touch the DOM/window.
export const client = "only";

export default function Chart() {
  /* ... */
}
```

| `client` value | Hydrates | Use it for |
| --- | --- | --- |
| `"visible"` _(default)_ | When scrolled into view | Most islands |
| `"load"` | Immediately on page load | Above-the-fold, must-be-instant UI |
| `"idle"` | When the main thread is idle | Non-urgent interactivity |
| `"only"` | Client only, never server-rendered | Libraries that need `window`/`document` (charts, editors) |

## Frameworks

**React works out of the box** — Blume turns it on automatically the moment your project contains a `.tsx`/`.jsx` island.

The [React Compiler](https://react.dev/learn/react-compiler) is on by default whenever React is enabled, so your islands are auto-memoized — no hand-written `useMemo`/`useCallback` needed. It ships with Blume; there's nothing to install. Opt out in `blume.config.ts`:

```ts blume.config.ts
export default defineConfig({
  react: { compiler: false },
});
```

**Vue and Svelte** are supported too; install the matching Astro integration and Blume wires up the renderer when it sees a `.vue` or `.svelte` island:

```bash
# Vue
npm install @astrojs/vue vue

# Svelte
npm install @astrojs/svelte svelte
```

```vue islands/Toggle.vue lineNumbers
<script setup>
import { ref } from "vue";
const on = ref(false);
</script>

<template>
  <button @click="on = !on">{{ on ? "On" : "Off" }}</button>
</template>
```

Props you pass in MDX (`<Counter start={5} />`) are forwarded to the component, and children (`<Counter>label</Counter>`) arrive as the default slot.

:::tip
Islands hydrate on the client, so anything you pass as a prop must be serializable — strings, numbers, plain objects, not functions.
:::

## Hooks

Islands hydrate on their own, so there's no React context to thread project data through. Instead, `blume/hooks` reads a small snapshot the layout serializes into the page — no props to drill:

```tsx islands/PageInfo.tsx lineNumbers
import { useBlume, usePage } from "blume/hooks";

export default function PageInfo() {
  const blume = useBlume();
  const page = usePage();
  if (!(blume && page)) {
    return null;
  }
  return (
    <p>
      You're reading <strong>{page.title}</strong> on {blume.config.title}.
    </p>
  );
}
```

| Hook | Returns |
| --- | --- |
| `useBlume()` | `{ config, navigation }` for the site, or `null` before mount |
| `usePage()` | `{ route, title }` for the current page, or `null` before mount |
| `useSearch()` | `{ search, results, loading }` — query the configured search provider |
| `useAskAI()` | `{ ask, messages, loading, reset }` — stream from the Ask AI endpoint |

`useBlume()` and `usePage()` return `null` until the island mounts (so server and client render the same first frame) — guard for it. The snapshot is emitted only on pages that ship React, so a fully static site pays nothing.

On [custom pages](/docs/advanced/custom-pages) built with `PageLayout`, pass `clientData` so islands there can read it:

```astro
<PageLayout
  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
  {/* …other props… */}
/>
```

---

# Folder meta
Source: https://useblume.dev/docs/content/meta

Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).

## Defining meta

Export a `defineMeta` object for a fully typed config. Place the file at the root of the folder it configures — `guides/meta.ts` configures the **Guides** group:

```ts meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});
```

Every field is optional — set only what you want to override.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `title` | `string` | The group's label. Defaults to the humanized folder name. |
| `icon` | `string` | Icon shown next to the label. |
| `order` | `number` | Position among sibling groups and pages. Lower numbers sort first. |
| `collapsed` | `boolean` | Under the [`group` display mode](/docs/content/navigation#display-modes), whether the group starts collapsed. |
| `display` | `"flat" \| "group" \| "page"` | Render mode for this group; overrides the global [`navigation.sidebar.display`](/docs/content/navigation#display-modes). |
| `pages` | `string[]` | Explicit order for the group's children, by slug. |

The `pages` array lists children by slug — the folder or file name with its numeric prefix and any parentheses stripped (so `01-quickstart.mdx` is `"quickstart"`). Children you leave out still appear, after the listed ones.

How groups render — flat headers, collapsible disclosures, or drill-in panels — defaults to the sidebar-wide `navigation.sidebar.display`; set `display` here to override it for this group alone. A folder's `index` page can also set it from frontmatter, which wins over `meta.ts` — see [per-group overrides](/docs/content/navigation#per-group-overrides).

## Computed meta

Because `meta.ts` is a real module, you can compute the meta — pass a function (sync or `async`) instead of an object to build it at scan time. Handy for ordering pages from an external source:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));
```

## Ordering within a group

The `pages` array sets the order of a group's children. Anything it omits falls back to each page's frontmatter `sidebar.order`, then the file system (an `index` page first, then numeric prefixes, then alphabetical). For the full sidebar precedence — including an explicit config sidebar — see [Navigation › Ordering](/docs/content/navigation#ordering).

To group pages _without_ adding a URL segment, you don't need a `meta.ts` at all: use a parenthesized folder name — see [Pages › Group folders](/docs/content#group-folders).

## Internationalization

Under [i18n](/docs/content/i18n), folder meta resolves per locale: put a `meta.ts` under `fr/guides/` to order the French group independently.

For folder meta that's identical in every language, add a `$` marker so one file serves all locales without duplication:

```txt
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

A locale-specific `meta.ts` still overrides the shared `meta.$.ts` for that language.

## Where to next

**[Navigation](/docs/content/navigation)**

How the sidebar, breadcrumbs, and tabs are built.

**[Frontmatter](/docs/reference/frontmatter)**

Per-page metadata, including the `sidebar` overrides.

---

# Navigation
Source: https://useblume.dev/docs/content/navigation

Blume builds your sidebar from the file system, then lets you refine it as much — or as little — as you want: page by page, folder by folder, or with one explicit config. Breadcrumbs, previous/next links, and the on-page outline all follow from the same model, with nothing to wire up.

## The generated sidebar

By default the sidebar mirrors your content tree:

- folders become **groups**, files become **pages**
- a page's label is its frontmatter `title`; a group's label is the humanized folder name
- items sort by [numeric prefix](/docs/content), then alphabetically, and a folder's `index` page comes first

That's enough for many sites — everything below is opt-in.

## Page label, icon, and badge

Tune how a single page appears in the sidebar from its frontmatter, under `sidebar`:

```yaml lineNumbers
sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group
```

See [Frontmatter](/docs/reference/frontmatter) for the full page schema.

## Folder groups

Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta) beside its pages to set the group's title, icon, order, and the order of its children:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

See [Folder meta](/docs/content/meta) for every field and computing meta at scan time.

A folder's `meta.title` and its own `index` page's frontmatter `title` are resolved independently — translating one under i18n and forgetting the other renders a correct sidebar with a stale `<title>`/heading on the landing page itself. Blume reports a `BLUME_NAV_INDEX_TITLE_MISMATCH` warning when they diverge. Untranslated pages filled in from the fallback locale are exempt — their title belongs to the fallback locale, and the fix is translating the page, not editing its frontmatter.

To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).

## Display modes

`navigation.sidebar.display` sets how every sidebar group renders:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`** (default) — a non-collapsible header with its pages listed beneath. Pages that aren't in any group always list first, above the group sections, so they can't be mistaken for a group's children.
- **`group`** — a collapsible `<details>` disclosure per group. Groups start collapsed by default; a group containing the current page always starts open, so only the section you're in is expanded. Set `collapsed: false` in [folder meta](/docs/content/meta) to force a group open regardless.
- **`page`** — each group is a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.

:::tip
`page` mode keeps deep sections tidy — reach for it when groups have many children and you'd rather drill into them than scroll past them.
:::

### Per-group overrides

Any generated group can opt out of the global mode — no explicit sidebar required. Set `display` in the folder's [`meta.ts`](/docs/content/meta), or — when the folder has an `index` page — under `sidebar` in that page's frontmatter, and only that group changes:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

A generated group's effective mode resolves highest priority first:

1. `sidebar.display` in the group's own `index` page frontmatter
2. `display` in the folder's `meta.ts`
3. The global `navigation.sidebar.display`
4. The Blume default (`flat`)

A group's `display` applies to that group only — nested subgroups resolve their own value through the same chain. A `page`-mode group with an index page still drills into its sub-panel: the index page lists as the panel's first item, and landing on its URL opens the panel directly.

`sidebar.display` means nothing anywhere else — on a non-index page, on the content root's own `index` page (the root isn't a group; use `navigation.sidebar.display`), or on any page when an [explicit sidebar](#explicit-sidebar) is configured (its items own each group's mode) — so Blume reports a `BLUME_SIDEBAR_DISPLAY_IGNORED` warning instead of silently dropping it. `collapsed` remains specific to `group` mode; it's inert when a group resolves to `flat` or `page`.

A group in an [explicit sidebar](#explicit-sidebar) overrides the global mode with its own `display`, exactly as before.

## Ordering

When the sidebar is generated, order is resolved highest priority first:

1. **Config sidebar**

    An explicit `navigation.sidebar` replaces the generated tree entirely.

2. **Folder meta**

    The `pages` array in `meta.ts` orders a group.

3. **Frontmatter**

    `sidebar.order` on a page.

4. **File system**

    An `index` page first, then numeric prefixes, then alphabetical by label.

Two siblings that land on the same explicit or numeric order fall back to alphabetical order between themselves — Blume reports a `BLUME_DUPLICATE_SIDEBAR_ORDER` warning so the tie doesn't go unnoticed.

## Hidden pages

Hide a page from the sidebar — and from previous/next pagination — while keeping it built and reachable by its URL:

```yaml
sidebar:
  hidden: true
```

## Tabs

Render top-level sections as tabs in the header, useful for splitting a large site into distinct areas — say adapters, an API, and AI guides. A tab is highlighted when the current route falls under its `path`:

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

An enabled [OpenAPI or AsyncAPI reference](/docs/advanced/api-reference) mounts at its route but doesn't add a tab on its own — point a tab at that route to surface it in the header (and, for the native renderer, to scope its operations sidebar), with whatever label you like:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

A tab's `path` is its section prefix, and it doubles as the link target. A section whose `path` isn't a page of its own — a folder with no `index.mdx` — would link to a 404, so the tab falls back to the first page in the section instead. Set `href` when you want it to land somewhere else:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

This matters for routes that aren't part of the content tree, since the fallback can't see them: the generated [changelog](/docs/advanced/changelog) index, or a [custom page](/docs/advanced/custom-pages) you added under `pages/`. Without `href`, a `/changelog` tab lands on the newest entry rather than the index. Tabs that don't set `href` are unaffected.

On an [i18n](/docs/content/i18n) site, a tab's `label` (and a dropdown item's) can be a per-locale map instead of a string — the active locale's entry wins, then the default locale's:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}
```

Tabs also **scope the sidebar**: when the current route falls under a tab's `path`, the sidebar shows only that section's pages — so `/adapters/*` lists the adapters and nothing else. The folder at a tab's `path` becomes the section, so this needs no extra config beyond the tabs themselves; structure your content into a folder per tab and point each tab at it.

On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the pages that _don't_ belong to a tab — each tab's folder is hidden from it, since that section already has its own tab in the header. So a root landing page lists your loose top-level pages while the sectioned content stays behind its tab, mirroring Fumadocs' root folders. If a route has no pages of its own to show this way, the full tree is shown instead, so the sidebar is never left blank.

## Selectors

For switching between whole partitions of a site — a product, a version, or any grouped set of destinations — add a `selector`. Each renders as a dropdown in the header, showing the option whose `path` matches the current route:

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

Each item takes a `label`, a `path`, and optional `icon`, `description`, and `tag`. `kind` (`dropdown`, `product`, `version`, or `language`) is a hint for how the selector is used; all render the same dropdown.

With [versioning](/docs/content/versioning) configured, Blume renders a version selector automatically — declaring your own `kind: "version"` selector here replaces the automatic one, so hand-rolled setups keep working.

## Featured links

Pin links to the top of the sidebar, above every section — a blog, a changelog, a contact or support page that should always be one click away. Unlike the generated tree, featured links are **not scoped by tab**: they show on every route, on every breakpoint.

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

Each link takes a `label`, an `href`, and an optional `icon` (a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG — the same as anywhere else). An `href` may point anywhere: an external URL opens in a new tab, while an internal route (`/contact`) is validated against your pages at build time, warning you if nothing matches.

## Explicit sidebar

For full control, list explicit items in `navigation.sidebar` — a bare array is shorthand for `sidebar.items`, and the object form combines them with a global [`display`](#display-modes). When items are set, Blume uses them verbatim and skips file-system generation:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}
```

Each item is a page route (a string), a group (`label` + `items`), or a link (`label` + `href`). Groups can nest, override the global [`display` mode](#display-modes), and start `collapsed`.

## Header actions

`navigation.actions` puts plain links in the header, left of the icon buttons, and `navigation.cta` is the one filled button:

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

`cta` is singular on purpose — a docs header has room for exactly one thing a reader is being asked to do, and a row of buttons asks for nothing. Secondary links belong in `actions`, or in [`featured`](#featured-links) if they should sit with the sidebar instead.

An `http(s)` or protocol-relative href opens in a new tab; a route stays in the tab, and is validated against your pages at build time like a `featured` link — so a page served by another app on the same host (`/signup` on the product, say) should be written as an absolute URL. `actions` are hidden below the `sm` breakpoint, where the header has room for the logo and the navigation toggle and nothing else. `cta` hides there too, except on a page with no navigation toggle — a landing page on `PageLayout` with no tabs — where it stays, since nothing else can surface it on a phone.

## Repository link

When you set [`github`](/docs/configuration) in your config, Blume shows a GitHub icon in the header — beside the theme toggle — that links to your repository. It's on by default; hide it with `navigation.repo`:

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // hide the header GitHub link (default: true)
}
```

The link only appears when `github` is configured, so projects without a repo are unaffected either way.

`repo` also takes an absolute URL, which points the header mark anywhere on GitHub:

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

That's for a project whose docs repo is private. `github` drives the per-page edit link, the header mark and the [agent manifest](/docs/configuration/ai)'s repository together, so such a project has to leave `github` unset — and a URL is what lets it still show a mark pointing somewhere public. The icon stays the GitHub mark, so a link to another host belongs in [`actions`](#header-actions).

## Breadcrumbs and pagination

These come for free from the sidebar tree — no configuration:

- **Breadcrumbs** show the current page's parent group above the title.
- **Previous and next** links at the foot of each page follow sidebar order, skipping hidden pages.

## On this page

A right-rail outline is generated automatically from each page's `##` and `###` headings, so long pages stay scannable. On narrower screens, where the right rail is hidden, it collapses into an “On this page” dropdown above the content.

## Page actions

Below the table of contents, every page shows a set of quick actions:

- **Edit on GitHub** — links straight to the source file. Appears once you set [`github`](/docs/configuration) in your config.
- **Scroll to top** — smoothly returns to the top of long pages.
- **Give feedback** — opens a prefilled GitHub issue with an optional reaction and note (also requires `github`).

Others hand the page to AI tools — **Copy as Markdown** and **Open in chat** — covered in [AI](/docs/configuration/ai#copy-as-markdown).

With [`export`](/docs/configuration/export) on, an **Export** action also lets readers download the page as a PDF or EPUB.

---

# Content sources
Source: https://useblume.dev/docs/content/sources

By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let you pull pages from somewhere else — a remote repository, a CMS, or any custom backend — and mix several sources into a single site. Sources are read at build time; Blume stays static-first.

## The default

With no configuration, Blume scans your content root (`docs` by default) as one implicit filesystem source. The top-level `content.root`/`include`/`exclude` options still work exactly as before — nothing to change.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: { root: "docs" },
});
```

## Multiple sources

Add a `content.sources` array to compose sources. Each entry is namespaced by an optional `prefix`, so its routes nest under `/<prefix>/…`. When `sources` is present it replaces the implicit default, so include a `filesystem` entry for your local docs.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      // Local docs at the site root
      { type: "filesystem", root: "docs" },

      // Remote MDX from a GitHub repo, mounted under /sdk
      {
        type: "mdx-remote",
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      },
    ],
  },
});
```

If two sources resolve to the same route, Blume reports a `BLUME_DUPLICATE_ROUTE` build error — give each source a distinct `prefix`.

## Obsidian

The built-in `obsidian` source reads an [Obsidian](https://obsidian.md) vault in place. There is no export step and nothing generated into your repo: the vault stays the source of truth, and Blume lowers Obsidian's dialect to Markdown as it loads.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "obsidian",
        prefix: "notes",
        vault: "vault",
        // Vault folder names to skip at any depth, on top of dot-folders
        exclude: ["Templates", "Daily"],
      },
    ],
  },
});
```

`[[Wikilinks]]` become route links, addressed by note name across the whole vault rather than by path, the way Obsidian addresses notes. Custom link text (`[[Note|label]]`), heading anchors (`[[Note#Install]]`), full paths (`[[folder/Note]]` and `[[folder/Note.md]]`), the partial paths Obsidian's default "shortest path when possible" setting writes (`[[guides/Note]]`), and the `[[Note\|label]]` form Obsidian writes inside a table cell all work, and a note that sets `slug` in its frontmatter is linked at the route that slug publishes. When two notes share a name, a note whose full vault path is exactly that name wins — Obsidian resolves a link as a path before a name — then the first in vault order (folders before notes, case-insensitively, like Obsidian's file explorer). Blume warns only when a wikilink actually resolves through such a collision; write a longer path to disambiguate. A block reference (`[[Note#^id]]`) links to its note without an anchor: blocks render with no id to land on. A heading anchor resolves against the target note's real headings, matched the way Obsidian's autocomplete writes them (with `**bold**`, `` `code` ``, and link syntax stripped) and slugged by the same `extractHeadings` pass that fills the page manifest — so a link to `#Install` lands on the heading rather than on an id no page emits. `[[#Install]]` addresses a heading in the note you are writing. A link to a heading that doesn't exist keeps the page link, drops the anchor, and warns.

Frontmatter keeps what Blume's [page schema](/docs/reference/frontmatter) accepts plus any key you declare in [`frontmatter.extend`](/docs/reference/frontmatter#custom-keys) (or, for notes of that `type`, a content type's `frontmatter`); every other Obsidian property — Dataview fields, Templater dates, `publish`, and Obsidian's own `tags`, `aliases`, and `cssclasses` — is dropped when a note is lowered, so a vault written with the Properties UI builds without frontmatter errors. `aliases` is dropped rather than resolved — alias link targets are not supported yet. A relative Markdown image beside a note (`![chart](./chart.png)`) is served from the vault, and when the vault lives inside your git repository, vault pages get git-derived ["Last updated" dates](/docs/configuration#last-modified) like any other page. "Edit this page" links resolve through `github.dir`, so a vault that sits beside the docs app in a monorepo still links to its file; a vault outside the repository gets no link.

Locale directories and version snapshots inside the vault are read the same way the filesystem source reads them: `fr/Note.md` publishes under `/fr/` with [i18n](/docs/content/i18n) configured, `v1.0/Note.md` under `/v1.0/` with [versions](/docs/content/versioning), and wikilinks to those notes point at the route each one publishes.

:::note
A heading that itself contains a link gets its manifest anchor from the heading's Markdown and its rendered `id` from its text content. The two differ for that heading, so a wikilink to it may land on the page rather than on the section.
:::

A link to an `index` note lands on its folder's route rather than a phantom `/index`. **An unresolved wikilink degrades to plain text with a build warning instead of failing the build**, so a vault mid-refactor still publishes. Single-line `%%comments%%` are stripped, a wikilink inside an HTML comment (`<!-- [[Draft]] -->`) is left alone since Obsidian hides it too, and a note with no `title` in its frontmatter is titled by its filename — the same rule Obsidian itself applies. An `index` note is the one exception: it names a route rather than a note, so its title falls through to Blume's usual derivation (first heading, then the humanized segment). Fenced, indented, and inline code passes through verbatim, so a note documenting the syntax survives.

Dot-folders are skipped, including Obsidian's own `.obsidian` config directory and `.trash` — which the dev watcher also ignores, so moving a pane in the app or deleting a note to the trash doesn't rebuild your site. Editing a note does. The directories no content scan reads (`node_modules`, `dist`, `.git`, …) are skipped too, so a vault rooted at the project itself doesn't publish dependency READMEs. Symlinks inside the vault are followed, the way the filesystem source follows them, so a shared folder linked into the vault publishes with it. A vault that sits inside `content.root` must be excluded from the filesystem source (`exclude: ["vault/**"]`); `blume version cut` then leaves it out of the snapshot, since the vault keeps publishing its own notes as current.

Not yet lowered: callouts (`> [!note]`) render as plain blockquotes, embeds (`![[image.png]]`) pass through untouched, multi-line `%%comments%%` are left in place, and there is no backlink graph.

## Remote MDX

The built-in `mdx-remote` source fetches raw `.md`/`.mdx` over HTTP. Enumerate files either from a GitHub repo subtree (`github`) or explicitly against a raw base URL (`url` + `files`):

```ts blume.config.ts
{
  type: "mdx-remote",
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
}
```

A private repo's token is read from the `GITHUB_TOKEN` environment variable — it is never inlined into your config or generated output, and it is only ever sent to GitHub's own hosts (`api.github.com`, `raw.githubusercontent.com`), never to a custom `url` base.

Remote pages are rendered with full MDX-plus-component fidelity: their bodies are materialized into a hidden staging directory and rendered through Astro alongside your local docs, so callouts, tabs, and every other Blume component keep working.

### Caching and offline builds

Each remote source keeps a snapshot under `.blume/cache/<source>/`. If a fetch fails — a network blip or a CMS outage — Blume serves the last-known-good snapshot with a warning rather than failing the build. The cache lives inside `.blume/` and is regenerated, never committed.

In dev, remote content is fetched once and frozen for the session; restart the dev server to refresh it. Local filesystem sources hot-reload as usual. To poll a remote source for changes instead, set `pollInterval` (seconds) on it — the dev server re-fetches on that interval and reloads only when the content actually changes. Leave it unset to avoid hitting the API while you work.

## GitHub Releases

The built-in `github-releases` source turns a repo's releases into a changelog: each release becomes a `type: changelog` entry, so your release notes _are_ your changelog — nothing to write twice. Combined with the generated [changelog timeline](/docs/advanced/changelog), publishing a GitHub release ships a changelog entry.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // include prereleases (default off)
        // drafts: false,       // include drafts (needs a write token)
        // limit: 100,          // cap releases, newest-first
      },
    ],
  },
});
```

Each release maps to the changelog fields automatically: its name (or tag) becomes the title, its published date drives the timeline order, the tag becomes `changelog.version`, and prereleases are tagged `Prerelease` (others `Release`). The notes render as the entry body. Give the source a `prefix` so its release pages nest under a route like `/changelog/v1-2-0`.

A private repo authenticates with the `GITHUB_TOKEN` environment variable — the same token the other GitHub features use, never inlined into your config. Like every remote source it's cached under `.blume/cache/<source>/` and served offline if the API is unreachable. Because a changelog is supplementary, a fetch failure with no cache (say a CI build without a token) degrades to an empty changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in your CI and deploy environments to populate it.

## Sanity

The built-in `sanity` source runs a GROQ query and maps each document's fields to frontmatter and its Portable Text body to Markdown. The `@sanity/client` package is an optional peer dependency — install it only if you use this source.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "sanity",
        prefix: "guides",
        projectId: "abc123",
        dataset: "production",
        query: `*[_type == "guide"]`,
        // Field paths default to title / slug.current / body / _updatedAt
        fields: { slug: "slug.current", body: "content" },
      },
    ],
  },
});
```

A read token for a private dataset comes from the `SANITY_TOKEN` environment variable. Custom Portable Text block types map to Blume components through the adapter's `serializers` option, available when you construct `sanitySource` directly via a [custom source](#custom-sources).

## Notion

The built-in `notion` source turns a Notion database into a collection: each row becomes a page, its properties become frontmatter, and its block tree becomes MDX. Callouts, toggles, columns, and code blocks map to the matching Blume components. `@notionhq/client` (v5 or later) is an optional peer dependency; Blume reads the database through its first data source.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "notion",
        prefix: "handbook",
        database: process.env.NOTION_DB_ID,
        // Property names default to the title-typed prop / Description / Slug / Order
        // Set publishedValue to treat Status as a publish gate (opt-in)
        publishedValue: "Published",
      },
    ],
  },
});
```

The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build. API calls are paced through a small request pool (3 at a time, matching Notion's per-integration rate limit) so databases with hundreds of pages import without tripping `429` responses; set `concurrency` on the source to tune it.

## Preview and sync

Two flags control how remote content is fetched and what's included:

- **`--preview`** on `blume dev` or `blume build` renders drafts and pulls unpublished CMS content — Sanity switches to its `previewDrafts` perspective, and Notion stops filtering by `Status`. Production builds without the flag exclude drafts as usual, so a preview build is a safe way to review unpublished work before it ships.
- **`blume sync`** re-fetches every remote source and regenerates the runtime. Dev is cache-first — a remote source is fetched once and served from `.blume/cache` on restart (fast and offline-tolerant), so `blume sync` is how you pull the latest CMS content without restarting the dev server (a running server hot-reloads). Add `--force` to drop the cache first, or set `pollInterval` on a source to refresh automatically.

```sh
blume dev --preview      # author workflow: see drafts live
blume build --preview    # render a full preview build
blume sync               # refresh remote content now
blume sync --force       # ...ignoring any cached snapshot
```

## Custom sources

Any object implementing the `ContentSource` interface can be passed directly, which is how an adapter with custom serializers — or any backend not built in — plugs in without its SDK touching the core install:

```ts blume.config.ts
import { defineConfig } from "blume";
import { sanitySource } from "blume/sources/sanity.ts";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "custom",
        source: sanitySource({
          name: "guides",
          prefix: "guides",
          projectId: "abc123",
          dataset: "production",
          query: `*[_type == "guide"]`,
          // Map custom Portable Text blocks to Blume components
          serializers: {
            callout: (block) => `<Callout>${block.text}</Callout>`,
          },
        }),
      },
    ],
  },
});
```

A source normalizes its native shape (Portable Text, Notion blocks, remote HTML) to Markdown/MDX text, so the same components and markdown features apply no matter where a page comes from.

A custom source that reads local files should set `sourcePath` on each entry and `contentRoot` on the source itself. `sourcePath` names the file in diagnostics and resolves relative images beside it; `contentRoot` bounds the git `log` that dates pages, so without it the source's pages get no git-derived ["Last updated" date](/docs/configuration#last-modified).

---

# Syntax
Source: https://useblume.dev/docs/content/syntax

Blume renders standard Markdown and MDX with a curated, GitHub-flavored feature set — no imports, no configuration. Write content the way you already do; this page shows everything that's supported, with a live preview and the source for each.

## Headings

Structure a page with headings. Blume renders your frontmatter `title` as the page heading, so start your content at `##` — `##` and `###` become entries in the table of contents. Every `##`–`######` heading is also wrapped in a link to its own anchor, so readers can click a heading to copy, bookmark, or share a permalink straight to that section (hover to reveal the `#`). Turn this off with `markdown: { headingAnchors: false }` in `blume.config.ts`.

```md
## Section

### Subsection

#### Detail
```

### Custom anchors

Anchor ids are generated from the heading text, so a reworded heading gets a new anchor. Append `[#custom-id]` to pin the anchor instead — the marker never renders, and links keep working no matter how the heading reads. Pinned anchors also stay identical across [translated locales](/docs/content/i18n), where auto-generated ids would otherwise differ per language.

```md
## Getting started [#setup]
```

Link to it as `/page#setup`. The syntax matches Fumadocs, so migrated content works verbatim.

The `{#custom-id}` form used by Pandoc, kramdown, and Markdown-based specification toolchains is accepted as an equivalent in `.md` files. In `.mdx`, a bare `{…}` is a JSX expression and the page fails to compile — `blume check` reports the marker as `BLUME_MDX_CURLY_ANCHOR` — so write `[#custom-id]` there, or escape the braces. The escaped form pins the same anchor in both formats, which makes it the right spelling for a partial that `.mdx` pages [include](/docs/content/includes):

```md
## Getting started \{#setup\}
```

Fragment links can also target a raw HTML element with an `id` (`<a id="setup"></a>`); `blume validate` accepts those alongside heading anchors.

### Table of contents markers

Two more trailing markers control how a heading appears in the table of contents. `[!toc]` keeps a heading on the page but out of the TOC; `[toc]` does the reverse — the heading shows only in the TOC, as an invisible anchor target, which is useful for labeling sections built from components rather than prose. Markers chain in any order. One exception, inherited from CommonMark: a trailing bracket whose label has a link-reference definition anywhere on the page (`[toc]: /url`) is a shortcut reference link, not a marker, and stays in the heading text.

```md
## Appears on the page only [!toc]

## Appears in the TOC only [toc]

## Both markers together [toc] [#custom-id]
```

Markers are always parsed — a heading that literally ends in marker-shaped text would be treated as marked. Backslash-escaping doesn't help (Markdown resolves `\[` to `[` before the marker parse runs); to show literal marker text at the end of a heading, wrap it in inline code: `` ## Using `[toc]` ``.

## Emphasis

Inline formatting for stressing words, marking deletions, and showing code or keystrokes mid-sentence.

**Bold**, _italic_, ~~strikethrough~~, and `inline code`.

```md
**Bold**, _italic_, ~~strikethrough~~, and `inline code`.
```

## Superscript and subscript

For footnote markers, ordinals, and scientific or chemical notation inline.

E = mc^2^ and H~2~O.

{/* prettier-ignore */}
```md
E = mc^2^ and H~2~O.
```

## Blockquotes

Set off a quotation, callout aside, or an editorial note from the surrounding text.

> Documentation that's fast, AI-ready, and zero-config — down to the template.

```md
> Documentation that's fast, AI-ready, and zero-config — down to the template.
```

## Lists

Use unordered lists for unordered sets, ordered lists for sequences, and task lists for checklists and roadmaps.

- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide

```md
- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide
```

## Tables

Tabulate structured data — config options, comparison matrices, parameter lists. Use colons in the divider row to align columns.

| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |

```md
| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |
```

For a table without a header row — key–value pairs, for example — leave the header cells empty. Markdown requires the header and divider rows syntactically, but Blume drops the empty header from the rendered table.

```md
|                |          |
| -------------- | -------- |
| Current status | E-3 visa |
```

## Links and images

Link to other pages or external sites. Images accept a relative path to a file next to your content, any path under `public/` (served at the site root), or a remote URL.

Read the [quickstart](/docs/quickstart) to get started.

```md
Read the [quickstart](/docs/quickstart) to get started.

![Alt text](./screenshot.png)
```

**Prefer relative paths for local images** — they're optimized at build time: compressed, converted to WebP, and stamped with intrinsic `width`/`height` so the page doesn't shift while loading. Keep the image next to the page that uses it (or in a shared folder inside your content directory) and reference it relatively:

```md
![Build output](./images/build-output.png)
```

Absolute paths under `public/` (`![Alt text](/screenshot.png)`) are served verbatim with no optimization — use them for files that must keep their exact bytes and URL, like a logo referenced from outside your docs. Remote images are also passed through untouched unless their host is authorized in the [`image` config](/docs/configuration#images).

Content images are click-to-zoom by default — readers can click any image to open it in a lightbox. Turn this off with `markdown: { imageZoom: false }` in `blume.config.ts`, or opt a single image out with `data-no-zoom`.

## Horizontal rule

Separate major shifts in topic within a long page.

---

```md
---
```

## Code blocks

Fenced code blocks are syntax-highlighted with a header showing the language — with a brand icon for recognized languages — and a copy button. Add a **title** after the language — typically a filename — and it replaces the language label in the header.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```

````md
```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```
````

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.

Highlighting uses the `github-light`/`github-dark` themes by default. Swap in any [bundled Shiki theme](https://shiki.style/themes) per color mode with `markdown.codeBlocks.theme` — it colors every code surface at once (fences, inline snippets, `<CodeBlock>`, and `<Diff>`):

```ts blume.config.ts
export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: "vesper" },
    },
  },
});
```

You can also provide a custom [Shiki theme definition](https://shiki.style/guide/load-theme) directly. Import a VS Code-compatible theme JSON file (using an import attribute when your runtime requires one) and assign it to either color mode; bundled names and custom definitions can be mixed:

```ts blume.config.ts
import darkTheme from "./themes/acme-dark.json" with { type: "json" };

export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: darkTheme },
    },
  },
});
```

### Line numbers

Append `lineNumbers` to render a line-number gutter — on its own or alongside a title:

```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```

````md
```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```
````

### Highlighting

Annotate code with GitHub-style comments to draw attention to lines, words, and changes. The comments are stripped from the rendered output, so the code stays copy-paste clean. All four are on by default — no configuration.

Mark a line with `// [!code highlight]` to give it a highlighted background:

```ts
const config = defineConfig({
  title: "My docs", // [!code highlight]
});
```

Show changes with `// [!code ++]` for additions and `// [!code --]` for removals, rendered as a green/red diff:

```ts
export default defineConfig({
  title: "My docs", // [!code --]
  title: "Blume docs", // [!code ++]
});
```

Highlight every occurrence of a term on a line with `// [!code word:serve]`:

```ts
import { serve } from "blume"; // [!code word:serve]

serve({ port: 3000 });
```

Dim everything except the lines you mark with `// [!code focus]` (the rest sharpens on hover):

```ts
export default defineConfig({
  title: "My docs", // [!code focus]
  description: "Built with Blume",
});
```

Or highlight lines by **number** instead of comments — useful when you can't edit the code. Put a brace range after the language; single lines, comma lists, and `start-end` spans all work:

```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```

````md
```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```
````

### Display types

Mark a TypeScript block `twoslash` to display real types straight from the compiler — powered by [Twoslash](https://shiki.style/packages/twoslash). Hover any token to see its inferred type, and add an inline `^?` query to pin a type below the line.

```ts twoslash
const config = {
  title: "My docs",
  version: 1,
};

config.title;
//     ^?
```

````md
```ts twoslash
const config = { title: "My docs", version: 1 };

config.title;
//     ^?
```
````

### TypeScript and JavaScript tabs

Mark a `ts` or `tsx` block `ts2js` to render it as a tab pair: your TypeScript alongside an auto-generated JavaScript variant, so you maintain one snippet and readers pick their dialect. The conversion strips type syntax and type-only imports while keeping your formatting, comments, and JSX exactly as written — and tabs sync, so choosing JavaScript once switches every pair on the page. Like diagrams and math, this is an MDX-only feature — in a `.md` file the block renders as a plain TypeScript fence.

```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```

````md
```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```
````

Other fence meta composes: a `title="..."` shows on both tabs, while `{1,4-5}` line ranges apply only to the TypeScript tab (line numbers shift once types are gone). The one exception is `twoslash` — hover types can't carry over to generated code, so a fence marked both stays a plain Twoslash block.

:::note
Hide the language icons or wrap long lines instead of scrolling with `markdown: { code: { icons: false, wrap: true } }` in `blume.config.ts`.
:::

## Package install

A `package-install` block turns a single install command into a tabbed snippet for npm, pnpm, yarn, and bun — so readers copy the one that matches their setup. Like diagrams and math, this is an MDX-only feature — in a `.md` file the block renders as a plain code fence.

```package-install
npm i blume
```

````md
```package-install
npm i blume
```
````

## Diagrams

A `mermaid` block renders a [Mermaid](https://mermaid.js.org) diagram straight from text. The fence contents are passed to Mermaid verbatim, so every diagram type Mermaid supports works here. Diagrams follow the active color theme and re-render when it changes. Author one by fencing the source with `mermaid`:

````md
```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```
````

Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.

### Flowchart

```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```

### Sequence diagram

```mermaid
sequenceDiagram
  participant R as Reader
  participant B as Blume
  R->>B: Request /docs
  B-->>R: Prerendered HTML
```

### Class diagram

```mermaid
classDiagram
  class Page {
    +string title
    +string route
    +render()
  }
  Page <|-- Doc
  Page <|-- Changelog
```

### State diagram

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: build
  Published --> [*]
```

### Entity relationship

```mermaid
erDiagram
  PAGE ||--o{ HEADING : contains
  PAGE {
    string title
    string route
  }
```

### User journey

```mermaid
journey
  title Publishing a page
  section Write
    Draft MDX: 5: Author
  section Ship
    blume build: 4: Author
    Deploy: 3: Author
```

### Gantt

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Docs
    Draft   :a1, 2026-01-01, 7d
    Review  :after a1, 3d
```

### Git graph

```mermaid
gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit
```

### Pie chart

```mermaid
pie title Content types
  "Docs" : 70
  "Blog" : 20
  "Changelog" : 10
```

### Mindmap

```mermaid
mindmap
  root((Blume))
    Content
      MDX
      Markdown
    Build
      Static HTML
      llms.txt
```

### Timeline

```mermaid
timeline
  title Blume milestones
  2025 : Prototype
  2026 : 1.0 release
```

## Callouts

Callouts pull a reader's attention to context, advice, or risk. Write them as `:::type` directives; add a title in brackets, like `:::warning[Heads up]`. Directives are an MDX-only feature — in a `.md` file a `:::note` line stays literal text.

### Note

Neutral, supporting context the reader should keep in mind.

:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::

```md
:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::
```

### Tip

A helpful shortcut or best practice that isn't required but makes life easier.

:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::

```md
:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::
```

### Success

Confirm a positive outcome or that a step completed as expected.

:::success
Your docs built successfully and are ready to deploy.
:::

```md
:::success
Your docs built successfully and are ready to deploy.
:::
```

### Warning

Flag something that needs care to avoid a mistake or surprising behavior.

:::warning[Heads up]
Switching to `output: "server"` requires an adapter before you can deploy.
:::

```md
:::warning[Heads up]
Switching to `output: "server"` requires an adapter before you can deploy.
:::
```

### Danger

Call out a destructive or breaking action that can't easily be undone.

:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::

```md
:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::
```

### Info

An informational aside; an alias-friendly default that reads as neutral.

:::info
The core theme ships no client framework JS.
:::

```md
:::info
The core theme ships no client framework JS.
:::
```

The names `caution`, `error`, `important`, and `warn` are accepted as aliases for `warning`, `danger`, `note`, and `warning` respectively.

## Math

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
$$
a^2 + b^2 = c^2
$$
```

:::note
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. The class names inside the rendered markup (`.katex-html`, `.katex-base`, …) are KaTeX's own internals, not a styling contract Blume maintains — they can change when KaTeX upgrades, so target the `.katex-display` wrapper for custom styles.
:::

## Smart punctuation

Blume converts straight quotes and dashes to typographic equivalents as you write, so prose reads like it was typeset — no special characters required.

"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.

```md
"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
```

---

# Versioning
Source: https://useblume.dev/docs/content/versioning

Blume versions your docs the way releases actually work: the latest documentation lives at your content root with clean, unprefixed URLs, and each past version is a frozen snapshot in its own folder. Cut a snapshot when you ship, and Blume wires up the switcher, the "old version" notice, search scoping, SEO, and the agent surface for you. It's opt-in: without a `versions` block, nothing changes.

## Enable it

Add a `versions` block naming the current docs and any archived snapshots:

```ts blume.config.ts lineNumbers
versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}
```

`current` labels the unprefixed tree in the switcher (with an optional `badge`). Each archived entry's `id` is both the snapshot's directory name and its URL segment — ids must start with a letter (`v1.0`, not `1.0`) so they can never collide with [numeric ordering prefixes](/docs/content/navigation#ordering). List archived versions newest first; that order is the switcher order.

## Cut a version

When you release, freeze the current docs with one command:

```bash
blume version v1.0
```

This copies your content tree into `docs/v1.0/` (existing snapshots excluded), rewrites root-absolute links inside the copy so they stay within the snapshot (`/guides/x` becomes `/v1.0/guides/x`, fenced and inline code untouched), and registers the id in `blume.config.ts` — or prints the entry to paste when your config is shaped in a way it won't touch. Links to pages that aren't part of the copied tree — generated API references, remote sources like a changelog — keep pointing at the live pages, since the snapshot has no copy of them. Run `blume version` with no id to list the configured versions.

Review and commit the new directory like any other content. Restart `blume dev` to pick it up.

```txt
docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart
```

**Archived means frozen.** Future edits belong in the live tree; a snapshot is the docs as they were. Blume leans on that: snapshots keep their own folder meta and translations, [`blume translate`](/docs/reference/translate) never retranslates them, and a configured explicit sidebar applies only to the current docs — a snapshot's sidebar always comes from its own files.

## The switcher and the notice

With versions configured, the header grows a version dropdown automatically. Switching lands on the same page in the target version when it exists, and on that version's root when it doesn't (set `switcher.redirect: "root"` to always land on the root). If you declare your own `kind: "version"` selector in [`navigation.selectors`](/docs/content/navigation#selectors), it replaces the automatic one.

Every archived page also shows a non-dismissible notice with a "Go to latest" link pointing at the page's live equivalent. Customize or disable it per version:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0", banner: "These docs cover the 1.x SDK." },
    { id: "v0.9", banner: false },
  ],
}
```

## SEO

Old docs are search engines' favorite trap: the stale page outranks the live one, or both compete. Blume defaults to the answer SEO guides recommend and no other docs framework automates — archived pages stay indexable but declare the **latest equivalent as their canonical**, so the live page is authoritative while version-only content (a page that no longer exists in the latest docs) remains findable with a self-canonical.

Per version you can pick a different treatment:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0" }, // canonical → latest (default)
    { id: "v0.9", canonical: "self" }, // every page authoritative
    { id: "v0.8", noindex: true }, // deindexed entirely
  ],
}
```

The sitemap follows suit: archived pages whose canonical points at a live equivalent are left out, `noindex` versions are left out wholesale, and version-only pages stay listed. A page's own `seo.canonical` frontmatter always wins.

## Search

The search dialog scopes results to the version being viewed, with an "All versions" toggle (remembered per reader) beside the language one. Cross-version hits name their version on the result row. Orama (the default), FlexSearch, Algolia, and Typesense all honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.

## Agents

The agent surface is version-aware — something no other docs framework does:

- The MCP `search_docs` and `list_pages` tools default to the current docs and accept `version`: an archived id (`"v1.0"`) or `"all"`. `get_navigation` returns an archived snapshot's tree on request.
- `llms.txt` sections archived versions after the current docs, labeled `1.0 (archived)`, so an agent reading the index knows which docs are frozen.
- `llms-full.txt` stays current-only — the flat dump never interleaves frozen copies of the same page.
- Raw Markdown mirrors (`.md` URLs) exist for every version's pages, as for any route.

## With i18n

Versioning composes with [internationalization](/docs/content/i18n). On disk the version folder is outermost — a snapshot naturally contains its locale folders — while in URLs the locale stays outermost, matching the rest of the site:

```txt
docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
```

Locale fallback works within each version: an untranslated snapshot page renders the fallback locale's content at the localized URL, and `hreflang` alternates group per version. A version id may not collide with a configured locale code — Blume rejects that config outright.

## What stays unversioned

Versioning covers the docs content tree. The blog, changelog, API references generated from OpenAPI specs, and custom pages are always current. Two more behaviors worth knowing: header tabs are defined against the current docs, so inside an archived tree the sidebar renders unscoped by tabs; and large sites should note each snapshot is a full copy — content, search index entries, and navigation data all grow per version.

---

# Deployment
Source: https://useblume.dev/docs/deployment

## Deploy anywhere (static)

`blume build` compiles your docs to plain HTML, CSS, and a local search index in `dist/`. There's no server to run — point any static host at the folder.

| Setting          | Value          |
| ---------------- | -------------- |
| Build command    | `blume build`  |
| Output directory | `dist`         |
| Node version     | 22.12 or newer |

These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, or any bucket or CDN. Make sure `blume` is a dependency so the host can run the build.

A static build includes:

- every docs and custom page as static HTML
- a local search index (Orama by default, Pagefind opt-in)
- a [`sitemap.xml`](/docs/configuration/seo#sitemap) and [`robots.txt`](/docs/configuration/seo#robots) when `deployment.site` is set
- `llms.txt` and `llms-full.txt` for AI tools
- redirect pages
- prerendered [Open Graph images](/docs/configuration/seo#open-graph-images) when `seo.og.enabled` is on

### Set your site URL

Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume detects it from the platform's environment at build time — no config required.

Set `deployment.site` to override the detected value, or to provide one on hosts that don't expose it (GitHub Pages, S3, a custom CDN):

```ts blume.config.ts lineNumbers
deployment: {
  site: "https://docs.example.com",
}
```

When detecting automatically, Blume prefers your stable production domain over per-deploy preview URLs, so the canonical origin stays put across deploys.

During `blume dev`, the site URL falls back to your local dev server (e.g. `http://localhost:4321`) when none is set, so site-gated features — Open Graph images, canonicals, the sitemap — work out of the box. Builds never use this fallback, so production output is never pointed at localhost.

## Preview locally

Before you ship, preview the production build exactly as a static host would serve it:

```bash
blume build
blume preview
```

## Subpath deploys

Serving docs under a path like `example.com/docs`? Set `deployment.base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.

```ts blume.config.ts lineNumbers
deployment: {
  base: "/docs",
}
```

## Mount the docs under a path

`basePath` mounts every generated route under a segment (`/docs/getting-started`) while leaving the sidebar untouched — the top level is your sections, not a wrapper group. Use it when the docs live at `/docs/*` but the site root stays yours (like Docusaurus `routeBasePath` or Fumadocs `baseUrl`).

```ts blume.config.ts lineNumbers
basePath: "/docs",
```

Write links as if mounted at root (`/getting-started`); Blume rewrites them, along with redirects, the sitemap, canonical URLs, Open Graph images, `llms.txt`, and the search index. Public assets (images, files under `public/`) stay at the site root.

This is a distinct concept from the two paths above:

- A per-source [`prefix`](/docs/content/sources#multiple-sources) namespaces **one** source and **does** add a sidebar group.
- `deployment.base` is the host subdirectory the **whole** app is served from. The two compose — with both set, a page lands at `{deployment.base}/{basePath}/page`.

## Server rendering

Static output covers most docs. Switch to server output when you need request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

The `vercel` and `node` adapters ship with Blume — choosing one just works. The `netlify` and `cloudflare` adapters must be installed in your project (e.g. `bun add -d @astrojs/netlify`); the CLI warns you if the package is missing:

| Adapter      | Package               | Use for                              |
| ------------ | --------------------- | ------------------------------------ |
| `vercel`     | `@astrojs/vercel`     | Vercel — the most polished path      |
| `netlify`    | `@astrojs/netlify`    | Netlify Functions                    |
| `node`       | `@astrojs/node`       | Self-hosted Node servers, containers |
| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers and Pages         |

On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy (on Netlify and Cloudflare, install the adapter package too). Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.

A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.

On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/configuration/ai#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path.

:::note
Server features have their own configuration — for example, Ask AI needs a model API key. See the [AI guide](/docs/configuration/ai) for setup.
:::

## Redirects

Map old URLs to new ones in `blume.config.ts`:

```ts blume.config.ts
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.
:::

:::note
Write both `from` and `to` as if mounted at root — under [`deployment.base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A base you've already written into `to` by hand is preserved rather than doubled.
:::

## Content types

A static build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify and Cloudflare (Pages/Workers static assets) read `_headers`; hosts that don't (Vercel, S3) ignore the file harmlessly. A `_headers` you ship in `public/` is left untouched.

## 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:

| Feature | Variable |
| --- | --- |
| Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
| Ask AI (other providers) | the provider's default key env var (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or your configured `apiKeyEnv` |
| Mixedbread search | `MIXEDBREAD_API_KEY` |

Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.

## Build summary

Every build prints a summary — output mode, adapter, resolved site URL, search provider, redirect count, sitemap and `llms.txt` status, and any enabled server features — so you can confirm what shipped (including anything auto-detected) before you deploy.

---

# FAQ
Source: https://useblume.dev/docs/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 type — `:::note`, `:::tip`, `:::info`, `:::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 the same fix in its own repo, and you can apply it in any project.

1. Save the patch as `patches/oxfmt@0.66.0.patch`:

   ```diff patches/oxfmt@0.66.0.patch
   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
   --- a/dist/markdown-BgZGxhM2.js
   +++ b/dist/markdown-BgZGxhM2.js
   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
    		case "sentence": return Oh(e, r);
    		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
    		case "whitespace": {
   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   +			let { next: a, 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(":::");
   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
   +			// linkReference between two sentence nodes at the paragraph level: the
   +			// fence word ends the sentence before the reference, and the body's
   +			// leading newline opens the sentence after it. So when this whitespace
   +			// starts its sentence, climb to the paragraph and check whether the two
   +			// preceding siblings are a (link) reference and a sentence ending in a
   +			// `:::` fence word.
   +			let oxfmtPrevIsTitledFence = !1;
   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
   +				if (oxfmtSentIdx >= 2) {
   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
   +				}
   +			}
   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
   +			// words, so the whole directive is one sentence. For a newline
   +			// whitespace, walk back to the start of its visual line within the
   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
   +				let oxfmtLineFirst = null;
   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
   +					let oxfmtSib = e.parent.children[oxfmtJ];
   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
   +					oxfmtLineFirst = oxfmtSib;
   +				}
   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
   +			}
   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
    			return ou(e, n.value, u, !1, t);
    		}
    		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.66.0": "patches/oxfmt@0.66.0.patch"
     }
   }
   ```

3. Reinstall so the patch is applied:

   ```package-install
   bun install
   ```

:::warning[Version-pinned]
The patch targets a specific oxfmt build — its diff references a file whose name is hashed per release (`dist/markdown-*.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.
:::

---

# Quickstart
Source: https://useblume.dev/docs/quickstart

Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.12 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.

## Install and run

1. **Install Blume**

    Add the package to a new or existing project.

    ```package-install
    npm i blume
    ```

2. **Scaffold a project**

    `blume init` asks a few questions — where to create the project, what your
    docs site is called, which template, and where your content lives — then
    scaffolds the minimum surface: a content folder and a config file. Pass
    `--yes` to skip the prompts and take the defaults.

    ```bash
    blume init
    ```

    ```txt
    docs/
      index.mdx
    blume.config.ts
    ```

3. **Start the dev server**

    Blume generates the runtime and serves your docs with hot reload.

    ```bash
    blume dev
    ```

4. **Build for production**

    Static HTML is written to `dist/`, with a local search index built over it.

    ```bash
    blume build
    ```

:::tip
Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.
:::

## Write your first page

Every page is Markdown or MDX with a little frontmatter — the `title` and `description` render as the page heading and intro automatically. Drop this into `docs/index.mdx`:

```mdx docs/index.mdx lineNumbers
---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::
```

Save it, and the dev server reloads instantly. Navigation, search, and page metadata are inferred from your files as you add them — keep writing, and the site keeps up.

## Next steps

**[Configuration](/docs/configuration)**

Tune the title, theme, search, and deployment.

**[Components](/docs/content/components)**

Explore the built-in component library.

**[AI](/docs/configuration/ai)**

Ship `llms.txt` and an Ask AI assistant.

**[Deployment](/docs/deployment)**

Go live on any static host.

---

# CLI
Source: https://useblume.dev/docs/reference/cli

```bash
blume <command> [options]
```

## Commands

| Command | Description |
| --- | --- |
| `blume init [dir]` | Scaffold a project (interactive by default). |
| `blume dev` | Start the dev server with hot reload. |
| `blume build` | Build the static (or server) site. |
| `blume preview` | Preview the last build. |
| `blume add <item>` | Install a source component from the registry. |
| `blume sync` | Re-fetch remote content sources and regenerate. |
| `blume eject` | Promote the runtime into a standalone Astro app. |
| `blume check` | Type-check the site with `astro check`. |
| `blume doctor` | Diagnose config and content problems. |
| `blume validate` | Validate links across your content. |
| `blume audit` | Audit the built site for SEO and health issues. |
| `blume eval` | Test the docs: an agent answers your questions using only the documentation. |
| `blume translate` | Translate docs into the configured locales with a local agent CLI. |
| `blume version [id]` | Freeze the current docs as an [archived version](/docs/content/versioning) (no id lists configured versions). |

## Common flags

- `blume init` — in a terminal, walks you through a few questions (where to create the project, site name, template, content sources); each flag below pre-answers its question.
- `blume init --yes` — skip the prompts and scaffold with defaults (also the behavior in CI or when stdin isn't a terminal).
- `blume init --content-dir <dir>` — set the content folder (default `docs`).
- `blume init --template docs|api|sdk|changelog` — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
- `blume init --package-manager npm|pnpm|yarn|bun` — tailor the printed next-steps to your package manager.
- `blume init --eject` — scaffold, then eject to a standalone Astro project (falls back to guiding you through `blume eject` when dependencies aren't installed yet).
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — scan a different content folder without editing `blume.config.ts`.
- `blume dev --debug` — verbose Astro/Vite logging for troubleshooting.
- `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
- `blume build --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. `blume dev --strict` opts dev into the same fail-fast behavior.
- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
- `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
- `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
- `blume build --isolated` — build into a throwaway `.blume-verify/` runtime (and its own `dist/`) instead of `.blume/`, so a running `blume dev` server and your real `dist/` are left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
- `blume preview --host --port <n>` — bind the preview server.
- `blume sync --force` — re-fetch remote sources, dropping the cached snapshot first.
- `blume add <item> --force` — overwrite files that already exist.
- `blume check --preview` — include drafts and unpublished CMS content when checking.
- `blume check --strict` — fail on content diagnostics as well as type errors.
- `blume check --isolated` — type-check in a throwaway `.blume-verify/` runtime so a running `blume dev` server is left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
- `blume eject --yes` — skip the confirmation prompt.
- `blume validate --external` — also check external links over the network.
- `blume validate --strict` — exit non-zero on warnings too.
- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI and editor integrations.
- `blume audit --fail-on error|warning|info` — the CI gate; defaults to `error`. `--strict` is an alias for `--fail-on warning`.
- `blume audit --url <origin>` — also probe a live deployment for status codes, response headers, and redirect chains.
- `blume audit --external` — probe outbound links over the network.
- `blume audit --only <check|category>` / `--skip <check|category>` — narrow the report while you work through it (comma-separated).
- `blume audit --list-checks` — print every check the audit can report.
- `blume audit --verbose` — list every affected page with each finding's full detail, such as which link target is broken.
- `blume audit --json` — emit the report as JSON on stdout.
- `blume audit --claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
- `blume eval` — run the questions in `evals.yaml` through an agent that reads only your docs; see [Evals](/docs/reference/eval).
- `blume eval init` — have the agent draft a starter `evals.yaml` from your docs.
- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — see [Evals](/docs/reference/eval) for each flag.
- `blume translate --claude` / `--codex` — translate missing and outdated pages into your configured locales; see [Translate](/docs/reference/translate).
- `blume translate --check` — report translation drift and exit non-zero (the CI gate), without running an agent.
- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — see [Translate](/docs/reference/translate) for each flag.

## Verifying while the dev server runs

`blume dev` serves a live Astro server rooted at the generated `.blume/` runtime and regenerates it on every change. `blume build` and `blume check` regenerate the _same_ `.blume/`, so running either while the dev server is live would corrupt it — both refuse with an error and exit non-zero:

```
A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

The `--isolated` flag is the escape hatch. It relocates the entire generated runtime (and, for `build`, its output `dist/`) to a sibling `.blume-verify/` directory, so the verification never writes anything the dev server — or your real `dist/` — depends on:

```bash
# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist
```

`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. `--analyze` and the `--budget-js`/`--budget-css` gates still run, measured against the isolated output. Blume adds `.blume-verify/` to your `.gitignore` automatically.

This is especially useful when a coding agent needs to verify changes while you keep the dev server open. To make plain `blume build`/`blume check` isolate without the flag — for example in an agent's shell — set `BLUME_RUNTIME_DIR` to the runtime directory to use:

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## Type-checking

`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) over your project. It regenerates the `.blume` runtime, syncs Astro's content types, then reports any TypeScript errors — in your `blume.config.ts`, in custom `.astro` pages, and in the components they import. It exits non-zero when there are errors, so it works as a `typecheck` step in CI:

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

Add a `tsconfig.json` extending Astro's config to your project root so authored pages resolve `blume/*` imports and virtual modules like `blume:data`:

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}
```

Without a project `tsconfig.json`, only the generated runtime is checked.

## Validating links

`blume validate` checks every link discovered in your content:

- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors.
- **Anchor links** (`#section`, `/guides/intro#setup`) must match an anchor on the target page — a heading's id (generated or [pinned](/docs/content/syntax#custom-anchors)) or a raw HTML element's `id` attribute — with misses reported as warnings. Ids inside code blocks, inline code, HTML comments, and `<Prompt>` blocks don't count.

- **Asset links** are checked where the file lives: an absolute path (`/logo.png`) against the `public/` directory, a relative image embed (`![](./diagram.png)`) against the page's own folder. A plain link to a relative path still resolves as a site route — only image embeds go through the image pipeline.
- **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.

## Auditing the built site

`blume validate` reads your _content_; `blume audit` reads the _built site_. It crawls the HTML in `dist/` after a build and reports SEO and site-health issues — titles, meta descriptions, canonicals, Open Graph and X cards, headings, hreflang, images, the sitemap, `robots.txt`, and structured data.

Because Blume built the site, every finding names the source file **and the front matter line** that fixes it, not just the URL a crawler would see:

```
⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.
```

Run it after a build:

```bash
blume build
blume audit
```

Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use `--verbose` to expand every affected page with its full detail, and `--only`/`--skip` to work through one category at a time. `blume audit --list-checks` prints the full catalog.

### Failing CI

The exit code is the contract. By default `blume audit` fails only on errors — things that are definitely broken, like a link to a page that was never built, a redirect loop, or an invalid sitemap. Advisory findings (a short description, a duplicate title) are warnings and do not fail the build:

```bash
blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings
```

### Checking a live deployment

Some things only the real server can tell you: whether a page that exists in `dist/` actually 404s behind a bad rewrite, whether responses are compressed, and whether an `X-Robots-Tag` header is quietly deindexing a page whose HTML looks perfectly fine. Point the audit at a deployment to add those checks:

```bash
blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links
```

Outbound links are graded rather than flatly failed: a 404 is a broken link you can fix, while a 403 or 5xx is usually rate limiting or someone else's outage and is reported as a warning.

### Fixing the findings with an agent

If you use [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli), the audit can hand its findings straight to it:

```bash
blume audit --claude   # or --codex
```

This writes the complete JSON report — every affected page, not the terminal's three-page preview — to a file and opens the agent interactively with a prompt that walks it through the findings: edit the source file each finding names, apply its suggested fix, then run `blume build` and `blume audit` again until the report is clean. The session is interactive by design: you review the edits through the agent's own permission flow, and the agent is told never to fix a finding by deleting content.

`--only` and `--skip` narrow the handoff the same way they narrow the report, so you can send one category at a time.

### What it does and doesn't check

The check set is deliberately narrower than a general-purpose SEO crawler's. Much of what such a crawler reports cannot happen to a Blume site — it never emits `rel=nofollow`, and Vite's content-hashed bundles are never missing or redirecting — and reporting those as permanent zeroes would just teach you to ignore the report.

Two limits worth stating plainly:

- **Structured data** is validated for well-formedness (valid JSON, a `@context`, a `@type` on every node). Blume does not validate against the full schema.org vocabulary or Google's rich-results rules.
- **Core Web Vitals** are not checked. They need a real browser, and a flag that quietly measured nothing would be worse than not having one — so `blume audit` reports the layout-shift causes it _can_ see offline (images with no `width`/`height`, oversized assets) and leaves the rest alone for now.

Anything the audit did not run is reported as skipped rather than silently passing:

```
⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)
```

---

# Evals
Source: https://useblume.dev/docs/reference/eval

`blume audit` tells you whether crawlers can find your docs. `blume eval` tells you whether anyone can actually _use_ them: an AI agent reads your documentation the way a stranger would and tries to answer real user questions from it. When the docs don't state the answer, the run fails and names the page that should.

```bash
blume eval
```

```
blume eval  3 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: the adapter is auto-detected
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
```

## How it works

Each question runs through two agent sessions, using an agent CLI you already have installed — [Claude Code](https://claude.com/claude-code) by default, or [Codex](https://developers.openai.com/codex/cli) with `--agent codex`. Blume holds no API keys and calls no model itself.

1. **The reader** answers the question using _only_ your documentation. It runs in an empty directory with its file, shell, and web tools disabled, connected to a private [MCP server](/docs/configuration/ai) that serves your docs — the same `search_docs`/`get_page` tools a real agent uses against your deployed site. It cannot read your repo, so it experiences the docs exactly like a fresh user: what isn't written doesn't exist.
2. **The judge** grades the answer against the facts you listed, with no tools at all. Paraphrase passes; a missing or contradicted fact fails — and so does "the documentation doesn't say."

The MCP snapshot is built from your content sources directly, so there is no need to run `blume build` first, and nothing is deployed or uploaded anywhere.

An answer the docs _can't_ support fails even when the agent's prior knowledge happens to be right — that's the point. Your docs are the only source that ships.

## Writing evals

Questions live in `evals.yaml` at the project root. To have an agent draft a starter file from your existing docs:

```bash
blume eval init
```

Or write it by hand:

```yaml
questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - the output directory is dist
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - pagefind is the default
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped
```

- `expected` lists the facts a correct answer must state, in substance — the judge accepts paraphrase and rejects contradiction.
- `routes` names the page(s) that should answer the question. A failure is then anchored to that page's source file in the report; a hint that no longer matches a page is warned about rather than silently dropped.
- `severity: warning` keeps a question in the report without failing CI; `skip: true` sits a question out entirely.

Write questions your users actually ask — the ones from support threads, GitHub issues, and onboarding calls. The best evals encode a promise your docs make ("zero-config deploys") as a question that breaks when a PR breaks the promise.

## Failing CI

The exit code is the contract: any failed question exits non-zero. `--threshold` relaxes the gate to a passing fraction when you're digging out of a backlog:

```bash
blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout
```

The JSON report carries the same `diagnostics` + `summary` shape as `blume validate --json` and `blume audit --json`, with the per-question results (answer, score, missing facts, cost) alongside.

Because each question is two model sessions, an eval run costs real money and minutes — the per-question spend is printed as it runs. A sensible CI setup runs `blume eval` on docs changes rather than every push.

## Fixing the findings

Each failure names the missing facts and the page that should state them. To hand the whole report to the agent instead:

```bash
blume eval --fix
```

This writes the full JSON report to a file and opens the agent interactively with a prompt that walks it through each failed question: read the named page, add the missing facts in the page's voice, and rerun `blume eval` until everything passes. The session is interactive by design — you review the edits through the agent's own permission flow — and the agent is told never to delete questions or weaken expected facts to get to green.

## Flags

- `--agent claude|codex` — which agent CLI runs the reader and judge. Defaults to `claude`.
- `--file <path>` — the evals file. Defaults to `evals.yaml`.
- `--threshold <0..1>` — minimum passing fraction before the run exits non-zero. Defaults to `1`.
- `--timeout <seconds>` — reader time limit per question. Defaults to `180`.
- `--json` — emit the report as JSON on stdout.
- `--fix` — after a failing run, hand the report to the agent to fix the docs interactively.
- `--verbose` — include the reader's full answer under each failure.

---

# Frontmatter
Source: https://useblume.dev/docs/reference/frontmatter

Every page accepts the following frontmatter. All fields are optional.

| Prop | Type | Default | Description |
| - | - | - | - |
| `title?` | `string` | - | Page title. |
| `description?` | `string` | - | Page summary. |
| `type?` | `string` | `doc` | Content type. blog/changelog drive feeds. |
| `date?` | `string` | - | Publish date for blog/changelog feeds (ISO or YAML date). |
| `authors?` | `string \| string[] \| object[]` | - | Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Preserved as-is. |
| `slug?` | `string` | - | Override the generated slug. |
| `draft?` | `boolean` | `false` | Exclude from production builds. |
| `lastModified?` | `string` | - | Pin the page's "last updated" date (ISO or YAML date); overrides the git-derived date. |

## Sidebar

```yaml lineNumbers
sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page
```

`display` sets the render mode of the page's folder group ([per-group overrides](/docs/content/navigation#per-group-overrides)) and is only meaningful on a folder's `index` page under the generated sidebar — anywhere else (a non-index page, the content root's own `index` page, or any page under an explicit `navigation.sidebar`) it has no group to configure, and Blume warns with `BLUME_SIDEBAR_DISPLAY_IGNORED`.

## SEO

```yaml lineNumbers
seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
```

## Search

```yaml lineNumbers
search:
  exclude: false
  tags: [api]
```

## Changelog

Changelog entries (`type: changelog`) accept an optional `changelog` object for richer feed and display metadata:

```yaml lineNumbers
type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features
```

`date` may live here or at the top level — both feed the [changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the generated timeline page and feed.

## Custom keys

Any key outside this reference fails the build, so typos are caught early. Projects that carry their own metadata can opt extra keys in via [`frontmatter.extend`](/docs/configuration#frontmatter) in `blume.config.ts`, each validated by a schema the project supplies:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

```yaml page.mdx
---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---
```

Schemas are accepted through the [Standard Schema](https://standardschema.dev) interface, so Zod (whichever version your project installs), Valibot, and ArkType all work. Every declared key is validated on every page — absent ones included — so a required schema enforces the key site-wide; mark it `.optional()` to validate only where present. All other keys stay strictly validated, and built-in fields can't be redeclared.

### Per-type keys

To require keys only on one content type — an RFC's `status`, an incident report's `severity` — declare them under [`content.types`](/docs/configuration#content) instead, keyed by the frontmatter `type` they apply to:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

```yaml rfcs/openapi-request-schemas.mdx
---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---
```

Per-type keys follow the same validation rules as `extend`, scoped to pages whose resolved `type` matches — including pages that set no `type`, when the declaration is for [`content.defaultType`](/docs/configuration#content). A key belongs to one declaration, site-wide or per-type, not both. And a key declared only for another type stays unknown elsewhere, so a stray `status` on a plain doc page still fails the build.

A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/reference/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.

Schemas are exported from `blume/schema` for editor and migration tooling.

---

# Translate
Source: https://useblume.dev/docs/reference/translate

Once [i18n](/docs/content/i18n) is on, every edit to a source page quietly outdates its translations. `blume translate` closes that loop: it computes exactly which pages are missing or stale in each locale, translates them headlessly with a local agent CLI, and records what it did in a committed ledger so the next run — and CI — knows what's current.

```bash
blume translate --claude
```

```
blume translate  3 item(s) · 2 locale(s) · Claude Code

  ✔ docs/guides/install.mdx → fr 24.2s $0.11
  ✔ docs/guides/install.mdx → de 22.8s $0.10
  ✔ meta titles (2) → de 4.1s $0.01

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
```

## How it works

Blume owns the pipeline; the agent only translates text. For each file that needs work, Blume builds a translation prompt, runs the agent CLI headlessly with its file, shell, and web tools disabled, validates the reply's structure, and writes the target file itself — [Claude Code](https://claude.com/claude-code) with `--claude`, or [Codex](https://developers.openai.com/codex/cli) with `--codex`. Blume holds no API keys and calls no model itself.

Every validated write is recorded in `blume.translations.json` at the project root: for each source file and locale, a hash of the source at the moment it was translated. **Commit this file.** It's how a rerun knows the difference between "already translated" and "translated, but the source changed since" — and it's what makes the CI gate possible.

The ledger is flushed after every finished file, so stopping a long run (Ctrl+C) loses at most the translations that were in flight — the next run picks up where you left off. Files run 4 at a time by default; raise it with `--concurrency` if your machine and the agent's rate limits allow.

Reruns are incremental: a source that hasn't changed since its last translation is skipped, so running `blume translate` after editing one page translates one page per locale. When a stale page is retranslated, the agent is shown the existing translation and told to match its register, dialect, and terminology — a one-paragraph source edit produces a one-paragraph translation diff, not a from-scratch rewrite.

A first translation has no precedent to match, so pin the choice up front with [`style` on the locale](/docs/content/i18n) (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`). The guidance rides along in every translation prompt, and where an existing translation disagrees with it, `style` wins — so a retranslation also nudges older pages toward the configured style.

## What gets translated

- **Pages** — `.md`/`.mdx` files in the default locale. The agent translates the prose and only the human-visible frontmatter values (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`). Targets follow your parser: `fr/guides/install.mdx` under `dir`, `guides/install.fr.mdx` under `dot`.
- **Folder navigation titles** — under the `dir` parser, each locale's needed [`meta.ts`](/docs/content/meta) titles are translated in one batched call, and the generated per-locale `meta.ts` copies every other key (`order`, `pages`, `icon`, `collapsed`) verbatim so the locale's sidebar keeps its ordering.

Translations you wrote by hand are **adopted, never overwritten**: a translation that exists but has no ledger entry is stamped as current and left alone. Only `--force` retranslates it.

## Validation

The agent is never trusted with structure. Before writing, Blume checks each reply and rebuilds the file from the source:

- The frontmatter is reconstructed from the source file's data, with only the six translatable values overlaid — keys the agent invented are dropped, keys it deleted are restored, and `slug`, `icon`, `order`, and dates are source-verbatim by construction.
- The number of code fences must match the source, the body must be non-empty, and the frontmatter must parse.

A reply that fails validation writes nothing — the item is reported as failed and the run moves on. Everything that succeeded stays stamped in the ledger, so a rerun retries only the failures.

## Failing CI

`blume translate --check` is the read-only gate: it reports every missing and stale pair and exits non-zero when there's drift, without running an agent or writing anything.

```bash
blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

The JSON report carries the same `diagnostics` + `summary` shape as `blume validate --json`, `blume audit --json`, and `blume eval --json`, with the drift grouped per locale. Hand-authored (untracked) translations never fail the gate.

## Limitations

- Meta title translation is `dir`-parser only — the `dot` parser has no per-locale `meta.ts` mechanism. A `meta.ts` that default-exports a function is skipped with a warning; author that locale's copy by hand.
- Remote and CMS-backed sources are skipped: there is no local file to write the translation to.
- Header tab labels live in `blume.config.ts`, not content — localize them there with [per-locale label maps](/docs/content/navigation#tabs).
- Translation quality is the agent's. Review the output like any other contribution — the ledger only guarantees freshness, not fluency.

## Flags

- `--claude` / `--codex` — which agent CLI translates. Exactly one is required (except with `--check`).
- `--check` — report drift and exit non-zero, without writing anything.
- `--concurrency <n>` — parallel agent sessions. Defaults to `4`, max `16`.
- `--locale <codes>` — comma-separated target locales (defaults to every non-default locale).
- `--force` — retranslate everything, up-to-date and hand-authored files included.
- `--timeout <seconds>` — agent time limit per file. Defaults to `600`; the ceiling exists to catch hung agents, so large pages have room to finish.
- `--json` — emit the report as JSON on stdout, in both modes.

---

# परिचय
Source: https://useblume.dev/hi/docs

एक फ़ोल्डर में Markdown या MDX डालें, `blume dev` चलाएँ, और एक प्रोडक्शन-ग्रेड डॉक्स साइट पाएँ — नेविगेशन, सर्च, थीमिंग, Open Graph इमेज, और एक समृद्ध कंपोनेंट लाइब्रेरी — बिना कोई ऐप बॉयलरप्लेट लिखे या उसका रखरखाव किए।

**[त्वरित शुरुआत](/docs/quickstart)**

Blume इंस्टॉल करें और मिनटों में अपना पहला पेज शिप करें।

**[कॉन्फ़िगरेशन](/docs/configuration)**

शीर्षक, थीम, सर्च, और डिप्लॉयमेंट को ट्यून करें।

## Blume क्यों मौजूद है

डॉक्स तेज़, AI-तैयार, और शून्य-कॉन्फ़िग होने चाहिए — यहाँ तक कि किसी स्टार्टर टेम्पलेट की ज़रूरत ही न पड़े। कुछ डॉक्स टूल आपको एक शब्द लिखने से पहले ही रखरखाव के लिए पूरा कोडबेस थमा देते हैं। दूसरे आपकी कंटेंट के इर्द-गिर्द टेम्पलेट बनाते हैं, लेकिन आपको अपनी मैनेज्ड सर्विस में बाँध देते हैं।

Blume दोनों दुनियाओं का सर्वश्रेष्ठ लेता है। फ्रेमवर्क ही टेम्पलेट है, इसलिए आप केवल अपनी कंटेंट को ही छूते हैं। जब आप कस्टमाइज़ करना चाहें, तो आप बिल्ट-इन कंपोनेंट्स को बदलकर, एकल कॉन्फ़िगरेशन फ़ाइल में संशोधन करके, या सीधे Astro साइट चाहने पर इजेक्ट करके भी शुरुआत कर सकते हैं। [FAQ](/docs/faq) में बताया गया है कि यह Mintlify, Fumadocs, और बाकी टूल्स की तुलना में कैसा है।

## Blume को अलग क्या बनाता है

### डिफ़ॉल्ट रूप से तेज़

Blume, Astro और Vite पर बनता है और डिफ़ॉल्ट रूप से स्टैटिक HTML रेंडर करता है — तेज़, कैश करने योग्य, और होस्ट करने में सस्ता। कोर थीम कोई क्लाइंट फ्रेमवर्क JS शिप नहीं करती, इसलिए पेज बॉक्स से बाहर ही Core Web Vitals पर अच्छा स्कोर करते हैं। डेव स्टार्टअप और हॉट रीलोड Vite-नेटिव महसूस होते हैं, और आप सर्वर फ़ीचर्स को केवल तभी चुनते हैं जब आपको उनकी ज़रूरत हो।

### बॉक्स से बाहर ही AI-तैयार

हर Blume साइट धाराप्रवाह मशीनी भाषा बोलती है। यह [`llms.txt` और `llms-full.txt`](/docs/configuration/ai) उत्सर्जित करती है, किसी भी पेज के URL में `.md` जोड़कर उसका कच्चा Markdown परोसती है, [OpenAPI द्वारा वर्णित एक JSON API](/docs/configuration/ai#json-api) उजागर करती है, और पाठकों को हर पेज पर **Copy as Markdown** और **Open in chat** क्रियाएँ देती है। एक वैकल्पिक इन-पेज **Ask AI** असिस्टेंट जोड़ें, या एक [**MCP सर्वर**](/docs/configuration/ai#mcp-server) होस्ट करें ताकि Claude Code और Cursor जैसे कोडिंग एजेंट आपके डॉक्स को सीधे सर्च और पढ़ सकें — कोई स्क्रैपिंग नहीं, कोई होस्टेड सर्विस नहीं। आपका Markdown इंसानों और मॉडल दोनों के लिए सत्य का स्रोत है।

### शून्य कॉन्फ़िगरेशन — यहाँ तक कि टेम्पलेट भी

डॉक्स का एक फ़ोल्डर ही एक संपूर्ण प्रोजेक्ट है। क्लोन करने के लिए कोई स्टार्टर नहीं, सेट अप करने के लिए कोई Astro या Tailwind नहीं, और रखरखाव के लिए कोई टेम्पलेट नहीं। नेविगेशन आपकी फ़ाइलों से अनुमानित होता है, [सर्च](/docs/configuration/search) बिना किसी होस्टेड सर्विस के डेव और प्रोडक्शन में काम करता है, और थीमिंग मुट्ठी भर टोकन्स भर है। हर चीज़ का एक समझदार डिफ़ॉल्ट है; कॉन्फ़िगरेशन वह चीज़ है जिस तक आप पहुँचते हैं, वह नहीं जिससे आप शुरुआत करते हैं।

### जड़ तक टाइप-सेफ

आपकी [`blume.config.ts`](/docs/configuration) और हर [`meta.ts`](/docs/content/meta) असली TypeScript हैं — एक स्कीमा द्वारा मान्य और `defineConfig` तथा `defineMeta` के साथ लिखी गईं। आपका एडिटर हर विकल्प को ऑटोकम्प्लीट करता है और टाइपो, अमान्य मान, तथा गायब फ़ील्ड्स को टाइप करते ही पकड़ लेता है, बिल्ड से बहुत पहले। कॉन्फ़िगरेशन ऐसा कोड है जिसे आप रीफैक्टर कर सकते हैं, कंप्यूट कर सकते हैं, और भरोसा कर सकते हैं — न कि ढीले-टाइप वाला YAML।

## सब कुछ शामिल

- **कंपोनेंट्स** — कॉलआउट, कार्ड, स्टेप्स, टैब्स, अकॉर्डियन, बैज, फ़ाइल ट्री, और पैरामीटर टेबल, MDX में [बिना किसी इम्पोर्ट](/docs/content/components) के उपयोग योग्य।
- **लोकल सर्च** — Orama डेव और प्रोडक्शन में काम करता है; बड़ी साइटों के लिए Pagefind एक फ़्लैग भर दूर है। कोई होस्टेड इंडेक्स नहीं।
- **AI** — [`llms.txt`, कच्चे Markdown URL, OpenAPI विवरण के साथ एक JSON API, Copy as Markdown, Open in chat, एक Ask AI असिस्टेंट, और एक होस्टेड MCP सर्वर](/docs/configuration/ai)।
- **नेविगेशन** — फ़ाइलों से अनुमानित, `meta.ts` या कॉन्फ़िग से परिष्कृत।
- **SEO** — मेटाडेटा, Open Graph इमेज, RSS फ़ीड, और JSON-LD, [बिल्ट इन](/docs/configuration/seo)।
- **कस्टमाइज़ेशन** — कंपोनेंट ओवरराइड, React आइलैंड्स, कस्टम पेज, थीम टोकन्स, और `blume add` के ज़रिए एक सोर्स-कंपोनेंट रजिस्ट्री।
- **इजेक्ट** — `blume eject` एक स्टैंडअलोन Astro प्रोजेक्ट तैयार करता है जो अब भी `blume` पैकेज का उपयोग करता है।

## यह कैसे काम करता है

Blume CLI आपकी कंटेंट खोजता है, एक कंटेंट ग्राफ़ बनाता है, और `.blume/` के अंतर्गत एक छिपा हुआ Astro प्रोजेक्ट जनरेट करता है जिसे वह डेव और बिल्ड के लिए चलाता है। जनरेट किया गया रनटाइम एक कार्यान्वयन विवरण है — आप Markdown लिखते हैं, बाकी सब Blume संभालता है — जब तक आप इजेक्ट करके उसका स्वामित्व लेने का निर्णय न लें।

## अगले कदम

**[कॉन्फ़िगरेशन](/docs/configuration)**

शीर्षक, थीम, सर्च, और डिप्लॉयमेंट को ट्यून करें।

**[कंपोनेंट्स](/docs/content/components)**

बिल्ट-इन कंपोनेंट लाइब्रेरी का अन्वेषण करें।

**[AI](/docs/configuration/ai)**

`llms.txt` और एक Ask AI असिस्टेंट शिप करें।

**[CLI](/docs/reference/cli)**

हर `blume` कमांड और फ़्लैग।

---

# OpenAPI / AsyncAPI
Source: https://useblume.dev/hi/docs/advanced/api-reference

Blume को किसी OpenAPI स्पेक पर इंगित करें और यह एक नेटिव API संदर्भ तैयार करता है: **प्रति ऑपरेशन एक वास्तविक पृष्ठ**, टैब-स्कोप वाले साइडबार में टैग के अनुसार समूहीकृत, स्कीमा तालिकाओं, अनुरोध/प्रतिक्रिया उदाहरणों, जनरेट किए गए कोड नमूनों और एक इंटरैक्टिव [Try it](#try-it-प्लेग्राउंड) पैनल के साथ। चूँकि प्रत्येक ऑपरेशन एक असली Blume पृष्ठ है, इसे अपना स्वयं का URL मिलता है, यह **साइट खोज** और `llms.txt` में दिखाई देता है, और इसे एक Open Graph छवि मिलती है — ठीक वैसे ही जैसे किसी भी हाथ से लिखे दस्तावेज़ को। नीचे दिया गया कॉन्फ़िग उदाहरण के तौर पर Blume को सार्वजनिक Petstore स्पेक पर इंगित करता है।

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}
```

यह संदर्भ को `/reference` पर माउंट करता है (एक अवलोकन पृष्ठ) और प्रत्येक ऑपरेशन को `/reference/<tag>/<operation>` पर। `spec` या तो एक `http(s)` URL होता है या आपकी परियोजना में किसी स्थानीय फ़ाइल का पथ। Blume इसे [Scalar के OpenAPI पार्सर](https://github.com/scalar/scalar) से पार्स करता है — Swagger 2.0 और OpenAPI 3.0 स्पेक स्वचालित रूप से 3.1 में अपग्रेड कर दिए जाते हैं। इसके बजाय किसी GraphQL API का दस्तावेज़ीकरण कर रहे हैं? [GraphQL संदर्भ](/docs/advanced/graphql) देखें।

यह संदर्भ स्वयं कोई हेडर टैब नहीं जोड़ता। इसे सामने लाने के लिए, किसी [नेविगेशन टैब](/docs/content/navigation#tabs) को इसके रूट पर इंगित करें — इससे नेटिव रेंडरर के लिए ऑपरेशन साइडबार का दायरा भी तय होता है:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
ऑपरेशन खोज के लिए उनके **सारांश और टैग** के आधार पर अनुक्रमित किए जाते हैं। रेंडर की गई स्कीमा तालिकाएँ और कोड नमूने पूर्ण-पाठ अनुक्रमित नहीं होते; खोज किसी ऑपरेशन के शीर्षक और अनुभाग से मेल खाती है, फिर उसके अपने पृष्ठ से लिंक करती है।
:::

## एक स्थानीय स्पेक

सापेक्ष पथ आपकी परियोजना के रूट से हल किया जाता है और बिल्ड के समय पढ़ा जाता है। JSON और YAML दोनों काम करते हैं:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}
```

## रूट

`route` यह नियंत्रित करता है कि संदर्भ कहाँ माउंट हो — अवलोकन पृष्ठ और प्रत्येक ऑपरेशन रूट का उपसर्ग (और वह रूट जिस पर आप नेविगेशन टैब इंगित करते हैं):

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}
```

## कोड नमूने और स्कीमा

`codeSamples` चुनता है कि प्रति ऑपरेशन कौन-सी भाषाएँ रेंडर हों (अंतर्निहित: `curl`, `js`, `python`); `expandSchemas` नेस्टेड स्कीमा पंक्तियों को सिकुड़ी हुई के बजाय विस्तारित अवस्था में शुरू करता है:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}
```

## "Try it" प्लेग्राउंड

नेटिव रूप से रेंडर किए गए ऑपरेशन पृष्ठ डिफ़ॉल्ट रूप से एक इंटरैक्टिव **Try it** पैनल के साथ आते हैं। Blume फ़ॉर्म को ऑपरेशन से ही जनरेट करता है: प्रत्येक पथ, क्वेरी और हेडर पैरामीटर के लिए एक इनपुट, अनुरोध-बॉडी स्कीमा से बना एक बॉडी संपादक, और सब कुछ स्पेक के उदाहरणों से पहले से भरा हुआ। एक सर्वर चयनकर्ता स्पेक के `servers` सूचीबद्ध करता है, साथ ही किसी अन्य बेस URL के लिए एक मुक्त-पाठ फ़ील्ड, और प्रामाणीकरण इनपुट ऑपरेशन की [हल की गई सुरक्षा](#प्राधिकरण) से मेल खाते हैं — bearer टोकन, API कुंजी और basic क्रेडेंशियल, तथा OAuth2 के लिए एक टोकन पेस्ट फ़ील्ड (एक एक्सेस टोकन साथ लाएँ; Blume फ़्लो नहीं चलाता)।

पैनल और कोड नमूने एक-दूसरे के साथ कदम मिलाकर चलते हैं: फ़ॉर्म में टाइप किए गए मान जनरेट किए गए नमूनों को लाइव अपडेट करते हैं, इसलिए कॉपी की गई curl कमांड हमेशा ठीक उसी से मेल खाती है जो **Send** करता। और यह रास्ते से हटकर रहता है — पैनल सर्वर-रेंडर होकर सिकुड़ी अवस्था में आता है, और इसका JavaScript तभी लोड होता है जब कोई पाठक इसे पहली बार खोलता है। जो पाठक इसे कभी छूते ही नहीं, वे इसका कुछ भी डाउनलोड नहीं करते।

`playground: false` ही पूरा बंद-स्विच है:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}
```

### क्रेडेंशियल

प्रामाणीकरण इनपुट में टाइप किए गए क्रेडेंशियल मेमोरी में रहते हैं और रीलोड पर गायब हो जाते हैं। **Remember on this device** चुनने पर वे `localStorage` में संचित हो जाते हैं, जिनका दायरा दस्तावेज़ ऑरिजिन तक सीमित होता है — जिस API को कॉल किया जा रहा है, उसके अलावा वे कहीं नहीं भेजे जाते। जो भी टाइप किया जाए, कोड नमूने प्लेसहोल्डर (`YOUR_TOKEN` इत्यादि) ही दिखाते रहते हैं, जब तक पाठक **Include my values in samples** को चालू न कर दे।

### CORS और प्रॉक्सी

[Scalar रेंडरर](#scalar-रेंडरर) की तरह ही, अनुरोध **सीधे ब्राउज़र से** लक्ष्य API तक जाते हैं, इसलिए API को दस्तावेज़ साइट से क्रॉस-ऑरिजिन अनुरोधों की अनुमति देनी चाहिए (`Access-Control-Allow-Origin`)। जो API ऐसा नहीं कर सकते, उनके लिए `playground.proxy` सेट करें: एक URL अनुरोधों को आपके द्वारा होस्ट किए गए प्रॉक्सी से होकर भेजता है, और `true` अंतर्निहित `/_api-proxy` रूट को सक्षम करता है — जिसके लिए एक सर्वर बिल्ड चाहिए, इसलिए इसे [`deployment.output: "server"`](/docs/deployment#server-rendering) की आवश्यकता होती है:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}
```

अंतर्निहित प्रॉक्सी केवल उन्हीं ऑरिजिन तक अनुरोध अग्रेषित करता है जिन्हें आपके स्पेक `servers` में घोषित करते हैं — रीडायरेक्ट के आर-पार भी — इसलिए किसी सार्वजनिक दस्तावेज़ परिनियोजन को उसके नेटवर्क के अन्य होस्ट की ओर नहीं मोड़ा जा सकता। पैनल में टाइप किया गया **Custom base URL** एक प्रलेखित सर्वर नहीं होता: प्रॉक्सी सक्षम होने पर, उस तक जाने वाले अनुरोध 403 के साथ अस्वीकार कर दिए जाते हैं।

## एकाधिक स्पेक

एक से अधिक स्पेक प्रकाशित करने के लिए `sources` का उपयोग करें। प्रत्येक स्रोत को अपना अवलोकन रूट, ऑपरेशन पृष्ठ और हेडर टैब मिलता है। प्रत्येक को एक `label` दें (टैब के लिए और उसका रूट प्राप्त करने के लिए उपयोग किया जाता है), या एक स्पष्ट `route` सेट करें:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}
```

`spec` एकल-प्रविष्टि वाले `sources` का संक्षिप्त रूप है, इसलिए आप `sources` तभी उपयोग करते हैं जब आपके पास एक से अधिक हों।

### प्रति-स्रोत अनुक्रमण

जनरेट किए गए पृष्ठ डिफ़ॉल्ट रूप से खोज, `llms.txt` और क्रॉलर अनुक्रमण में शामिल होते हैं। कोई द्वितीयक या अतिव्यापी स्पेक अपने पृष्ठों को छिपाए बिना या नेविगेशन से हटाए बिना किसी भी सतह से बाहर निकल सकता है:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}
```

- `includeInSearch: false` स्रोत के अवलोकन और ऑपरेशनों को साइट खोज से बाहर रखता है।
- `includeInLlms: false` उन्हें दोनों `llms.txt` फ़ाइलों से बाहर रखता है।
- `noindex: true` क्रॉलर noindex मेटाडेटा जोड़ता है और पृष्ठों को साइटमैप से हटा देता है।

प्रत्येक ऑपरेशन पृष्ठ का मेटा विवरण स्वयं ऑपरेशन का `description` (या `summary`) होता है, जिसके बाद एंडपॉइंट का नाम बताने वाला एक जनरेट किया गया वाक्य आता है — "Reference for the `GET /pets` endpoint in the Petstore API." — इसलिए संक्षिप्त एक-पंक्ति सारांशों वाला स्पेक भी प्रति पृष्ठ एक विशिष्ट, स्निपेट-लंबाई का विवरण देता है। वह वाक्य अंग्रेज़ी में होता है। जिस साइट का स्पेक गद्य किसी अन्य भाषा में लिखा गया हो, वहाँ स्रोत पर `seoDescriptionSuffix: false` सेट करके उसे हटा दें और प्रत्येक पृष्ठ का वर्णन केवल लिखे गए गद्य से करें; जिस ऑपरेशन में न `description` हो और न `summary`, वह अपने शीर्षक (`GET /pets`) पर लौट आता है, इसलिए कोई भी पृष्ठ खाली विवरण के साथ प्रकाशित नहीं होता:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}
```

[Scalar रेंडरर](#scalar-रेंडरर) के साथ केवल `noindex` लागू होता है — Scalar द्वारा रेंडर किया गया संदर्भ पहले से ही Blume की खोज और `llms.txt` के बाहर होता है, इसलिए वहाँ दोनों `include*` सेटिंग्स के लिए कुछ करने को नहीं बचता।

## प्राधिकरण

जो ऑपरेशन [सुरक्षा आवश्यकताएँ](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) घोषित करते हैं, वे अपने पैरामीटर के ऊपर एक **Authorization** अनुभाग रेंडर करते हैं, और जनरेट किए गए कोड नमूने एक प्लेसहोल्डर क्रेडेंशियल भेजते हैं (`Authorization: Bearer YOUR_TOKEN`, एक API-कुंजी हेडर, या एक क्वेरी कुंजी — जो भी उस योजना की माँग हो)। कॉन्फ़िगर करने के लिए कुछ नहीं है: Blume स्पेक से `security` पढ़ता है, इसलिए संदर्भ हमेशा उससे मेल खाता है जो API वास्तव में लागू करता है।

OpenAPI का अर्थ-विधान जस का तस लागू होता है:

- किसी ऑपरेशन का अपना `security` दस्तावेज़ के रूट डिफ़ॉल्ट को अधिरोहित करता है; `security: []` इसे **सार्वजनिक** चिह्नित करता है और कोई Authorization अनुभाग रेंडर नहीं करता।
- एकाधिक आवश्यकता प्रविष्टियाँ विकल्प होती हैं — "or" समूहों के रूप में रेंडर की जाती हैं; एक प्रविष्टि के भीतर की हर योजना एक साथ आवश्यक होती है। पहला विकल्प कोड नमूनों को आपूर्ति करता है।
- एक खाली `{}` प्रविष्टि का अर्थ है कि उस ऑपरेशन के लिए प्रमाणीकरण **वैकल्पिक** है, और अनुभाग ऐसा ही बताता है।
- OAuth2 स्कोप प्रति योजना सूचीबद्ध किए जाते हैं; `components.securitySchemes` से योजना के `description` इनलाइन रेंडर होते हैं।

## Scalar रेंडरर

नेटिव रेंडरर डिफ़ॉल्ट है — ऑपरेशन पृष्ठ, खोज एकीकरण और ऊपर बताया गया ["Try it" प्लेग्राउंड](#try-it-प्लेग्राउंड), ये सब उसी का काम हैं। यदि आप इसके बजाय [Scalar](https://scalar.com) का स्वयं-निहित API संदर्भ UI एम्बेड करना चाहते हैं — इसका अपना साइडबार, खोज, थीम और एक ही रूट पर अनुरोध क्लाइंट — तो `renderer: "scalar"` सेट करें:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}
```

Scalar द्वारा रेंडर किया गया संदर्भ अपने स्वयं के रूट पर एक स्वयं-निहित एम्बेड होता है — यह Blume के साइडबार, खोज या `llms.txt` में नहीं बुनता, और Blume का [`playground`](#try-it-प्लेग्राउंड) कॉन्फ़िग इस पर लागू नहीं होता। यह Blume के लाइट/डार्क टॉगल का अनुसरण अवश्य करता है: माउंट होते समय एम्बेड पृष्ठ की थीम से बँध जाता है और उसी के साथ बदलता है, इसलिए Scalar का अपना थीम स्विच छिपा दिया जाता है (रंग मोड वापस Scalar को सौंपने के लिए `scalar.forceDarkModeState` या `scalar.darkMode` सेट करें)। Scalar अपना स्वयं का अनुरोध क्लाइंट लाता है, जो आपके **लक्ष्य API को सीधे ब्राउज़र से** कॉल करता है (`playground.proxy` रूट यहाँ उपलब्ध नहीं है), इसलिए API को दस्तावेज़ साइट से क्रॉस-ऑरिजिन अनुरोधों की अनुमति देनी चाहिए (`Access-Control-Allow-Origin`)। `theme` केवल Scalar रेंडरर पर लागू होता है।

### Scalar विकल्प पास करना

`theme` उस एक विकल्प का संक्षिप्त रूप है जिसे अधिकांश लोग चुनते हैं, लेकिन Scalar इससे कहीं अधिक का समर्थन करता है। एक `scalar` ऑब्जेक्ट किसी भी [Scalar कॉन्फ़िगरेशन](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) को सीधे एम्बेडेड संदर्भ तक अग्रेषित करता है — Blume कुंजियों पर रोक नहीं लगाता, इसलिए जो कुछ भी Scalar स्वीकार करता है वह प्रवाहित हो जाता है:

```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 का अपना [`i18n`](/docs/content/i18n) दस्तावेज़ क्रोम का अनुवाद करता है, लेकिन Scalar की एक अलग स्थानीयकरण प्रणाली है — एम्बेडेड संदर्भ का भी अनुवाद करने के लिए `scalar.localization.locale` सेट करें। `scalar` ऑब्जेक्ट के विकल्प Blume के व्युत्पन्न कॉन्फ़िग पर भारी पड़ते हैं, इसलिए यहाँ सेट की गई कोई भी चीज़ (`theme`, `customCss`, या स्पेक `content`/`url` सहित) Blume के डिफ़ॉल्ट को अधिरोहित कर देती है। यही `scalar` ब्लॉक `asyncapi` संदर्भ पर भी काम करता है।

## AsyncAPI

इवेंट-चालित API समान आकार वाले एक सहोदर `asyncapi` ब्लॉक का उपयोग करते हैं — और उसी नेटिव रेंडरर का भी। प्रत्येक `send`/`receive` ऑपरेशन एक वास्तविक पृष्ठ बन जाता है, जिसमें संदेश पेलोड और हेडर स्कीमा तालिकाएँ, चैनल पैरामीटर, प्रोटोकॉल बाइंडिंग, स्पेक के `securitySchemes` से व्युत्पन्न एक Authorization अनुभाग (सर्वर-स्तर और ऑपरेशन-स्तर, विकल्प "or" समूहों के रूप में), और एक ["Try it"](#इवेंट्स-के-लिए-try-it) संदेश संयोजक होता है। केवल डिफ़ॉल्ट रूट अलग है (`/events`):

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}
```

AsyncAPI **2.x स्पेक आधिकारिक AsyncAPI कनवर्टर से स्वचालित रूप से 3.x में सामान्यीकृत हो जाते हैं**, इसलिए `publish`/`subscribe` चैनल स्थिर URL वाले `send`/`receive` ऑपरेशन पृष्ठों पर मैप होते हैं — बाद में स्पेक फ़ाइल को स्वयं कनवर्टर से अपग्रेड करने पर कुछ भी नहीं हिलता। ऑपरेशन टैग के अनुसार समूहीकृत होते हैं; बिना टैग वाले ऑपरेशन अपने चैनल पते के अंतर्गत समूहीकृत होते हैं।

कोड नमूने **प्रोटोकॉल-सजग** होते हैं, जो ऑपरेशन की बाइंडिंग (या उसके सर्वरों के प्रोटोकॉल) के आधार पर तय होते हैं: WebSockets के लिए `wscat` और एक ब्राउज़र `WebSocket` स्निपेट, Kafka के लिए `kcat`, MQTT के लिए `mosquitto_pub`/`mosquitto_sub`। `codeSamples` उस सेट को उसी तरह फ़िल्टर करता है जिस तरह वह `openapi` ब्लॉक पर भाषाएँ चुनता है; जिस प्रोटोकॉल के लिए कोई समर्थित टूल नहीं है, वह किसी गढ़े हुए क्लाइंट के बजाय केवल संदेश पेलोड उदाहरण रेंडर करता है।

ऊपर प्रलेखित सब कुछ जस का तस लागू रहता है, [`playground`](#इवेंट्स-के-लिए-try-it) सहित: `route`, `label`/`route` के साथ `sources`, `expandSchemas`, [प्रति-स्रोत अनुक्रमण](#प्रति-स्रोत-अनुक्रमण) फ़्लैग (`seoDescriptionSuffix` भी — जनरेट किया गया वाक्य एंडपॉइंट के बजाय चैनल और क्रिया का नाम बताता है), और ऑपरेशन सारांश व टैग के आधार पर खोज अनुक्रमण।

`renderer: "scalar"` सेट करने से आप एम्बेडेड Scalar SPA में वापस लौट जाते हैं, जहाँ — OpenAPI की तरह — केवल `noindex` लागू होता है। Scalar का अपना कोई AsyncAPI प्लेग्राउंड नहीं है; इसका एम्बेड दस्तावेज़ का प्रकार स्वयं पहचान लेता है और चैनल, ऑपरेशन, संदेश तथा एक Models अनुभाग रेंडर करता है, इसलिए इस अदला-बदली में संयोजक हाथ से निकल जाता है।

### इवेंट्स के लिए "Try it"

नेटिव रूप से रेंडर किए गए ऑपरेशन पृष्ठ यहाँ भी एक **Try it** पैनल के साथ आते हैं, उन्हीं शर्तों पर जिन पर [OpenAPI पैनल](#try-it-प्लेग्राउंड) आता है: सर्वर-रेंडर होकर सिकुड़ी अवस्था में, और इसका JavaScript तभी लोड होता है जब कोई पाठक इसे पहली बार खोलता है।

प्रोटोकॉल जो भी हो, पैनल एक पेलोड संपादक के साथ खुलता है जो संदेश के `examples` से पहले से भरा होता है — या, जब संदेश कोई घोषित नहीं करता, तो पेलोड स्कीमा से लिए गए एक नमूना मान से — और टाइप करते समय संदेश पेलोड स्कीमा के विरुद्ध सत्यापित होता रहता है। उसके नीचे प्रत्येक चैनल पैरामीटर के लिए एक इनपुट और चैनल के `servers` से भरा एक सर्वर चयनकर्ता होता है, साथ ही किसी अन्य URL के लिए एक मुक्त-पाठ फ़ील्ड। प्रोटोकॉल-सजग कोड नमूने फ़ॉर्म के साथ ठीक वैसे ही कदम मिलाकर चलते हैं जैसे किसी HTTP ऑपरेशन पर curl, js और python चलते हैं: चैनल पता टेम्पलेट आपके टाइप किए गए पैरामीटर मानों से भर दिया जाता है, इसलिए कॉपी किया गया `wscat`, `WebSocket`, `kcat` या `mosquitto_pub` स्निपेट वही दर्शाता है जो फ़ॉर्म कहता है।

लाइव कनेक्ट केवल WebSocket के लिए है। किसी `ws` या `wss` बाइंडिंग पर पैनल हल किए गए चैनल URL से जुड़ता है, कनेक्शन की स्थिति दिखाता है, और हर फ़्रेम को टाइमस्टैम्प के साथ लॉग करता है। AsyncAPI 3 किसी क्रिया को API के पक्ष से बताता है, और पैनल उसी का अनुसरण करता है: एक `receive` ऑपरेशन वह है जिसे API आपसे प्राप्त करता है, इसलिए उसे एक **Send** बटन मिलता है जो संयोजित पेलोड प्रकाशित करता है; एक `send` ऑपरेशन केवल आपकी ओर संदेश प्रवाहित करता है, इसलिए वह जुड़ता है और लॉग करता है। कोई पुनः-कनेक्ट तर्क नहीं है — एक बार सॉकेट बंद हो जाने पर, जब तक आप दोबारा न जुड़ें, वह बंद ही रहता है। Kafka, MQTT, AMQP और हर दूसरे प्रोटोकॉल को संयोजक तथा कॉपी करने योग्य CLI नमूने मिलते हैं, और पैनल पृष्ठ पर यही बात कहता है: Blume किसी ब्राउज़र टैब से ब्रोकर कनेक्टिविटी का नाटक नहीं करता।

`asyncapi.playground`, `openapi.playground` का दर्पण है — नेटिव रेंडरर के साथ डिफ़ॉल्ट रूप से चालू, और `false` ही पूरा बंद-स्विच है:

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}
```

:::note
`playground.proxy` इवेंट ऑपरेशनों पर लागू नहीं होता। यह HTTP अनुरोध अग्रेषित करता है, और एक WebSocket कनेक्ट सीधे ब्राउज़र से URL में नामित सर्वर तक जाता है, इसलिए प्रॉक्सी के लिए किसी चीज़ के आगे बैठने को कुछ बचता ही नहीं।
:::

इवेंट संयोजक कोई ब्रोकर क्रेडेंशियल एकत्र नहीं करता। प्रत्येक ऑपरेशन पृष्ठ का **Authorization** अनुभाग प्रलेखित करता है कि ब्रोकर क्या अपेक्षा करता है, और एक WebSocket कनेक्ट केवल वही ले जाता है जो पहले से URL में मौजूद है। इवेंट ऑपरेशनों के लिए कुछ भी संचित नहीं किया जाता।

---

# ब्लॉग
Source: https://useblume.dev/hi/docs/advanced/blog

Blume में ब्लॉग बस एक टाइप वाला कंटेंट है। किसी पेज को `type: blog` से चिह्नित करें और Blume उसे अपने आप एक RSS फ़ीड तथा अधिक समृद्ध आर्टिकल मेटाडेटा दे देता है। [changelog](/docs/advanced/changelog) के विपरीत, यहाँ कोई जनरेट किया हुआ इंडेक्स पेज नहीं होता — लैंडिंग पेज आप स्वयं तैयार करते हैं, जिससे डिज़ाइन पूरी तरह आपके हाथों में रहता है।

## एक पोस्ट लिखें

पोस्ट एक सामान्य `.md` या `.mdx` पेज होता है जिसके फ़्रंटमैटर में `type: blog` होता है। परंपरा के अनुसार पोस्ट `blog/` के अंतर्गत रहते हैं, लेकिन जो मायने रखता है वह टाइप है — फ़ोल्डर नहीं:

```mdx blog/introducing-blume.mdx lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
```

हर पोस्ट को एक `date` दें ताकि फ़ीड आइटम नए से पुराने क्रम में लगें और उनमें `pubDate` शामिल हो, तथा एक `description` भी दें — इसका उपयोग फ़ीड सारांश और SEO दोनों के लिए होता है।

## RSS फ़ीड

Blume **`/blog/rss.xml`** पर एक ब्लॉग फ़ीड बनाता है, जो `date` के अनुसार नए से पुराने क्रम में सजा होता है। फ़ीड को एक पूर्ण (absolute) साइट URL चाहिए, इसलिए [`deployment.site`](/docs/deployment) सेट करें; इसके बाद Blume हर पेज पर एक `<link rel="alternate">` टैग जोड़ देता है ताकि रीडर उसे अपने आप खोज लें।

फ़ीड डिफ़ॉल्ट रूप से चालू रहती है। इसे [`seo.rss`](/docs/configuration/seo#rss-feeds) के अंतर्गत समायोजित करें:

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

फ़ीड छोड़ने के लिए `rss.types` से `"blog"` हटा दें।

## स्ट्रक्चर्ड डेटा

जब [स्ट्रक्चर्ड डेटा](/docs/configuration/seo#structured-data) चालू होता है, तो हर पोस्ट को उसके विवरण और प्रकाशन तिथि के साथ एक schema.org **`BlogPosting`** के रूप में निर्गत किया जाता है — यही वह समृद्ध आर्टिकल टाइप है जिसकी सर्च इंजन ब्लॉग कंटेंट के लिए अपेक्षा करते हैं।

## इंडेक्स बनाना

Blume `/blog` लैंडिंग पेज जनरेट नहीं करता, इसलिए आप उसे स्वयं बनाते हैं। सबसे सरल विकल्प एक ऐसा कंटेंट पेज है जो हर पोस्ट से हाथ से लिंक करता हो:

```mdx blog/index.mdx lineNumbers
---
title: Blog
description: News and writing from the team.
---

<CardGroup cols={2}>
  <Card title="Introducing Blume" href="/blog/introducing-blume">
    Why we built a markdown-first docs framework.
  </Card>
</CardGroup>
```

इसके बजाय पोस्ट को अपने आप सूचीबद्ध करने के लिए, `pages/blog/index.astro` पर एक [कस्टम पेज](/docs/advanced/custom-pages) जोड़ें जो Astro के `docs` कंटेंट कलेक्शन से पढ़ता है और हर एंट्री को `blume:data` से मिले उसके रूट के साथ जोड़ता है:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    date: entry.data.date,
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }))
  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

इसे पूरे साइट लेआउट में लपेटने के लिए [कस्टम पेज](/docs/advanced/custom-pages#using-the-site-layout) देखें।

**[कस्टम पेज](/docs/advanced/custom-pages)**

ब्लॉग इंडेक्स माउंट करें और blume:data से पढ़ें।

**[SEO](/docs/configuration/seo)**

फ़ीड, Open Graph इमेज, और स्ट्रक्चर्ड डेटा।

---

# चेंजलॉग
Source: https://useblume.dev/hi/docs/advanced/changelog

Blume बॉक्स से बाहर ही एक चेंजलॉग के साथ आता है। हर रिलीज़ को एक सामान्य कंटेंट फ़ाइल के रूप में लिखें, उसे `type: changelog` से चिह्नित करें, और Blume हर एंट्री को एक जनरेट किए गए टाइमलाइन पेज और एक RSS फ़ीड में इकट्ठा कर देता है — न कोई लेआउट बनाना है, न कोई सूची बनाए रखनी है। या फ़ाइलों को पूरी तरह छोड़ दें और [अपना चेंजलॉग GitHub Releases से लें](#from-github-releases)।

## एक एंट्री लिखें

एक चेंजलॉग एंट्री एक सामान्य `.md` या `.mdx` पेज होती है जिसके फ़्रंटमैटर में `type: changelog` होता है। परंपरा के अनुसार वे `changelog/` के अंतर्गत रहती हैं, लेकिन जो मायने रखता है वह टाइप है — फ़ोल्डर नहीं:

```mdx changelog/v1-2-0.mdx lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks
```

हर एंट्री को एक `date` दें ताकि टाइमलाइन और फ़ीड नए से पुराने क्रम में सॉर्ट हों। बिना उद्धरण चिह्नों वाली YAML तिथि ठीक है — Blume उसे सामान्यीकृत कर देता है।

### `changelog` ऑब्जेक्ट

वैकल्पिक `changelog` ऑब्जेक्ट टाइमलाइन और फ़ीड के लिए अधिक समृद्ध मेटाडेटा जोड़ता है:

| Prop | Type | Default | Description |
| - | - | - | - |
| `changelog.version?` | `string` | - | रिलीज़ संस्करण। जब कोई टाइटल न हो तो v-उपसर्ग वाले लेबल पर वापस चला जाता है। |
| `changelog.category?` | `string` | - | एंट्री के बगल में एक टैग के रूप में दिखाया जाता है, जैसे Release, Features, Fixes। |
| `changelog.date?` | `string` | - | प्रकाशन तिथि। यह यहाँ या शीर्ष स्तर पर हो सकती है — दोनों टाइमलाइन और RSS फ़ीड को फ़ीड करते हैं। |

## टाइमलाइन पेज

एक बार जब आपके पास कम से कम एक `type: changelog` एंट्री हो, तो Blume अपने आप एक **`/changelog`** पेज जनरेट कर देता है। यह एक केंद्रित, पूर्ण-चौड़ाई वाली टाइमलाइन के रूप में रेंडर होता है — बिना साइडबार या विषय-सूची के — जिसमें हर एंट्री नई से पुरानी क्रम में होती है, और उसके कंटेंट के बगल में बाएँ रेल में उसकी तिथि, लेबल और `category` टैग दिखाई देते हैं:

- एंट्री का **title** उसका लेबल बन जाता है — या जब कोई टाइटल न हो तो `v{version}`। यह उस एंट्री के अपने पेज से लिंक करता है, इसलिए एक रिलीज़ टाइमलाइन में एक पंक्ति भी है और एक साझा करने योग्य परमालिंक भी।
- `category` तिथि के बगल में एक टैग के रूप में रेंडर होता है।
- ड्राफ़्ट और `sidebar.hidden` एंट्रियाँ छोड़ दी जाती हैं।

यह पेज केवल तभी दिखाई देता है जब `/changelog` रूट पर पहले से कुछ न हो। इसे अपने स्वयं के डिज़ाइन से बदलने के लिए, `pages/changelog.astro` पर एक [कस्टम पेज](/docs/advanced/custom-pages) जोड़ें — वह नियंत्रण ले लेता है और Blume डिफ़ॉल्ट टाइमलाइन जनरेट करना बंद कर देता है।

क्योंकि यह पेज लिखा नहीं बल्कि जनरेट किया जाता है, यह कंटेंट ट्री का हिस्सा नहीं होता — इसलिए `/changelog` की ओर इशारा करने वाला हेडर [टैब](/docs/content/navigation#tabs) इसके बजाय नवीनतम एंट्री पर पहुँच जाता है। टैब को एक `href` दें ताकि वह इंडेक्स पर ही पहुँचे:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

### प्रमुख संस्करण के अनुसार समूहीकृत

जब आपके संस्करण [semver](https://semver.org) का पालन करते हैं और एक से अधिक मेजर तक फैले होते हैं, तो Blume टाइमलाइन को प्रमुख संस्करण के अनुसार पेजिनेट करता है। केवल नवीनतम मेजर लाइन दिखाई जाती है, और नीचे एक **Show N.x releases** बटन होता है जो एक क्लिक में अगली सबसे पुरानी मेजर लाइन दिखाता है:

- पहचान स्वचालित है — कोई कॉन्फ़िगरेशन नहीं। यह केवल तभी सक्रिय होती है जब सूचीबद्ध हर रिलीज़ `major.minor.patch` के रूप में पार्स होती हो और एक से अधिक मेजर हों; अन्यथा टाइमलाइन सपाट रहती है।
- यह मोनोरेपो द्वारा प्रकाशित स्कोप्ड टैग्स को सहन करता है, इसलिए `pkg@2.0.0` `2.x` के अंतर्गत समूहीकृत होता है और `pkg@1.4.0` `1.x` के अंतर्गत।
- यह प्रोग्रेसिव एन्हांसमेंट है: हर रिलीज़ अब भी पेज के HTML में (और उसकी RSS फ़ीड तथा सर्च इंडेक्स में) मौजूद रहती है, इसलिए बिना JavaScript वाले पाठक — और क्रॉलर — पूरा इतिहास देखते हैं। बटन पुराने मेजर को केवल तभी संक्षिप्त करता है जब पेज हाइड्रेट हो जाता है।

## GitHub Releases से

एंट्रियाँ हाथ से लिखने के बजाय, अंतर्निर्मित [`github-releases` स्रोत](/docs/content/sources#github-releases) को किसी रेपो की ओर इंगित करें और हर रिलीज़ एक `type: changelog` एंट्री बन जाती है — वही टाइमलाइन और फ़ीड, सीधे उन रिलीज़ों से पोषित जिन्हें आप पहले से प्रकाशित करते हैं। Blume का अपना [चेंजलॉग](/changelog) इसी तरह बना है:

```ts blume.config.ts
content: {
  sources: [
    { type: "filesystem", root: "content" },
    {
      type: "github-releases",
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    },
  ],
}
```

रिलीज़ का नाम टाइटल बन जाता है, उसका टैग `changelog.version` बन जाता है, और उसकी प्रकाशन तिथि टाइमलाइन को सॉर्ट करती है। हर रिलीज़ पेज को उसके नोट्स से सारांशित एक अद्वितीय मेटा विवरण भी मिलता है — मार्कडाउन हटाकर, सेक्शन हेडिंग्स और चेंजसेट कमिट-हैश उपसर्ग हटाकर, उस सर्च-स्निपेट लंबाई तक काटकर जिसकी जाँच [`blume audit`](/docs/reference/cli#auditing-the-built-site) करता है — बजाय साइट विवरण पर वापस जाने के। एक निजी रेपो `GITHUB_TOKEN` एनवायरनमेंट वेरिएबल से प्रमाणित होता है। हर विकल्प के लिए [कंटेंट स्रोत](/docs/content/sources#github-releases) देखें।

## RSS फ़ीड

Blume **`/changelog/rss.xml`** पर एक चेंजलॉग फ़ीड भी बनाता है, जो `date` के अनुसार नए से पुराने क्रम में सॉर्ट होती है। फ़ीड्स को एक निरपेक्ष साइट URL की आवश्यकता होती है, इसलिए [`deployment.site`](/docs/deployment) सेट करें; तब Blume हर पेज पर एक `<link rel="alternate">` टैग इंजेक्ट करता है ताकि पाठक इसे अपने आप खोज सकें।

फ़ीड डिफ़ॉल्ट रूप से चालू है। इसे [`seo.rss`](/docs/configuration/seo#rss-feeds) के अंतर्गत ट्यून करें:

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

टाइमलाइन को रखते हुए फ़ीड छोड़ने के लिए `rss.types` से `"changelog"` हटा दें।

## स्ट्रक्चर्ड डेटा

जब [स्ट्रक्चर्ड डेटा](/docs/configuration/seo#structured-data) चालू होता है, तो हर चेंजलॉग एंट्री को उसके विवरण और प्रकाशन तिथि के साथ एक schema.org **`TechArticle`** के रूप में उत्सर्जित किया जाता है, ताकि सर्च इंजन रिलीज़ों को तिथि-युक्त लेखों के रूप में इंडेक्स कर सकें।

**[फ़्रंटमैटर](/docs/reference/frontmatter#changelog)**

संपूर्ण चेंजलॉग फ़्रंटमैटर स्कीमा।

**[कस्टम पेज](/docs/advanced/custom-pages)**

जनरेट की गई टाइमलाइन को अपने स्वयं के लेआउट से बदलें।

---

# कस्टम पेज
Source: https://useblume.dev/hi/docs/advanced/custom-pages

एक Blume साइट का अधिकांश भाग Markdown होता है, लेकिन कभी-कभी आपको ऐसा रूट चाहिए होता है जो डॉक _न_ हो — एक लैंडिंग पेज, एक प्राइसिंग पेज, हाथ से बनाया गया ब्लॉग या चेंजलॉग इंडेक्स, या एक इंटरैक्टिव डैशबोर्ड। अपने **pages** फ़ोल्डर में एक `.astro` फ़ाइल रखें और Blume उसे आपके कंटेंट के साथ-साथ एक वास्तविक रूट के रूप में माउंट कर देता है।

## पेज जोड़ें

अपने प्रोजेक्ट रूट पर एक `pages/` फ़ोल्डर बनाएँ और उसमें एक `.astro` फ़ाइल जोड़ें:

```astro pages/pricing.astro lineNumbers
---
import data from "blume:data";
---

<h1>Pricing for {data.config.title}</h1>
```

`blume dev` इसे तुरंत उठा लेता है और `blume build` इसे स्टैटिक HTML में प्रीरेंडर कर देता है। फ़ोल्डर का नाम [`content.pages`](/docs/configuration#content) से कॉन्फ़िगर किया जा सकता है (डिफ़ॉल्ट `"pages"`)।

कस्टम पेज डिस्क पर अपना मूल स्थान बनाए रखते हैं, इसलिए रिलेटिव इम्पोर्ट, कंपोनेंट इम्पोर्ट और [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) सभी ठीक वैसे ही काम करते हैं जैसे एक सामान्य Astro प्रोजेक्ट में — Blume हर फ़ाइल को उसकी जगह पर ही माउंट करता है, उसे कॉपी नहीं करता।

## फ़ाइलें और रूट्स

pages फ़ोल्डर के अंतर्गत हर फ़ाइल का पाथ ही उसका रूट बन जाता है। `index` पैरेंट फ़ोल्डर से मैप होता है, और डायनैमिक `[param]` सेगमेंट संरक्षित रहते हैं:

| फ़ाइल                     | रूट           |
| ------------------------- | ------------- |
| `pages/pricing.astro`     | `/pricing`    |
| `pages/blog/index.astro`  | `/blog`       |
| `pages/blog/[slug].astro` | `/blog/:slug` |
| `pages/changelog.astro`   | `/changelog`  |

एक ही पाथ पर कस्टम पेज जेनरेट किए गए रूट पर **भारी पड़ता** है। उदाहरण के लिए, `pages/changelog.astro` जोड़ने पर Blume की [जेनरेट की गई चेंजलॉग टाइमलाइन](/docs/advanced/changelog) की जगह आपका अपना पेज आ जाता है।

## साइट डेटा पढ़ना

वही रिज़ॉल्व किया गया कॉन्फ़िग, नेविगेशन, रूट्स और फ़ीड्स पढ़ने के लिए `blume:data` इम्पोर्ट करें जिनका उपयोग बाकी साइट करती है:

```astro pages/all-pages.astro lineNumbers
---
import data from "blume:data";
---

<h1>All pages</h1>
<ul>
  {
    data.routes
      .filter((route) => route.indexable)
      .map((route) => (
        <li>
          <a href={route.path}>{route.title}</a>
        </li>
      ))
  }
</ul>
```

Blume प्रोजेक्ट के भीतर यह मॉड्यूल स्वतः टाइप्ड होता है। आप इसका शेप स्पष्ट रूप से भी ला सकते हैं — टाइप्ड हेल्पर्स, प्रॉप्स, या अपने स्वयं के tsconfig के लिए — `import type { BlumeData } from "blume"` के साथ:

```ts
import type { BlumeData, BlumeRoute } from "blume";

const indexable = (data: BlumeData): BlumeRoute[] =>
  data.routes.filter((route) => route.indexable);
```

यह मॉड्यूल निम्नलिखित उपलब्ध कराता है:

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `BlumeDataConfig` | - | Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host, and the REST api base — null when unset), search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom. |
| `navigation` | `Navigation` | - | The sidebar, tabs, and selectors inferred from your content (default locale). |
| `navigationByLocale` | `Record<string, Navigation>` | - | Per-locale navigation trees, keyed by locale code. Empty unless i18n is configured. |
| `routes` | `BlumeRoute[]` | - | Every content page: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }. |
| `feeds` | `BlumeFeed[]` | - | Generated RSS feeds: { href, title }. |
| `fontCssVars` | `string[]` | - | CSS variable names for the configured fonts (Astro <Font> integration). |
| `ui` | `UIStrings` | - | Resolved UI chrome strings for the default locale (search, sidebar, and footer labels). |
| `uiByLocale` | `Record<string, UIStrings>` | - | Per-locale UI strings, keyed by locale code. Empty unless i18n is configured. |

`routes` पेज मेटाडेटा रखता है, लेकिन `type` या `date` जैसा फ़्रंटमैटर नहीं। कंटेंट टाइप के आधार पर फ़िल्टर की गई सूची बनाने के लिए — जैसे ब्लॉग या चेंजलॉग इंडेक्स — इसे Astro के `docs` कंटेंट कलेक्शन के साथ जोड़ें, जिसमें फ़्रंटमैटर होता है:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

// Each route's id matches its collection entry id.
const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

## रनटाइम हेल्पर्स

`blume/runtime` सामान्य डेटा पैटर्न को बंडल करता है ताकि आपको `blume:data` के आंतरिक हिस्सों तक पहुँचना न पड़े।

**`getBlumeCollection(data, query?)`** कंटेंट रूट्स चुनता है — कलेक्शन, लोकेल, या पाथ प्रीफ़िक्स के आधार पर फ़िल्टर किए हुए, ड्राफ़्ट और छिपे हुए पेज हटाकर और परिणाम पाथ के अनुसार क्रमबद्ध — जो ठीक वही है जिसकी एक कस्टम इंडेक्स को ज़रूरत होती है:

```astro pages/blog/index.astro lineNumbers
---
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const posts = getBlumeCollection(data, { prefix: "/blog" });
---

<ul>
  {posts.map((post) => (
    <li><a href={post.path}>{post.title}</a></li>
  ))}
</ul>
```

**`<BlumePage>`** किसी कंटेंट एंट्री के बॉडी को एक कस्टम पेज के भीतर रेंडर करता है, जिसमें Blume के बिल्ट-इन MDX कंपोनेंट (कॉलआउट, कार्ड, स्टेप्स…) पहले से जुड़े होते हैं — किसी लैंडिंग पेज पर किसी डॉक को प्रस्तुत करने या वास्तविक कंटेंट दिखाने वाला अनुकूलित इंडेक्स बनाने के लिए:

```astro pages/index.astro lineNumbers
---
import BlumePage from "blume/components/BlumePage.astro";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const [intro] = getBlumeCollection(data, { prefix: "/docs" });
---

{intro && <BlumePage id={intro.entryId} />}
```

अपने स्वयं के ओवरराइड या आइलैंड्स (जो जेनरेट किए गए रनटाइम में रहते हैं और डिफ़ॉल्ट रूप से इम्पोर्ट नहीं होते) जोड़ने के लिए `components` पास करें, और `"docs"` के अलावा किसी अन्य कलेक्शन से पढ़ने के लिए `collection` पास करें।

## साइट लेआउट का उपयोग

`RootLayout` एक कस्टम पेज को पूरा डॉक्स क्रोम देता है — हेडर, साइडबार, सर्च, TOC और थीम — उसे उसी 3-कॉलम ग्रिड में लपेटकर जिसका उपयोग जेनरेट किए गए पेज करते हैं। लैंडिंग या मार्केटिंग पेज के लिए वह ग्रिड बाधा बनता है, इसलिए उसकी जगह **`PageLayout`** चुनें: यह डॉक्यूमेंट शेल, हेडर, थीम और फ़ॉन्ट देता है, और फिर एक अकेला पूरी चौड़ाई वाला `<slot />` (न साइडबार, न प्रोज़, न TOC)। एक वैकल्पिक `footer` स्लॉट `<main>` के बाद रेंडर होता है:

```astro pages/index.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
import Footer from "./_home/Footer.astro";

const { config } = data;
---

<PageLayout
  site={{ title: config.title, description: config.description }}
  logo={config.logo}
  banner={config.banner}
  analytics={config.analytics}
  navigation={data.navigation}
  favicon={config.favicon}
  fontCssVars={data.fontCssVars}
  themeMode={config.theme.mode}
  searchEnabled={config.search.enabled}
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  page={{ title: "Acme — the fastest docs", description: config.description }}
>
  <section class="mx-auto max-w-5xl px-6 py-24">
    <h1>Build docs that fly</h1>
  </section>
  <Footer slot="footer" />
</PageLayout>
```

कस्टम पेज को वही हेडर मिलता है जो डॉक्स पेजों को मिलता है, इसलिए उसमें रहने वाला क्रोम भी साथ आता है: सर्च, थीम टॉगल, भाषा स्विचर, और — जब [Ask AI](/docs/configuration/ai) कॉन्फ़िगर हो — Ask AI ट्रिगर। इनमें से किसी को भी प्रति पेज जोड़ने की ज़रूरत नहीं। किसी एक पेज पर Ask ट्रिगर बंद रखने और बाकी हर जगह चालू रखने के लिए `askEnabled={false}` पास करें।

`siteUrl` (और `ogEnabled`) पास करने से पेज का `canonical` और एक जेनरेट किया गया `og:image` स्वतः प्राप्त होता है: Blume हर स्टैटिक कस्टम पेज के लिए एक Open Graph कार्ड रेंडर करता है — होम सहित, जो सबसे अधिक साझा किया जाने वाला URL है — जो `/og/<route>.png` पर सर्व होता है (`/` के लिए `/og/index.png`)। होम कार्ड साइट टाइटल का उपयोग करता है और डिस्क्रिप्शन को आइब्रो के रूप में रखता है; किसी गहरे पेज का शीर्षक उसके अंतिम पाथ सेगमेंट से बनता है। किसी को भी ओवरराइड करने के लिए `ogImage` या `canonical` स्पष्ट रूप से सेट करें। `ogImage` एक रूट-रिलेटिव पाथ लेता है — `public/` में मौजूद कोई फ़ाइल, जो [`deployment.site`](/docs/deployment) के सापेक्ष उस पूर्ण URL में रिज़ॉल्व होती है जिसकी क्रॉलर्स को ज़रूरत होती है — या एक बाहरी URL, जो बिना बदले पास हो जाता है:

```astro pages/index.astro lineNumbers
<PageLayout
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  ogImage="/opengraph-image.png"
  ogImageAlt="Acme — the fastest docs"
  ogImageSize={{ width: 1200, height: 630 }}
  page={{ title: config.title }}
>
  <!-- page content -->
</PageLayout>
```

केवल यही पेज बदलता है — बाकी हर रूट अपना जेनरेट किया गया कार्ड बनाए रखता है — इसलिए इसी तरह आप अकेले होम पेज को एक अनुकूलित शेयर इमेज देते हैं। जेनरेट किया गया कार्ड अपना आकार और ऑल्ट टेक्स्ट क्रॉलर्स को स्वयं घोषित कर देता है; अपने स्वयं के `ogImage` के लिए, साथ में `ogImageAlt` और `ogImageSize` पास करें ताकि शेयर कार्ड को भी वही व्यवहार मिले।

पेज schema.org JSON-LD भी उत्सर्जित करता है — वही `WebSite` ग्राफ़ जो डॉक्स पेज रखते हैं, ताकि होम पेज (जो आमतौर पर एक कस्टम पेज होता है) ऐसा अकेला URL न रह जाए जिसके पास स्ट्रक्चर्ड डेटा न हो। इसे [`structuredData`](/docs/configuration/seo) कॉन्फ़िग के साथ समकालिक रखने के लिए `structuredDataEnabled={config.structuredData}` पास करें, या किसी एक पेज पर इसे बंद करने के लिए `structuredDataEnabled={false}`।

`page.title` का उपयोग डॉक्यूमेंट टाइटल के रूप में ज्यों का त्यों होता है (कोई `- siteTitle` सफ़िक्स नहीं), क्योंकि मार्केटिंग पेज आमतौर पर अपना खुद का सेट करते हैं। इसके बजाय किसी कस्टम पेज को पूरा डॉक्स क्रोम देने के लिए — साइडबार, TOC और सब कुछ — उसे `RootLayout` में लपेटें, वही लेआउट जिसका उपयोग जेनरेट किए गए पेज करते हैं। आवश्यक प्रॉप्स सीधे `blume:data` से लें:

```astro pages/pricing.astro lineNumbers
---
import RootLayout from "blume/components/layout/RootLayout.astro";
import data from "blume:data";
---

<RootLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  banner={data.config.banner}
  navigation={data.navigation}
  page={{ title: "Pricing", route: "/pricing" }}
  headings={[]}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  indexable={true}
>
  <h1>Pricing</h1>
</RootLayout>
```

:::note
`RootLayout` जेनरेट किए गए रनटाइम का हिस्सा है, इसलिए इसके प्रॉप्स रिलीज़ों के बीच बदल सकते हैं। जब आप ऐसा लेआउट चाहते हैं जो पूरी तरह आपका हो, तो [`blume eject`](/docs/configuration/customization#eject) `.blume/` को एक मानक Astro प्रोजेक्ट में बदल देता है जिसके पूर्ण स्वामी आप होते हैं।
:::

## 404 पेज

Blume बॉक्स से बाहर ही एक डिफ़ॉल्ट **not found** पेज देता है: साइट क्रोम (हेडर, सर्च, थीम) में लिपटा एक केंद्रित "404" संदेश, जो किसी भी अमेल URL के लिए सर्व होता है। `blume build` इसे `404.html` में लिखता है, जिसे स्टैटिक होस्ट स्वतः सर्व करते हैं, और `blume dev` इसे अज्ञात रूट्स के लिए दिखाता है। संदेश के नीचे एक **Where to look next** सूची हर टॉप-लेवल सेक्शन को लिंक करती है, साथ ही `sitemap.xml` और [`llms.txt`](/docs/configuration/ai#llmstxt) इंडेक्स भी जब वे मौजूद हों, ताकि किसी पाठक — या किसी पुराने URL का अनुसरण करने वाले एजेंट — के पास लौटने का रास्ता रहे।

इस पेज का एक Markdown जुड़वाँ रूप `/404.md` पर और एक JSON जुड़वाँ रूप `/404.json` पर ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) प्रॉब्लम डिटेल्स) भी है, जिनमें वही रिकवरी लिंक होते हैं ([`deployment.site`](/docs/deployment) सेट होने पर पूर्ण URL के रूप में), साथ ही JSON API चालू होने पर [`openapi.json`](/docs/configuration/ai#json-api) का विवरण भी। किसी [Vercel सर्वर बिल्ड](/docs/deployment#server-rendering) पर, किसी अनुपस्थित पेज के लिए ऐसा अनुरोध जो [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation) भेजता है, या ऐसे `.md` URL की माँग करता है जिसके पीछे कोई पेज नहीं है, उसे HTML शेल के बजाय `404` स्टेटस के साथ Markdown बॉडी मिलती है; और जो `Accept: application/json` भेजता है, या ऐसे `.json` URL की माँग करता है जिसके पीछे कोई फ़ाइल नहीं है, उसे प्रॉब्लम डॉक्यूमेंट मिलता है — ताकि किसी एजेंट को यह जानने के लिए कि आगे कहाँ जाना है, क्रोम से भरा पूरा पेज कभी पार्स न करना पड़े।

इसे अपने पेज से बदलने के लिए, एक `pages/404.astro` जोड़ें। यह `/404` रूट का स्वामी उसी तरह बनता है जैसे `pages/changelog.astro` चेंजलॉग को अपने अधीन ले लेता है — आपका पेज जीतता है और डिफ़ॉल्ट हटा दिया जाता है। इसे किसी भी अन्य कस्टम पेज की तरह बनाएँ, `PageLayout` या `RootLayout` में:

```astro pages/404.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
---

<PageLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  navigation={data.navigation}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  page={{ title: "Page not found", route: "/404" }}
  noindex={true}
>
  <section class="mx-auto max-w-2xl px-6 py-24 text-center">
    <h1>This page took a wrong turn</h1>
    <a href="/">Back to home</a>
  </section>
</PageLayout>
```

डिफ़ॉल्ट डिज़ाइन बनाए रखते हुए केवल उसके शब्द बदलने के लिए — अन्य भाषाओं के लिए भी — `i18n.ui` के ज़रिए `notFound` [UI स्ट्रिंग्स](/docs/content/i18n) (`title`, `description`, `home`) को ओवरराइड करें।

## इंटरैक्टिव पेज

कस्टम पेज सामान्य Astro हैं, इसलिए आप हाइड्रेशन डायरेक्टिव के साथ React (या किसी भी फ़्रेमवर्क) के [आइलैंड्स](/docs/configuration/customization#interactive-islands) रख सकते हैं। जैसे ही आपके प्रोजेक्ट में कोई `.tsx` या `.jsx` फ़ाइल होती है, React स्वतः चालू हो जाता है।

**[Customization](/docs/configuration/customization)**

कंपोनेंट ओवरराइड, React आइलैंड्स, रजिस्ट्री और eject।

**[Blog](/docs/advanced/blog)**

पोस्ट लिखें और एक कस्टम ब्लॉग इंडेक्स बनाएँ।

---

# GraphQL
Source: https://useblume.dev/hi/docs/advanced/graphql

Blume को एक GraphQL स्कीमा की ओर इंगित करें और यह एक नेटिव API संदर्भ तैयार करता है: **प्रति रूट फ़ील्ड एक वास्तविक पेज** — क्वेरीज़, म्यूटेशन्स और सब्सक्रिप्शन्स — साथ ही **प्रति नामित टाइप एक पेज** (ऑब्जेक्ट्स, इनपुट ऑब्जेक्ट्स, एनम्स, इंटरफ़ेस, यूनियन और कस्टम स्केलर)। हर पेज तर्क (arguments), डिफ़ॉल्ट, अप्रचलन (deprecations) और उपयोग बैकलिंक दिखाता है, साथ ही एक जनरेट किया गया उदाहरण ऑपरेशन, कोड नमूने और एक इंटरैक्टिव [Try it](#try-it-playground) पैनल भी। चूँकि हर पेज एक वास्तविक Blume पेज है, इसे अपना स्वयं का URL मिलता है, यह **साइट खोज** और `llms.txt` में दिखाई देता है, और इसे एक Open Graph छवि मिलती है — ठीक वैसे ही जैसे किसी भी हाथ से लिखे दस्तावेज़ को।

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
}
```

यह संदर्भ को `/graphql` पर माउंट करता है (एक अवलोकन पेज), जिसमें रूट फ़ील्ड `/graphql/queries/<field>`, `/graphql/mutations/<field>` और `/graphql/subscriptions/<field>` पर होते हैं, और टाइप्स प्रकार के अनुसार `/graphql/objects/<type>`, `/graphql/enums/<type>` इत्यादि पर समूहीकृत होते हैं।

`spec` या तो आपके प्रोजेक्ट में किसी स्थानीय फ़ाइल का पथ होता है या एक `http(s)` URL, और यह दो प्रारूप स्वीकार करता है:

- **SDL टेक्स्ट** — टाइप परिभाषाओं वाली एक `.graphql` फ़ाइल।
- **एक इंट्रोस्पेक्शन परिणाम** — मानक इंट्रोस्पेक्शन क्वेरी चलाने से उत्पन्न JSON, या तो कच्चे `{ "__schema": … }` स्वरूप में या पूर्ण `{ "data": { "__schema": … } }` रेस्पॉन्स एन्वेलप के रूप में।

`endpoint` लाइव GraphQL API का URL है। एक स्कीमा, OpenAPI दस्तावेज़ के विपरीत, किसी सर्वर का नाम नहीं देती — इसलिए एंडपॉइंट ही वह लक्ष्य है जिसे Try it पैनल और जनरेट किए गए कोड नमूने उपयोग करते हैं। इसे छोड़ दें और नमूने एक प्लेसहोल्डर URL के साथ रेंडर होंगे जिसे पाठक बदल सकते हैं।

यह संदर्भ स्वयं कोई हेडर टैब नहीं जोड़ता। इसे सामने लाने के लिए, किसी [नेविगेशन टैब](/docs/content/navigation#tabs) को उसके रूट की ओर इंगित करें — इससे संदर्भ साइडबार का दायरा भी निर्धारित होता है:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}
```

## जनरेट किए गए उदाहरण

हर ऑपरेशन पेज में एक संपूर्ण, वैध उदाहरण ऑपरेशन होता है — प्रति तर्क एक वेरिएबल, स्कीमा के अनुसार टाइप किया हुआ, रिटर्न टाइप पर एक सीमित-गहराई वाले सिलेक्शन सेट के साथ — साथ ही मेल खाते उदाहरण वेरिएबल और एक उदाहरण रेस्पॉन्स जो उसी सिलेक्शन को प्रतिबिंबित करता है। कोड नमूने हर कॉन्फ़िगर की गई भाषा में सटीक HTTP अनुरोध (`{ query, variables }` का एक JSON `POST`) दिखाते हैं:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  codeSamples: ["curl", "js"],   // built in: curl, js, python
}
```

## टाइप पेज

नामित टाइप्स को अपने स्वयं के डीप-लिंक करने योग्य पेज मिलते हैं, जो साइडबार में प्रकार के अनुसार समूहीकृत होते हैं: फ़ील्ड और इनपुट फ़ील्ड अपने लिंक किए गए टाइप्स के साथ, एनम मान, यूनियन सदस्य, इंटरफ़ेस कार्यान्वयन, और एक **Used by** अनुभाग जिसमें वे ऑपरेशन सूचीबद्ध होते हैं जो उस टाइप को लौटाते या स्वीकार करते हैं तथा वे अन्य टाइप्स जो उसका संदर्भ देते हैं। स्पेक-परिभाषित स्केलर (`String`, `Int`, …) को पेज नहीं मिलते; कस्टम स्केलर को मिलते हैं, उनके `specifiedBy` URL सहित।

## एकाधिक स्कीमा

`sources` की प्रत्येक प्रविष्टि एक स्कीमा को उसके अपने रूट पर रेंडर करती है। प्रति-स्रोत `endpoint` ब्लॉक-स्तरीय एंडपॉइंट को ओवरराइड करता है:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  endpoint: "https://api.example.com/graphql",
  sources: [
    { label: "Public API", spec: "./schema.graphql" },
    {
      label: "Admin API",
      route: "/graphql-admin",
      spec: "./admin.graphql",
      endpoint: "https://admin.example.com/graphql",
    },
  ],
}
```

प्रत्येक स्रोत वही [प्रति-स्रोत नियंत्रण](/docs/advanced/api-reference#per-source-indexing) लेता है जो OpenAPI ब्लॉक लेता है: `includeInSearch`, `includeInLlms`, `noindex` और `seoDescriptionSuffix` (यहाँ जनरेट किया गया वाक्य क्वेरी, म्यूटेशन या टाइप का नाम लेता है — "Reference for the `pets` query in the GraphQL API.")।

## Try it प्लेग्राउंड

क्वेरी और म्यूटेशन पेज एक इंटरैक्टिव पैनल रेंडर करते हैं: अनुरोध बॉडी (क्वेरी और वेरिएबल) संपादित करें, इसे अपने एंडपॉइंट या किसी कस्टम URL की ओर इंगित करें, और भेजें — कोड नमूने लाइव अपडेट होते हैं ताकि आप जो कॉपी करें वह बाइट-दर-बाइट वही हो जो भेजा गया था। इसे `playground: false` से अक्षम करें। सब्सक्रिप्शन पेज इसके बजाय जनरेट किया गया ऑपरेशन और एक उदाहरण इवेंट दिखाते हैं: सब्सक्रिप्शन एक स्टेटफ़ुल ट्रांसपोर्ट (WebSocket या SSE) पर चलते हैं, जिसे प्लेग्राउंड का एकल HTTP `POST` नहीं समझ सकता।

यदि आपका GraphQL API डॉक्स साइट से क्रॉस-ऑरिजिन अनुरोधों की अनुमति नहीं देता, तो सेंड को एक CORS प्रॉक्सी के माध्यम से रूट करें — अपना कोई URL, या अंतर्निर्मित `/_api-proxy` एंडपॉइंट के लिए `true` (जिसके लिए `deployment.output: "server"` आवश्यक है)। अंतर्निर्मित प्रॉक्सी केवल उन्हीं ऑरिजिन्स पर अग्रेषित करता है जिन्हें आपकी प्रलेखित स्पेक्स घोषित करती हैं — प्रत्येक कॉन्फ़िगर किया गया GraphQL `endpoint`, साथ ही किसी प्रलेखित [OpenAPI स्पेक](/docs/advanced/api-reference) से कोई भी निरपेक्ष `servers[].url` — ताकि एक सार्वजनिक डॉक्स डिप्लॉयमेंट को अन्य होस्ट्स की ओर लक्षित न किया जा सके। इससे कार्यशील प्रॉक्सी के लिए `endpoint` आवश्यक हो जाता है: इसके बिना, प्रॉक्सी के पास इस संदर्भ के लिए अनुमति देने योग्य कोई ऑरिजिन नहीं होता और वह हर सेंड को अस्वीकार कर देता है (बिल्ड इस बारे में चेतावनी देता है)।

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
  playground: { proxy: true },
}
```

---

# स्किल्स
Source: https://useblume.dev/hi/docs/advanced/skills

Blume [एजेंट स्किल्स](https://docs.claude.com/en/docs/claude-code/skills) के साथ आता है — ऐसे प्लेबुक जो किसी कोडिंग एजेंट (Claude Code, Codex, Cursor) को यह सिखाते हैं कि Blume से जुड़ा काम कैसे किया जाए, बिना आपके समझाए। ये GitHub पर रिपॉज़िटरी के `skills/` फ़ोल्डर में रहते हैं और इंस्टॉल किए गए पैकेज में `skills/` के अंतर्गत बंडल किए जाते हैं, इसलिए किसी भी एजेंट को सीधे `SKILL.md` की ओर इंगित किया जा सकता है।

## Blume

मुख्य स्किल। यह एजेंट को सिखाती है कि Blume क्या है और किसी साइट को कैसे स्कैफ़ोल्ड करना, लिखना और कॉन्फ़िगर करना है — फ़ाइलसिस्टम से व्युत्पन्न नेविगेशन, कॉन्फ़िग स्कीमा, कंटेंट कंपोनेंट्स — और इसे इंस्टॉल किए गए पैकेज में बंडल किए गए पूरे डॉक्स की ओर इंगित करती है (`blume` के भीतर की `docs/` डायरेक्टरी, जो वहीं से रिज़ॉल्व होती है जहाँ आपका पैकेज मैनेजर इसे इंस्टॉल करता है — pnpm मोनोरेपो में वह डिपेंडिंग वर्कस्पेस का `node_modules` होता है, रिपॉज़िटरी की रूट नहीं)। इसे किसी भी ऐसे प्रोजेक्ट में इंस्टॉल करें जहाँ कोई एजेंट आपके डॉक्स बनाने में मदद करता है:

```bash
npx skills add haydenbleasel/blume
```

## स्वयं-अपडेट होने वाले डॉक्स

`blume-update-docs` आपके डॉक्स को उस प्रोडक्ट के साथ सिंक में रखता है जिसका वे दस्तावेज़ीकरण करते हैं। हर रन पर — आमतौर पर आपके एजेंट रनर में कॉन्फ़िगर किए गए शेड्यूल से — यह हाल ही में मर्ज हुए PR, चेंजलॉग, कॉन्फ़िग स्कीमा और CLI हेल्प का डॉक्स कंटेंट के साथ ऑडिट करता है, केवल उन्हीं पेजों को अपडेट करता है जो तथ्यात्मक रूप से पुराने पड़ चुके हैं (फ़ीचर-फ़्लैग किए गए काम को नज़रअंदाज़ किया जाता है), `blume build` से सत्यापित करता है, और एक `blume/*` पुल रिक्वेस्ट खोलता या अपडेट करता है। अगर कुछ भी बदला नहीं है, तो यह शोरगुल वाला PR खोलने के बजाय एक साफ़ नो-ऑप रिपोर्ट करता है।

```bash
npx skills add haydenbleasel/blume --skill blume-update-docs
```

Blume इस ऑटोमेशन को होस्ट नहीं करता — इस स्किल को Claude Code में किसी शेड्यूल्ड टास्क, Codex या Cursor ऑटोमेशन, या साधारण cron से जोड़ें, और उसे रिपॉज़िटरी इतिहास पढ़ने तथा PR खोलने की अनुमति दें। एक सामान्य साप्ताहिक प्रॉम्प्ट:

```text
Use the blume-update-docs skill. Review the PRs merged within the last 7 days and compare them to the docs content. Ignore work behind feature flags. If docs need updates, make them, verify the docs build, and open a blume/* PR. If not, report what you checked and do not open a PR.
```

---

# कॉन्फ़िगरेशन फ़ाइल
Source: https://useblume.dev/hi/docs/configuration

Blume आपके प्रोजेक्ट रूट से `blume.config.ts` पढ़ता है। ऑटोकम्पलीट और टाइप-चेकिंग के लिए अपने कॉन्फ़िग को `defineConfig` में लपेटें — हर फ़ील्ड वैकल्पिक है, और उसका एक समझदार डिफ़ॉल्ट होता है।

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});
```

## एक सम्पूर्ण उदाहरण

सबसे आम विकल्पों को छूता हुआ एक व्यापक उदाहरण (बाकी के लिए हर फ़ीचर की गाइड देखें):

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [sitemap()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — see the Search guide
  search: {
    provider: "orama",
  },

  // Markdown features
  markdown: {
    imageZoom: true,
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
    },
    codeBlocks: {
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // AI — see the AI guide
  ai: {
    llmsTxt: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — see the Deployment guide
  deployment: {
    output: "static",
    site: "https://docs.example.com",
  },
});
```

## साइट

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `title` | `"Documentation"` | साइट का नाम — हेडर, पेज शीर्षकों और OG कार्ड्स में दिखता है। |
| `description` | — | डिफ़ॉल्ट मेटा विवरण, जो SEO और OG के लिए उपयोग होता है। |
| `logo` | — | हेडर में दिखने वाला ब्रांड चिह्न और/या वर्डमार्क। |
| `banner` | — | हेडर के ऊपर साइट-व्यापी घोषणा पट्टी। |

### लोगो

`logo` को किसी SVG की ओर इंगित करें और Blume उसे इनलाइन कर देता है, जिससे `currentColor` वाला लोगो अपने आप लाइट और डार्क थीम का अनुसरण करता है:

```ts blume.config.ts
logo: "/logo.svg",
```

SVG आपके प्रोजेक्ट रूट में या `public/` में रह सकता है। ब्रांड एक चिह्न (`image`) और एक वर्डमार्क (`text`) से बनता है; ऑब्जेक्ट रूप आपको इन्हें अलग-अलग सेट करने देता है:

```ts blume.config.ts lineNumbers
logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},
```

`image` वही मान लेता है जो शॉर्टहैंड लेता है — एक अकेला पाथ, या अलग-अलग लाइट/डार्क आर्टवर्क के लिए `{ light, dark, alt }` (रास्टर इमेज `public/` में ही होनी चाहिए)।

`text` वर्डमार्क को चिह्न से स्वतंत्र रूप से नियंत्रित करता है:

- **`text` को छोड़ दें** और ब्रांड आपकी साइट के `title` का उपयोग करेगा (डिफ़ॉल्ट)।
- **`text: ""` सेट करें** ताकि केवल चिह्न दिखे — तब उपयोगी जब लोगो इमेज में पहले से ही वर्डमार्क शामिल हो।
- **`image` के बिना `text` सेट करें** केवल-टेक्स्ट वाले लोगो के लिए।

### फ़ेविकॉन

कोई फ़ेविकॉन विकल्प नहीं है — Blume उसे फ़ाइलनाम से अपने आप पहचान लेता है, ठीक वैसे ही जैसे Next.js करता है। अपने प्रोजेक्ट रूट या `public/` डायरेक्टरी में एक `icon` या `favicon` फ़ाइल (`.svg`, `.png`, या `.ico`) रखें और वह ब्राउज़र टैब का आइकॉन बन जाती है:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/
```

जब कई मौजूद हों, तो SVG की प्राथमिकता PNG से ऊपर और PNG की ICO से ऊपर होती है, और `public/` की फ़ाइल को रूट वाली फ़ाइल पर वरीयता मिलती है। अगर Blume को कोई आइकॉन नहीं मिलता, तो वह अपने ही चिह्न पर लौट आता है।

गहरे रंग का चिह्न डार्क ब्राउज़र क्रोम के सामने ग़ायब हो जाता है, इसलिए आप डार्क मोड के लिए एक दूसरी फ़ाइल भेज सकते हैं। अपनी आइकॉन फ़ाइल का एक `-dark` सहोदर जोड़ें — वही नाम और वही डायरेक्टरी, एक्सटेंशन से पहले `-dark` के साथ (`icon.png` → `icon-dark.png`) — और Blume दोनों आइकॉन एक `prefers-color-scheme` मीडिया क्वेरी के पीछे उत्सर्जित करता है, साथ ही उन ब्राउज़रों और क्रॉलरों के लिए एक सादा लाइट टैग भी जो आइकॉन पर मीडिया क्वेरीज़ को अनदेखा करते हैं:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/
```

केवल उसी आइकॉन के सहोदर का उपयोग होता है जिसे Blume ने चुना है — किसी अलग नाम वाली `-dark` फ़ाइल अनदेखी ही रहती है, इसलिए कोई असंबंधित फ़ाइल ग़लती से आपके चिह्न के साथ नहीं जुड़ सकती। डार्क फ़ाइल वैकल्पिक है; केवल एक आइकॉन होने पर Blume पहले की तरह एक ही टैग उत्सर्जित करता है। Blume का अपना फ़ॉलबैक चिह्न दोनों वैरिएंट के साथ आता है।

### Apple टच आइकॉन

जब कोई आपकी साइट को अपनी होम स्क्रीन पर जोड़ता है तो iOS जिस आइकॉन का उपयोग करता है, उसे भी इसी तरह पहचाना जाता है। अपने प्रोजेक्ट रूट या `public/` डायरेक्टरी में एक `apple-icon` फ़ाइल (`.png`, `.jpg`, या `.jpeg`) — या `apple-touch-icon.png`, वह नाम जो ज़्यादातर फ़ेविकॉन जेनरेटर बनाते हैं — रखें और Blume आपके लिए `<link rel="apple-touch-icon">` जोड़ देता है। कोई डिफ़ॉल्ट नहीं है; अगर कोई फ़ाइल नहीं मिलती, तो कोई टैग नहीं निकाला जाता।

```
my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/
```

फ़ाइल को प्रोजेक्ट रूट के बजाय `public/` में रखें: रूट-स्तर के आइकॉन के लिए Blume जिस इनलाइन डेटा URI का उपयोग करता है, iOS उसे अनदेखा कर देता है, इसलिए केवल `public/` की फ़ाइल (जो `/apple-icon.png` पर सर्व होती है) ही भरोसेमंद तरीके से होम स्क्रीन तक पहुँचती है। फ़ेविकॉन के विपरीत, यहाँ कोई `-dark` सहोदर नहीं है — iOS होम-स्क्रीन आइकॉन पर मीडिया क्वेरीज़ को अनदेखा करता है, इसलिए कोई डार्क वैरिएंट कभी सर्व किया ही नहीं जा सकता।

### बैनर

हेडर के ऊपर साइट-व्यापी घोषणा पट्टी दिखाएँ। एक स्ट्रिंग पास करें, या एक लिंक और डिसमिस बटन वाला ऑब्जेक्ट:

```ts blume.config.ts
banner: "Docs are in beta — expect changes.",
```

```ts blume.config.ts lineNumbers
banner: {
  content: "Blume v1 is here!",
  link: { text: "Read more", href: "/blog/v1" },
  dismissible: true,
  id: "v1",
},
```

जब `dismissible` चालू होता है, तो पट्टी एक क्लोज़ बटन दिखाती है और उसके बाद उस विज़िटर के लिए छिपी रहती है। डिसमिस की कुंजी डिफ़ॉल्ट रूप से कंटेंट टेक्स्ट होती है, इसलिए संदेश संपादित करने पर बैनर वापस आ जाता है; संपादनों के बाद भी उसे डिसमिस बनाए रखने के लिए एक स्थिर `id` सेट करें।

## कंटेंट

आपका कंटेंट कहाँ रहता है और Blume उसे कैसे खोजता है। फ़ाइलें रूट्स कैसे बनती हैं, इसके लिए [पेज](/docs/content) देखें।

```ts blume.config.ts lineNumbers
content: {
  root: "docs",
}
```

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `root` | `"docs"` | वह फ़ोल्डर जिसे Blume कंटेंट के लिए स्कैन करता है। |
| `include` | `["**/*.{md,mdx}"]` | वे ग्लोब्स जो कंटेंट फ़ाइलों से मेल खाते हैं। |
| `exclude` | `["**/_*", "**/.*"]` | नज़रअंदाज़ करने के लिए ग्लोब्स (अंडरस्कोर- और डॉट-फ़ाइलें)। |
| `pages` | `"pages"` | कस्टम `.astro` पेजों के लिए फ़ोल्डर। |
| `defaultType` | `"doc"` | जब फ़्रंटमैटर में `type` न हो तो उपयोग किया जाने वाला पेज `type`। |
| `types` | `{}` | प्रति-प्रकार कंटेंट परिभाषाएँ — कस्टम फ़्रंटमैटर कुंजियाँ जो एक ही `type` वाले पेजों तक सीमित होती हैं। [फ़्रंटमैटर](#frontmatter) देखें। |

स्टैटिक एसेट्स `public/` में रहती हैं — `public/logo.png` पर मौजूद फ़ाइल `/logo.png` पर सर्व होती है, इसलिए `![](/images/create.png)` जैसा संदर्भ `public/images/create.png` के सापेक्ष हल होता है। **सापेक्ष पाथ** से संदर्भित इमेज (`![](./diagram.png)`) इसके बजाय आपके कंटेंट के बगल में रहती हैं, और [बिल्ड समय पर ऑप्टिमाइज़](/docs/content/syntax#links-and-images) की जाती हैं।

## इमेज

सापेक्ष पाथ से संदर्भित लोकल इमेज बिल्ड समय पर अपने आप ऑप्टिमाइज़ हो जाती हैं — कंप्रेस की जाती हैं, WebP में बदली जाती हैं, और उन्हें अंतर्निहित `width`/`height` एट्रिब्यूट्स दिए जाते हैं ताकि लोड होते समय लेआउट न खिसके। कॉन्फ़िगर करने को कुछ नहीं है; लेखन संबंधी मार्गदर्शन के लिए [लिंक और इमेज](/docs/content/syntax#links-and-images) देखें।

रिमोट इमेज डिफ़ॉल्ट रूप से बिना छेड़े सर्व की जाती हैं। Blume उन्हें भी बिल्ड समय पर डाउनलोड और ऑप्टिमाइज़ करे, इसके लिए उनके होस्ट्स को अधिकृत करें:

```ts blume.config.ts lineNumbers
image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}
```

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `domains` | `[]` | वे होस्टनेम जिनकी रिमोट इमेज ऑप्टिमाइज़ की जा सकती हैं। |
| `remotePatterns` | `[]` | पैटर्न-आधारित प्राधिकरण (`protocol`, `hostname`, `port`, `pathname`); होस्टनेम `*.` (एक स्तर) और `**.` (किसी भी गहराई) वाइल्डकार्ड स्वीकार करते हैं। |

## फ़्रंटमैटर

पेज फ़्रंटमैटर की सख़्ती से जाँच होती है — कोई अनजान कुंजी बिल्ड को विफल कर देती है, इसलिए टाइपो जल्दी पकड़ में आ जाते हैं। प्रोजेक्ट-विशिष्ट मेटाडेटा (एक ओनर, एक समीक्षा तिथि) रखने के लिए, अतिरिक्त कुंजियों को `frontmatter.extend` के अंतर्गत घोषित करें, हर एक को आपके द्वारा दिए गए स्कीमा से मैप करके:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

कोई भी [Standard Schema](https://standardschema.dev) लाइब्रेरी काम करती है — Zod (आपका प्रोजेक्ट जो भी संस्करण इंस्टॉल करे), Valibot, ArkType। एक्सटेंशन से बाहर की कुंजियाँ सख़्ती से जाँची जाती रहती हैं, इसलिए टाइपो पकड़ने में कोई बदलाव नहीं आता। जाँच के अर्थ-नियमों के लिए [कस्टम कुंजियाँ](/docs/reference/frontmatter#custom-keys) देखें।

`extend` के अंतर्गत दी गई कुंजियाँ साइट-व्यापी लागू होती हैं। कुंजियों को केवल एक कंटेंट प्रकार के पेजों पर आवश्यक बनाने के लिए — किसी RFC का `status`, किसी रनबुक का `service` — उन्हें इसके बजाय `content.types` के अंतर्गत प्रति-प्रकार घोषित करें:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

कोई कुंजी या तो साइट-व्यापी घोषित की जा सकती है या प्रति-प्रकार, दोनों नहीं। स्कोपिंग कैसे हल होती है, इसके लिए [प्रति-प्रकार कुंजियाँ](/docs/reference/frontmatter#per-type-keys) देखें।

`facets` उन कस्टम कुंजियों के नाम देता है जिनके मान फ़िल्टर करने योग्य मेटाडेटा बन जाते हैं: वे खोज दस्तावेज़ों (`blume-search.json` और MCP इंडेक्स) के साथ चलती हैं, और [MCP टूल्स](/docs/configuration/ai#mcp-server) एक `filters` इनपुट स्वीकार करते हैं जो उनसे मेल खाता है, ताकि कोई एजेंट, मान लीजिए, `architecture` डोमेन में केवल `enforced` RFC ही प्राप्त कर सके। हर फ़ैसेट एक घोषित कस्टम कुंजी होनी चाहिए — प्रति-प्रकार या साइट-व्यापी — और केवल स्ट्रिंग (या स्ट्रिंग में बदले गए संख्या/बूलियन) मान ही फ़ैसेट बनते हैं।

## GitHub

`github` के ज़रिए Blume को अपनी रिपॉज़िटरी की ओर इंगित करें। यह हेडर के [रिपॉज़िटरी लिंक](/docs/content/navigation#repository-link) और **Edit on GitHub** तथा **Give feedback** [पेज एक्शन](/docs/content/navigation#page-actions) को संचालित करता है:

```ts blume.config.ts lineNumbers
github: {
  owner: "acme",
  repo: "docs",
}
```

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `owner` | — | वह GitHub अकाउंट या संगठन जिसके पास रिपॉज़िटरी है। |
| `repo` | — | रिपॉज़िटरी का नाम। |
| `branch` | `"main"` | वह ब्रांच जिस पर एडिट लिंक इंगित करते हैं। |
| `dir` | — | रिपो रूट से प्रोजेक्ट रूट तक का पाथ (मोनोरिपो के लिए)। |
| `host` | `"https://github.com"` | Enterprise इंस्टॉलेशनों के लिए, GitHub इंस्टेंस का ऑरिजिन। HTTP(S) होना चाहिए; उसके ऑरिजिन में सामान्यीकृत किया जाता है। |
| `api` | `host` से व्युत्पन्न | REST API बेस, किसी Enterprise इंस्टेंस के विरुद्ध `<GithubInfo>` के लिए। HTTP(S) होना चाहिए; एक ऑरिजिन और पाथ में सामान्यीकृत किया जाता है। |

### GitHub Enterprise

जिन दस्तावेज़ों की रिपॉज़िटरी किसी GitHub Enterprise इंस्टेंस पर रहती है, वे `host` सेट करते हैं, और रिपो से निकला हर लिंक — हेडर का चिह्न, एडिट लिंक, एजेंट मैनिफ़ेस्ट — सार्वजनिक साइट के बजाय उसी इंस्टेंस की ओर इंगित करता है:

```ts blume.config.ts lineNumbers
github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}
```

[`<GithubInfo>`](/docs/content/components) जिस REST API बेस से क्वेरी करता है, वह `host` से व्युत्पन्न होता है: डेटा रेज़िडेंसी वाला Enterprise Cloud टेनेंट (`acme.ghe.com`) अपने `api.` सबडोमेन से सर्व होता है, और किसी भी अन्य होस्ट को Enterprise Server (`/api/v3`) माना जाता है। जब आपका इंस्टेंस कहीं और स्थित हो, तो `api` को स्पष्ट रूप से सेट करें।

:::warning
जो इंस्टेंस केवल सादे HTTP पर पहुँच योग्य है, वह अपनी गिनतियाँ फिर भी रेंडर करता है, लेकिन `GITHUB_TOKEN` को अनुरोध में सादे पाठ में भेजने के बजाय रोक लिया जाता है — इसलिए किसी निजी रिपो का कार्ड उनके बिना ही लौटता है।
:::

:::note
`host` उन लिंक्स को कवर करता है जिन्हें Blume `github` से व्युत्पन्न करता है। केवल हेडर के चिह्न को कहीं और इंगित करने के लिए — मान लीजिए किसी संगठन की ओर, जब दस्तावेज़ों की रिपो स्वयं निजी हो — एक निरपेक्ष URL के साथ [`navigation.repo`](/docs/content/navigation#repository-link) का उपयोग करें।
:::

## अंतिम बार संशोधित

हर पेज के नीचे "Last updated on …" पंक्ति दिखाएँ। डिफ़ॉल्ट रूप से बंद; हर पेज की तिथि उसके git इतिहास से निकालने के लिए `lastModified` को `true` सेट करें:

```ts blume.config.ts
lastModified: true,
```

| मान | विवरण |
| --- | --- |
| `false` | अक्षम (डिफ़ॉल्ट)। |
| `true` | तिथि git इतिहास (कमिट तिथियों) से पढ़ें। |
| `{ type: "git" }` | `true` जैसा ही, स्पष्ट रूप से लिखा हुआ। |
| `{ type: "frontmatter" }` | git कभी न चलाएँ — केवल `lastModified` फ़्रंटमैटर फ़ील्ड का उपयोग करें। |

git स्रोत हर फ़ाइल को छूने वाला सबसे हालिया कमिट पढ़ता है, इसलिए यह किसी भी git रिपॉज़िटरी में काम करता है — मोनोरिपो सहित — और बिल्ड समय पर रिपो का इतिहास चाहिए। CI प्लेटफ़ॉर्म आम तौर पर उथला (shallow) क्लोन चेकआउट करते हैं, जो चुपचाप ज़्यादातर तिथियाँ गिरा देता है (ऐसा होने पर बिल्ड `BLUME_SHALLOW_GIT_HISTORY` के साथ चेतावनी देता है): Vercel पर `VERCEL_DEEP_CLONE=true` एनवायरनमेंट वेरिएबल सेट करें; `actions/checkout` के साथ `fetch-depth: 0` सेट करें। पेज का अपना `lastModified` फ़्रंटमैटर हमेशा जीतता है, जो किसी तिथि को पिन करने या अभी तक कमिट न हुई फ़ाइलों के लिए उपयोगी है:

```mdx page.mdx
---
title: My page
lastModified: 2026-06-20
---
```

सक्षम होने पर, तिथि पेज के स्ट्रक्चर्ड डेटा में schema.org `dateModified` के रूप में भी उत्सर्जित होती है।

## तिथि प्रारूप

"Last updated" स्टैम्प और [चेंजलॉग](/docs/advanced/changelog) टाइमलाइन दोनों अपनी तिथियाँ एक ही `dateFormat` के ज़रिए रेंडर करते हैं, ताकि वे एक जैसी पढ़ी जाएँ। तिथियाँ हमेशा साइट की लोकेल में रेंडर होती हैं; `dateFormat` उनका _स्वरूप_ नियंत्रित करता है। यह डिफ़ॉल्ट रूप से लंबे रूप में होता है (`July 21, 2026`, `2026年7月21日`):

```ts blume.config.ts
dateFormat: { dateStyle: "long" },
```

`dateFormat` [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) विकल्पों के लिए एक पास-थ्रू है। किसी लंबाई के लिए `dateStyle` प्रीसेट का उपयोग करें:

```ts blume.config.ts
dateFormat: { dateStyle: "medium" },
```

या `2026/07/21` जैसी संख्यात्मक शैली के लिए अलग-अलग घटक फ़ील्ड्स:

```ts blume.config.ts
dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
```

| विकल्प | विवरण |
| --- | --- |
| `dateStyle` | प्रीसेट लंबाई: `"full"`, `"long"`, `"medium"`, या `"short"`। घटक फ़ील्ड्स के साथ नहीं जोड़ा जा सकता। |
| `weekday`, `era`, `year`, `month`, `day` | अलग-अलग घटक, जैसे `year: "numeric"`, `month: "2-digit"`। |
| `timeZone` | IANA टाइम ज़ोन। डिफ़ॉल्ट `UTC` है, ताकि साइट कहीं भी बिल्ड हो, तिथि एक जैसी पढ़ी जाए। |
| `calendar`, `numberingSystem` | कैलेंडर प्रणाली (जैसे `"japanese"`) और अंक प्रणाली (जैसे `"arab"`)। |

## SEO

Open Graph इमेज, RSS फ़ीड्स, और JSON-LD स्ट्रक्चर्ड डेटा, `seo` के अंतर्गत समूहित। मेटाडेटा, फ़्रंटमैटर ओवरराइड्स, और पूरे संदर्भ के लिए [SEO गाइड](/docs/configuration/seo) देखें।

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}
```

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `og.enabled` | ऑटो | प्रति-पेज Open Graph इमेज — साइट URL सेट होने पर चालू। |
| `rss.enabled` | `true` | ब्लॉग और चेंजलॉग कंटेंट के लिए फ़ीड्स बनाएँ। |
| `rss.types` | `["blog", "changelog"]` | वे कंटेंट प्रकार जिन्हें अपनी-अपनी फ़ीड मिलती है। |
| `rss.limit` | `50` | प्रति फ़ीड अधिकतम आइटम। |
| `sitemap` | `true` | sitemap.xml बनाएँ (deployment.site चाहिए)। |
| `robots` | `true` | Sitemap लिंक के साथ robots.txt बनाएँ। |
| `structuredData` | `true` | हर पेज के हेड में schema.org JSON-LD उत्सर्जित करें। |

ये पूर्ण URL के लिए एक निरपेक्ष [`deployment.site`](/docs/deployment) के साथ सबसे अच्छा काम करते हैं।

## विषय-सूची

इस-पेज-पर वाली रूपरेखा डिफ़ॉल्ट रूप से चालू रहती है और `H2`–`H3` शीर्षकों को सूचीबद्ध करती है। `toc` के साथ इसे बंद करें, या शीर्षक-सीमा बदलें:

```ts blume.config.ts
export default defineConfig({
  toc: false, // hide it everywhere
});
```

या इसके बजाय शीर्षक-सीमा को संकीर्ण करें:

```ts blume.config.ts
export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});
```

## फ़ीचर विकल्प

इनमें से हर एक की अपनी गाइड है। कॉन्फ़िग फ़ील्ड प्रवेश-बिंदु है:

| फ़ील्ड | यह क्या कॉन्फ़िगर करता है | गाइड |
| --- | --- | --- |
| `theme` | एक्सेंट रंग, कोने की त्रिज्या, फ़ॉन्ट्स, लाइट/डार्क मोड | [थीमिंग](/docs/configuration/theming) |
| `navigation` | स्पष्ट साइडबार और हेडर टैब्स | [नेविगेशन](/docs/content/navigation) |
| `search` | प्रोवाइडर (Orama, Pagefind, Algolia, और अन्य) और इंडेक्सिंग | [खोज](/docs/configuration/search) |
| `markdown` | मार्कडाउन रेंडरिंग विकल्प — कोड ब्लॉक्स, हेडिंग एंकर, इमेज ज़ूम | [सिंटैक्स](/docs/content/syntax) |
| `ai` | `llms.txt`, Ask AI, और कोडिंग एजेंट्स के लिए होस्टेड MCP सर्वर | [AI](/docs/configuration/ai) |
| `analytics` | Vercel, PostHog, और कस्टम स्क्रिप्ट्स | [एनालिटिक्स](/docs/configuration/analytics) |
| `seo` | मेटाडेटा, OG इमेज, फ़ीड्स, स्ट्रक्चर्ड डेटा | [SEO](/docs/configuration/seo) |
| `deployment` | आउटपुट मोड, अडैप्टर, और साइट URL | [डिप्लॉयमेंट](/docs/deployment) |
| `redirects` | स्थायी और अस्थायी रीडायरेक्ट्स | [डिप्लॉयमेंट](/docs/deployment#redirects) |
| `integrations` | Blume के अंतर्निर्मित इंटीग्रेशन के बाद जोड़े गए Astro इंटीग्रेशन | [कस्टमाइज़ेशन](/docs/configuration/customization#astro-integrations) |

## प्राथमिकता

सेटिंग्स सबसे कम से सबसे अधिक प्राथमिकता के क्रम में हल होती हैं, इसलिए आपको केवल वही ओवरराइड करना पड़ता है जिसकी ज़रूरत हो:

1. **Blume डिफ़ॉल्ट्स**

    हर फ़ील्ड के लिए एक समझदार डिफ़ॉल्ट।

2. **blume.config.ts**

    आपका प्रोजेक्ट-व्यापी कॉन्फ़िगरेशन।

3. **फ़ोल्डर मेटा**

    किसी सेक्शन के शीर्षक और क्रम के लिए [`meta.ts`](/docs/content/meta)।

4. **पेज फ़्रंटमैटर**

    प्रति-पेज ओवरराइड्स जीतते हैं।

---

# AI
Source: https://useblume.dev/hi/docs/configuration/ai

Blume में कुछ AI सुविधाएँ हैं: बाहरी टूल्स के लिए मशीन-पठनीय डॉक्स (`llms.txt` और एक OpenAPI विवरण के साथ एक [JSON API](#json-api), दोनों डिफ़ॉल्ट रूप से चालू), एक इन-पेज **Ask AI** सहायक, और कोडिंग एजेंट्स के लिए एक होस्टेड **MCP सर्वर**। Ask AI और MCP ऑप्ट-इन हैं, और जब तक आप कोई सुविधा चालू नहीं करते, स्टैटिक डॉक्स पूरी तरह स्टैटिक बने रहते हैं।

## llms.txt

Blume आपके डॉक्स के मशीन-पठनीय संस्करण उत्सर्जित करता है जिन्हें कोडिंग एजेंट और चैट सहायक उपभोग कर सकते हैं। यह डिफ़ॉल्ट रूप से चालू है; इसे बंद करने के लिए `llmsTxt: false` सेट करें:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: false,
}
```

सक्षम होने पर, `blume build` आपकी साइट के रूट में दो फ़ाइलें लिखता है:

- **`/llms.txt`** — एक संक्षिप्त इंडेक्स: आपकी साइट का शीर्षक और विवरण, फिर हर पेज की एक लिंक की गई सूची उसके सारांश के साथ, ऐसे अनुभागों में व्यवस्थित जो आपके साइडबार को प्रतिबिंबित करते हैं — फ़ोल्डर और समूह शीर्षक बन जाते हैं, इसलिए एजेंट को डॉक्स की संरचना दिखती है, एक सपाट ढेर नहीं।
- **`/llms-full.txt`** — पूरा संग्रह: हर पेज का पूरा Markdown मुख्य भाग, उसके स्रोत URL के साथ, एक ही फ़ाइल में।

ड्राफ़्ट पेज बाहर रखे जाते हैं। [`deployment.site`](/docs/deployment) सेट करें ताकि लिंक और स्रोत URL निरपेक्ष पतों में हल हों।

`llmsTxt` एक ऑब्जेक्ट रूप भी लेता है जिसमें यह नियंत्रित करने के विकल्प हैं कि फ़ाइलों में क्या शामिल हो। यदि आपका [API संदर्भ](/docs/advanced/api-reference) किसी प्लेसहोल्डर या उदाहरण स्पेक का दस्तावेज़ीकरण करता है, तो उसके जनरेट किए गए पेजों को दोनों फ़ाइलों से बाहर रखने के लिए `openapi: false` सेट करें:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    enabled: true, // default
    openapi: false, // exclude generated API reference pages
  },
}
```

ऑब्जेक्ट रूप `details` भी लेता है: ऐसा Markdown जो `llms.txt` में शीर्षक और सारांश के ठीक बाद, पेज अनुभागों से पहले रखा जाता है — [llms.txt स्पेक](https://llmstxt.org) का मुक्त-रूप "details" ब्लॉक। यही वह जगह है जहाँ एजेंट्स को बताया जाता है कि आपके उत्पाद का सहारा _कब_ लेना है और उसे कैसे कॉल करना है, जिसे रेडीनेस स्कैनर स्पष्ट रूप से खोजते हैं; एक इंस्टॉल कमांड और पैकेज नाम भी यहीं आते हैं:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    details: [
      "## When to use Acme",
      "",
      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
    ].join("\n"),
  },
}
```

`llms.txt` का अंत दो जनरेट किए गए अनुभागों से होता है जिन्हें किसी कॉन्फ़िगरेशन की ज़रूरत नहीं। **Agent skills** [`ai.skills`](#skills-discovery) के माध्यम से प्रकाशित प्रत्येक स्किल को उसके विवरण के साथ सूचीबद्ध करता है (जहाँ कोई स्किल बताती है कि उसका उपयोग कब करना है)। **Agent resources** बिल्ड द्वारा उत्सर्जित हर मशीन-पठनीय आर्टिफ़ैक्ट को लिंक करता है — `llms-full.txt`, प्रति-पेज [कच्चा Markdown](#raw-markdown) प्रतिबिंब, [MCP सर्वर](#mcp-server) और उसका डिस्कवरी दस्तावेज़, स्किल्स इंडेक्स, [API कैटलॉग](#api-catalog), [`agent-readability.json`](#agent-readability), और [साइटमैप](/docs/configuration/seo#sitemap) — प्रत्येक केवल तभी जब वह मौजूद हो, ताकि जो एजेंट `llms.txt` के अलावा कुछ न पढ़े, वह भी पूरी सतह खोज ले।

किसी एक पेज को दोनों फ़ाइलों से बाहर रखने के लिए, उसके फ़्रंटमैटर में `ai.exclude` सेट करें:

```mdx
---
title: Internal notes
ai:
  exclude: true
---
```

पेज फिर भी रेंडर होता है, खोज में बना रहता है, और साइटमैप में अपना स्थान बनाए रखता है — केवल `llms.txt` फ़ाइलें ही इसे छोड़ती हैं।

किसी भी फ़ाइल पर पूर्ण नियंत्रण लेने के लिए, अपने `public/` फ़ोल्डर में अपनी स्वयं की `llms.txt` या `llms-full.txt` जोड़ें। कस्टम फ़ेविकॉन की तरह, इसे स्वचालित रूप से उठा लिया जाता है और जनरेट की गई फ़ाइल के स्थान पर भेजा जाता है — एक को ओवरराइड करें और Blume फिर भी दूसरी जनरेट करता है।

## कच्चा Markdown

किसी भी पेज के URL में `.md` या `.mdx` जोड़ें ताकि उसका कच्चा Markdown स्रोत प्राप्त हो — LLMs, कोडिंग एजेंट्स और "copy as Markdown" वर्कफ़्लो के लिए एकदम सही। यह हर पेज के लिए, dev और production दोनों में, बिना किसी कॉन्फ़िगरेशन के उपलब्ध है।

| URL               | क्या लौटाता है                              |
| ----------------- | ------------------------------------------- |
| `/quickstart`     | रेंडर किया गया पेज                          |
| `/quickstart.md`  | सादा Markdown, कंपोनेंट्स परिवर्तित किए हुए |
| `/quickstart.mdx` | कच्चा MDX स्रोत, ठीक वैसा ही जैसा लिखा गया  |

नेस्टेड रूट्स भी उसी तरह काम करते हैं (`/content/syntax.md`), और होम पेज `/index.md` पर सर्व किया जाता है।

`.md` वैरिएंट उन उपभोक्ताओं के लिए कंपोनेंट्स को सादे Markdown में _डाउनलेवल_ करता है जो JSX की व्याख्या नहीं कर सकते: `<TypeTable>` एक Markdown तालिका बन जाती है, `<Callout>` एक लेबल किया गया ब्लॉककोट, `<Steps>` एक क्रमबद्ध सूची, `<Tabs>` बोल्ड-लेबल वाले अनुभाग, `<Card>` अपने मुख्य भाग के ऊपर अपना शीर्षक एक लिंक के रूप में (और `<CardGroup>` उसमें रखे कार्ड्स), और `<YouTube>` एक लिंक। प्रॉप्स का मूल्यांकन पेज के `frontmatter` को स्कोप में रखकर किया जाता है, इसलिए `title={frontmatter.status}` जैसा प्रॉप उसी मान में हल होता है जो रेंडर किया गया पेज दिखाता है। जो कुछ भी सटीक रूप से परिवर्तित नहीं किया जा सकता — कोई कस्टम कंपोनेंट, या किसी इम्पोर्ट से गणना किया गया प्रॉप — उसे जस का तस छोड़ दिया जाता है, और फ़ेंस किए गए कोड ब्लॉक्स के भीतर के कंपोनेंट मार्कअप को कभी नहीं छुआ जाता। यही रूपांतरण `llms-full.txt` और MCP सर्वर के `get_page` टूल पर भी लागू होता है, इसलिए हर एजेंट-सामने वाली सतह साफ़ Markdown पढ़ती है। जब आपको अपरिवर्तित स्रोत चाहिए, तो `.mdx` वैरिएंट का उपयोग करें।

### कंटेंट नेगोशिएशन

एजेंट्स को `.md` परंपरा जानने की ज़रूरत नहीं है: किसी पेज के अपने URL को [`Accept: text/markdown`](https://acceptmarkdown.com) हेडर के साथ अनुरोध करने पर उसी पते पर Markdown वैरिएंट सर्व होता है, `Vary: Accept` के साथ ताकि कैश दोनों को अलग रखें। dev सर्वर हेडर को बिना किसी सेटअप के सम्मानित करता है, और एक [Vercel या Cloudflare सर्वर बिल्ड](/docs/deployment#server-rendering) उसी नेगोशिएशन को डिप्लॉय में स्वचालित रूप से जोड़ देता है — Vercel पर रूटिंग नियम, Cloudflare पर एक जनरेट किया गया Worker — किसी कॉन्फ़िगरेशन की आवश्यकता नहीं। होमपेज हमेशा नेगोशिएट करता है, तब भी जब वह किसी कंटेंट पेज के बजाय एक कस्टम लैंडिंग पेज हो: उसका Markdown प्रतिबिंब [`llms.txt`](#llmstxt) इंडेक्स पर वापस गिरता है, इसलिए साइट रूट से Markdown माँगने वाले एजेंट को साइट का मशीन-पठनीय नक्शा मिलता है। Markdown प्रतिक्रियाएँ एक `x-markdown-tokens` हेडर भी ले जाती हैं — एक अनुमानित टोकन गणना (~4 अक्षर प्रति टोकन), [Cloudflare के Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) की परंपरा का अनुसरण करते हुए — हर उस सतह पर जहाँ Blume प्रतिक्रिया हेडर नियंत्रित करता है: dev सर्वर, सर्वर-रेंडर की गई प्रतिक्रियाएँ, और Vercel तथा Cloudflare पर नेगोशिएट किया गया होमपेज। अन्य डिप्लॉय लक्ष्य पूर्व-रेंडर किए गए पेजों को एक स्टैटिक परत से सर्व करते हैं जिसमें अनुरोध-समय का कोई हुक नहीं होता, इसलिए वहाँ एजेंट सीधे `.md` URL लाते हैं; [एजेंट रीडेबिलिटी मैनिफ़ेस्ट](#agent-readability) केवल उन डिप्लॉयमेंट्स पर `contentNegotiation` का विज्ञापन करता है जो हेडर को सम्मानित करते हैं।

अनुपस्थित पेज भी नेगोशिएट करते हैं। हर बिल्ड `/404.md` पर एक Markdown [404 पेज](/docs/advanced/custom-pages#404-page) उत्सर्जित करता है — नहीं-मिला संदेश, उसके बाद हर शीर्ष-स्तरीय अनुभाग, साइटमैप, और `llms.txt` की ओर पुनर्प्राप्ति लिंक — और Vercel पर, किसी अस्तित्वहीन URL के लिए ऐसा अनुरोध जो Markdown को प्राथमिकता देता है, या ऐसा कोई भी `.md` URL जिसके पीछे कोई पेज न हो, HTML शेल के बजाय वही बॉडी एक वास्तविक `404` स्थिति के साथ प्राप्त करता है।

### कस्टम कंपोनेंट सीरियलाइज़र

`ai.markdownComponents` के साथ अपने स्वयं के कंपोनेंट्स को एक Markdown रूप दें — JSX नाम से सीरियलाइज़र का एक मानचित्र। प्रत्येक सीरियलाइज़र कंपोनेंट के `props` (MDX एट्रिब्यूट्स से स्थैतिक रूप से मूल्यांकित, पेज के `frontmatter` को स्कोप में रखकर), उसके `children` (पहले ही Markdown में डाउनलेवल किए हुए), और पेज का `frontmatter` डेटा प्राप्त करता है, और प्रतिस्थापन लौटाता है — या JSX को जस का तस छोड़ने के लिए `null`:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import type { ComponentMarkdown } from "blume";

const chart: ComponentMarkdown = ({ props }) =>
  `![${props.title}](/charts/${props.slug}.png)`;

export default defineConfig({
  ai: {
    markdownComponents: {
      Chart: chart,
    },
  },
});
```

कंटेनर कंपोनेंट्स के लिए, `childComponents("Name")` टैग के अनुसार सीधे चिल्ड्रन निकालता है — ठीक उसी तरह जैसे अंतर्निर्मित `<Steps>` सीरियलाइज़र अपने `<Step>` आइटम एकत्र करता है — और `childBlocks()` हर सीधे चाइल्ड को क्रम में लौटाता है, कंपोनेंट्स और गद्य दोनों, प्रत्येक पहले ही Markdown के एक ब्लॉक में डाउनलेवल किया हुआ (अंतर्निर्मित `<CardGroup>` सीरियलाइज़र बस उन्हीं ब्लॉक्स को खाली पंक्तियों से जोड़कर बना है)। समान नाम वाली एक प्रविष्टि अंतर्निर्मित सीरियलाइज़र को बदल देती है, इसलिए आप बदल सकते हैं कि `<Callout>` कैसे डाउनलेवल होता है — या किसी एक को पूरी तरह बाहर करने के लिए `null` लौटा सकते हैं।

सीरियलाइज़र `blume.config.ts` में रहते हैं, `components.tsx` में नहीं: कॉन्फ़िग फ़ाइल बिल्ड समय पर निष्पादित होती है, जबकि कंपोनेंट्स फ़ाइल का केवल स्थैतिक विश्लेषण किया जाता है (यह `.astro` फ़ाइलें इम्पोर्ट कर सकती है, जो साइट बिल्ड के बाहर नहीं चल सकतीं)। आपके कंपोनेंट्स स्वयं पहले की तरह ही `components.tsx` में पंजीकृत रहते हैं — `markdownComponents` केवल उनका एजेंट-सामने वाला Markdown रूप जोड़ता है।

## Copy as Markdown

हर पेज पर एक **Copy as Markdown** क्रिया होती है — विषय-सूची के नीचे [पेज क्रियाओं](/docs/content/navigation#page-actions) में — जो पेज का कच्चा Markdown क्लिपबोर्ड पर कॉपी करती है। यह वही स्रोत है जो ऊपर [`.md` URL](#raw-markdown) पर सर्व किया जाता है, किसी LLM, किसी इशू, या आपके नोट्स में पेस्ट करने के लिए तैयार। यह हर पेज पर, dev और production दोनों में, बिना किसी कॉन्फ़िगरेशन के उपलब्ध है।

जहाँ Clipboard API उपलब्ध न हो या ब्राउज़र इसे अस्वीकार कर दे — इन-ऐप ब्राउज़र, WebViews, असुरक्षित ऑरिजिन — वहाँ यह क्रिया पुराने कॉपी कमांड पर वापस गिरती है, और यदि क्लिपबोर्ड पर कुछ भी न पहुँचे तो बटन चुप रहने के बजाय **Copy failed** बताता है (`actions.copyFailed` के माध्यम से स्थानीयकृत)। यही फ़ॉलबैक Blume द्वारा रेंडर किए जाने वाले हर कॉपी बटन के पीछे है।

## चैट में खोलें

**Open in chat** क्रिया वर्तमान पेज को किसी AI सहायक में खोलती है — v0, ChatGPT, Claude, T3 Chat, Scira, या Cursor — एक ऐसे प्रॉम्प्ट के साथ पहले से भरा हुआ जो उसे पेज के कच्चे Markdown की ओर इंगित करता है ताकि वह उसके बारे में सवालों का जवाब दे सके जो आप पढ़ रहे हैं:

> Read `https://your-site/this-page.md` so I can ask you questions about this page.

Copy as Markdown की तरह, इसे किसी सेटअप की ज़रूरत नहीं है। सहायक पेज को उसके सार्वजनिक URL से लाता है, इसलिए यह पेज डिप्लॉय होते ही काम करने लगता है।

यह प्रॉम्प्ट [UI शब्दकोश](/docs/content/i18n#translated-ui) (`actions.openInChatPrompt`) का हिस्सा है, इसलिए स्थानीयकृत साइटें इसे अपनी भाषा में भेजती हैं, और `i18n.ui` शब्दावली को ओवरराइड कर सकता है — `{url}` प्लेसहोल्डर बनाए रखें, जिसे पेज के कच्चे-Markdown URL से बदल दिया जाता है।

क्रिया को अनुकूलित करने के लिए, `ai.openInChat` सेट करें। `false` इसे पूरी तरह छिपा देता है, और प्रदाता कुंजियों की एक सरणी — `"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"` — केवल उन्हीं प्रदाताओं को दिखाती है, उसी क्रम में जिस क्रम में आप उन्हें सूचीबद्ध करते हैं:

```ts blume.config.ts lineNumbers
ai: {
  openInChat: ["claude", "chatgpt", "cursor"],
}
```

अपनी सामग्री में इनलाइन एक कॉपी-करने-योग्य प्रॉम्प्ट एम्बेड करने के लिए — पूरे-पेज की क्रिया के बजाय — [Prompt कंपोनेंट](/docs/content/components#prompt) का उपयोग करें, जो एक **Copy prompt** बटन और एक वैकल्पिक open-in-Cursor लिंक के साथ एक लेबल की गई पंक्ति रेंडर करता है।

## Ask AI

एक सहायक जोड़ें जो पाठकों के सवालों का जवाब एक इन-पेज चैट पैनल में देता है, जिसके पीछे एक स्ट्रीमिंग सर्वर एंडपॉइंट और [AI SDK](https://ai-sdk.dev) है:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "gateway", // default
    model: "openai/gpt-5.5",
  },
}
```

### सुझाए गए प्रश्न

खाली स्थिति को कुछ शुरुआती प्रॉम्प्ट्स से भरें। प्रत्येक एक क्लिक-योग्य सुझाव के रूप में रेंडर होता है — भेजने के लिए किसी एक पर क्लिक करें — लेबल के बगल में एक वैकल्पिक [Lucide आइकन](/docs/content/components#icon) के साथ:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    suggestions: [
      { label: "What is Blume?", icon: "rocket" },
      { label: "How do I write a docs page?", icon: "file-text" },
      { label: "How do I configure the theme?", icon: "settings" },
    ],
  },
}
```

`label` वह प्रश्न है जो पूछा जाता है; `icon` वैकल्पिक है। `suggestions` को अनसेट (या खाली) छोड़ दें और पैनल एक सादे इनपुट के साथ खुलता है।

### कस्टम निर्देश

`instructions` के साथ अपना स्वयं का सिस्टम-प्रॉम्प्ट टेक्स्ट जोड़ें — पहचान, भाषा, लहजा, या कुछ भी और जो सहायक को ध्यान में रखना चाहिए:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    instructions:
      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
  },
}
```

आपका टेक्स्ट अंतर्निर्मित निर्देशों को बदलने के बजाय उनमें **जोड़ा जाता है**: अंतर्निर्मित भाग [ग्राउंडिंग](#grounding) अनुबंध रखता है — केवल पुनःप्राप्त पेजों से उत्तर दें, उन्हें Markdown लिंक्स के रूप में उद्धृत करें — जिस पर चैट पैनल के उद्धरण निर्भर करते हैं, इसलिए आप जो भी जोड़ें, वह बरकरार रहता है।

### ग्राउंडिंग

Ask AI **आपके डॉक्स में ग्राउंडेड** है। हर प्रश्न के लिए यह सबसे प्रासंगिक पेज पुनःप्राप्त करता है — वही लेक्सिकल [Orama](/docs/configuration/search) इंडेक्स उपयोग करते हुए जो ऑन-पेज खोज को शक्ति देता है — और उन्हें मॉडल के सिस्टम प्रॉम्प्ट में डालता है, ताकि उत्तर मॉडल के अपने ज्ञान के बजाय आपकी सामग्री से आएँ। सहायक को कहा जाता है कि वह केवल पुनःप्राप्त पेजों से उत्तर दे, बताए कि कब कोई बात कवर नहीं है, और जिन पेजों से उसने लिया है उनका उद्धरण दे।

पाठक वर्तमान में जिस पेज पर है, उसे सबसे पहले संदर्भ में जोड़ा जाता है और पुनःप्राप्ति को उस पेज की भाषा तक सीमित करने के लिए उपयोग किया जाता है, ताकि उत्तर इस बात के अनुरूप रहें कि वे डॉक्स में कहाँ हैं। पुनःप्राप्ति अनुरोध समय पर बिल्ड में पकाए गए एक स्नैपशॉट से चलती है, इसलिए यह आपके [खोज](/docs/configuration/search) प्रदाता की परवाह किए बिना काम करती है — तब भी जब खोज `none` पर सेट हो — और इसे किसी कॉन्फ़िगरेशन की ज़रूरत नहीं है।

**[Inkeep](#backends)** को छोड़कर हर बैकएंड के लिए ग्राउंडिंग चालू है, जो अपने डैशबोर्ड में आपके द्वारा इंडेक्स की गई सामग्री पर अपनी स्वयं की पुनःप्राप्ति चलाता है।

### पुनःप्राप्ति आकार

कोई प्रश्न कितना दस्तावेज़ीकरण साथ ले जाता है, यह इस बात पर सबसे बड़ा लीवर है कि पाठक पहले शब्द के लिए कितनी देर प्रतीक्षा करता है: मॉडल एक भी टोकन उत्सर्जित करने से पहले हर डाले गए अक्षर को पढ़ता है। किसी होस्टेड फ्रंटियर मॉडल पर यह अदृश्य होता है, लेकिन किसी स्व-होस्टेड बैकएंड पर यह हावी रहता है। `retrieval` इसका आकार तय करता है:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    retrieval: {
      maxResults: 3, // fewer pages retrieved per question
      excerptChars: 1200, // shorter excerpt from each one
      contextBudget: 3000, // smaller total injection
    },
  },
}
```

| विकल्प          | डिफ़ॉल्ट | विवरण                                      |
| --------------- | -------- | ------------------------------------------ |
| `maxResults`    | `6`      | प्रति प्रश्न पुनःप्राप्त किए गए दस्तावेज़। |
| `excerptChars`  | `2000`   | प्रत्येक पुनःप्राप्त पेज से रखे गए अक्षर।  |
| `contextBudget` | `10000`  | सभी अंशों में मिलाकर, कुल डाले गए अक्षर।   |

ये तीनों आपस में विनिमेय नहीं हैं। `contextBudget` पूरे इंजेक्शन की सीमा तय करता है, `excerptChars` यह तय करता है कि किसी एक लंबे पेज के भीतर उसका अंश कितनी गहराई तक पहुँचता है — इसे तब बढ़ाएँ जब पूरा उत्तर एक ही पेज में हो और अंश उसे बीच में काट दे — और `maxResults` यह सीमित करता है कि पुनःप्राप्ति कितने पेज जोड़े। पाठक जिस पेज को देख रहा है, उसे पुनःप्राप्त पेजों के ऊपर डाला जाता है, इसलिए कोई उत्तर `maxResults` से एक पेज अधिक तक का उद्धरण दे सकता है।

डिफ़ॉल्ट मान किसी होस्टेड मॉडल के अनुकूल हैं। इन्हें तब घटाएँ जब आप अपने स्वयं के हार्डवेयर से सर्व कर रहे हों और टाइम-टू-फ़र्स्ट-टोकन का महत्व रिकॉल से अधिक हो; उत्तर दोनों ही स्थितियों में ग्राउंडेड रहते हैं, और सहायक को कहा जाता है कि खाली जगह भरने के बजाय यह बताए कि कब कोई बात कवर नहीं है।

### बाहरी एंडपॉइंट

क्या आपके पास पहले से AI के लिए एक API बैकएंड है? पैनल को उसकी ओर इंगित करें और डॉक्स बिल्ड को स्टैटिक रखें:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}
```

Blume वही `POST` बॉडी भेजता है जो उसका अंतर्निर्मित रूट भेजता है:

```json
{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}
```

एक सफल प्रतिक्रिया लौटाएँ जिसकी बॉडी एक सादी UTF-8 टेक्स्ट स्ट्रीम हो। यदि एंडपॉइंट किसी अन्य ऑरिजिन पर है, तो CORS के साथ डॉक्स ऑरिजिन की अनुमति दें: `OPTIONS` और `POST` स्वीकार करें, `content-type` अनुरोध हेडर की अनुमति दें, और प्रीफ़्लाइट तथा स्ट्रीम की गई प्रतिक्रिया दोनों पर CORS हेडर लौटाएँ। `endpoint` सेट होने पर, Blume चैट UI जनरेट करता है लेकिन कोई सर्वर रूट, ग्राउंडिंग स्नैपशॉट, प्रदाता निर्भरता, या प्रदाता-सीक्रेट चेतावनी नहीं; आपका बैकएंड पुनःप्राप्ति, प्रमाणीकरण, दर सीमा, मॉडल एक्सेस और उद्धरणों का स्वामी होता है।

### सर्वर आउटपुट आवश्यक

Blume का अंतर्निर्मित Ask AI बैकएंड एक सर्वर रूट (`POST /api/ask`) है, इसलिए यह स्टैटिक बिल्ड पर नहीं चल सकता। सर्वर आउटपुट पर स्विच करें और एक एडाप्टर चुनें:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

Ask AI सक्षम और बिना बाहरी `endpoint` वाला एक स्टैटिक बिल्ड तुरंत विफल हो जाता है, एक संदेश के साथ जो आपको `deployment.output` को `server` पर सेट करने के लिए कहता है। एडाप्टर्स के लिए [Deployment](/docs/deployment) देखें।

### बैकएंड्स

डिफ़ॉल्ट रूप से Ask AI **Vercel AI Gateway** के माध्यम से रूट होता है: `model` एक `provider/model` स्ट्रिंग है, इसलिए आप इसे बदलकर मॉडल बदलते हैं (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, इत्यादि) और कोई प्रदाता SDK इंस्टॉल नहीं करना पड़ता। गेटवे आपके परिवेश से `AI_GATEWAY_API_KEY` पढ़ता है और जब आप Vercel पर डिप्लॉय करते हैं तो स्वचालित रूप से जुड़ जाता है।

Ask AI को कहीं और इंगित करने के लिए `provider` सेट करें। प्रत्येक बैकएंड अपनी API कुंजी एक परिवेश चर से पढ़ता है और एक प्रदाता SDK के माध्यम से स्ट्रीम करता है जिसे आप अपने प्रोजेक्ट में इंस्टॉल करते हैं — केवल वही जिसका आप उपयोग करते हैं:

| `provider` | `model` | API कुंजी env चर | इंस्टॉल करने योग्य SDK |
| --- | --- | --- | --- |
| `gateway` (डिफ़ॉल्ट) | AI Gateway के माध्यम से एक `provider/model` स्ट्रिंग | `AI_GATEWAY_API_KEY` | कोई नहीं — Blume के साथ आता है |
| `openrouter` | कोई भी [OpenRouter](https://openrouter.ai) मॉडल | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
| `llmgateway` | कोई भी [LLMGateway](https://llmgateway.io) मॉडल | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
| `inkeep` | एक [Inkeep](https://inkeep.com) QA मॉडल | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
| `openai-compatible` | जो कुछ भी आपका एंडपॉइंट सर्व करता है | `apiKeyEnv` से सेट करें | `@ai-sdk/openai-compatible` |

ये SDKs वैकल्पिक पीयर निर्भरताएँ हैं, इसलिए अपने प्रोजेक्ट में वही जोड़ें जिसकी आपके बैकएंड को ज़रूरत है (जैसे `npm install @openrouter/ai-sdk-provider`)। यदि यह अनुपस्थित है, तो Vite इम्पोर्ट हल करने में विफल हो, उससे पहले ही बिल्ड सटीक पैकेज नाम के साथ चेतावनी देता है।

उदाहरण के लिए, OpenRouter उपयोग करने के लिए:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openrouter",
    model: "anthropic/claude-sonnet-4-5",
  },
}
```

कोई भी OpenAI-संगत एंडपॉइंट `openai-compatible` के माध्यम से काम करता है — `baseUrl` और उसकी कुंजी रखने वाला env चर दें:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openai-compatible",
    baseUrl: "https://my-gateway.example.com/v1",
    apiKeyEnv: "MY_GATEWAY_API_KEY",
    model: "gpt-4o",
  },
}
```

किसी भिन्न env चर या प्रॉक्सी की ओर इंगित करने के लिए किसी भी बैकएंड पर `apiKeyEnv` (और, नामित प्रदाताओं के लिए, `baseUrl`) सेट करें।

:::note
**Inkeep** उस सामग्री से उत्तर देता है जिसे आपने Inkeep डैशबोर्ड में इंडेक्स किया है — यह अपनी स्वयं की पुनःप्राप्ति चलाता है — इसलिए Blume इसे अनग्राउंडेड छोड़ देता है। हर दूसरा बैकएंड इस साइट के पेजों में [ग्राउंडेड](#grounding) है।
:::

कुंजियाँ `process.env` से पढ़ी जाती हैं, जो Node, Vercel और Netlify एडाप्टर्स को कवर करता है। Cloudflare पर, कुंजी को प्लेटफ़ॉर्म के [रनटाइम बाइंडिंग](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) के माध्यम से उपलब्ध कराएँ। Ask AI सक्षम करने से इन-पेज आइलैंड के लिए React भी चालू हो जाता है — देखें [Customization](/docs/configuration/customization#interactive-islands)।

### दर सीमा

`POST /api/ask` एंडपॉइंट **अप्रमाणित** है — इसे होना ही पड़ता है, ताकि इन-पेज सहायक इसे कॉल कर सके। Blume हर अनुरोध को मान्य करता है — विकृत बॉडी अस्वीकार करते हुए, इसे 1–40 संदेशों तक सीमित करते हुए, और केवल `user`/`assistant` भूमिकाएँ स्वीकार करते हुए ताकि कोई कॉलर अपना सिस्टम प्रॉम्प्ट इंजेक्ट करके रूट को एक सामान्य LLM प्रॉक्सी में न बदल सके — ताकि यह सीमित रहे कि एक कॉल आपके मॉडल के विरुद्ध कितना खर्च कर सकता है, लेकिन यह किसी को बार-बार एंडपॉइंट कॉल करने से नहीं रोक सकता। यदि लागत का दुरुपयोग चिंता का विषय है, तो रूट को किसी दर सीमक के पीछे रखें — आपके होस्ट की (जैसे Vercel की) एज दर सीमा, कोई मिडलवेयर, या आपके मॉडल प्रदाता की प्रति-कुंजी खर्च सीमाएँ।

## MCP सर्वर

एक [Model Context Protocol](https://modelcontextprotocol.io) सर्वर होस्ट करें ताकि कोडिंग एजेंट (Claude Code, Cursor, VS Code, claude.ai कनेक्टर्स) आपके डॉक्स को सीधे खोज और पढ़ सकें — बिना स्क्रैपिंग के:

```ts blume.config.ts lineNumbers
ai: {
  mcp: {
    enabled: true,
    route: "/mcp", // where the server is mounted
  },
}
```

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `enabled` | `false` | MCP सर्वर जनरेट और होस्ट करें। |
| `route` | `/mcp` | वह पथ जिस पर Streamable-HTTP एंडपॉइंट माउंट होता है। |
| `name` | title | क्लाइंट्स को दिखाया जाने वाला सर्वर नाम (डिफ़ॉल्ट title)। |
| `instructions` | — | कनेक्ट होने वाले एजेंट्स को दिया जाने वाला वैकल्पिक सिस्टम संकेत। |

सर्वर केवल-पढ़ने योग्य टूल उपलब्ध कराता है — `search_docs`, `get_page`, `list_pages`, और `get_navigation` — और हर पेज को एक MCP संसाधन के रूप में (`resources/list` पेजों को उनके सर्व किए गए URLs पर `text/markdown` प्रकार के साथ गिनाता है; `resources/read` पेज का एजेंट Markdown लौटाता है, वही आउटपुट जो `get_page` देता है), ताकि जो क्लाइंट्स URI द्वारा संदर्भ जोड़ते हैं वे बिना कोई टूल कॉल किए डॉक्स ब्राउज़ कर सकें। यह `/.well-known/mcp.json` तथा `/.well-known/mcp/server-card.json` पर डिस्कवरी दस्तावेज़ प्रकाशित करता है। सर्वर कार्ड [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card एक्सटेंशन स्कीमा का अनुसरण करता है (रिवर्स-DNS `name`, `remotes` ट्रांसपोर्ट एंडपॉइंट्स), साथ ही प्रस्ताव के पूर्ववर्ती संशोधन के विरुद्ध बनाए गए स्कैनर्स के लिए initialize-आकार वाले संगतता फ़ील्ड (`serverInfo`, `capabilities`, `transports`) के साथ। हर पेज का **Connect to MCP** मेनू Claude Code, Cursor, VS Code और Codex के लिए कॉपी-एंड-गो इंस्टॉल प्रदान करता है ([`deployment.site`](/docs/deployment) सेट होने पर दिखता है)।

`search_docs` अपना स्वयं का पूर्ण-पाठ इंडेक्स चलाता है, इसलिए यह आपके [खोज](/docs/configuration/search) प्रदाता की परवाह किए बिना काम करता है — और तब भी जब खोज `none` पर सेट हो। MCP सर्वर ऑन-पेज खोज से एक अलग सुविधा है।

`search_docs` और `list_pages` दोनों एक वैकल्पिक `contentTypes` फ़िल्टर स्वीकार करते हैं, जो परिणामों को दिए गए फ़्रंटमैटर [`type`s](/docs/reference/frontmatter) वाले पेजों तक सीमित करता है — `["rfc"]`, `["blog", "changelog"]` — ताकि ऐसी साइट पर काम करने वाला एजेंट जो डॉक्स को RFCs, रनबुक्स या नीतियों के साथ मिलाती है, पुनःप्राप्ति को उस प्रकार के पेज तक सीमित कर सके जिसकी उसे ज़रूरत है। हर परिणाम अपना कंटेंट प्रकार बताता है, और `list_pages` का आउटपुट उपयोग में मौजूद प्रकार दिखाता है।

दोनों टूल एक `filters` ऑब्जेक्ट भी स्वीकार करते हैं जो उन फ़ेसेट्स के विरुद्ध मिलान करता है जिन्हें कोई साइट प्रति कंटेंट प्रकार घोषित करती है ([`content.types.<type>.facets`](/docs/configuration#frontmatter)) — कस्टम फ़्रंटमैटर कुंजियाँ जिनके मान फ़िल्टर करने योग्य मेटाडेटा बन जाते हैं:

```json
{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}
```

हर `filters` प्रविष्टि का मेल खाना आवश्यक है (परिणाम अपने फ़ेसेट मान साथ रखते हैं, और `list_pages` हर पेज के मान दिखाता है), इसलिए एक नॉलेज बेस प्रोग्रेसिव-डिस्क्लोज़र एजेंट वर्कफ़्लो चला सकता है — लागू मानकों की गणना करें, केवल उन्हीं के भीतर खोजें — अपने किसी सर्वर के बिना।

### सर्वर आउटपुट आवश्यक

MCP सर्वर एक लाइव एंडपॉइंट (`/mcp`) है, इसलिए यह स्टैटिक बिल्ड पर नहीं चल सकता। सर्वर आउटपुट पर स्विच करें और एक एडाप्टर चुनें:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "node", // or "vercel" | "netlify" | "cloudflare"
  site: "https://docs.example.com",
}
```

`ai.mcp.enabled` वाला एक स्टैटिक बिल्ड तुरंत विफल हो जाता है, एक संदेश के साथ जो आपको `deployment.output` को `server` पर सेट करने के लिए कहता है। एडाप्टर्स के लिए [Deployment](/docs/deployment) देखें। डिप्लॉय होने के बाद, Claude Code से इस तरह कनेक्ट करें:

```bash
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

## JSON API

हर Blume साइट अपने डॉक्स को एक छोटे केवल-पढ़ने योग्य **JSON API** के रूप में भी सर्व करती है — [MCP सर्वर](#mcp-server) के टूल्स का REST जुड़वाँ, उसी पेज स्नैपशॉट के ऊपर, उन एजेंट्स और फ़ंक्शन-कॉलिंग फ़्रेमवर्क्स के लिए जो MCP के बजाय सादा HTTP बोलते हैं। यह डिफ़ॉल्ट रूप से चालू है और इसे किसी कॉन्फ़िगरेशन की ज़रूरत नहीं:

| एंडपॉइंट | क्या लौटाता है |
| --- | --- |
| `/api/docs/pages.json` | हर पेज, उसके रूट, शीर्षक, विवरण, कंटेंट प्रकार, लोकेल, फ़ेसेट्स, और उसके रेंडर किए गए, Markdown तथा JSON रूपों के URLs के साथ। |
| `/api/docs/pages/{route}.json` | एक पेज: उसकी इंडेक्स प्रविष्टि और साथ में एजेंट Markdown (वही बॉडी जो `get_page` लौटाता है)। `{route}` अग्रगामी स्लैश के बिना पेज रूट है, होम के लिए `index`। |
| `/api/docs/navigation.json` | नेविगेशन ट्री — हेडर टैब्स और साइडबार पदानुक्रम। |
| `/api/docs/search?q=` | पूर्ण-पाठ खोज, वही `limit`, `contentTypes`, `locale`, `version`, और `filters[key]` स्कोपिंग के साथ जो `search_docs` में है। केवल सर्वर आउटपुट। |
| `/openapi.json` | पूरी मशीन-पठनीय सतह का OpenAPI 3.1 विवरण। |

पेज इंडेक्स, प्रति-पेज दस्तावेज़, और नेविगेशन पूर्व-रेंडर किए जाते हैं, इसलिए एक स्टैटिक साइट उन्हें किसी भी होस्ट से फ़ाइलों के रूप में सर्व करती है। खोज एक लाइव एंडपॉइंट है और केवल [सर्वर आउटपुट](/docs/deployment#server-rendering) के अंतर्गत मौजूद रहती है, जहाँ यह वही इंडेक्स चलाती है जो `search_docs` चलाता है। त्रुटियाँ [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) प्रॉब्लम डिटेल्स (`application/problem+json`) होती हैं, जिनमें एक स्थिर `code`, एक `detail`, और एक `resolution` संकेत होता है जो एजेंट को बताता है कि आगे कहाँ जाना है — कोई अनुपस्थित पेज, कोई खाली खोज क्वेरी, या सर्वर आउटपुट पर कोई भी ऐसा `/api/…` URL जिसका उत्तर कोई एंडपॉइंट न देता हो:

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

`/openapi.json` पर मौजूद **OpenAPI दस्तावेज़** आपके कॉन्फ़िग से प्रति बिल्ड जनरेट होता है, इसलिए यह केवल उसी का वर्णन करता है जो डिप्लॉय की गई साइट सर्व करती है: हर JSON एंडपॉइंट एक अद्वितीय `operationId`, टाइप किए गए पैरामीटर्स, और प्रतिक्रिया स्कीमा के साथ, साथ ही उसके बगल की टेक्स्ट सतहें — [`.md` प्रतिबिंब](#raw-markdown), [`llms.txt`](#llmstxt) और `llms-full.txt`, [`agent-readability.json`](#agent-readability) — और [MCP एंडपॉइंट](#mcp-server) जब वह सक्षम हो। जो फ़्रेमवर्क किसी OpenAPI विवरण से टूल्स बनाते हैं, उन्हें वही पहुँच मिलती है जो एक MCP क्लाइंट के पास होती है। यह दस्तावेज़ [API कैटलॉग](#api-catalog), [रीडेबिलिटी मैनिफ़ेस्ट](#agent-readability), होमपेज के `Link` हेडर में `rel="service-desc"` के रूप में, और `llms.txt` से लिंक किया जाता है।

इसमें से कुछ भी आपके अपने [API संदर्भ](/docs/advanced/api-reference) को नहीं छूता: कोई दस्तावेज़ीकृत स्पेक पेजों में रेंडर किया जाता है, कभी `/openapi.json` पर सर्व नहीं होता, और कैटलॉग दोनों को सूचीबद्ध करता है। आपके द्वारा स्वयं भेजी गई `public/openapi.json` उस रूट को अपने अधिकार में ले लेती है (JSON एंडपॉइंट बने रहते हैं)। `/api/…` कैच-ऑल तब पीछे हट जाता है जब कोई डॉक्स अनुभाग `/api` नेमस्पेस से सर्व होता है (`content/api/overview.md`) या कोई कस्टम पेज `/api/` के अंतर्गत किसी शेष रूट का स्वामी हो, ताकि वे पेज जीतते रहें। इसमें से कुछ भी प्रकाशित न करने के लिए `ai.api` को `false` सेट करें:

```ts blume.config.ts lineNumbers
ai: {
  api: false,
}
```

## एजेंट रीडेबिलिटी

Blume आपकी साइट के रूट पर एक **`/agent-readability.json`** मैनिफ़ेस्ट लिखता है जो इस पेज पर वर्णित एजेंट-सामने वाली सतह को इंडेक्स करता है — ताकि एक एजेंट परंपराओं का अनुमान लगाने या HTML स्क्रैप करने के बजाय इसे एक ही फ़ेच में खोज सके। `llms.txt` की तरह, यह डिफ़ॉल्ट रूप से चालू है:

```ts blume.config.ts lineNumbers
seo: {
  agentReadability: true,
}
```

मैनिफ़ेस्ट केवल वही सूचीबद्ध करता है जो आपने सक्षम किया है — [कच्चा Markdown](#raw-markdown) प्रतिबिंब पैटर्न, [JSON API](#json-api) और उसका OpenAPI विवरण, [`llms.txt`](#llmstxt) और `llms-full.txt`, [MCP सर्वर](#mcp-server) और उसका डिस्कवरी दस्तावेज़, [Ask AI](#ask-ai) एंडपॉइंट, [साइटमैप](/docs/configuration/seo#sitemap), और [RSS फ़ीड्स](/docs/configuration/seo#rss-feeds) — साथ ही आपकी साइट का नाम, विवरण, स्रोत रिपॉज़िटरी, और [content-signal](/docs/configuration/seo#content-signals) उपयोग नीति। [`deployment.site`](/docs/deployment) सेट होने पर URL निरपेक्ष होते हैं और अन्यथा रूट-सापेक्ष:

```json agent-readability.json
{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "https://docs.example.com/{route}.md"
    },
    "api": {
      "openapi": "https://docs.example.com/openapi.json",
      "pages": "https://docs.example.com/api/docs/pages.json",
      "search": "https://docs.example.com/api/docs/search"
    },
    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
    "llmsTxt": "https://docs.example.com/llms.txt",
    "mcp": {
      "discovery": "https://docs.example.com/.well-known/mcp.json",
      "url": "https://docs.example.com/mcp"
    }
  },
  "description": "Docs for the Acme API.",
  "generator": "blume@1.0.0",
  "name": "Acme Docs",
  "site": "https://docs.example.com",
  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
  "repository": "https://github.com/acme/docs"
}
```

`contentNegotiation` फ़ील्ड केवल तब प्रकट होता है जब डिप्लॉय की गई साइट वास्तव में `Accept: text/markdown` हेडर को सम्मानित करती है — देखें [कंटेंट नेगोशिएशन](#content-negotiation); हर दूसरे डिप्लॉयमेंट पर मैनिफ़ेस्ट केवल `.md` प्रतिबिंब पैटर्न का विज्ञापन करता है।

इसे छोड़ने के लिए `seo.agentReadability` को `false` सेट करें, या नियंत्रण लेने के लिए अपनी स्वयं की `public/agent-readability.json` भेजें — Blume कभी भी उस फ़ाइल को अधिलेखित नहीं करता जिसे आप `public/` में रखते हैं।

### डिस्कवरी Link हेडर

जो एजेंट किसी साइट की जाँच करते हैं उन्हें मैनिफ़ेस्ट खोजने का पता नहीं होता — इसलिए Blume होमपेज पर एक [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` प्रतिक्रिया हेडर में भी इसका विज्ञापन करता है, IANA-पंजीकृत संबंध प्रकारों का उपयोग करते हुए:

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
  </openapi.json>; rel="service-desc"; type="application/json",
  </agent-readability.json>; rel="describedby"; type="application/json",
  </llms.txt>; rel="describedby"; type="text/plain",
  </index.md>; rel="alternate"; type="text/markdown"
```

प्रत्येक प्रविष्टि केवल तभी दिखती है जब उसकी सुविधा चालू हो। `alternate` लिंक होमपेज के Markdown प्रतिबिंब की ओर इंगित करता है — जब होम रूट एक कंटेंट पेज हो तो पेज का अपना [कच्चा Markdown](#raw-markdown), या जब वह लैंडिंग पेज हो तो संश्लेषित `llms.txt` फ़ॉलबैक। `service-desc` लिंक ([RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)) [JSON API](#json-api) के OpenAPI विवरण की ओर इंगित करता है, और `api-catalog` [जनरेट किए गए API कैटलॉग](#api-catalog) की ओर। हेडर हर उस सतह पर जाता है जिसे Blume नियंत्रित करता है: dev सर्वर (`curl -I localhost:4321` से जाँचें), उत्सर्जित `_headers` फ़ाइल के माध्यम से स्टैटिक बिल्ड (Netlify और Cloudflare), और डि��्लॉय के रूटिंग नियमों के माध्यम से Vercel सर्वर बिल्ड।

हालाँकि, हर एजेंट रूट से प्रवेश नहीं करता — जो किसी खोज परिणाम या साझा किए गए लिंक का अनुसरण करता है, वह किसी गहरे पेज पर पहुँचता है और होमपेज हेडर कभी नहीं देखता। इसलिए हर रेंडर किया गया पेज भी अपने HTML `<head>` में वही डिस्कवरी लिंक ले जाता है, उन्हीं IANA-पंजीकृत संबंधों का उपयोग करते हुए:

```html
<link
  rel="describedby"
  href="/agent-readability.json"
  type="application/json"
/>
<link rel="describedby" href="/llms.txt" type="text/plain" />
<link rel="alternate" href="/docs/example.md" type="text/markdown" />
```

यहाँ `alternate` लिंक _उस पेज के अपने_ [कच्चे-Markdown प्रतिबिंब](#raw-markdown) की ओर इंगित करता है, ताकि एजेंट जिस HTML पर पहुँचा है उससे सीधे टोकन-कुशल संस्करण पर छलाँग लगा सके। चूँकि हेड लिंक पूर्व-रेंडर किए गए HTML के साथ चलते हैं, वे उन होस्ट्स पर भी काम करते हैं जो `_headers` को अनदेखा करते हैं और कस्टम प्रतिक्रिया हेडर भेज ही नहीं सकते (GitHub Pages, S3) — चाहे एजेंट किसी भी पेज पर प्रवेश करे।

### API कैटलॉग

जब साइट APIs प्रकाशित करती है, तो Blume `/.well-known/api-catalog` पर एक [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API कैटलॉग जनरेट करता है — एक [linkset](https://www.rfc-editor.org/rfc/rfc9264) जो एजेंट्स को केवल डोमेन से आपके APIs की गणना करने देता है, हर बिल्ड सतह पर उसके पंजीकृत `application/linkset+json` मीडिया प्रकार के साथ सर्व किया जाता है। कॉन्फ़िगर करने को कुछ नहीं है: कैटलॉग उसी से व्युत्पन्न होता है जो पहले से `blume.config.ts` में है। प्रत्येक [OpenAPI या AsyncAPI संदर्भ](/docs/advanced/api-reference) अपने रेंडर किए गए डॉक्स रूट पर एंकर की गई एक प्रविष्टि बन जाता है, जिसमें `service-doc` उन डॉक्स की ओर और `service-desc` स्पेक की ओर इंगित करता है जब वह किसी फ़ेच-योग्य URL पर रहता हो; साइट का अपना [JSON API](#json-api) एक ऐसी प्रविष्टि बन जाता है जिसका वर्णन उसकी `/openapi.json` करती है; और [MCP सर्वर](#mcp-server) अपने डिस्कवरी दस्तावेज़ को सेवा विवरण के रूप में लेकर एक प्रविष्टि बन जाता है:

```json .well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://docs.example.com/reference",
      "service-doc": [
        { "href": "https://docs.example.com/reference", "type": "text/html" }
      ],
      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
    },
    {
      "anchor": "https://docs.example.com/api/docs",
      "service-desc": [
        {
          "href": "https://docs.example.com/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://docs.example.com/mcp",
      "service-desc": [
        {
          "href": "https://docs.example.com/.well-known/mcp.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    }
  ]
}
```

बिना किसी API संदर्भ, बिना MCP सर्वर, और [JSON API](#json-api) बंद किए हुए साइट कोई कैटलॉग उत्सर्जित नहीं करती — उसमें कुछ होता ही नहीं। हर जगह की तरह, आपके द्वारा स्वयं भेजी गई `public/.well-known/api-catalog` फ़ाइल जनरेट की गई फ़ाइल पर भारी पड़ती है।

### WebMCP

[WebMCP](https://webmachinelearning.github.io/webmcp/) एक उभरता हुआ ब्राउज़र API है जो किसी पेज को सीधे एक एजेंटिक ब्राउज़र के साथ टूल्स पंजीकृत करने देता है — किसी अलग सर्वर कनेक्शन की ज़रूरत नहीं। हर Blume पेज डॉक्स की केवल-पढ़ने योग्य सतह को पेज के मॉडल संदर्भ पर पंजीकृत करता है: `search_docs` (साइट खोज), `get_page` (किसी पेज का [कच्चा Markdown](#raw-markdown)), और `list_pages` ([`llms.txt`](#llmstxt) इंडेक्स)। स्क्रिप्ट बहुत छोटी है, जब तक कोई टूल वास्तव में कॉल न हो तब तक कोई खोज मशीनरी लोड नहीं करती, और API के बिना हर ब्राउज़र में चुपचाप no-op हो जाती है — जो आज [Chrome के अर्ली प्रीव्यू](https://developer.chrome.com/blog/webmcp-epp) के बाहर सभी ब्राउज़र हैं। यह उसी सतह पर पंजीकृत होती है जिसे अस्थिर स्पेक उपलब्ध कराता है (`navigator.modelContext` या `document.modelContext`), `provideContext` या प्रति-टूल `registerTool` के माध्यम से।

यह डिफ़ॉल्ट रूप से चालू है; ऑप्ट आउट करने के लिए `webmcp: false` सेट करें:

```ts blume.config.ts lineNumbers
ai: {
  webmcp: false,
}
```

### स्किल्स डिस्कवरी

यदि आपका प्रोजेक्ट [एजेंट स्किल्स](https://agentskills.io) भेजता है — [Blume रिपॉज़िटरी स्वयं भेजती है](#agent-skill) — तो `ai.skills` को उस डायरेक्टरी की ओर इंगित करें जो उन्हें रखती है, और बिल्ड उन्हें [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) के अनुसार डिस्कवरी के लिए प्रकाशित करता है:

```ts blume.config.ts lineNumbers
ai: {
  skills: "./skills",
}
```

पथ आपके प्रोजेक्ट रूट के सापेक्ष हल होता है, और `SKILL.md` वाली प्रत्येक उपडायरेक्टरी एक प्रकाशित स्किल बन जाती है। जो स्किल केवल एक अकेली `SKILL.md` है, उसे शब्दशः `/.well-known/agent-skills/<name>/SKILL.md` (`type: "skill-md"`) पर कॉपी किया जाता है; सहायक संसाधनों (`scripts/`, `references/`, `assets/`) वाली स्किल को एक नियतात्मक `.tar.gz` (`type: "archive"`) में बंडल किया जाता है ताकि अनपैक करने के बाद उसके सापेक्ष संदर्भ हल हों, स्क्रिप्ट एक्ज़ीक्यूट बिट्स संरक्षित रखते हुए। `/.well-known/agent-skills/index.json` पर डिस्कवरी इंडेक्स v0.2.0 `$schema` रखता है और, प्रति स्किल, उसका नाम, प्रकार, विवरण (`SKILL.md` फ़्रंटमैटर से), आर्टिफ़ैक्ट URL, और SHA-256 डाइजेस्ट जिसके विरुद्ध क्लाइंट डाउनलोड सत्यापित करते हैं।

जिन स्किल्स का `name`/`description` अनुपस्थित या स्पेक-अमान्य है, उन्हें टूटी हुई प्रकाशित करने के बजाय एक बिल्ड चेतावनी के साथ छोड़ दिया जाता है, और आपके द्वारा स्वयं भेजी गई `public/.well-known/agent-skills/index.json` पूरी सतह पर नियंत्रण ले लेती है।

### DNS-आधारित डिस्कवरी (DNS-AID)

[DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) एक उभरता हुआ IETF ड्राफ़्ट है जो एजेंट्स को एक भी HTTP अनुरोध किए बिना किसी साइट की AI सतह खोजने देता है, एक well-known DNS प्रवेश-बिंदु पर ServiceMode [SVCB/HTTPS रिकॉर्ड्स](https://www.rfc-editor.org/rfc/rfc9460) की क्वेरी करके। DNS रिकॉर्ड आपके ज़ोन में रहते हैं, बिल्ड में नहीं, इसलिए यह एकमात्र डिस्कवरी सतह है जिसे Blume आपके लिए प्रकाशित नहीं कर सकता — इसके बजाय, अपने DNS प्रदाता के साथ एक रिकॉर्ड जोड़ें:

```txt
_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
```

यदि आपका प्रदाता `HTTPS` रिकॉर्ड प्रकार प्रदान करता है तो उसका उपयोग करें (Vercel DNS करता है; यह सादे `SVCB` प्रकार का समर्थन नहीं करता), अन्यथा `alpn` और `port` पैरामीटर्स वाला एक ServiceMode `SVCB` रिकॉर्ड। ड्राफ़्ट यह भी अनुशंसा करता है कि ज़ोन को DNSSEC से हस्ताक्षरित किया जाए ताकि सत्यापन करने वाले रिज़ॉल्वर प्रमाणित उत्तर लौटाएँ — Cloudflare जैसे प्रदाता इसे एक क्लिक में सक्षम कर देते हैं, जबकि कुछ (Vercel DNS सहित) इसका समर्थन बिल्कुल नहीं करते।

`blume audit --url <origin>` यह आपके लिए जाँचता है: जब [`deployment.site`](/docs/deployment) सेट हो, तो नेटवर्क स्तर DNS-over-HTTPS के माध्यम से प्रवेश-बिंदु की क्वेरी करता है और यदि कोई मौजूद न हो तो प्रकाशित करने योग्य सटीक रिकॉर्ड बताता है, साथ ही यह भी कि उत्तर DNSSEC-प्रमाणित हैं या नहीं। यदि आपका नेटवर्क सार्वजनिक रिज़ॉल्वर (Google, Cloudflare) ब्लॉक करता है तो लुकअप को अपने स्वयं के रिज़ॉल्वर की ओर इंगित करने के लिए `BLUME_DOH_URL` सेट करें।

### Web Bot Auth

[Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) दूसरी दिशा में काम करता है: यह एजेंट्स द्वारा आपके डॉक्स पढ़ने के बारे में नहीं है, बल्कि **आपके संगठन के एजेंट्स द्वारा स्वयं की पहचान बताने** के बारे में है जब वे कहीं और अनुरोध करते हैं। आपके एजेंट अपने अनुरोधों पर [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421) से हस्ताक्षर करते हैं, और प्राप्त करने वाली साइटें उन्हें आपके डोमेन पर प्रकाशित एक सार्वजनिक-कुंजी निर्देशिका के विरुद्ध सत्यापित करती हैं। यदि आपका संगठन एजेंट चलाता है और आपकी Blume साइट उसी डोमेन पर है जिसके रूप में वे पहचान बताते हैं, तो उनकी सार्वजनिक कुंजियाँ प्रकाशित करें:

```ts blume.config.ts lineNumbers
ai: {
  webBotAuth: {
    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
  },
}
```

फिर Blume हर बिल्ड सतह पर JWKS को `/.well-known/http-message-signatures-directory` पर उसके पंजीकृत मीडिया प्रकार के साथ सर्व करता है। निर्देशिका परिभाषा से ही सार्वजनिक है, इसलिए कॉन्फ़िग केवल सार्वजनिक कुंजियाँ ही स्वीकार करता है — निजी सामग्री (`d`, `p`, `q`, …) वाली JWK एक लीक हुई क्रेडेंशियल भेजने के बजाय एक त्रुटि के साथ सत्यापन में विफल हो जाती है। एक Ed25519 जोड़ी इस तरह जनरेट करें:

```bash
node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
```

सार्वजनिक JWK ऊपर दिए गए कॉन्फ़िग में जाती है; निजी वाली वहाँ जाती है जहाँ आपका हस्ताक्षर करने वाला एजेंट चलता है (एक सीक्रेट मैनेजर, कभी भी रिपॉज़िटरी नहीं)। यदि आपका संगठन एजेंट संचालित नहीं करता, तो इसे छोड़ दें — एक खाली निर्देशिका सत्यापित करने योग्य कुछ भी विज्ञापित नहीं करती।

चूँकि `blume.config.ts` बिल्ड समय पर निष्पादित होता है, कुंजी को हार्डकोड करना ज़रूरी नहीं है — इसे बिल्ड-समय के परिवेश चर से लोड करें ताकि कॉन्फ़िग कुंजी ब्लॉब्स से मुक्त रहे और बिना किसी कमिट के रोटेट किया जा सके:

```ts blume.config.ts lineNumbers
const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;

export default defineConfig({
  ai: {
    webBotAuth: {
      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
    },
  },
});
```

जिन परिवेशों में यह चर नहीं है वे कोई निर्देशिका प्रकाशित नहीं करते, और इस तरह लोड की गई कुंजी को ठीक वैसे ही सत्यापित किया जाता है जैसे किसी इनलाइन कुंजी को — निजी-सामग्री जाँच सहित। (सार्वजनिक कुंजी कोई रहस्य नहीं है, इसलिए इसे इनलाइन कमिट करना भी उतना ही ठीक है; env चर एक सुविधा-संबंधी विकल्प है, सुरक्षा-संबंधी नहीं।)

## एजेंट स्किल

किसी कोडिंग एजेंट की मदद से Blume साइट बना रहे हैं? Blume [एजेंट स्किल](https://docs.claude.com/en/docs/claude-code/skills) इंस्टॉल करें ताकि उसे पता हो कि Blume कैसे काम करता है, बिना आपके समझाए:

```bash
npx skills add haydenbleasel/blume
```

स्किल एजेंट को सिखाती है कि Blume क्या है और किसी साइट को कैसे स्कैफ़ोल्ड, लिखा और कॉन्फ़िगर किया जाए, और उसे इंस्टॉल किए गए पैकेज में बंडल किए गए पूरे डॉक्स की ओर इंगित करती है (`blume` के भीतर की `docs/` डायरेक्टरी, जहाँ भी आपका पैकेज मैनेजर उसे इंस्टॉल करता है)।

यह [Blume द्वारा भेजी जाने वाली एजेंट स्किल्स](/docs/advanced/skills) में से एक है, साथ ही एक अनुसूचित एजेंट रन से आपके उत्पाद के साथ डॉक्स को समन्वित रखने वाली स्किल भी है।

---

# एनालिटिक्स
Source: https://useblume.dev/hi/docs/configuration/analytics

Blume आपके लिए `blume.config.ts` में एक ही `analytics` ब्लॉक से एनालिटिक्स इंजेक्ट करता है। Vercel Web Analytics और PostHog फ़र्स्ट-क्लास हैं, और एक `scripts` एस्केप हैच बाक़ी हर प्रोवाइडर को कवर करता है — Plausible, Fathom, Google Analytics, Umami, और अन्य।

एनालिटिक्स **केवल प्रोडक्शन बिल्ड** में लोड होता है। स्क्रिप्ट्स `blume build` द्वारा उत्सर्जित की जाती हैं, कभी भी `blume dev` द्वारा नहीं, इसलिए लोकल ट्रैफ़िक कभी आपके डैशबोर्ड तक नहीं पहुँचता और आपको अलग "डेवलपमेंट" प्रोजेक्ट की ज़रूरत नहीं पड़ती।

:::note
एनालिटिक्स ऑप्ट-इन है। `analytics` ब्लॉक न होने पर Blume कुछ भी इंजेक्ट नहीं करता।
:::

## Vercel Web Analytics

[Vercel Web Analytics](https://vercel.com/docs/analytics) जोड़ने के लिए `vercel: true` सेट करें। Blume, Vercel की फ़र्स्ट-पार्टी स्क्रिप्ट इंजेक्ट करता है, जो Vercel डैशबोर्ड में प्रोजेक्ट के लिए Web Analytics सक्षम होने के बाद आपके अपने डोमेन से सर्व की जाती है।

```ts blume.config.ts lineNumbers
analytics: {
  vercel: true,
}
```

किसी की-ज़रूरत नहीं है — स्क्रिप्ट उसी प्रोजेक्ट को रिपोर्ट करती है जिसके तहत वह डिप्लॉय हुई है। यह केवल Vercel डिप्लॉयमेंट्स पर डेटा एकत्र करती है, जहाँ `/_vercel/insights` एंडपॉइंट मौजूद होता है।

## PostHog

[PostHog](https://posthog.com) जोड़ने के लिए अपनी **प्रोजेक्ट API की** दें। होस्ट डिफ़ॉल्ट रूप से PostHog Cloud US होता है; EU Cloud (`https://eu.i.posthog.com`) या सेल्फ़-होस्टेड इंस्टेंस के लिए `host` सेट करें।

```ts blume.config.ts lineNumbers
analytics: {
  posthog: {
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // optional, this is the default
  },
}
```

प्रोजेक्ट API की को ब्राउज़र तक भेजना सुरक्षित है — यह एक सार्वजनिक, राइट-ओनली की है।

## कस्टम स्क्रिप्ट्स

किसी भी अन्य एनालिटिक्स प्रोवाइडर को लोड करने के लिए `scripts` का उपयोग करें। हर एंट्री एक `<script>` टैग रेंडर करती है और उसमें `src` (बाहरी) या `content` (इनलाइन) में से **ठीक एक** सेट होना चाहिए।

```ts blume.config.ts lineNumbers
analytics: {
  scripts: [
    // Plausible
    {
      src: "https://plausible.io/js/script.js",
      strategy: "defer",
      attributes: { "data-domain": "example.com" },
    },
    // Fathom
    {
      src: "https://cdn.usefathom.com/script.js",
      strategy: "defer",
      attributes: { "data-site": "ABCDEFG" },
    },
    // An inline snippet
    {
      content: "console.log('analytics ready')",
    },
  ],
}
```

`attributes` अतिरिक्त HTML एट्रिब्यूट्स (`data-*`, `id`, …) का मैप है जो टैग पर स्प्रेड किए जाते हैं, और `strategy` बाहरी स्क्रिप्ट्स में `async` या `defer` जोड़ता है।

## विकल्प

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `vercel` | `false` | Vercel Web Analytics जोड़ें (केवल Vercel डिप्लॉयमेंट्स)। |
| `posthog.key` | — | PostHog प्रोजेक्ट API की। सेट होने पर PostHog सक्षम करती है। |
| `posthog.host` | `https://us.i.posthog.com` | PostHog इंजेशन होस्ट (EU Cloud या सेल्फ़-होस्टेड)। |
| `scripts[].src` | — | बाहरी स्क्रिप्ट URL. `content` के साथ परस्पर अनन्य। |
| `scripts[].content` | — | इनलाइन स्क्रिप्ट बॉडी। `src` के साथ परस्पर अनन्य। |
| `scripts[].strategy` | — | बाहरी स्क्रिप्ट के लिए `async` या `defer`. |
| `scripts[].attributes` | — | `<script>` टैग पर स्प्रेड किए जाने वाले अतिरिक्त HTML एट्रिब्यूट्स। |

तीनों को मिलाकर इस्तेमाल किया जा सकता है — Vercel, PostHog, और कस्टम स्क्रिप्ट्स एक साथ सक्षम करें। अपनी बिल्ट साइट को डिप्लॉय करने के लिए, [Deployment](/docs/deployment) देखें।

---

# कस्टमाइज़ेशन
Source: https://useblume.dev/hi/docs/configuration/customization

## कंपोनेंट ओवरराइड्स

अपने प्रोजेक्ट रूट में एक `components.ts` (या `components.tsx`) जोड़ें और `defineComponents` एक्सपोर्ट करें। `mdx` मैप या तो किसी बिल्ट-इन कंपोनेंट को **बदल देता है** या एक नया कंपोनेंट **जोड़ता है** — जो बिना किसी इम्पोर्ट के हर `.mdx` पेज में उपलब्ध रहता है।

```ts components.ts lineNumbers
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";
import Pricing from "./components/Pricing.astro";

export default defineComponents({
  mdx: {
    Callout, // replace the built-in Callout
    Pricing, // add a new <Pricing /> component
  },
});
```

कीज़ वही नाम होते हैं जो आप MDX में लिखते हैं (`<Callout>`, `<Pricing>`)। जब आप React कंपोनेंट्स इम्पोर्ट करें तो `.tsx` फ़ाइलनाम का उपयोग करें।

### रेफ़रेंस रूप

हर ओवरराइड — चाहे `mdx`, `layout`, या `islands` में हो — तीन रूप स्वीकार करता है:

```ts components.ts
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";

export default defineComponents({
  mdx: {
    Callout, // 1. an imported component
    Note: "./components/Note.astro", // 2. a path string (resolved from the project root)
    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. a descriptor
  },
});
```

**डिस्क्रिप्टर** रूप एक हाइड्रेशन मोड जोड़ता है ताकि कोई इंटरैक्टिव React/Vue/Svelte कंपोनेंट अपना JavaScript भेजे और क्लाइंट पर जीवंत हो जाए। `client` मोड के बिना कोई फ़्रेमवर्क कंपोनेंट स्टैटिक HTML के रूप में रेंडर होता है — Blume ऐसा कंपोनेंट मिलने पर बिल्ड चेतावनी प्रिंट करता है, क्योंकि यह आमतौर पर एक गलती होती है।

| `client` | हाइड्रेट होता है |
| --- | --- |
| `"load"` | पेज लोड होते ही तुरंत |
| `"idle"` | जब मेन थ्रेड निष्क्रिय हो |
| `"visible"` | जब स्क्रॉल करके दृश्य में आए |
| `"media"` | जब कोई `media` क्वेरी मैच करे (`media: "(min-width: 40rem)"` जोड़ें) |
| `"only"` | केवल क्लाइंट पर, कभी सर्वर-रेंडर नहीं |

जिन इंटरैक्टिव कंपोनेंट्स का उपयोग आप कई पेजों में करते हैं, उनके लिए [`islands` समूह](/docs/content/islands#registering-islands-in-componentsts) `client: "visible"` के साथ डिस्क्रिप्टर रूप का संक्षिप्त रूप है।

### किसी ओवरराइड को टाइप करना

जब आप किसी बिल्ट-इन को बदलें, तो उसका प्रॉप टाइप `blume/components` से इम्पोर्ट करें ताकि आपका कंपोनेंट अनुबंध से मेल खाए — ये टाइप्स कंपोनेंट्स से ही व्युत्पन्न होते हैं, इसलिए वे कभी अलग नहीं होते:

```tsx components/Callout.tsx
import type { CalloutProps } from "blume/components";

export default function Callout(props: CalloutProps) {
  // …your own callout, same props as the built-in
}
```

कंटेंट कंपोनेंट्स के लिए प्रॉप टाइप्स एक्सपोर्ट किए जाते हैं (`CalloutProps`, `CardProps`, `TabsProps`, `StepsProps`, `BadgeProps`, और अन्य)।

## लेआउट स्लॉट्स

`layout` मैप Blume के क्रोम के किसी हिस्से को आपके अपने कंपोनेंट से बदल देता है। हर ओवरराइड को वही प्रॉप्स मिलते हैं जो उस बिल्ट-इन को मिलते हैं जिसे वह बदल रहा है, इसलिए आप डिफ़ॉल्ट को रैप कर सकते हैं या शुरू से बना सकते हैं।

```ts components.ts
import { defineComponents } from "blume";
import Footer from "./components/Footer.astro";
import Logo from "./components/Logo.astro";

export default defineComponents({
  layout: {
    Logo, // brand mark + title in the header
    Footer, // site-wide footer (no built-in — renders only when set)
  },
});
```

जुड़े हुए स्लॉट्स:

| स्लॉट | किसे बदलता है | प्रॉप्स |
| --- | --- | --- |
| `Layout` | पूरा पेज शेल (`RootLayout`) | वह सब कुछ जो बिल्ट-इन लेआउट को मिलता है, साथ ही `layout` मैप |
| `Header` | ऊपरी नेविगेशन बार | `site`, `logo`, `navigation`, `route`, `searchEnabled`, … |
| `Logo` | हेडर में ब्रांड लिंक (मार्क + शीर्षक) | `site`, `logo` |
| `Search` | हेडर का सर्च ट्रिगर + मोडल | `navigation`, `strings`, `locale`, `askEnabled` |
| `Sidebar` | प्राथमिक नेविगेशन ट्री | `items`, `currentRoute` |
| `MobileNav` | मोबाइल ड्रॉअर के अंदर का नेव (डिफ़ॉल्ट रूप से `Sidebar`) | `items`, `currentRoute` |
| `Breadcrumbs` | ब्रेडक्रम्ब पथ | `crumbs` |
| `TableOfContents` | इस पेज पर वाली रूपरेखा | `headings`, `title`, `variant` |
| `Pagination` | पिछला/अगला फुटर लिंक | `prev`, `next`, `strings` |
| `PageHeader` | लेख के ऊपर एक इंजेक्शन बिंदु (कोई बिल्ट-इन नहीं) | `page`, `headings`, `route` |
| `PageFooter` | लेख के नीचे एक इंजेक्शन बिंदु (कोई बिल्ट-इन नहीं) | `page`, `headings`, `route` |
| `Footer` | कंटेंट ग्रिड के बाद साइट-व्यापी फुटर (कोई बिल्ट-इन नहीं) | `site`, `navigation`, `ui` |

`PageHeader`, `PageFooter`, और `Footer` का कोई बिल्ट-इन कंपोनेंट नहीं है — जब तक आप उन्हें सेट नहीं करते वे कुछ भी रेंडर नहीं करते, जिससे वे किसी प्रोमो बैनर, "अंतिम बार अपडेट किया गया" नोट, या मार्केटिंग फुटर के लिए सुविधाजनक इंजेक्शन बिंदु बन जाते हैं।

लेआउट स्लॉट्स MDX ओवरराइड्स जैसे ही [तीन रेफ़रेंस रूप](#reference-form) स्वीकार करते हैं, इसलिए जब आप इंटरैक्टिव हेडर या फुटर चाहें तो कोई स्लॉट एक पाथ स्ट्रिंग या हाइड्रेटेड डिस्क्रिप्टर (`{ component, client }`) हो सकता है।

## इंटरैक्टिव आइलैंड्स

इंटरैक्टिव UI (React, Vue, या Svelte) के लिए, किसी कंपोनेंट को `islands/` फ़ोल्डर में रखें और उसे किसी भी MDX पेज में उपयोग करें — Blume उसे आपके लिए हाइड्रेट करता है, किसी रैपर या रजिस्ट्रेशन की ज़रूरत नहीं:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}
```

```mdx page.mdx
Use it anywhere: <Counter />
```

हाइड्रेशन रणनीतियों और फ़्रेमवर्क सेटअप के लिए [Islands](/docs/content/islands) देखें।

## कस्टम पेज

अपने डॉक्स के साथ पूरी तरह कस्टम रूट माउंट करने के लिए अपने `pages/` फ़ोल्डर के अंतर्गत `.astro` फ़ाइलें जोड़ें — एक लैंडिंग पेज, एक प्राइसिंग पेज, या हाथ से बनाया गया इंडेक्स। वे अपना स्थान बनाए रखते हैं, इसलिए रिलेटिव इम्पोर्ट्स और `getStaticPaths` सामान्य रूप से काम करते हैं, और वे `blume:data` मॉड्यूल से आपका कॉन्फ़िग, नेविगेशन, और रूट्स पढ़ सकते हैं।

पूरी गाइड के लिए [Custom Pages](/docs/advanced/custom-pages) देखें।

## रजिस्ट्री

`blume add` किसी Blume-रखरखावित कंपोनेंट को आपके प्रोजेक्ट में **सोर्स** के रूप में कॉपी करता है — वह आपका होता है और आप उसे स्वतंत्र रूप से संपादित कर सकते हैं। जो उपलब्ध है उसकी सूची देखने के लिए इसे बिना किसी आर्ग्युमेंट के चलाएँ:

```bash
blume add
```

कोई लेआउट स्लॉट (हेडर, साइडबार, ब्रेडक्रम्ब्स, टेबल ऑफ़ कंटेंट्स, पेजिनेशन, या फ़ीडबैक) या कोई भी कंटेंट कंपोनेंट (कॉलआउट, कार्ड, टैब्स, स्टेप्स, अकॉर्डियन, और अन्य) इंस्टॉल करें:

```bash
blume add callout
blume add pagination
```

कॉपी बाक़ी फ़्रेमवर्क को `blume/*` से इम्पोर्ट करती है, इसलिए जब तक आप उसे बदलते नहीं, वह ठीक बिल्ट-इन की तरह ही रेंडर होती है। `blume add` उसे रजिस्टर करने के लिए `defineComponents` स्निपेट प्रिंट करता है — कंटेंट कंपोनेंट्स `mdx` के अंतर्गत, लेआउट हिस्से `layout` के अंतर्गत।

## Astro इंटीग्रेशन

`blume.config.ts` में शीर्ष-स्तरीय `integrations` ऐरे से कोई भी Astro इंटीग्रेशन जोड़ें। पहले इंटीग्रेशन को अपनी साइट में इंस्टॉल करें; Blume उसे जनरेट किए गए रनटाइम की डिपेंडेंसीज़ में नहीं जोड़ता और न ही उसकी Astro संगतता प्रबंधित करता है।

```bash
npm install @astrojs/sitemap
```

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  integrations: [
    sitemap({
      filter: (page) => !page.includes("/drafts/"),
    }),
  ],
});
```

Blume अपने बिल्ट-इन इंटीग्रेशन को उनके मौजूदा क्रम में रखता है, फिर आपकी प्रविष्टियाँ घोषणा क्रम में जोड़ता है। यह उन्हें न तो क्रमबद्ध करता है और न ही डुप्लिकेट हटाता है, इसलिए समान `name` वाले दो इंटीग्रेशन दोनों चलते हैं। Blume यह सत्यापित करता है कि `integrations` एक ऐरे है, जबकि Astro हर प्रविष्टि को सत्यापित करता है और अमान्य इंटीग्रेशन की रिपोर्ट देता है।

चूँकि Blume आपके इंटीग्रेशन को इंस्टेंस कॉपी करने के बजाय जनरेट किए गए Astro कॉन्फ़िग से `blume.config.ts` को फिर से इम्पोर्ट करके लोड करता है, इसलिए कॉन्फ़िग मॉड्यूल प्रति रन दो बार मूल्यांकित होता है — एक बार जब Blume आपका कॉन्फ़िग पढ़ता है और एक बार जब Astro उसे लोड करता है। इंटीग्रेशन फ़ैक्ट्रियों को साइड-इफ़ेक्ट मुक्त रखें (इंटीग्रेशन लौटाएँ; निर्माण के समय फ़ाइलें न लिखें या कनेक्शन न खोलें) ताकि दूसरा मूल्यांकन हानिरहित रहे।

वही इंटीग्रेशन `blume dev` और `blume build` दोनों में चलते हैं। `blume dev` के दौरान `blume.config.ts` संपादित करने से छिपा हुआ Astro कॉन्फ़िग फिर से जनरेट होता है और कॉन्फ़िग रीस्टार्ट ट्रिगर होता है; यदि आपको संपादित इंटीग्रेशन प्रभावी होता न दिखे, तो `blume dev` को रीस्टार्ट करें। Blume यह नहीं बता सकता कि कौन-से कॉन्फ़िग संपादन इंटीग्रेशन को प्रभावित करते हैं, इसलिए एक बार `integrations` ग़ैर-खाली हो जाने पर, `blume.config.ts` का हर संपादन — यहाँ तक कि किसी असंबंधित फ़ील्ड का भी — हॉट-अप्लाई करने के बजाय डेव सर्वर को रीस्टार्ट करता है। Blume केवल `blume.config.ts` की सामग्री ट्रैक करता है, इसलिए उसके द्वारा इम्पोर्ट की गई किसी अलग फ़ाइल को संपादित करना अपने आप वह पुनर्जनन ट्रिगर नहीं करेगा — ऐसे संपादनों के बाद `blume dev` रीस्टार्ट करें। यदि आप इजेक्ट करते हैं, तो आपके स्वामित्व वाला `astro.config.mjs` `blume.config.ts` से एक रिलेटिव ब्रिज बनाए रखता है, इसलिए कॉन्फ़िगर किए गए इंटीग्रेशन चलते रहते हैं; बाद में आप पूर्ण स्वामित्व लेने के हिस्से के रूप में उन्हें सीधे Astro कॉन्फ़िग में ले जा सकते हैं।

## इजेक्ट

जब आपको पूरा नियंत्रण चाहिए, तो जनरेट किए गए रनटाइम को एक स्वतंत्र Astro प्रोजेक्ट में इजेक्ट करें:

```bash
blume eject --yes
```

इजेक्ट एक तरफ़ा कदम है: छिपा हुआ `.blume/` रनटाइम एक सामान्य Astro ऐप बन जाता है जिसका स्वामित्व आपके पास होता है और जिसे आप सीधे संशोधित कर सकते हैं। `blume` पैकेज इम्पोर्ट योग्य बना रहता है, इसलिए आप इसके कंपोनेंट्स, थीम, और Markdown प्रोसेसर बनाए रखते हैं।

### इजेक्ट के बाद क्या छूट जाता है

इजेक्ट करने के बाद, आपकी `build` स्क्रिप्ट सादा `astro build` चलाती है — साइट स्वयं उसी तरह बिल्ड होती है, लेकिन `blume build` जो आर्टिफ़ैक्ट्स ऊपर से जोड़ता था वे अब उत्पन्न नहीं होते। इजेक्ट कमांड उन्हीं के बारे में चेतावनी देता है जिनका आपका कॉन्फ़िग वास्तव में उपयोग करता है। उन्हें बनाए रखने के लिए:

- **Pagefind सर्च इंडेक्स** — `search.provider: "pagefind"` के साथ, सर्च UI इंडेक्स को बिल्ट साइट से लोड करता है, इसलिए जब तक आप स्वयं उसे इंडेक्स नहीं करते, प्रोडक्शन में सर्च टूट जाता है। `pagefind` को devDependency के रूप में इंस्टॉल करें और हर बिल्ड के बाद इंडेक्स करें: `"build": "astro build && pagefind --site dist"`।
- **होस्टेड सर्च सिंक** — किसी होस्टेड प्रोवाइडर का इंडेक्स अब बिल्ड पर पुश नहीं किया जाता; हर बिल्ड के बाद प्रोवाइडर के API या CLI से अपने सर्च रिकॉर्ड फिर से अपलोड करें।
- **sitemap.xml** — इसे मानक [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) इंटीग्रेशन से फिर से बनाएँ।
- **robots.txt** — अपना स्वयं का `public/robots.txt` के रूप में भेजें।
- **llms.txt / llms-full.txt और agent-readability.json** — इन्हें हाथ से लिखें (या अपने किसी बिल्ड स्टेप में जनरेट करें) और `public/` से सर्व करें।
- **प्लेटफ़ॉर्म रीडायरेक्ट फ़ाइलें** — स्टैटिक बिल्ड्स के लिए `_redirects` और `vercel.json` अब उत्पन्न नहीं किए जाते। आपके रीडायरेक्ट अब भी Astro-जनरेटेड मेटा-रिफ़्रेश पेजों के रूप में काम करते हैं, या आप उन्हें अपने होस्ट के अपने कॉन्फ़िग में ले जा सकते हैं।

---

# निर्यात
Source: https://useblume.dev/hi/docs/configuration/export

Blume विषय-सूची के नीचे मौजूद [पेज क्रियाओं](/docs/content/navigation#page-actions) में एक **निर्यात** क्रिया जोड़ सकता है, जिससे पाठक जिस पेज पर हैं उसे **PDF** या **EPUB** के रूप में सहेज सकते हैं। यह डिफ़ॉल्ट रूप से बंद रहता है और पूरी तरह क्लाइंट-साइड है — कोई सर्वर नहीं, और [स्टैटिक](/docs/deployment) बिल्ड स्टैटिक ही रहते हैं।

## इसे सक्षम करें

एक ही टॉगल से दोनों फ़ॉर्मैट चालू करें:

```ts blume.config.ts
export: true,
```

केवल एक फ़ॉर्मैट देने के लिए, इसके बजाय एक ऑब्जेक्ट पास करें:

```ts blume.config.ts
export: {
  pdf: true,
  epub: false,
},
```

जिस भी फ़ॉर्मैट को आप छोड़ देते हैं (या `false` सेट करते हैं) वह मेन्यू से बाहर रह जाता है। दोनों बंद होने पर — जो डिफ़ॉल्ट है — **निर्यात** क्रिया बिलकुल दिखाई नहीं देती।

## PDF

**PDF में निर्यात करें** आपके ब्राउज़र का प्रिंट डायलॉग एक ऐसी प्रिंट स्टाइलशीट के साथ खोलता है जो साइट के ढाँचे — हेडर, साइडबार, नेविगेशन — को हटाकर केवल लेख रह जाने देती है। पूरा करने के लिए **Save as PDF** चुनें।

चूँकि यह लाइव, पूरी तरह स्टाइल किए गए पेज को प्रिंट करता है, इसलिए परिणाम में स्पष्ट, चयन-योग्य टेक्स्ट, असली फ़ॉन्ट और सिंटैक्स-हाइलाइट किया गया कोड बना रहता है। इसे किसी डिपेंडेंसी की ज़रूरत नहीं है और यह dev में, प्रोडक्शन में और स्टैटिक होस्ट पर एक जैसा काम करता है।

:::note
PDF निर्यात ब्राउज़र के मूल प्रिंट डायलॉग से होकर जाता है, इसलिए "Save as PDF" का सटीक शब्द-प्रयोग और विकल्प ब्राउज़र पर निर्भर करते हैं। कोड-ब्लॉक और कॉलआउट की पृष्ठभूमि बनाए रखने के लिए डायलॉग में **Background graphics** सक्षम करें।
:::

## EPUB

**EPUB में निर्यात करें** मौजूदा पेज की एक स्व-निहित `.epub` फ़ाइल ब्राउज़र में तैयार करता है और उसे डाउनलोड कर देता है — Apple Books, Calibre, या किसी भी ई-रीडर के लिए तैयार। जनरेटर तभी लोड होता है जब कोई पाठक Export पर क्लिक करता है, इसलिए यह आपकी बाकी साइट पर कभी बोझ नहीं डालता।

फ़ाइल को ऐसे डिवाइस पर भी पठनीय रखने के लिए जिसके पास अपनी कोई स्टाइलशीट या JavaScript न हो, Blume पेज को साफ़, स्वतंत्र HTML में फिर से लिखता है: सिंटैक्स-हाइलाइट किया गया कोड सादे मोनोस्पेस में बदल जाता है, सजावटी आइकन और कॉपी बटन हटा दिए जाते हैं, और एक अंतर्निहित ई-रीडर स्टाइलशीट स्पेसिंग, कोड ब्लॉक और टेबल संभालती है।

## क्या निर्यात होता है

दोनों फ़ॉर्मैट उसी **एक पेज** को निर्यात करते हैं जिसे पाठक देख रहा है — पूरी साइट को नहीं — जो इस बात से मेल खाता है कि यह क्रिया कहाँ रहती है, उस पेज की विषय-सूची के नीचे।

:::note
EPUB में टैब बदलने के लिए कोई JavaScript नहीं होता, इसलिए टैब वाली सामग्री — जैसे [package-install](/docs/content/syntax) ब्लॉक और कोड ग्रुप — को एक साथ हर पैनल दिखाने के लिए विस्तारित कर दिया जाता है। Mermaid डायग्राम जैसे क्लाइंट-रेंडर किए गए एम्बेड शामिल नहीं होते।
:::

---

# खोज
Source: https://useblume.dev/hi/docs/configuration/search

Blume बिना किसी होस्टेड इन्फ्रास्ट्रक्चर और बिना API keys के लोकल खोज प्रदान करता है। यह ब्राउज़र में चलती है, `blume dev` और `blume build` दोनों में काम करती है, और केवल आपकी वास्तविक सामग्री को इंडेक्स करती है — नेविगेशन क्रोम और बाहर रखे गए पेज छोड़ दिए जाते हैं। जब आपकी ज़रूरतें इससे आगे बढ़ जाएँ, तो आप खोज के दिखने या व्यवहार करने के तरीके को बदले बिना किसी होस्टेड या सिमेंटिक बैकएंड पर स्विच कर सकते हैं — केवल आपके द्वारा कॉन्फ़िगर किया गया `search.provider` बदलता है।

Blume Fumadocs के प्रोवाइडर सेट की बराबरी करता है: **Orama**, **FlexSearch**, **Algolia**, **Orama Cloud**, **Typesense**, और **Mixedbread** (साथ ही **Pagefind**)। केवल कॉन्फ़िगर किए गए प्रोवाइडर का SDK ही आपके प्रोजेक्ट में इंस्टॉल होता है, इसलिए एक बैकएंड चुनने से बाकी कभी नहीं आते।

## खोज का उपयोग

खोज को <Badge variant="accent">⌘K</Badge> (या `Ctrl K`) से खोलें, या जब आप किसी फ़ील्ड में टाइप नहीं कर रहे हों तो `/` दबाएँ। `Esc` इसे बंद करता है, और `⌘J` (या `Ctrl J`) परिणाम प्रीव्यू पेन को टॉगल करता है।

क्वेरीज़ पेज के **शीर्षकों**, **विवरणों**, और **मुख्य टेक्स्ट** से मेल खाती हैं, जिसमें शीर्षक के मिलान सबसे ऊँची रैंक पाते हैं और विवरण मुख्य टेक्स्ट से ऊपर रहते हैं।

## लोकप्रिय पेज

पाठक के कोई क्वेरी टाइप करने से पहले, खोज डायलॉग एक **Popular** सूची दिखाता है। डिफ़ॉल्ट रूप से यह पहले छह साइडबार पेज होते हैं — जो मल्टी-टैब साइटों पर अक्सर गलत सेक्शन सामने ले आते हैं। इसके बजाय अपने मनचाहे लिंक पिन करें:

```ts blume.config.ts lineNumbers
search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},
```

प्रत्येक एंट्री एक `href` (आंतरिक रूट या बाहरी URL) और एक `label` लेती है, साथ ही एक वैकल्पिक `icon` — कोई [बिल्ट-इन आइकन](/docs/content/components#icon) नाम, इमेज पाथ/URL, या इनलाइन SVG (nav आइकनों जैसे ही _इनपुट_), जो डिफ़ॉल्ट रूप से एक फ़ाइल ग्लिफ़ होता है। साइडबार फ़ॉलबैक बनाए रखने के लिए `popular` को छोड़ दें या खाली रहने दें।

`href` ऐसे लिखें जैसे साइट रूट पर माउंट हो — `basePath` आपके लिए अपने आप लागू किया जाता है, ठीक `navigation.featured` की तरह। बाहरी URL बिना बदलाव के आगे बढ़ जाते हैं।

> **Warning**
>
> क्यूरेट की गई सूची लिंक का एक ही सेट होती है जो हर भाषा में साझा होती है। जिस
> साइट पर `i18n` कॉन्फ़िगर है, वहाँ साइडबार फ़ॉलबैक पाठक की locale का अनुसरण
> करता है, लेकिन `popular` एंट्रियाँ वहीं ले जाती हैं जहाँ उनका `href` कहता है —
> इसलिए locale-प्रीफ़िक्स वाले रूट तभी पिन करें जब आप हर पाठक को उसी एक भाषा में
> भेजना चाहते हों।

## क्या इंडेक्स होता है

Orama, FlexSearch, Algolia, Orama Cloud, और Typesense के लिए — और MCP सर्वर के `search_docs` टूल के लिए — Blume हर पेज का शीर्षक, विवरण, और सादे टेक्स्ट में बदला गया मुख्य भाग इंडेक्स करता है: कोड ब्लॉक, इमेज, और मार्कअप हटा दिए जाते हैं, ताकि परिणाम प्रासंगिक बने रहें। ये इंडेक्स आपकी सोर्स फ़ाइलों से बनते हैं, इसलिए ये dev और प्रोडक्शन में एक जैसे होते हैं। Pagefind इसके बजाय बिल्ड किए गए HTML को इंडेक्स करता है, और Mixedbread आपके कच्चे Markdown को सिंक करता है, इसलिए ये दोनों हमेशा कोड में भी खोजते हैं।

यदि आपके docs ऑप्शनों, मेथडों, या एरर नामों जैसे खोजे जाने योग्य शब्दों के लिए कोड उदाहरणों पर निर्भर करते हैं, तो fenced कोड को सोर्स से बने इंडेक्सों में शामिल करें:

```ts blume.config.ts lineNumbers
search: {
  indexing: {
    includeCodeBlocks: true,
  },
},
```

हर fence का मुख्य भाग और शीर्षक (ऊपर `blume.config.ts`) खोजे जाने योग्य बन जाते हैं; भाषा और fence मार्कर नहीं। `.mdx` पेजों पर इंडेक्स कंपोनेंट्स को उस टेक्स्ट के रूप में पढ़ता है जो वे दिखाते हैं — किसी Card का शीर्षक, किसी Tab का लेबल, किसी TypeTable के विवरण — और इसके लिए वही सीरियलाइज़र उपयोग होते हैं जो [एजेंट सरफ़ेस](/docs/configuration/ai) उपयोग करते हैं, इसलिए एक `ai.markdownComponents` एंट्री आपके अपने कंपोनेंट्स को भी कवर कर लेती है। इस ऑप्शन का Pagefind या Mixedbread पर कोई प्रभाव नहीं पड़ता। यह अपेक्षा रखें कि आपकी fenced सामग्री के साथ इंडेक्स बढ़ेगा — क्लाइंट इंडेक्स हर पाठक तक भेजा जाता है, होस्टेड प्रोवाइडर रिकॉर्ड के आकार की सीमा तय करते हैं (जब किसी एक पेज का रिकॉर्ड उसके प्लान की सीमा से आगे निकल जाता है तो Algolia सिंक बैच को अस्वीकार कर देता है, और पिछला इंडेक्स ही लाइव बना रहता है), और किसी fence के भीतर मिला मिलान परिणाम के अंश में सपाट किया हुआ कोड दिखाता है।

किसी [वर्शन वाली](/docs/content/versioning) साइट पर, परिणाम डिफ़ॉल्ट रूप से उसी वर्शन तक सीमित रहते हैं जिसे देखा जा रहा है, और डायलॉग के फ़ुटर में एक "All versions" टॉगल होता है (जो हर पाठक के लिए याद रखा जाता है)। दूसरे वर्शन के मिलान अपनी पंक्ति पर अपना वर्शन बताते हैं। Orama, FlexSearch, Algolia, और Typesense इस स्कोपिंग का पालन करते हैं — होस्टेड रिकॉर्ड एक `version` facet रखते हैं, जिसमें मौजूदा docs `"current"` के रूप में अपलोड होते हैं — जबकि Pagefind बिना स्कोप के रहता है, जो उसके locale व्यवहार के अनुरूप है।

## टैग

किसी पेज को खोज डायलॉग में एक फ़िल्टर के अंतर्गत समूहित करने के लिए उसके frontmatter में `search.tags` जोड़ें — पाठक एक क्लिक से परिणामों को किसी टैग तक सीमित कर सकते हैं। होस्टेड प्रोवाइडरों पर टैग एक facet भी बन जाते हैं।

```yaml
search:
  tags: [api, reference]
```

## प्रोवाइडर

क्लाइंट-साइड प्रोवाइडर बिना keys के चलते हैं और किसी अतिरिक्त config की ज़रूरत नहीं रखते। होस्टेड प्रोवाइडर `blume.config.ts` में **सार्वजनिक** क्रेडेंशियल लेते हैं (ब्राउज़र तक भेजना सुरक्षित) और बिल्ड के समय अपनी **गुप्त** एडमिन key एक environment variable से पढ़ते हैं — सीक्रेट कभी config या क्लाइंट बंडल में नहीं पहुँचता।

### Orama (डिफ़ॉल्ट)

Blume का डिफ़ॉल्ट इंजन। यह `/blume-search.json` पर सर्व किया जाने वाला एक JSON इंडेक्स बनाता है और ब्राउज़र में उससे क्वेरी करता है — तुरंत, क्लाइंट-साइड, और `blume dev` में संपादन करते ही लाइव। कोई keys नहीं, कोई सेवा नहीं।

```ts blume.config.ts lineNumbers
search: {
  provider: "orama", // default
}
```

#### गैर-लैटिन लिपियाँ

Orama का मानक टोकनाइज़र केवल बुनियादी लैटिन अक्षर, अंक, और गिने-चुने उच्चारण-चिह्न वाले स्वर ही रखता है, इसलिए किसी भी अन्य लिपि का टेक्स्ट — जापानी, चीनी, कोरियाई, और थाई, लेकिन उतना ही रूसी, यूनानी, हिब्रू, और हिन्दी भी — अन्यथा कोई भी मिलान नहीं देता। Blume इसे आपके लिए संभालता है: जब [`i18n.defaultLocale`](/docs/content/i18n) किसी गैर-लैटिन लिपि पर हल होता है, तो इंडेक्स एक शब्द-विभाजक टोकनाइज़र पर स्विच हो जाता है (जो ब्राउज़र- और Node-नेटिव `Intl.Segmenter` पर बना है)। बस अपनी साइट की भाषा घोषित करना ही काफी है:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}
```

वही टोकनाइज़र खोज डायलॉग, MCP सर्वर के `search_docs` टूल, और Ask AI ग्राउंडिंग के काम आता है। निर्णय लिपि से होता है, भाषा के नाम से नहीं — `az-Cyrl` विभाजित होती है जबकि `sr-Latn` नहीं — और पूरे इंडेक्स के लिए निर्णय डिफ़ॉल्ट locale ही करता है: मिश्रित-भाषा वाली साइट पर हर पेज डिफ़ॉल्ट locale का टोकनाइज़र साझा करता है। गैर-लैटिन डिफ़ॉल्ट के साथ यह सुरक्षित है, क्योंकि लैटिन शब्द विभाजन के बाद भी अक्षुण्ण रहते हैं, इसलिए अंग्रेज़ी के पेज डिफ़ॉल्ट भाषा के साथ-साथ खोजे जा सकते हैं। इसका उलटा सही नहीं है: लैटिन-डिफ़ॉल्ट वाली साइट पर गैर-लैटिन अनुवाद खोजे नहीं जा सकते। जो लैटिन-लिपि वाली भाषाएँ उच्चारण-चिह्नों पर बहुत निर्भर करती हैं (वियतनामी, या लैटिन लिपि में सर्बियाई), वे भी मानक टोकनाइज़र पर कमज़ोर प्रदर्शन करती हैं, जो केवल कुछ ही उच्चारण-चिह्न वाले स्वरों को समेटता है और बाकी पर शब्दों को तोड़ देता है।

जापानी और चीनी एक कदम और आगे जाती हैं। केवल विभाजन से एक संयुक्त शब्द उसके हिस्सों के रूप में इंडेक्स होता है — 資金決済法 को 資金, 決済 और 法 के रूप में — जिससे हर हिस्से का कहीं-न-कहीं उल्लेख करने वाला पेज उस पेज से आगे निकल सकता है जो वास्तव में उस शब्द के बारे में है। इसलिए Han, Hiragana और Katakana को ओवरलैप होने वाले अक्षर-युग्मों के रूप में इंडेक्स किया जाता है, और उन इंडेक्सों पर क्वेरीज़ ऐसे पेजों को प्राथमिकता देती हैं जो किसी शब्द के युग्मों को एक साथ रखते हैं, और जब कोई पेज उन सभी को नहीं रखता तो किसी-भी-युग्म मिलान तक ढील दे देती हैं, ताकि पूरा वाक्य टाइप करने पर भी उसके सबसे नज़दीकी पेज लौटें। कोरियाई और थाई अपने विभाजित शब्द बनाए रखती हैं।

### FlexSearch

एक दूसरा बिना key वाला, क्लाइंट-साइड विकल्प। यह वही `/blume-search.json` इंडेक्स दोबारा उपयोग करता है जो Orama प्रदान करता है और ब्राउज़र में एक [FlexSearch](https://github.com/nextapps-de/flexsearch) डॉक्युमेंट इंडेक्स बनाता है। `blume dev` और `blume build` में काम करता है।

FlexSearch में इसके समकक्ष कोई सेगमेंटेशन हुक नहीं है, इसलिए गैर-लैटिन लिपि वाली साइटों के लिए Orama (डिफ़ॉल्ट) या [Pagefind](#pagefind) को प्राथमिकता दें, जिसका `pagefind_extended` बाइनरी भाषाओं के एक व्यापक समूह को इंडेक्स करता है और चीनी, जापानी, और कोरियाई को नेटिव रूप से विभाजित करता है।

```ts blume.config.ts lineNumbers
search: {
  provider: "flexsearch",
}
```

### Pagefind

बहुत बड़े docs के लिए, [Pagefind](https://pagefind.app) चुनें। यह आपके बिल्ड किए गए HTML को इंडेक्स करता है और इंडेक्स को माँग पर शार्ड्स में लोड करता है, जिससे साइट चाहे कितनी भी बड़ी हो जाए, प्रारंभिक payload छोटा बना रहता है।

```ts blume.config.ts lineNumbers
search: {
  provider: "pagefind",
}
```

Pagefind केवल `blume build` के दौरान चलता है, इसलिए इस प्रोवाइडर के साथ `blume dev` में खोज उपलब्ध नहीं होती।

### Algolia

ब्राउज़र आपकी search-only key से सीधे [Algolia](https://www.algolia.com) से क्वेरी करता है। हर `blume build` इंडेक्स को `ALGOLIA_ADMIN_API_KEY` से मिली एडमिन key का उपयोग करके बदल देता है (यदि यह सेट नहीं है तो बिल्ड चेतावनी देकर अपलोड छोड़ देता है)। हर सिंक पर पूरा इंडेक्स बदल दिया जाता है, इसलिए हटाए गए या नाम बदले गए पेज बासी परिणामों के रूप में नहीं टिके रहते।

```ts blume.config.ts lineNumbers
search: {
  provider: "algolia",
  algolia: {
    appId: "YOUR_APP_ID",
    indexName: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
  },
}
```

### Orama Cloud

होस्टेड Orama। ब्राउज़र सार्वजनिक API key के साथ आपके इंडेक्स एंडपॉइंट से क्वेरी करता है; `blume build`, `ORAMA_PRIVATE_API_KEY` का उपयोग करके रिकॉर्ड इंडेक्स में भेजता है। सिंक सक्षम करने के लिए `indexId` सेट करें।

```ts blume.config.ts lineNumbers
search: {
  provider: "orama-cloud",
  oramaCloud: {
    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
    apiKey: "YOUR_PUBLIC_API_KEY",
    indexId: "your-index-id", // for the build-time sync
  },
}
```

### Typesense

सेल्फ-होस्टेड या क्लाउड [Typesense](https://typesense.org)। ब्राउज़र search-only key से कलेक्शन से क्वेरी करता है; `blume build`, `TYPESENSE_ADMIN_API_KEY` का उपयोग करके कलेक्शन फिर से बनाता है और डॉक्युमेंट इम्पोर्ट करता है। हर सिंक पर कलेक्शन हटाकर दोबारा बनाया जाता है ताकि हटाए गए या नाम बदले गए पेज बासी परिणामों के रूप में न टिकें — यदि आप कलेक्शन की सेटिंग्स हाथ से समायोजित करते हैं, तो बिल्ड के बाद उन्हें फिर से लागू करें।

```ts blume.config.ts lineNumbers
search: {
  provider: "typesense",
  typesense: {
    host: "xyz.a1.typesense.net",
    collection: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
    // port + protocol default to 443 / https
  },
}
```

### Mixedbread

[Mixedbread](https://www.mixedbread.com) के माध्यम से सिमेंटिक खोज। क्वेरीज़ एक जनरेट किए गए `/api/search` एंडपॉइंट से होकर जाती हैं जो आपकी key रखता है, इसलिए इस प्रोवाइडर को **सर्वर आउटपुट की आवश्यकता है** (`deployment.output: "server"`)। एंडपॉइंट `MIXEDBREAD_API_KEY` पढ़ता है। अपने बिल्ड में Mixedbread CLI से अपनी सामग्री को स्टोर में सिंक करें, जैसे `mxbai vs sync <STORE_ID> ./content --ci`।

```ts blume.config.ts lineNumbers
search: {
  provider: "mixedbread",
  mixedbread: {
    storeId: "YOUR_STORE_ID",
  },
}
```

### खोज को अक्षम करना

```ts blume.config.ts lineNumbers
search: {
  provider: "none",
}
```

## पेजों को बाहर रखना

केवल इंडेक्स-योग्य पेज ही खोजे जाते हैं। जब कोई पेज अपने frontmatter में `search.exclude` सेट करता है, तो उसे इंडेक्स से बाहर रखा जाता है:

```yaml
search:
  exclude: true
```

[छिपे हुए पेज](/docs/content/navigation#hidden-pages) भी डिफ़ॉल्ट रूप से बाहर रखे जाते हैं। उन्हें फिर भी इंडेक्स करने के लिए, इसे सक्षम करें:

```ts blume.config.ts lineNumbers
search: {
  indexing: { includeHiddenPages: true },
}
```

---

# SEO
Source: https://useblume.dev/hi/docs/configuration/seo

Blume आपके लिए खोज-योग्यता परत संभालता है: पेज मेटाडेटा, सोशल शेयर छवियाँ, फ़ीड और संरचित डेटा। कॉन्फ़िगर करने योग्य सुविधाएँ `blume.config.ts` में `seo` कुंजी के अंतर्गत रहती हैं; मेटाडेटा आपकी सामग्री से संचालित होता है।

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
  x: { handle: "@acme" },
}
```

इसमें से अधिकांश एक निरपेक्ष साइट URL के साथ और भी बेहतर काम करता है — [`deployment.site`](/docs/deployment) सेट करें ताकि फ़ीड, OG छवियाँ, कैनोनिकल, साइटमैप और JSON-LD पूर्ण URL उत्सर्जित कर सकें।

## मेटाडेटा

हर पेज आपके कॉन्फ़िग और फ्रंटमैटर से मानक `<head>` टैग रेंडर करता है:

- `<title>` — पेज का शीर्षक और साथ में आपकी साइट का `title`।
- `<meta name="description">` और `og:description` — पेज का `description`, जिसके न होने पर साइट का `description`।
- `og:title` और `og:site_name` — पेज का शीर्षक और आपकी साइट का `title`।
- `<link rel="canonical">` और `og:url` — पेज का निरपेक्ष URL (जब `deployment.site` सेट हो)।
- `og:type` — ब्लॉग पोस्ट और चेंजलॉग प्रविष्टियों पर `article`, अन्यत्र `website`। लेख पेज पेज के `date` और अंतिम-संशोधन टाइमस्टैम्प से `article:published_time` और `article:modified_time` भी उत्सर्जित करते हैं।
- `og:image` — पेज के लिए [OG छवि](#open-graph-images)। एक जनरेट किया गया कार्ड अपनी `og:image:width`, `og:image:height`, `og:image:type` और `og:image:alt` भी घोषित करता है, ताकि कोई क्रॉलर उसे पहले फ़ेच किए बिना ही कार्ड का लेआउट तय कर सके; आपके द्वारा स्वयं दी गई `seo.image` इनमें से कुछ भी घोषित नहीं करती, क्योंकि उसका आकार और फ़ॉर्मैट अज्ञात होता है।
- `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` — X कार्ड। जिन पेजों में छवि होती है उन्हें चौड़ा `summary_large_image` वैरिएंट मिलता है; जिनमें नहीं होती उन्हें भी सादे लिंक के रूप में रेंडर होने के बजाय संक्षिप्त `summary` कार्ड मिलता है।

### X श्रेय

X कार्ड की बाकी सारी जानकारी `og:*` टैग से पढ़ लेता है, इसलिए केवल वही मान हैं जिनका वह अनुमान नहीं लगा सकता — श्रेय देने वाले खाते। इन्हें `seo.x` के अंतर्गत सेट करें और Blume `twitter:site` (आपकी साइट का खाता) तथा `twitter:creator` (लेखक का) उत्सर्जित करता है। `@` वैकल्पिक है — `acme` और `@acme` दोनों काम करते हैं।

```ts blume.config.ts lineNumbers
seo: {
  x: { handle: "@acme", creator: "@jane" },
}
```

कोई पेज अपना स्वयं का लेखक घोषित कर सकता है, जो अतिथि पोस्ट के लिए उपयुक्त है:

```yaml lineNumbers
---
title: How we shipped it
seo:
  x:
    creator: "@guestauthor"
---
```

बाकी किसी भी टैग को प्रति-पेज `seo` फ्रंटमैटर से ओवरराइड करें:

```yaml lineNumbers
---
title: Pricing
description: Plans and pricing for every team size.
seo:
  title: Pricing — Acme
  canonical: https://acme.com/pricing
  noindex: false
---
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.title?` | `string` | - | Override the <title> and og:title for this page. |
| `seo.description?` | `string` | - | Override the meta + og:description. |
| `seo.image?` | `string` | - | Custom social image (see Open Graph). |
| `seo.canonical?` | `string` | - | Override the canonical URL. |
| `seo.noindex?` | `boolean` | - | Emit robots noindex and skip structured data. |
| `seo.x.creator?` | `string` | - | Credit this page to an X account (twitter:creator), overriding seo.x.creator from your config. |

## Open Graph छवियाँ

Blume बिल्ड समय पर हर पेज के लिए 1200×630 का सोशल कार्ड रेंडर कर सकता है — [Takumi](https://takumi.kane.tw) की बदौलत बिना हेडलेस ब्राउज़र के, इसलिए बिल्ड तेज़ बने रहते हैं। [`deployment.site`](/docs/deployment) सेट या स्वतः-पहचाना जाने पर यह डिफ़ॉल्ट रूप से चालू रहता है (`og:image` URL का निरपेक्ष होना ज़रूरी है ताकि वह क्रॉलर के काम आ सके), अन्यथा बंद। किसी भी दिशा में इसे बदलने के लिए `enabled` सेट करें:

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}
```

### जनरेट किए गए कार्ड पर ब्रांडिंग

जनरेट किए गए कार्ड को अपने ब्रांड से मिलाने के लिए एक स्थानीय SVG और रंग पैलेट सेट करें। लोगो `public/` में या प्रोजेक्ट रूट में रह सकता है। किसी भी पैलेट मान को छोड़ दें तो उसका डिफ़ॉल्ट बना रहेगा।

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

डिफ़ॉल्ट रूप से, हर कार्ड आपकी सामग्री और थीम से लिया जाता है — शीर्षपंक्ति के रूप में **पेज शीर्षक**, उपशीर्षक के रूप में **पेज विवरण** (वही पाठ जो उसका `og:description` है, इसलिए `description` पर `seo.description` वरीयता रखता है), आइब्रो के रूप में आपका **साइट शीर्षक**, और चिह्न के लिए आपकी थीम का **accent**। छवियाँ `/og/<slug>.png` पर परोसी जाती हैं, जो हर रूट का प्रतिरूप होती हैं, और सर्वर मोड में भी स्थिर फ़ाइलों के रूप में प्रीरेंडर की जाती हैं:

| पेज रूट             | छवि URL                    |
| ------------------- | -------------------------- |
| `/`                 | `/og/index.png`            |
| `/quickstart`       | `/og/quickstart.png`       |
| `/configuration/ai` | `/og/configuration/ai.png` |

किसी भी पेज के लिए जनरेट किए गए कार्ड को `seo.image` से ओवरराइड करें — `public/` में मौजूद कोई फ़ाइल या कोई बाहरी URL। यह जनरेट किए गए कार्ड पर वरीयता रखता है और `og` बंद होने पर भी काम करता है, इसलिए आप कस्टम छवियों को जनरेट की गई छवियों के साथ मिलाकर उपयोग कर सकते हैं:

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
हर पैलेट रंग कोई भी CSS रंग स्वीकार करता है — hex, `oklch(…)`, `rgb(…)`, इत्यादि। accent एक नामित प्रीसेट (`blue`, `teal`, …) भी स्वीकार करता है, जो [`theme.accent`](/docs/configuration/theming#accent) से मेल खाता है। जिस रंग को रेंडरर पार्स नहीं कर सकता, वह चुपचाप डिफ़ॉल्ट रंग वाला कार्ड भेजने के बजाय बिल्ड को विफल कर देता है।
:::

पेज शीर्षक या साइट शीर्षक में मौजूद इमोजी [Twemoji](https://github.com/jdecked/twemoji) ग्लिफ़ के रूप में रेंडर होते हैं, जो कार्ड रेंडर होते समय CDN से फ़ेच किए जाते हैं — इसलिए जिस बिल्ड के शीर्षकों में इमोजी हों उसे नेटवर्क एक्सेस चाहिए। हर ग्लिफ़ प्रति बिल्ड एक ही बार फ़ेच होता है, चाहे उसे कितने भी पेज उपयोग करें।

### कार्ड परतें दिखाएँ, छिपाएँ या ओवरराइड करें

शीर्षपंक्ति के अलावा कार्ड में तीन वैकल्पिक परतें होती हैं: ऊपर-बाईं ओर **ब्रांड चिह्न** (आपका लोगो, या साइट शीर्षक के पहले अक्षर वाली accent टाइल), शीर्षपंक्ति के नीचे **उपशीर्षक** (पेज का `description`, या जिन पेजों में वह न हो उनके लिए आपकी साइट का `description`), और आपके रेपो स्लग (`github` से) तथा साइट के URL वाला एक **फ़ुटर** — डिप्लॉयमेंट साइट का होस्ट और साथ में [`deployment.base`](/docs/deployment#subpath-deploys), जिससे किसी GitHub Pages प्रोजेक्ट साइट पर यह `user.github.io/repo` दिखता है। इनमें से किसी को भी अपनी स्ट्रिंग से ओवरराइड करें, या `false` देकर छिपाएँ:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}
```

### कार्ड फ़ॉन्ट

डिफ़ॉल्ट रूप से कार्ड Takumi के अंतर्निहित फ़ॉन्ट में रेंडर होता है, जो केवल लैटिन ग्लिफ़ को कवर करता है — किसी अन्य लिपि (जापानी, चीनी, कोरियाई, अरबी, …) में लिखा शीर्षक टोफू, यानी खाली डिब्बों के रूप में रेंडर होगा।

**[`theme.fonts`](/docs/configuration/theming#fonts) सेट करें और कार्ड उसी का अनुसरण करेगा।** जब आपका कॉन्फ़िग अपने फ़ॉन्ट चुनता है, तो जनरेट किए गए कार्ड स्वतः ही शीर्षपंक्ति को आपके डिस्प्ले फ़ॉन्ट में और विवरण तथा फ़ुटर को आपके बॉडी फ़ॉन्ट में रेंडर करते हैं, जिससे साझा किए गए लिंक साइट से मेल खाते हैं — इसमें ग़ैर-लैटिन कवरेज भी शामिल है, और यहाँ कुछ भी कॉन्फ़िगर करने की ज़रूरत नहीं। (ग़ैर-Google प्रदाताओं के फ़ॉन्ट परिवार छोड़ दिए जाते हैं — कार्ड रेंडरर केवल Google Fonts से फ़ेच कर सकता है — लेकिन स्थानीय फ़ॉन्ट फ़ाइलें काम करती हैं।)

कार्ड पर साइट से अलग फ़ॉन्ट उपयोग करने के लिए, या थीम को छुए बिना लिपि कवरेज जोड़ने के लिए, `og.fonts` स्पष्ट रूप से सेट करें — यह हमेशा थीम-आधारित फ़ॉन्ट पर भारी पड़ता है:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

हर प्रविष्टि या तो कोई Google Fonts परिवार नाम है, या एक ऑब्जेक्ट जो उसका `weight` (एक संख्या, एक सूची, या `"100..900"` जैसी वेरिएबल रेंज) और `style` (`"normal"`, `"italic"`, या दोनों) तय करता है, या फिर एक स्थानीय फ़ॉन्ट फ़ाइल — `src` प्रोजेक्ट रूट से हल होता है, और जब फ़ाइल का अपना मेटाडेटा निर्णायक नहीं होना चाहिए तब वैकल्पिक `weight` तथा `style` के साथ।

Google परिवार बिल्ड के समय फ़ेच किए जाते हैं — इसलिए इनका उपयोग करने वाले बिल्ड को नेटवर्क एक्सेस चाहिए — और रेंडरर केवल वही ग्लिफ़ सबसेट खींचता है जो प्रत्येक शीर्षक वास्तव में उपयोग करता है। फ़ॉलबैक प्रति-ग्लिफ़ होता है, इसलिए कोई परिवार जोड़ने का असर केवल उन्हीं ग्लिफ़ पर पड़ता है जिन्हें दूसरे फ़ॉन्ट नहीं बना सकते।

स्पष्ट रूप से `og.fonts: []` देने का अर्थ है पूरी तरह बाहर निकलना: `theme.fonts` सेट होने पर भी कार्ड अंतर्निहित फ़ॉन्ट ही रखते हैं।

### कस्टम पेज शीर्षक

किसी कस्टम [`.astro` पेज](/docs/advanced/custom-pages) के पास पढ़ने के लिए फ्रंटमैटर नहीं होता, इसलिए उसके जनरेट किए गए कार्ड का शीर्षक उसके रूट के अंतिम URL खंड को मानव-पठनीय बनाकर तय होता है — `/getting-started` बन जाता है "Getting Started", लेकिन `/cli` बन जाता है "Cli"। ऐसे कार्डों को `og.titles` से स्पष्ट रूप से नाम दें, जिसकी कुंजी रूट होती है (`"/"` होम को संबोधित करता है, जिसका कार्ड अन्यथा साइट शीर्षक धारण करता है):

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

प्रविष्टियाँ केवल कस्टम पेजों पर लागू होती हैं — किसी सामग्री पेज का कार्ड अपनी शीर्षपंक्ति हमेशा पेज शीर्षक से लेता है, इसलिए उनका नाम बदलने के लिए फ्रंटमैटर का उपयोग करें।

`seo.image` फ्रंटमैटर है, इसलिए यह केवल Markdown और MDX सामग्री को कवर करता है। किसी कस्टम [`.astro` पेज](/docs/advanced/custom-pages) को उसकी अपनी सोशल छवि देने के लिए — जैसे कोई मार्केटिंग होम या लैंडिंग पेज, और केवल होम पेज को एक विशेष शेयर छवि देने का यही तरीका है — `PageLayout` को `ogImage` प्रॉप पास करें।

## RSS फ़ीड

Blume `rss.types` में मौजूद हर उस सामग्री प्रकार के लिए एक RSS फ़ीड बनाता है जिसमें पेज हों — डिफ़ॉल्ट रूप से `blog` और `changelog` — जो `/<type>/rss.xml` पर परोसी जाती है। तिथियों के साथ ब्लॉग और चेंजलॉग प्रविष्टियाँ लिखने के लिए [फ़ीड](/docs/content#feeds) देखें।

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

| विकल्प | डिफ़ॉल्ट | विवरण |
| --- | --- | --- |
| `enabled` | `true` | फ़ीड जनरेट करें। |
| `types` | `["blog", "changelog"]` | वे सामग्री प्रकार जिन्हें एक-एक फ़ीड मिलती है। |
| `limit` | `50` | प्रति फ़ीड अधिकतम आइटम, नवीनतम पहले। |

Blume `<link rel="alternate">` टैग इंजेक्ट करता है ताकि ब्राउज़र और फ़ीड रीडर फ़ीड को स्वतः खोज सकें।

## संरचित डेटा

Blume हर पेज के `<head>` में [schema.org](https://schema.org) JSON-LD उत्सर्जित करता है ताकि सर्च इंजन आपकी सामग्री को समझ सकें। डिफ़ॉल्ट रूप से चालू:

```ts blume.config.ts lineNumbers
seo: {
  structuredData: true,
}
```

हर पेज में शामिल है:

- साइट पहचान के लिए एक **WebSite** नोड,
- पेज को एक **article** के रूप में — ब्लॉग पोस्ट के लिए `BlogPosting`, चेंजलॉग और डॉक्स के लिए `TechArticle` — उसके विवरण और प्रकाशन तिथि के साथ,
- नेविगेशन ट्रेल से बनी एक **BreadcrumbList**।

जब `deployment.site` सेट होता है तो URL निरपेक्ष होते हैं। `seo.noindex` से चिह्नित पेज छोड़ दिए जाते हैं।

### साइट पहचान

WebSite नोड यह बताता है कि कोई साइट मौजूद है; यह नहीं बताता कि वह _क्या_ है या उसे _कौन_ चलाता है — और AI एजेंट आपकी अनुशंसा या उद्धरण देने से पहले JSON-LD इसी के लिए पढ़ते हैं। दो वैकल्पिक ब्लॉक इसकी पूर्ति करते हैं, और दोनों के लिए `deployment.site` चाहिए (ये नोड निरपेक्ष पहचानकर्ता धारण करते हैं):

```ts blume.config.ts lineNumbers
seo: {
  organization: {
    name: "Acme", // defaults to the site title
    email: "hello@acme.com",
    telephone: "+1 555 0100",
    address: { addressLocality: "Sydney", addressCountry: "AU" },
    logo: "/logo.svg",
    sameAs: ["https://github.com/acme", "https://x.com/acme"],
  },
  software: {
    license: "MIT",
    operatingSystem: "Node.js 22+",
    price: 0, // emitted as an Offer; 0 marks it free
    sameAs: ["https://www.npmjs.com/package/acme"],
  },
}
```

`organization` हर पेज में एक **Organization** नोड जोड़ता है — WebSite और article नोड उसे `publisher` के रूप में उद्धृत करते हैं — जिसमें ईमेल और टेलीफ़ोन एक `ContactPoint` के रूप में (`contactType` डिफ़ॉल्ट रूप से `"customer support"`) और पता एक `PostalAddress` के रूप में रहता है, यानी वे दो फ़ील्ड जिन्हें व्यवसाय-सत्यापन जाँचें खोजती हैं। `name` और `url` डिफ़ॉल्ट रूप से साइट के होते हैं; रूट-सापेक्ष `logo` को किसी भी पेज URL की तरह निरपेक्ष बना दिया जाता है।

`software` होमपेज में एक **SoftwareApplication** नोड जोड़ता है: उत्पाद का नाम और विवरण (डिफ़ॉल्ट रूप से साइट के), `applicationCategory` (डिफ़ॉल्ट `"DeveloperApplication"`), ऑपरेटिंग सिस्टम, लाइसेंस, `price` सेट होने पर एक `Offer`, और `sameAs` में रजिस्ट्री या रिपॉज़िटरी URL। हर डिफ़ॉल्ट अपनाने के लिए `software: true` पास करें। कॉन्फ़िगर किए जाने पर संगठन को उसके `publisher` के रूप में उद्धृत किया जाता है।

## साइटमैप

Blume बिल्ड समय पर हर इंडेक्स-योग्य पेज का `sitemap.xml` लिखता है। इसके लिए निरपेक्ष [`deployment.site`](/docs/deployment) चाहिए और यह ड्राफ़्ट, छिपे हुए तथा `noindex` पेजों को छोड़कर हर पेज सूचीबद्ध करता है। किसी [संस्करणित](/docs/content/versioning) साइट पर, वे संग्रहीत पेज भी छोड़ दिए जाते हैं जिनका कैनोनिकल उनके लाइव समकक्ष की ओर इशारा करता है — इंडेक्स किया जाने वाला पेज लाइव पेज ही है। डिफ़ॉल्ट रूप से चालू:

```ts blume.config.ts lineNumbers
seo: {
  sitemap: true,
}
```

नियंत्रण अपने हाथ में लेने के लिए अपना स्वयं का `public/sitemap.xml` भेजें — `public/` में रखी गई किसी फ़ाइल को Blume कभी अधिलेखित नहीं करता।

## Robots

Blume एक `robots.txt` लिखता है जो सभी क्रॉलर को अनुमति देता है, आपके [कंटेंट सिग्नल](#content-signals) घोषित करता है, और साइटमैप उपलब्ध होने पर उस ओर इशारा करती हुई एक `Sitemap:` पंक्ति जोड़ता है। डिफ़ॉल्ट रूप से चालू:

```ts blume.config.ts lineNumbers
seo: {
  robots: true,
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://docs.example.com/sitemap.xml
```

### कंटेंट सिग्नल

`Content-Signal` पंक्ति — उभरती हुई कंटेंट-उपयोग परिपाटी — यह घोषित करती है कि AI क्रॉलर आपके डॉक्स का पुनः उपयोग कैसे कर सकते हैं। Blume इसे **डिफ़ॉल्ट रूप से चालू रखते हुए हर सिग्नल को `yes` पर** उत्सर्जित करता है, जो उसके इस रुख से मेल खाता है कि डॉक्स मनुष्यों और एजेंटों दोनों के लिए खुले हैं:

- `search` — पारंपरिक और AI सर्च इंडेक्सिंग
- `aiInput` — उत्तर देते समय ग्राउंडिंग / RAG
- `aiTrain` — मॉडल प्रशिक्षण

किसी भी सिग्नल को `false` पर सेट करके सीमित करें; जिन्हें आप छोड़ देंगे वे `yes` ही रहेंगे:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: {
    aiTrain: false, // opt out of training, keep search + grounding
  },
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /
```

घोषणा को पूरी तरह हटाने के लिए `contentSignals: false` सेट करें:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: false,
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.contentSignals?` | `boolean \| object` | - | Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually. |
| `contentSignals.search?` | `boolean` | - | Allow use for search indexing (search). Default true. |
| `contentSignals.aiInput?` | `boolean` | - | Allow use for AI grounding / RAG at answer time (ai-input). Default true. |
| `contentSignals.aiTrain?` | `boolean` | - | Allow use for AI model training (ai-train). Default true. |

कंटेंट सिग्नल एक प्राथमिकता व्यक्त करते हैं, एक्सेस नियंत्रण नहीं: वे सुव्यवस्थित ढंग से व्यवहार करने वाले क्रॉलर को बताते हैं कि आप अपनी सामग्री का उपयोग कैसे चाहते हैं, और उनका पालन करना क्रॉलर पर निर्भर है।

नियंत्रण अपने हाथ में लेने के लिए अपना स्वयं का `public/robots.txt` भेजें।

---

# थीमिंग
Source: https://useblume.dev/hi/docs/configuration/theming

Blume की थीम टोकन-संचालित है और लाइट व डार्क मोड में बिना किसी अतिरिक्त सेटअप के काम करती है। जितनी ज़रूरत हो उतना ही इस्तेमाल करें: आम मामलों के लिए कुछ कॉन्फ़िग टोकन, किसी भी डिज़ाइन टोकन को ओवरराइड करने के लिए एक `theme.css`, या कस्टम कंपोनेंट्स के लिए Tailwind यूटिलिटीज़।

## कॉन्फ़िग टोकन

रोज़मर्रा के नॉब आपकी कॉन्फ़िग में `theme` के अंतर्गत रहते हैं:

```ts blume.config.ts lineNumbers
theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}
```

### एक्सेंट

एक्सेंट रंग इंटरैक्टिव और हाइलाइट किए गए एलिमेंट्स को रंगत देता है — स्टेप मार्कर, सक्रिय टैब, बैज, कार्ड होवर, और भी बहुत कुछ। किसी नामित प्रीसेट या किसी भी CSS रंग का उपयोग करें:

```ts blume.config.ts lineNumbers
theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}
```

नामित प्रीसेट: `blue` (डिफ़ॉल्ट), `green`, `orange`, `pink`, `purple`, `red`, और `teal`।

एक स्ट्रिंग दोनों कलर मोड पर लागू होती है; [हर मोड के लिए अलग एक्सेंट](#dark-mode-colors) देने के लिए एक ऑब्जेक्ट पास करें।

### रेडियस

`radius` कार्ड्स, कोड ब्लॉक्स, कॉलआउट्स और इनपुट्स द्वारा साझा किए जाने वाले कोने के गोलाकारपन को सेट करता है — `none`, `sm`, `md` (डिफ़ॉल्ट), या `lg`।

### कलर मोड

`mode` प्रारंभिक कलर स्कीम सेट करता है:

- **`system`** (डिफ़ॉल्ट) — पाठक की OS प्राथमिकता का अनुसरण करता है
- **`light`** / **`dark`** — किसी एक स्कीम को डिफ़ॉल्ट बनाता है

हेडर में मौजूद एक टॉगल पाठकों को हमेशा स्विच करने देता है, और उनकी पसंद विज़िट्स के बीच याद रखी जाती है। डार्क मोड `<html>` एलिमेंट पर `data-theme="dark"` एट्रिब्यूट के साथ लागू किया जाता है।

### फ़ॉन्ट्स

`fonts` तीन भूमिकाओं के लिए टाइपफ़ेस सेट करता है:

- **`display`** — शीर्षक (`h1`–`h6`)
- **`body`** — बॉडी टेक्स्ट, UI, और प्रोज़
- **`mono`** — कोड ब्लॉक और इनलाइन कोड

शीर्षकों को डिस्प्ले-स्तर की letter-spacing (`-0.05em`) थीम से ही मिलती है, इसलिए आप `display` के लिए जो भी चुनें — Inter डिफ़ॉल्ट जैसे टेक्स्ट फ़ॉन्ट सहित — शीर्षक बड़े आकार में सही दिखते हैं, फ़ॉन्ट में निर्मित tracking पर निर्भर हुए बिना।

प्रत्येक का डिफ़ॉल्ट एक चयनित Google Font है, इसलिए Blume शुरुआत से ही सुविचारित दिखता है:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}
```

केवल वही भूमिकाएँ सेट करें जिन्हें आप बदलना चाहते हैं — बाकी अपने डिफ़ॉल्ट पर बनी रहती हैं:

```ts blume.config.ts lineNumbers
theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}
```

फ़ॉन्ट्स **सेल्फ़-होस्टेड** होते हैं: Blume उन्हें बिल्ड टाइम पर डाउनलोड करता है और आपकी अपनी साइट से सर्व करता है, इसलिए Google को कोई रनटाइम रिक्वेस्ट नहीं जाती और कोई लेआउट शिफ्ट नहीं होता (Astro स्वतः फ़ॉलबैक-मेट्रिक फ़ेस जनरेट करता है)।

एक सादा स्ट्रिंग नीचे दिए गए चयनित सेट में से एक Google Fonts स्लग है:

| श्रेणी | स्लग |
| --- | --- |
| सैन्स | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
| सेरिफ़ | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4` |
| मोनो | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono` |

#### किसी भी प्रोवाइडर की फ़ैमिली

क्या आपको ऐसी फ़ैमिली चाहिए जो चयनित सेट में नहीं है — मान लीजिए, कोई जो ग़ैर-लैटिन लिपि को कवर करती हो? फ़ैमिली के सटीक नाम के साथ एक ऑब्जेक्ट पास करें। यह उसी तरह सेल्फ़-होस्टेड और ऑप्टिमाइज़ की जाती है:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}
```

- **`name`** — फ़ैमिली का नाम ठीक वैसे ही जैसे प्रोवाइडर उसे सूचीबद्ध करता है।
- **`provider`** — फ़ैमिली कहाँ से आती है: `google` (डिफ़ॉल्ट), `fontsource`, `bunny`, या `fontshare`।
- **`weights`** — लोड किए जाने वाले वेट, संख्याओं के रूप में या `"100..900"` जैसी वेरिएबल रेंज के रूप में। डिफ़ॉल्ट `[400, 500, 600, 700]` है।
- **`subsets`** — लोड किए जाने वाले कैरेक्टर सबसेट, प्रोवाइडर के नामों के अनुसार (`latin`, `latin-ext`, `vietnamese`, `cyrillic`, `greek`, …)। डिफ़ॉल्ट रूप से `latin` के साथ वह सब जो आपके कॉन्फ़िगर किए गए लोकेल के लिए ज़रूरी है — नीचे देखें।
- **`fallback`** — फ़ॉन्ट लोड होने के दौरान और अनुपलब्ध ग्लिफ़ के लिए दिखाया जाने वाला सिस्टम स्टैक: `sans`, `serif`, या `mono`। मोनो भूमिका के लिए डिफ़ॉल्ट `mono` है और अन्यथा `sans`।

#### सबसेट और लोकेल

Google, Bunny, और Fontsource हर फ़ैमिली को प्रति-लिपि सबसेट में बाँटते हैं, और केवल उन्हीं सबसेट को `@font-face` मिलता है जिन्हें आप लोड करते हैं। Blume यह सूची आपके [`i18n.locales`](/docs/content/i18n) से निकालता है: वियतनामी, पोलिश, रूसी, या ग्रीक लोकेल वाली साइट `latin` के साथ-साथ `vietnamese`, `latin-ext`, `cyrillic`, या `greek` लोड करती है, ताकि डायक्रिटिक्स और ग़ैर-लैटिन अक्षर सिस्टम फ़ॉलबैक के बजाय आपके चुने हुए फ़ॉन्ट में रेंडर हों। जिन साइटों में `i18n` ब्लॉक नहीं है, या जिनमें केवल लैटिन-1 भाषाएँ हैं, वे अकेले `latin` लोड करती हैं। ब्राउज़र किसी सबसेट को तभी डाउनलोड करते हैं जब कोई पेज उसके कैरेक्टर इस्तेमाल करता है, और प्रीलोड भी उसी सूची का अनुसरण करते हैं।

निकाली गई सूची को ओवरराइड करने के लिए किसी फ़ैमिली पर `subsets` सेट करें — मान लीजिए, ऐसी एकल-लोकेल साइट के लिए जिसके कंटेंट को फिर भी ऐसी लिपि चाहिए जिसका संकेत उसका लोकेल नहीं देता:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}
```

`inter` जैसे चयनित स्लग लोकेल से निकाली गई सूची का अनुसरण करते हैं; उन फ़ैमिलीज़ के लिए भी सबसेट तय करने हेतु ऑब्जेक्ट रूप का उपयोग करें।

#### लोकल फ़ॉन्ट फ़ाइलें

ऐसे फ़ॉन्ट के लिए जो आपका अपना है (या जिसे कोई प्रोवाइडर सर्व नहीं करता), किसी भूमिका को अपने प्रोजेक्ट की फ़ॉन्ट फ़ाइलों की ओर इंगित करें। हर वेरिएंट एक `@font-face` बन जाता है:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}
```

पाथ प्रोजेक्ट रूट से रिज़ॉल्व होते हैं। `weight` और `style` (`normal`, `italic`, `oblique`) वैकल्पिक हैं — छोड़ देने पर Astro उन्हें फ़ॉन्ट फ़ाइल से पढ़ लेता है।

:::note
जब आप `theme.fonts` को स्पष्ट रूप से सेट करते हैं, तो आपके display और body फ़ॉन्ट स्वतः जनरेट किए गए [Open Graph कार्ड्स](/docs/configuration/seo#card-fonts) को भी स्टाइल करते हैं, ताकि शेयर किए गए लिंक साइट से मेल खाएँ। ग़ैर-Google प्रोवाइडर फ़ैमिलीज़ वहाँ छोड़ दी जाती हैं (कार्ड रेंडरर केवल Google Fonts से फ़ेच कर सकता है); लोकल फ़ाइलें हर जगह काम करती हैं।
:::

सिस्टम स्टैक पर वापस लौटना चाहते हैं? [`theme.css`](#themecss) में सीधे `--blume-font-*` टोकन ओवरराइड करें।

### डार्क-मोड रंग

`accent` और `background` एक ही नियम का पालन करते हैं: एक स्ट्रिंग दोनों कलर मोड पर लागू होती है, और एक `{ light, dark }` ऑब्जेक्ट हर मोड को अलग-अलग सेट करता है:

```ts blume.config.ts lineNumbers
theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}
```

हर रंग एक नामित प्रीसेट या कोई भी CSS रंग लेता है। `background` (और `backgroundImage`) के लिए किसी भी की को छोड़कर केवल एक मोड को ओवरराइड किया जा सकता है — `background: { dark: "#0a0a0a" }` डिफ़ॉल्ट लाइट बैकग्राउंड को बनाए रखता है।

### एक्शन रंग

`action` प्राथमिक कॉल-टू-एक्शन और `action` Tailwind यूटिलिटीज़ (`bg-action`, `text-action`) के लिए एक द्वितीयक एक्सेंट है। यह डिफ़ॉल्ट रूप से आपके `accent` पर सेट होता है:

```ts blume.config.ts
theme: {
  action: "#ff0066",
}
```

### बैकग्राउंड इमेज

`backgroundImage` के साथ अपने कंटेंट के पीछे एक बैकग्राउंड इमेज सेट करें — एक URL या `public/` के अंतर्गत एक पाथ। रंगों की तरह, एक स्ट्रिंग दोनों मोड पर लागू होती है और एक `{ light, dark }` ऑब्जेक्ट हर मोड की इमेज सेट करता है:

```ts blume.config.ts lineNumbers
theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}
```

## theme.css

किसी भी डिज़ाइन टोकन को ओवरराइड करने के लिए अपने प्रोजेक्ट रूट में एक `theme.css` रखें। यह कैस्केड की आख़िरी लेयर है, इसलिए यह डिफ़ॉल्ट्स और कॉन्फ़िग टोकन पर भारी पड़ती है:

```css theme.css lineNumbers
:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}
```

लाइट मोड के लिए टोकन `:root` के अंतर्गत और डार्क मोड के लिए `:root[data-theme="dark"]` के अंतर्गत सेट करें। कलर टोकन के अलग बिल्ट-इन डार्क मान डार्क सिलेक्टर की उच्चतर विशिष्टता पर घोषित होते हैं, इसलिए `--blume-accent`, `--blume-background`, और उनके साथियों का केवल `:root` में किया गया ओवरराइड सिर्फ़ लाइट मोड पर लागू होता है — जब दोनों मोड बदलने हों तो डार्क ब्लॉक भी घोषित करें।

`theme.css` साइट की Tailwind एंट्री में इनलाइन कर दी जाती है, इसलिए इसमें Tailwind डायरेक्टिव भी काम करते हैं। मोनोरेपो के लिए जानने योग्य डायरेक्टिव `@source` है: Blume यूटिलिटी क्लासेस के लिए आपके प्रोजेक्ट को स्कैन करता है, और जो पेज किसी सहोदर वर्कस्पेस पैकेज से कंपोनेंट्स इम्पोर्ट करता है, उसके लिए उस पैकेज को भी स्कैन किया जाना ज़रूरी है। उसकी ओर `theme.css` के सापेक्ष इंगित करें — मानक Tailwind नियम — और Blume उस पाथ को जनरेट की गई शीट में ले जाता है:

```css theme.css lineNumbers
@source "../../packages/ui/src";
```

### डिज़ाइन टोकन

| टोकन                        | क्या नियंत्रित करता है                     |
| --------------------------- | ------------------------------------------ |
| `--blume-background`        | पेज बैकग्राउंड                             |
| `--blume-foreground`        | बॉडी टेक्स्ट                               |
| `--blume-muted`             | हल्की सतहें — कॉलआउट, टेबल हेडर            |
| `--blume-muted-foreground`  | द्वितीयक टेक्स्ट                           |
| `--blume-border`            | बॉर्डर और डिवाइडर                          |
| `--blume-accent`            | एक्सेंट रंग                                |
| `--blume-accent-foreground` | एक्सेंट बैकग्राउंड पर टेक्स्ट और आइकन      |
| `--blume-action`            | द्वितीयक एक्सेंट (डिफ़ॉल्ट रूप से एक्सेंट) |
| `--blume-code-background`   | कोड ब्लॉक सतह                              |
| `--blume-radius`            | कोने का रेडियस                             |
| `--blume-font-display`      | शीर्षक फ़ॉन्ट                              |
| `--blume-font-body`         | बॉडी / UI फ़ॉन्ट                           |
| `--blume-font-mono`         | कोड फ़ॉन्ट                                 |

चयनित सूची से बाहर का कोई फ़ॉन्ट इस्तेमाल करने के लिए, या सिस्टम स्टैक पर वापस लौटने के लिए, किसी `--blume-font-*` टोकन को कोई भी फ़ॉन्ट स्टैक सेट करें:

```css theme.css lineNumbers
:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

## Tailwind यूटिलिटीज़

Blume की थीम आंतरिक रूप से Tailwind v4 के साथ बनी है, और आपके प्रोजेक्ट की `.astro`, `.tsx`, और `.jsx` फ़ाइलें भी स्कैन की जाती हैं — इसलिए आप कस्टम कंपोनेंट्स और पेजों को यूटिलिटी क्लासेस से स्टाइल कर सकते हैं, किसी Tailwind सेटअप की ज़रूरत नहीं। हर टोकन एक यूटिलिटी के रूप में उपलब्ध है, इसलिए आपके कंपोनेंट स्वतः थीम के अनुरूप चलते हैं:

| टोकन                        | यूटिलिटीज़                 |
| --------------------------- | -------------------------- |
| `--blume-background`        | `bg-background`            |
| `--blume-foreground`        | `text-foreground`          |
| `--blume-muted`             | `bg-muted`                 |
| `--blume-muted-foreground`  | `text-muted-foreground`    |
| `--blume-border`            | `border-border`            |
| `--blume-accent`            | `bg-accent`, `text-accent` |
| `--blume-accent-foreground` | `text-accent-foreground`   |
| `--blume-action`            | `bg-action`, `text-action` |
| `--blume-radius`            | `rounded-blume`            |
| `--blume-font-display`      | `font-display`             |
| `--blume-font-body`         | `font-sans`                |
| `--blume-font-mono`         | `font-mono`                |

## कैस्केड क्रम

स्टाइल तीन लेयर में रिज़ॉल्व होते हैं, हर लेयर पिछली को ओवरराइड करती है:

1. **बेस**

    Blume का रीसेट, डिफ़ॉल्ट टोकन, और कंपोनेंट स्टाइल।

2. **कॉन्फ़िग टोकन**

    `theme` से आने वाले `--blume-accent`, `--blume-radius`, और `--blume-font-*`
    टोकन।

3. **theme.css**

    आपके टोकन ओवरराइड — अंतिम फ़ैसला।

---

# पेज
Source: https://useblume.dev/hi/docs/content

आपके डॉक्स केवल Markdown और MDX फ़ाइलों का एक फ़ोल्डर हैं। Blume हर फ़ाइल को एक पेज में बदल देता है — रूटिंग, नेविगेशन और मेटाडेटा फ़ाइल सिस्टम से अनुमानित होते हैं, इसलिए सिंक में रखने के लिए कोई मैनिफ़ेस्ट नहीं होता।

कंटेंट आपके **कंटेंट रूट** के अंतर्गत रहता है (डिफ़ॉल्ट रूप से `docs/`; इसे [`blume.config.ts`](/docs/configuration) में `content.root` से बदलें)।

## Markdown और MDX

Blume दो तरह की फ़ाइलें रेंडर करता है:

- **`.md`** — सादे गद्य के लिए Markdown: GFM, frontmatter, स्मार्ट विराम-चिह्न, और सुपरस्क्रिप्ट/सबस्क्रिप्ट।
- **`.mdx`** — वह सब कुछ जो `.md` में है, साथ ही [कंपोनेंट्स](/docs/content/components) और केवल MDX वाले [डायरेक्टिव, पैकेज इंस्टॉल, और गणित](/docs/content/syntax)।

जब कोई पेज केवल गद्य हो तो `.md` चुनें, और जब उसमें कंपोनेंट्स या डायरेक्टिव चाहिए हों तो `.mdx`। बदलना बस फ़ाइल का नाम बदलने जितना आसान है।

## फ़ाइलें और रूट्स

हर फ़ाइल कंटेंट रूट के अंतर्गत अपने पाथ के अनुसार एक रूट से मैप होती है:

| फ़ाइल                     | रूट               |
| ------------------------- | ----------------- |
| `docs/index.mdx`          | `/`               |
| `docs/quickstart.mdx`     | `/quickstart`     |
| `docs/guides/theming.mdx` | `/guides/theming` |
| `docs/guides/index.mdx`   | `/guides`         |

नेस्टेड फ़ोल्डर नेस्टेड रूट बन जाते हैं, और किसी फ़ोल्डर के अंदर मौजूद `index.mdx` उस फ़ोल्डर का अपना पेज बन जाता है।

## संख्यात्मक उपसर्गों से क्रम तय करना

साइडबार में क्रम नियंत्रित करने के लिए किसी फ़ाइल या फ़ोल्डर के आगे एक संख्या लगाएँ। यह उपसर्ग URL से हटा दिया जाता है, इसलिए आप लिंक तोड़े बिना पेजों का क्रम बदल सकते हैं:

```txt
01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation
```

क्रम निर्धारण की कई परतें हैं — पूरी प्राथमिकता नियमावली के लिए [नेविगेशन](/docs/content/navigation) देखें।

## समूह फ़ोल्डर

किसी फ़ोल्डर के नाम को कोष्ठकों में लपेटें ताकि उसके पेज साइडबार में समूहित हो जाएँ, **बिना** कोई URL सेगमेंट जोड़े:

```txt
docs/(internal)/security.mdx  ->  /security
```

ये पेज एक साझा “Internal” साइडबार समूह में रहते हैं, लेकिन उनके URL सपाट और कोष्ठक-रहित बने रहते हैं।

## ड्राफ़्ट

किसी पेज को ड्राफ़्ट के रूप में चिह्नित करें ताकि वह प्रोडक्शन बिल्ड से बाहर रहे, फिर भी `blume dev` में उसका पूर्वावलोकन किया जा सके:

```yaml lineNumbers
---
title: Work in progress
draft: true
---
```

`blume build` ड्राफ़्ट को छोड़ देता है; `blume dev` उन्हें रेंडर करता है ताकि आप खुले में काम कर सकें।

## कंटेंट प्रकार

हर पेज का एक **प्रकार** होता है, जो `type` frontmatter फ़ील्ड से तय होता है (डिफ़ॉल्ट `doc`)। प्रकार Blume को पेजों के समूहों के साथ अलग-अलग व्यवहार करने देते हैं — सबसे महत्वपूर्ण यह कि `blog` और `changelog` पेज [फ़ीड](#feeds) में एकत्र किए जाते हैं।

```yaml lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---
```

प्रकार इस बात से स्वतंत्र है कि फ़ाइल कहाँ रहती है, लेकिन परंपरा के अनुसार ब्लॉग पोस्ट `blog/` के अंतर्गत और चेंजलॉग प्रविष्टियाँ `changelog/` के अंतर्गत रखी जाती हैं। दोनों को अपने आप एक RSS फ़ीड मिलती है, और चेंजलॉग प्रविष्टियाँ एक जनरेट की गई [`/changelog` टाइमलाइन](/docs/advanced/changelog) में भी एकत्र होती हैं। प्रत्येक को लिखने के लिए [ब्लॉग](/docs/advanced/blog) और [चेंजलॉग](/docs/advanced/changelog) देखें।

## फ़ीड

Blume [`rss.types`](/docs/configuration/seo#rss-feeds) में सूचीबद्ध हर कंटेंट प्रकार के लिए अपने आप एक RSS फ़ीड जनरेट करता है — डिफ़ॉल्ट रूप से `blog` और `changelog` — बशर्ते उसमें कम से कम एक पेज हो। फ़ीड `/<type>/rss.xml` पर सर्व की जाती हैं:

| प्रकार      | फ़ीड                 |
| ----------- | -------------------- |
| `blog`      | `/blog/rss.xml`      |
| `changelog` | `/changelog/rss.xml` |

हर प्रविष्टि को एक `date` दें ताकि आइटम नए-से-पुराने क्रम में सज सकें और उनमें `pubDate` हो। बिना उद्धरण चिह्न वाली YAML तिथि ठीक है — Blume उसे सामान्यीकृत कर देता है:

```yaml lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---
```

फ़ीड को एक निरपेक्ष साइट URL चाहिए, इसलिए [`deployment.site`](/docs/deployment) सेट करें। Blume हर पेज में `<link rel="alternate">` टैग जोड़ता है ताकि ब्राउज़र और फ़ीड रीडर उन्हें अपने आप खोज लें। प्रत्येक कंटेंट प्रकार को लिखने के लिए [ब्लॉग](/docs/advanced/blog) और [चेंजलॉग](/docs/advanced/changelog) देखें।

## इस पेज पर

हर पेज को उसके शीर्षकों से बनी एक स्वचालित विषय-सूची मिलती है। चौड़ी स्क्रीन पर यह आपके कंटेंट के बगल में एक स्टिकी साइडबार में रहती है; सँकरी स्क्रीन पर यह पेज के ऊपर एक **इस पेज पर** पैनल में सिमट जाती है। जैसे-जैसे आप स्क्रॉल करते हैं, आप जिस सेक्शन को पढ़ रहे होते हैं उसकी प्रविष्टि हाइलाइट हो जाती है, ताकि लंबे पेज में आपको हमेशा पता रहे कि आप कहाँ हैं।

Blume हर शीर्षक को एक ऐंकर में स्लगिफ़ाई करता है, इसलिए हर प्रविष्टि सीधे अपने सेक्शन से लिंक होती है — और आप URL के अंत में उसका स्लग जोड़कर किसी भी शीर्षक तक डीप-लिंक कर सकते हैं (`.../my-page#getting-started`)।

विषय-सूची में आपके `##` और `###` शीर्षक (H2 और H3) सूचीबद्ध होते हैं। जिस पेज में उस स्तर का कोई शीर्षक नहीं होता, उसमें बस कोई विषय-सूची नहीं होती।

## आगे कहाँ जाएँ

**[Frontmatter](/docs/reference/frontmatter)**

पेज मेटाडेटा: शीर्षक, विवरण, साइडबार, SEO, और सर्च।

**[सिंटैक्स](/docs/content/syntax)**

हर Markdown और MDX सुविधा जो आप लिख सकते हैं।

**[कंपोनेंट्स](/docs/content/components)**

किसी भी MDX पेज में उपलब्ध JSX कंपोनेंट्स।

**[नेविगेशन](/docs/content/navigation)**

साइडबार, क्रम और टैब्स को आकार दें।

**[फ़ोल्डर मेटा](/docs/content/meta)**

किसी साइडबार समूह को `meta.ts` फ़ाइल से कॉन्फ़िगर करें।

---

# घटक
Source: https://useblume.dev/hi/docs/content/components

Blume एक सुलभ, थीम-योग्य घटक सेट के साथ आता है जो किसी भी `.mdx` पेज में **बिना किसी import के** उपलब्ध है। हर एक को नीचे एक लाइव प्रीव्यू और उसके सोर्स के साथ दिखाया गया है। घटक वनीला हैं और React-मुक्त हैं; React तभी सक्रिय होता है जब आप अपना स्वयं का आइलैंड जोड़ते हैं।

## Card और CardGroup

कार्ड किसी गंतव्य से एक आइकन, शीर्षक और छोटे विवरण के साथ लिंक करते हैं। उत्तरदायी ग्रिड के लिए उन्हें `CardGroup` से समूहबद्ध करें। इनका उपयोग लैंडिंग पेजों, सेक्शन इंडेक्स और “अगले कदम” पर करें — जहाँ भी आप पाठक को आगे की ओर मार्गदर्शित कर रहे हों।

**[Quickstart](/docs/quickstart)**

Blume इंस्टॉल करें और अपना पहला पेज प्रकाशित करें।

**[Components](/docs/content/components)**

घटक लाइब्रेरी ब्राउज़ करें।

```astro lineNumbers
<CardGroup cols={2}>
  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
    Install Blume and ship your first page.
  </Card>
  <Card title="Components" href="/docs/content/components" icon="folder">
    Browse the component library.
  </Card>
</CardGroup>
```

`Card` में `title`, एक वैकल्पिक `href` (क्लिक न किए जा सकने वाले कार्ड के लिए इसे छोड़ दें), और Blume के अंतर्निहित आइकन सेट से एक `icon` लिया जाता है। `CardGroup` में `cols` लिया जाता है (डिफ़ॉल्ट `2`)।

## Steps

क्रमबद्ध निर्देशों के लिए एक क्रमांकित ऊर्ध्वाधर अनुक्रम — इंस्टॉल, सेटअप प्रवाह और ऐसे ट्यूटोरियल जहाँ क्रम मायने रखता है। हर `Step` में एक `title` लिया जाता है।

1. **Install Blume**

    पैकेज को अपने प्रोजेक्ट में जोड़ें।

2. **Write a page**

    अपने कंटेंट फ़ोल्डर में एक `.mdx` फ़ाइल रखें।

3. **Ship it**

    `blume build` चलाएँ और `dist/` डिप्लॉय करें।

```astro lineNumbers
<Steps>
  <Step title="Install Blume">Add the package to your project.</Step>
  <Step title="Write a page">
    Drop an `.mdx` file into your content folder.
  </Step>
  <Step title="Ship it">Run `blume build` and deploy `dist/`.</Step>
</Steps>
```

## Tabs

समतुल्य सामग्री के बीच वहीं पर स्विच करें — भाषा के प्रकार, OS-विशिष्ट कमांड, या वैकल्पिक तरीके — बिना सब कुछ पेज पर ढेर किए। हर `Tab` में एक `title` लिया जाता है।

**macOS**

टूलचेन इंस्टॉल करने के लिए Homebrew का उपयोग करें।

**Windows**

टूलचेन इंस्टॉल करने के लिए winget का उपयोग करें।

```astro lineNumbers
<Tabs>
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

बॉर्डर वाले बॉक्स के बजाय बिना बॉर्डर के रेंडर करने के लिए `inline` जोड़ें — पूरी चौड़ाई की एक रेखा पर टैब पट्टी, जिसके नीचे सामग्री गद्य की तरह प्रवाहित होती है। हैश के बजाय सक्रिय टैब को किसी URL क्वेरी पैरामीटर से सिंक करने के लिए `param` जोड़ें, जिससे चयन साझा करने योग्य बन जाता है: `?install=windows` पर समाप्त होने वाला लिंक Windows टैब पर खुलता है। हर समूह अपने स्वयं के `param` से सिंक होता है, इसलिए आप एक ही पेज पर कई स्वतंत्र, डीप-लिंक करने योग्य समूह उपयोग कर सकते हैं।

समान शीर्षक वाले टैब रखने वाले समूह एक साथ स्विच होते हैं — किसी एक में "macOS" चुनें और macOS टैब वाला हर समूह उसका अनुसरण करता है। उस सिंकिंग को सीमित करने के लिए `syncKey` जोड़ें: केवल एक ही कुंजी साझा करने वाले समूह एक साथ स्विच होते हैं, इसलिए ऐसे असंबंधित समूह जो संयोगवश कोई टैब शीर्षक साझा करते हैं, स्वतंत्र बने रहते हैं।

**macOS**

टूलचेन इंस्टॉल करने के लिए Homebrew का उपयोग करें।

**Windows**

टूलचेन इंस्टॉल करने के लिए winget का उपयोग करें।

```astro lineNumbers
<Tabs inline param="install">
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

## Badge

स्थिति या मेटाडेटा के लिए एक छोटा इनलाइन लेबल — संस्करण टैग, “new” या “beta” चिह्न, स्थिरता स्तर। `variant` रंग को अर्थ के अनुसार समायोजित करता है।

### डिफ़ॉल्ट

बिना किसी विशेष ज़ोर वाला तटस्थ मेटाडेटा।

<Badge>स्थिर</Badge>

```astro
<Badge>Stable</Badge>
```

### एक्सेंट

आपके थीम एक्सेंट का उपयोग करके ध्यान खींचता है — “new” या फ़ीचर्ड चिह्नों के लिए उपयुक्त।

<Badge variant="accent">नया</Badge>

```astro
<Badge variant="accent">New</Badge>
```

### सफलता

एक सकारात्मक या उत्तीर्ण स्थिति।

<Badge variant="success">उत्तीर्ण</Badge>

```astro
<Badge variant="success">Passing</Badge>
```

### चेतावनी

कुछ ऐसा जिसे सावधानी से उपयोग करना चाहिए, जैसे कोई प्रायोगिक सुविधा।

<Badge variant="warning">बीटा</Badge>

```astro
<Badge variant="warning">Beta</Badge>
```

### खतरा

एक नकारात्मक या ब्रेकिंग स्थिति, जैसे कोई अप्रचलन।

<Badge variant="danger">अप्रचलित</Badge>

```astro
<Badge variant="danger">Deprecated</Badge>
```

## Icon

नाम से एक आइकन रेंडर करें — यही `icon` प्रॉप कार्ड, स्टेप्स, टैब और साइडबार प्रविष्टियों को संचालित करता है। नाम [Lucide](https://lucide.dev/icons) से आते हैं, छोटे अक्षरों और केबाब-केस में (`rocket`, `gauge`, `book-open`)।

<Icon icon="rocket" size={20} />

```astro
<Icon icon="rocket" size={20} />
```

Blume केवल Lucide का समर्थन करता है — एक सादा नाम Lucide के विरुद्ध हल होता है, और अन्य आइकन इनपुट के साथ समरूपता के लिए आप नाम से पहले `lucide:` लगा सकते हैं (`lucide:rocket`)। `size` पिक्सेल आकार सेट करता है (डिफ़ॉल्ट `16`) और `color` उसे रंग देता है (कोई भी CSS रंग; डिफ़ॉल्ट `currentColor`)। अपनी स्वयं की कलाकृति रेंडर करने के लिए नाम के स्थान पर एक कच्चा `<svg>` स्ट्रिंग, एक इमेज URL, या एक स्थानीय इमेज पथ पास करें, और सहायक तकनीक के सामने उसे प्रकट करने के लिए एक `label` जोड़ें — इसके बिना आइकन केवल सजावटी होता है।

आइकन बिल्ड समय पर हल होते हैं और शून्य-JS SVG के रूप में इनलाइन होते हैं — रनटाइम पर कुछ भी फ़ेच नहीं किया जाता।

## फ़ाइल ट्री

किसी प्रोजेक्ट या फ़ोल्डर की संरचना दर्शाएँ। एक सामान्य Markdown सूची को लपेटें और Blume उसे ट्री के रूप में स्टाइल करता है — सेटअप और कॉन्फ़िग गाइड में संरचना समझाने के लिए उपयोगी।

<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>

```astro lineNumbers
<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>
```

## Accordion

संबंधित संकुचन योग्य आइटमों को एक ही बॉर्डर वाले कंटेनर में विभाजकों के साथ रखें — FAQ, वैकल्पिक चरण, या लंबे उदाहरण। हर चाइल्ड एक `AccordionItem` होता है (`title`, वैकल्पिक `icon`, `description`, `defaultOpen`)। किसी एकल स्वतंत्र प्रकटीकरण के लिए [Expandable](#expandable) का उपयोग करें।

<Accordion>
  <AccordionItem title="Does it support MDX?">
    हाँ — हर पेज `.md` या `.mdx` हो सकता है।
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    हाँ, Tailwind v4 टोकन और आपकी अपनी `theme.css` के माध्यम से।
  </AccordionItem>
</Accordion>

```astro lineNumbers
<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>
```

## Expandable

नेस्टेड विवरण के लिए एक हल्का इनलाइन प्रकटीकरण — किसी फ़ील्ड की उप-प्रॉपर्टीज़ या एक वैकल्पिक टिप्पणी का विस्तार। `title` टॉगल को लेबल करता है (डिफ़ॉल्ट “Show more”); विस्तारित अवस्था में शुरू करने के लिए `defaultOpen` सेट करें।

<Expandable title="Show advanced options">
  ये सेटिंग्स वैकल्पिक हैं और इन्हें शायद ही कभी बदलने की आवश्यकता होती है।
</Expandable>

```astro
<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>
```

## Columns

कार्ड या ब्लॉक को समान चौड़ाई वाले कॉलमों के उत्तरदायी ग्रिड में व्यवस्थित करें जो मोबाइल पर पुनः प्रवाहित होता है। `Columns` में `cols` लिया जाता है; हर सेल को एक `Column` में लपेटें।

<Columns cols={2}>
  <Column>
    **Fast**

    Astro और Vite पर बनाया गया।
  </Column>
  <Column>
    **Themeable**

    Tailwind v4 डिज़ाइन टोकन।
  </Column>
</Columns>

```astro lineNumbers
<Columns cols={2}>
  <Column>
    <Card title="Fast" icon="rocket">
      Built on Astro and Vite.
    </Card>
  </Column>
  <Column>
    <Card title="Themeable" icon="sun">
      Tailwind v4 design tokens.
    </Card>
  </Column>
</Columns>
```

## CodeGroup

कई कोड ब्लॉक को एक टैब्ड स्विचर में समूहबद्ध करें — प्रति भाषा या फ़ाइल एक टैब। टैब लेबल हर ब्लॉक का शीर्षक होता है (भाषा के बाद वाला टेक्स्ट), और समूह का कॉपी बटन टैब बार में स्थित होता है तथा वही ब्लॉक कॉपी करता है जो दिख रहा हो। टैब बार के बजाय मेन्यू से स्विच करने के लिए `dropdown` जोड़ें।

<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>

````astro
<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>
````

## Frame

किसी इमेज या किसी भी दृश्य को एक केंद्रित, बॉर्डर वाले फ़्रेम में लपेटें, जिसमें वैकल्पिक `caption` (Markdown के रूप में रेंडर) और `hint` हो।

<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <svg
    width="160"
    height="72"
    viewBox="0 0 160 72"
    role="img"
    aria-label="Sample frame"
  >
    <rect width="160" height="72" rx="8" fill="#3b82f6" />
  </svg>
</Frame>

```astro lineNumbers
<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <img src="/screenshot.png" alt="Product screenshot" />
</Frame>
```

## YouTube

किसी YouTube वीडियो को एक उत्तरदायी, गोपनीयता-अनुकूल (`youtube-nocookie.com`) 16:9 फ़्रेम में एम्बेड करें जो कोई क्लाइंट JavaScript नहीं भेजता। एक वीडियो `id` या पूरा `url` पास करें, साथ ही एक वैकल्पिक `title` (सुलभता के लिए) और सेकंडों में `start` समय।

[Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

```astro lineNumbers
<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
<YouTube url="https://youtu.be/aqz-KE-bpKQ" start={30} />
```

## Color

कॉपी करने योग्य हेक्स मानों के साथ रंग स्वैच दिखाएँ — किसी पैलेट या ब्रांड रंगों को प्रलेखित करने के लिए उपयोगी। स्वैच सूची के लिए `variant="compact"` का उपयोग करें, या उन्हें समूहबद्ध करने के लिए `Color.Row` के साथ `variant="table"` का। हर `Color.Item` में एक `name` और एक `value` लिया जाता है (एक हेक्स स्ट्रिंग, या थीम-सजग रंगों के लिए `{ light, dark }`)।

<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>

```astro lineNumbers
<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>
```

## Tree

विस्तारित की जा सकने वाली फ़ोल्डरों के साथ एक श्रेणीबद्ध फ़ाइल/फ़ोल्डर संरचना रेंडर करें। (त्वरित, सूची-आधारित संस्करण के लिए [फ़ाइल ट्री](#file-tree) देखें; `Tree` प्रति-फ़ोल्डर नियंत्रण देता है।) `Tree.Folder` (`name`, वैकल्पिक `defaultOpen`, `openable`) और `Tree.File` (`name`) का उपयोग करें।

<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>

```astro lineNumbers
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>
```

## Panel

पूरक, अलग रखी गई सामग्री के लिए एक शीर्षक वाला कंटेनर। `title` वैकल्पिक है।

<Panel title="Good to know">
  पैनल मुख्य प्रवाह को बाधित किए बिना सहायक विवरण रखते हैं।
</Panel>

```astro
<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>
```

## Tooltip

किसी इनलाइन शब्द के लिए होवर पर परिभाषा या संकेत प्रकट करें। `tip` होवर टेक्स्ट है; एक वैकल्पिक `headline` और आगे के लिंक हेतु `cta` + `href` जोड़ें।

अधिक जानने के लिए <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> शब्द पर होवर करें।

```astro
Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term.
```

## Tile

एक क्लिक करने योग्य प्रीव्यू जो शीर्षक और विवरण के ऊपर एक दृश्य — आइकन या इमेज — के साथ शुरू होता है। गैलरी और शोकेस के लिए उपयुक्त। इसमें `title`, `description` और `href` लिए जाते हैं; चाइल्ड दृश्य होता है।

<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>

```astro
<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>
```

## Prompt

एक लेबल और कॉपी बटन वाली एकल पंक्ति। `description` (Markdown) दृश्यमान लेबल है; बॉडी स्वयं प्रॉम्प्ट है — छिपी हुई, और **Copy prompt** बटन दबाने पर क्लिपबोर्ड में कॉपी हो जाती है। `actions` बटनों को नियंत्रित करता है (उदा. `["copy", "cursor"]`)।

<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  POST /v1/pets एंडपॉइंट के लिए संदर्भ दस्तावेज़ लिखें।
</Prompt>

```astro
<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>
```

## Visibility

दर्शकों के अनुसार सामग्री दिखाएँ या छिपाएँ। `for="web"` केवल साइट पर रेंडर होता है; `for="agents"` उस एजेंट-उन्मुख Markdown को लक्षित करता है जिसे AI एजेंट पढ़ते हैं (`llms-full.txt` और हर पेज का `.md` मिरर)।

```astro
<Visibility for="web">Shown on the site only.</Visibility>
<Visibility for="agents">Shown only in the generated Markdown.</Visibility>
```

## टाइप टेबल

किसी ऑब्जेक्ट की प्रॉपर्टीज़ — उसके प्रॉप्स, टाइप और डिफ़ॉल्ट — को प्रलेखित करने के लिए टेबल। पंक्तियाँ `TypeTable` के साथ हाथ से लिखें, या `AutoTypeTable` के साथ सीधे किसी TypeScript इंटरफ़ेस या टाइप एलियास से उत्पन्न करें।

### टाइप टेबल

एक **Prop / Type** ग्रिड जहाँ हर पंक्ति विस्तारित होकर अपना विवरण और ब्योरा प्रकट करती है। प्रॉपर्टी नाम से कुंजीबद्ध एक `type` मैप पास करें; हर प्रविष्टि में एक `type`, साथ ही वैकल्पिक `description`, `default`, `required` फ़्लैग, `typeDescription` और `typeDescriptionLink` लिया जाता है। वैकल्पिक प्रॉप्स (`required` सेट न होने पर) नाम के बाद `?` दिखाते हैं।

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | - | The button's visible label. |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | Visual style. |
| `disabled?` | `boolean` | - | |

```astro lineNumbers
<TypeTable
  type={{
    label: {
      type: "string",
      required: true,
      description: "The button's visible label.",
    },
    variant: {
      type: '"primary" | "ghost"',
      default: '"primary"',
      description: "Visual style.",
    },
    disabled: { type: "boolean" },
  }}
/>
```

### ऑटो टाइप टेबल

किसी TypeScript टाइप से टाइप टेबल उत्पन्न करें ताकि दस्तावेज़ सोर्स के साथ समकालिक बने रहें। `AutoTypeTable` को `path` (आपके प्रोजेक्ट रूट से हल किया गया) और एक टाइप `name` के साथ किसी फ़ाइल की ओर इंगित करें। विवरण JSDoc टिप्पणियों से आते हैं, डिफ़ॉल्ट `@default` टैग से, और वैकल्पिक प्रॉपर्टीज़ (`?`) को तदनुसार चिह्नित किया जाता है।

```astro
<AutoTypeTable path="./src/button.ts" name="ButtonProps" />
```

आप `path` के बजाय `type` के साथ टाइप को इनलाइन भी पास कर सकते हैं — छोटे उदाहरणों के लिए सुविधाजनक:

<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>

```astro lineNumbers
<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>
```

## GitHub जानकारी

एक कार्ड जो किसी GitHub रिपॉज़िटरी से उसके लाइव स्टार और फ़ोर्क काउंट के साथ लिंक करता है। काउंट बिल्ड समय पर फ़ेच किए जाते हैं — कोई क्लाइंट JavaScript नहीं — और API अनुपलब्ध होने पर भी कार्ड रेंडर होता है। `owner` और `repo` पास करें, या अपने `blume.config` की रिपॉज़िटरी उपयोग करने के लिए उन्हें छोड़ दें। API दर सीमा हटाने के लिए एक `GITHUB_TOKEN` एनवायरनमेंट वेरिएबल सेट करें।

कार्ड इंस्टेंस को [`github.host`](/docs/configuration#github-enterprise) से पढ़ता है, इसलिए किसी Enterprise-होस्टेड साइट पर स्पष्ट `owner`/`repo` भी उसी इंस्टेंस को संबोधित करते हैं। किसी एक कार्ड को कहीं और इंगित करने के लिए `host` पास करें — मान लीजिए, किसी Enterprise साइट से कोई सार्वजनिक प्रोजेक्ट; REST बेस उससे उसी तरह व्युत्पन्न होता है जैसे `github.host` से होता है।

<GithubInfo owner="haydenbleasel" repo="blume" />

```astro lineNumbers
<!-- Uses the repo from blume.config -->
<GithubInfo />

<!-- Or point it at any repository -->
<GithubInfo owner="haydenbleasel" repo="blume" />

<!-- Or at a repository on another instance -->
<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
```

## Component

`Component` आपके प्रोजेक्ट की `examples/` डायरेक्टरी से एक उदाहरण फ़ाइल को उसके हाइलाइट किए गए सोर्स के साथ-साथ लाइव प्रीव्यू के रूप में टैब में रेंडर करता है। इसे `path` के साथ किसी फ़ाइल की ओर इंगित करें — `examples/` के अंतर्गत उसका स्थान, बिना एक्सटेंशन के (इसलिए `examples/counter.tsx` के लिए `path="counter"`)। React, Vue, Svelte और Astro उदाहरण सभी समर्थित हैं; फ़्रेमवर्क उदाहरण हाइड्रेट होते हैं, Astro वाले स्थैतिक रूप से रेंडर होते हैं। यह एक ही फ़ाइल से प्रीव्यू और कोड को समकालिक रखता है।

प्रीव्यू एक पृथक फ़्रेम में रेंडर होता है जहाँ दस्तावेज़ की स्टाइल कभी नहीं पहुँचती — कोई गद्य मार्जिन, टाइपोग्राफ़ी, या थीम क्रोम आपके घटक में नहीं रिसता। फ़्रेम को Tailwind मिलता है (प्रीफ़्लाइट + आपके प्रोजेक्ट और आपकी उदाहरण डायरेक्टरी से स्कैन की गई यूटिलिटीज़), Blume के डिज़ाइन टोकन मिलते हैं ताकि `bg-background` जैसी क्लासेज़ डिफ़ॉल्ट रूप से साइट पैलेट का अनुसरण करें, और यह साइट के लाइट/डार्क टॉगल का लाइव अनुसरण करता है। पेन स्वयं को रेंडर किए गए उदाहरण के अनुसार आकार देता है — और लोड होने के बाद उदाहरण के बढ़ने या घटने पर भी उसे ट्रैक करता रहता है — जिसमें Preview और Code टैब एक ही ऊँचाई साझा करते हैं, इसलिए उन्हें बदलने पर पेज कभी नहीं खिसकता।

प्रीव्यू को अपने स्वयं के डिज़ाइन सिस्टम — मान लीजिए, shadcn वेरिएबल्स — से स्टाइल करने के लिए, `examples.css` को किसी स्टाइलशीट की ओर इंगित करें। इसे Blume के डिफ़ॉल्ट के बाद हर प्रीव्यू फ़्रेम में इंजेक्ट किया जाता है, इसलिए आपके टोकन जीतते हैं। इसमें `@import "tailwindcss"` न करें; फ़्रेम पहले से ही Tailwind प्रदान करता है। डार्क-मोड ओवरराइड के लिए `.dark` और `[data-theme="dark"]` दोनों काम करते हैं:

```ts
// blume.config.ts
export default defineConfig({
  examples: { css: "examples/theme.css" },
});
```

```css
/* examples/theme.css */
:root {
  --primary: oklch(0.6 0.2 260);
}

.dark {
  --primary: oklch(0.75 0.15 260);
}

@theme inline {
  --color-primary: var(--primary);
}
```

डायरेक्टरी भी कॉन्फ़िगर करने योग्य है — जब आपके उदाहरण कहीं और रहते हों (उदा. रजिस्ट्री लेआउट) तो `source` सेट करें (या स्ट्रिंग शॉर्टहैंड, `examples: "..."` का उपयोग करें)। `path` हमेशा उसके सापेक्ष होता है:

```ts
// blume.config.ts
export default defineConfig({
  examples: "registry/files-sdk",
});
```

```astro
<!-- registry/files-sdk/file-list/basic.tsx -->
<Component path="file-list/basic" />
```

`examples` एक ग्लोब भी हो सकता है (कुछ भी जिसमें `*`, `?`, `[]`, `{}`, या `!` हो)। केवल मेल खाने वाली फ़ाइलें खोजी जाती हैं, और `path` ग्लोब के स्थैतिक उपसर्ग (पहले वाइल्डकार्ड से पहले वाला भाग) के सापेक्ष होता है। यह ऐसी रजिस्ट्री के लिए है जो हर घटक के सोर्स को उसके उदाहरण के साथ रखती है — केवल उदाहरणों की ओर इंगित करें ताकि सोर्स, जिनमें प्रीव्यू के लिए कोई डिफ़ॉल्ट एक्सपोर्ट नहीं होता, शामिल न हो जाएँ:

```ts
// blume.config.ts
export default defineConfig({
  // registry/files-sdk/file-list/file-list.tsx — source, left out
  // registry/files-sdk/file-list/examples/basic.tsx — discovered
  examples: "registry/files-sdk/**/examples/*",
});
```

```astro
<!-- keyed relative to registry/files-sdk -->
<Component path="file-list/examples/basic" />
```

किसी मोनोरेपो में, आपके उदाहरण जिन घटकों को इम्पोर्ट करते हैं वे आमतौर पर किसी सहोदर वर्कस्पेस पैकेज में रहते हैं। Tailwind का `@source` फ़ाइलें स्कैन करता है, इम्पोर्ट नहीं: Blume आपके प्रोजेक्ट और `examples` डायरेक्टरी को स्कैन करता है (जहाँ भी `source` इंगित करता हो, प्रोजेक्ट के बाहर भी), इसलिए केवल उस सहोदर पैकेज के भीतर उपयोग की गई कोई क्लास तब तक उत्पन्न नहीं होती जब तक आप उस पैकेज को स्कैन में न जोड़ें। ऐसा `examples.css` (प्रीव्यू फ़्रेमों के लिए) या `theme.css` (साइट के लिए) में एक `@source` निर्देश के साथ करें, जो उस फ़ाइल के सापेक्ष लिखा जाए जिसमें वह स्थित है — यही मानक Tailwind नियम है — और Blume उसे उत्पन्न शीट में ले जाता है:

```css
/* examples/theme.css */
@source "../../../packages/ui/src";
```

```tsx
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <button
      className="rounded-blume border-border bg-background text-foreground hover:bg-muted border px-4 py-2 text-sm font-medium transition-colors"
      onClick={() => setCount((value) => value + 1)}
      type="button"
    >
      Clicked {count} {count === 1 ? "time" : "times"}
    </button>
  );
};

export default Counter;
```

```astro
<!-- examples/counter.tsx -->
<Component path="counter" />
```

एक Astro उदाहरण बिना किसी क्लाइंट JavaScript के लाइव रेंडर होता है:

```astro
---
interface Props {
  title?: string;
}

const { title = "Hello from Astro" } = Astro.props;
---

<div class="rounded-blume border border-border bg-muted/30 px-5 py-4">
  <p class="m-0 font-semibold text-foreground text-sm">{title}</p>
  <p class="m-0 mt-1 text-muted-foreground text-sm">
    A static, server-rendered example — no client JavaScript ships.
  </p>
</div>
```

## CodeBlock

`CodeBlock` किसी कोड स्ट्रिंग को उन्हीं Shiki थीम और ट्रांसफ़ॉर्मर्स के साथ हाइलाइट करता है जो आपके फ़ेंस किए गए कोड के लिए उपयोग होते हैं — लाइट/डार्क स्वैप सहित — उन जगहों के लिए जहाँ फ़ेंस नहीं जा सकता, जैसे कोई लैंडिंग पेज या कस्टम घटक। `code` और एक `lang` पास करें:

<CodeBlock
  lang="ts"
  code={`export const greet = (name: string): string =>
  \`Hello, \${name}!\`;`}
/>

```astro
---
import CodeBlock from "blume/components/content/CodeBlock.astro";
---

<CodeBlock lang="ts" code={source} />
```

स्वयं HTML स्ट्रिंग में हाइलाइट करने के लिए (उदा. अपने स्वयं के घटक के भीतर), `blume/markdown` से अंतर्निहित हेल्पर इम्पोर्ट करें:

```ts
import { highlightCode } from "blume/markdown";

const html = await highlightCode(source, "ts");
```

## Diff

`Diff` एक git-शैली का डिफ़ रेंडर करता है, जो आपके कोड ब्लॉक की तरह उसी Shiki थीम से हाइलाइट होता है और पूरी तरह बिल्ड समय पर तैयार होता है — कोई क्लाइंट JavaScript नहीं। इसे दो इनलाइन स्ट्रिंग (`old` / `new`), दो फ़ाइल पथ (`before` / `after`), या एक यूनिफ़ाइड पैच (एक इनलाइन `patch` स्ट्रिंग या एक `src` फ़ाइल) दें।

<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>

```astro
<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>
```

अपने प्रोजेक्ट की दो फ़ाइलों का डिफ़ लें, उसके रूट के सापेक्ष:

<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />

```astro
<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />
```

या एक यूनिफ़ाइड पैच रेंडर करें — या तो `src` के साथ किसी फ़ाइल से, या `patch` के साथ इनलाइन:

<Diff src="diffs/greet.patch" />

```astro
<Diff src="diffs/greet.patch" />
```

```astro
<Diff
  patch={`--- a/greet.ts
+++ b/greet.ts
@@ -1,3 +1,4 @@
-export function greet(name) {
-  return "Hi, " + name;
+export function greet(name: string): string {
+  const greeting = "Hi, " + name + "!";
+  return greeting;
 }`}
/>
```

---

# अंतर्राष्ट्रीयकरण
Source: https://useblume.dev/hi/docs/content/i18n

Blume एक ही प्रोजेक्ट को कई भाषाओं में परोसता है। अनूदित फ़ाइलें सही जगह पर रखें और Blume आपके लिए रूटिंग, भाषा स्विचर, प्रति-लोकेल नेविगेशन और SEO जोड़ देता है — रखरखाव के लिए कोई अलग रूटिंग लेयर नहीं है। यह ऑप्ट-इन है: `i18n` ब्लॉक के बिना, आपकी साइट पहले की तरह ही एकभाषी बनी रहती है। यह [वर्ज़निंग](/docs/content/versioning) के साथ भी संयोजित होता है — एक फ़्रोज़न स्नैपशॉट अपने अनुवाद बनाए रखता है, और लोकेल फ़ॉलबैक हर वर्ज़न के भीतर काम करता है।

## इसे सक्षम करें

अपने लोकेल और उनमें से कौन-सा डिफ़ॉल्ट है, यह सूचीबद्ध करते हुए एक `i18n` ब्लॉक जोड़ें:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}
```

प्रत्येक लोकेल में एक `code` (URL में उपयोग किया जाता है), एक `label` (भाषा स्विचर में दिखाया जाता है), और दाएँ-से-बाएँ लिपियों के लिए एक वैकल्पिक `dir` होता है (डिफ़ॉल्ट रूप से `"ltr"`)। एक वैकल्पिक `style` [`blume translate`](/docs/reference/translate) को उस लोकेल के लिए स्वतंत्र-रूप मार्गदर्शन देता है — रजिस्टर, बोली, शब्दावली, जैसे `"Brazilian Portuguese, informal você"` — ताकि यह चुनाव एजेंट पर छोड़ने के बजाय पहले ही अनुवाद से तय हो जाए।

## अनूदित सामग्री व्यवस्थित करें

डिफ़ॉल्ट लोकेल आपके कंटेंट रूट में रहता है। हर दूसरा लोकेल अपने `code` के नाम वाला एक टॉप-लेवल फ़ोल्डर होता है, जो डिफ़ॉल्ट संरचना को प्रतिबिंबित करता है:

```txt
docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar
```

| फ़ाइल                           | रूट                     |
| ------------------------------- | ----------------------- |
| `docs/index.mdx`                | `/`                     |
| `docs/guides/quickstart.mdx`    | `/guides/quickstart`    |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

आप केवल वही फ़ाइलें अनूदित करते हैं जो आप चाहते हैं — बाकी सब अपने आप फ़ॉलबैक हो जाता है ([फ़ॉलबैक](#fallbacks) देखें)।

### फ़ाइलनाम प्रत्यय

अनुवादों को मूल के पास ही रखना पसंद करते हैं? `parser: "dot"` सेट करें और फ़ोल्डर उपयोग करने के बजाय फ़ाइलों को लोकेल प्रत्यय के साथ नाम दें:

```txt
docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)
```

विरल अनुवादों के लिए अच्छा — पूरे ट्री को प्रतिबिंबित किए बिना उन कुछ पृष्ठों को साथ रखें जिनका आपने अनुवाद किया है।

### साझा फ़ाइलें

ऐसी सामग्री के लिए जो हर भाषा में एक जैसी है — एक चेंजलॉग, एक स्टेटस पेज — एक `$` मार्कर जोड़ें ताकि एक ही फ़ाइल बिना दोहराव के सभी लोकेल को परोसे:

```txt
docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

किसी लोकेल-विशिष्ट `meta.ts` उस भाषा के लिए साझा वाले को अब भी ओवरराइड करती है।

## डिफ़ॉल्ट-लोकेल URL

डिफ़ॉल्ट रूप से डिफ़ॉल्ट लोकेल का कोई URL उपसर्ग नहीं होता (`/`, `/guides/quickstart`) जबकि अन्य लोकेल उपसर्ग सहित होते हैं (`/fr/…`)। इससे आपकी प्राथमिक भाषा के URL साफ़ रहते हैं। हर लोकेल को, डिफ़ॉल्ट सहित, उपसर्ग देने के लिए:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## प्रति-लोकेल नेविगेशन

हर भाषा को उस लोकेल की फ़ाइलों से बना अपना खुद का साइडबार मिलता है — इसलिए अनुवाद संरचना, क्रम या लेबल में भिन्न हो सकते हैं। फ़ोल्डर [`meta.ts`](/docs/content/meta) फ़ाइलें भी प्रति लोकेल हल होती हैं: डिफ़ॉल्ट `dir` पार्सर के तहत, फ़्रेंच समूह को स्वतंत्र रूप से क्रमबद्ध करने के लिए `fr/guides/` के अंदर एक `meta.ts` रखें। `dot` पार्सर के तहत अनुवाद मूल के पास ही रहते हैं, इसलिए किसी फ़ोल्डर की `meta.ts` हर लोकेल पर लागू होती है। [नेविगेशन](/docs/content/navigation) के बारे में बाकी सब कुछ हर भाषा के लिए एक जैसा ही काम करता है।

हेडर टैब कॉन्फ़िगर किए जाते हैं, सामग्री से व्युत्पन्न नहीं, इसलिए उनके लेबल `blume.config.ts` में स्थानीयकृत होते हैं: एक टैब `label` सादे-स्ट्रिंग रूप के साथ-साथ एक प्रति-लोकेल मैप (`{ en: "Docs", fr: "Documentation" }`) भी स्वीकार करता है, और जिन लोकेल को आपने नहीं भरा है उनके लिए डिफ़ॉल्ट लोकेल की प्रविष्टि पर फ़ॉलबैक करता है। देखें [टैब](/docs/content/navigation#tabs)।

## फ़ॉलबैक

जब कोई पृष्ठ अभी तक अनूदित नहीं होता, तो Blume स्थानीयकृत URL पर फ़ॉलबैक लोकेल की सामग्री रेंडर करता है — इसलिए लिंक काम करता है, पृष्ठ पूरी तरह पूर्व-रेंडर होता है, और सर्च इंजन किसी मृत छोर पर नहीं भेजे जाते। फ़ॉलबैक डिफ़ॉल्ट रूप से आपका `defaultLocale` होता है:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}
```

फ़ॉलबैक पृष्ठ खोज इंडेक्स से बाहर रखे जाते हैं और `hreflang` में असली अनुवाद के रूप में प्रचारित नहीं किए जाते, इसलिए अअनूदित सामग्री रैंकिंग के लिए प्रतिस्पर्धा नहीं करती। वे उस लोकेल के साइडबार में फिर भी दिखते हैं, ताकि नेविगेशन पूरा बना रहे — एक पाठक किसी भी भाषा में हर पृष्ठ तक पहुँच सकता है।

:::tip
अपने सबसे महत्वपूर्ण पृष्ठों — होमपेज, क्विकस्टार्ट और शीर्ष गाइड — का अनुवाद करके शुरू करें, और बाकी को फ़ॉलबैक होने दें। आप समय के साथ बिना किसी लिंक को तोड़े अनुवाद भरते जा सकते हैं।
:::

## एजेंट से अनुवाद करना

आपको लोकेल हाथ से भरने की ज़रूरत नहीं है। [`blume translate`](/docs/reference/translate) हर उस पृष्ठ को ढूँढता है जो प्रत्येक लोकेल में गायब या पुराना है और उसे एक लोकल एजेंट CLI ([Claude Code](https://claude.com/claude-code) या [Codex](https://developers.openai.com/codex/cli)) से अनूदित करता है:

```bash
blume translate --claude
```

Blume हर परिणाम की संरचना — फ़्रंटमैटर, कोड फ़ेंस, लिंक — को मान्य करता है और फ़ाइलें खुद लिखता है; एजेंट केवल टेक्स्ट का अनुवाद करता है। एक कमिट किया गया लेजर (`blume.translations.json`) ट्रैक करता है कि हर अनुवाद किस स्रोत रिवीज़न से आया था, इसलिए दोबारा चलाने पर केवल वही छुआ जाता है जो बदला है, और जो अनुवाद आपने हाथ से लिखे हैं उन्हें ज्यों-का-त्यों अपनाया जाता है, कभी ओवरराइट नहीं किया जाता। CI में, `blume translate --check` तब विफल होता है जब कोई स्रोत पृष्ठ अपने अनुवादों से आगे खिसक गया हो।

## भाषा स्विचर

जब i18n चालू होता है, तो हेडर में अपने आप एक भाषा स्विचर दिखाई देता है, जो आपके `locales` से बनाया जाता है। हर पृष्ठ के लिए यह हर भाषा में मेल खाते अनुवाद को लिंक करता है; जहाँ कोई अनुवाद गायब है वहाँ यह फ़ॉलबैक पृष्ठ को लिंक करता है और उसे अअनूदित के रूप में चिह्नित करता है। कॉन्फ़िगर करने के लिए कुछ नहीं है।

## अनूदित UI

Blume अपने खुद के इंटरफ़ेस क्रोम — “इस पृष्ठ पर”, “खोजें”, “GitHub पर संपादित करें”, और बाकी — के लिए अंतर्निहित अनुवाद के साथ आता है, इसलिए जिस लोकेल के लिए अंतर्निहित पैक है उसे बिना किसी अतिरिक्त काम के अनूदित UI मिलता है। **आप केवल अपनी सामग्री का अनुवाद करते हैं।**

पैक 30 से अधिक भाषाओं के लिए उपलब्ध हैं — अरबी, बंगाली, बल्गेरियाई, कैटलन, चीनी (सरलीकृत और पारंपरिक), क्रोएशियाई, चेक, डेनिश, डच, फ़िनिश, फ़्रेंच, जर्मन, ग्रीक, हिब्रू, हिन्दी, हंगेरियन, इंडोनेशियाई, इतालवी, जापानी, कोरियाई, नॉर्वेजियन, फ़ारसी, पोलिश, पुर्तगाली (और ब्राज़ीली पुर्तगाली), रोमानियाई, रूसी, सर्बियाई, स्लोवाक, स्पेनिश, स्वीडिश, थाई, तुर्की, यूक्रेनी, और वियतनामी। ये समुदाय द्वारा अनुरक्षित हैं — कोई लोकेल जोड़ने या किसी अनुवाद को बेहतर करने के लिए एक PR खोलें।

गायब या न भेजी गई स्ट्रिंग्स डिफ़ॉल्ट लोकेल पर, फिर अंग्रेज़ी पर फ़ॉलबैक करती हैं। किसी स्ट्रिंग को ओवरराइड करने या अपनी खुद की भाषा देने के लिए, लोकेल द्वारा कीयुक्त `i18n.ui` सेट करें:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}
```

## SEO

स्थानीयकृत SEO आपके लिए संभाला जाता है — प्रति पृष्ठ कोई मेटाडेटा लिखने की ज़रूरत नहीं:

- `<html lang>` और `dir` सक्रिय लोकेल से सेट किए जाते हैं।
- `hreflang` वैकल्पिक लिंक किसी पृष्ठ के हर असली अनुवाद को जोड़ते हैं, साथ ही डिफ़ॉल्ट लोकेल की ओर इशारा करने वाला एक `x-default` भी।
- कैनोनिकल URL लोकेल-सही होते हैं, और JSON-LD `inLanguage` ले जाता है।

[`deployment.site`](/docs/deployment) सेट करें ताकि इन्हें निरपेक्ष URL के रूप में उत्सर्जित किया जा सके।

## खोज

खोज सक्रिय भाषा तक सीमित होती है: किसी `/fr/…` पृष्ठ पर डायलॉग फ़्रेंच परिणाम लौटाता है, साथ में एक **सभी भाषाएँ** टॉगल होता है जिससे एक साथ हर लोकेल में खोजा जा सके। डिफ़ॉल्ट (Orama) और FlexSearch इंडेक्स ब्राउज़र में फ़िल्टर करते हैं; होस्टेड प्रदाता हर रिकॉर्ड पर एक `locale` फ़ैसेट रखते हैं।

## दाएँ-से-बाएँ

किसी लोकेल पर `dir: "rtl"` सेट करें और Blume पूरे इंटरफ़ेस को प्रतिबिंबित कर देता है — साइडबार, हेडर, विषय-सूची, पेजिनेशन, खोज और मेन्यू — और `<html dir>` को उससे मेल खाने के लिए सेट करता है। दो चीज़ें जानबूझकर बाएँ-से-दाएँ ही रहती हैं: **कोड ब्लॉक** (कोड किसी भी भाषा में LTR पढ़ा जाता है) और **फ़ॉलबैक सामग्री** — एक अअनूदित पृष्ठ उसी भाषा की दिशा बनाए रखता है जिसमें वह वास्तव में लिखा गया है, ताकि RTL लोकेल के तहत दिखाई गई अंग्रेज़ी भी सही पढ़ी जाए जबकि आसपास का क्रोम प्रतिबिंबित हो।

## आगे कहाँ

**[नेविगेशन](/docs/content/navigation)**

हर लोकेल के साइडबार, क्रम और टैब को आकार दें।

**[SEO](/docs/configuration/seo)**

साइटमैप, Open Graph और संरचित डेटा।

---

# इनक्लूड
Source: https://useblume.dev/hi/docs/content/includes

एक स्निपेट एक बार लिखें और उसे किसी भी पृष्ठ में जोड़ दें। अपनी स्वयं की पंक्ति पर लिखा गया `<include>` कथन बिल्ड समय पर किसी दूसरी फ़ाइल को इस प्रकार एम्बेड करता है, मानो उसकी सामग्री इनलाइन लिखी गई हो — शीर्षक पृष्ठ की विषय-सूची में जुड़ जाते हैं, पाठ खोज द्वारा अनुक्रमित होता है, और सामग्री पृष्ठ के `.md` मिरर तथा llms-full.txt में दिखाई देती है।

```mdx
<include>./_snippets/prerequisites.mdx</include>
```

पथ को इनक्लूड करने वाली फ़ाइल के सापेक्ष हल किया जाता है। `/` से आरंभ होने वाले पथ आपके कंटेंट रूट से हल होते हैं, जिससे गहराई में नेस्ट किए गए पृष्ठ `../../..` की श्रृंखलाओं के बिना साझा स्निपेट्स का संदर्भ ले सकते हैं:

```mdx
<include>/_snippets/prerequisites.mdx</include>
```

यह सिंटैक्स Fumadocs के include सिंटैक्स से मेल खाता है, इसलिए माइग्रेट की गई सामग्री बिना किसी बदलाव के काम करती है।

यह रहा इसका जीवंत उदाहरण — नीचे दिया गया यह कॉलआउट एक साझा स्निपेट से जोड़ा गया है:

:::tip
यह कॉलआउट `_snippets/include-demo.mdx` में स्थित है — यह यहाँ इसलिए रेंडर होता है क्योंकि पृष्ठ इसे `<include>` स्टेटमेंट के माध्यम से जोड़ता है।
:::

## पार्शियल्स

ऐसी कोई भी फ़ाइल जिसका नाम (या फ़ोल्डर) अंडरस्कोर से आरंभ होता है, डिफ़ॉल्ट रूप से रूटिंग, नेविगेशन, खोज और साइटमैप से बाहर रखी जाती है — यही परिपाटी साझा स्निपेट्स के लिए स्वाभाविक स्थान है:

```text
docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx
```

पार्शियल एक सामान्य Markdown या MDX फ़ाइल होती है। जोड़े जाने पर उसका फ़्रंट मैटर हटा दिया जाता है (इनक्लूड करने वाले पृष्ठ का फ़्रंट मैटर मान्य होता है), और शेष सब कुछ — कॉलआउट, कोड फ़ेंस, कंपोनेंट, गणितीय व्यंजक — ठीक वैसे ही रेंडर होता है जैसे इनलाइन होने पर होता। पार्शियल्स अन्य पार्शियल्स को इनक्लूड कर सकते हैं; चक्रीय इनक्लूड को त्रुटि के रूप में रिपोर्ट किया जाता है।

पार्शियल के भीतर सापेक्ष छवि संदर्भ काम करते रहते हैं: उन्हें इनक्लूड करने वाले पृष्ठ के अनुसार पुनः आधारित किया जाता है, इसलिए पार्शियल के साथ रखी गई `![आरेख](./diagram.png)` वहाँ भी हल हो जाती है जहाँ भी पार्शियल जोड़ा जाए।

`blume dev` के चलते समय किसी पार्शियल का संपादन उन सभी पृष्ठों को पुनः लोड कर देता है जो उसे इनक्लूड करते हैं।

## कोड फ़ाइलें इनक्लूड करना

ऐसा लक्ष्य जो `.md`/`.mdx` नहीं है, उसे फ़ेंस्ड कोड ब्लॉक के रूप में एम्बेड किया जाता है, जिसमें भाषा का अनुमान एक्सटेंशन से लगाया जाता है। भाषा को ओवरराइड करने के लिए (या किसी Markdown फ़ाइल को जोड़ने के बजाय स्रोत के रूप में दिखाने के लिए) `lang` का उपयोग करें, और शीर्षक जैसी फ़ेंस मेटा स्ट्रिंग पास करने के लिए `meta` का:

```mdx
<include>./examples/config.ts</include>

<include lang="ts" meta='title="blume.config.ts"'>
  ../blume.config.ts
</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>
```

## नियम और डायग्नोस्टिक्स

इनक्लूड कथनों को अपनी स्वयं की पंक्ति पर होना चाहिए — वे ब्लॉक-स्तरीय होते हैं, इनलाइन नहीं। फ़ेंस्ड कोड ब्लॉक के भीतर मौजूद कथनों को अछूता छोड़ दिया जाता है, इसलिए आप स्वयं इस सिंटैक्स का दस्तावेज़ीकरण कर सकते हैं (जैसा यह पृष्ठ करता है)।

लक्ष्य आपके कंटेंट रूट के भीतर होने चाहिए: उसके बाहर की कोई फ़ाइल संस्करण स्नैपशॉट्स और इजेक्ट किए गए प्रोजेक्ट्स से चुपचाप अनुपस्थित हो जाएगी, इसलिए `blume` उसे जोड़ने के बजाय `BLUME_INCLUDE_OUTSIDE_ROOT` रिपोर्ट करता है। जो लक्ष्य मौजूद ही नहीं है वह `BLUME_INCLUDE_NOT_FOUND` है, और इनक्लूड्स का चक्र `BLUME_INCLUDE_CYCLE` है — तीनों `blume build` को विफल कर देते हैं (फिर भी बिल्ड करने के लिए `--no-strict` पास करें) और `blume validate` में दिखाई देते हैं।

किसी पार्शियल के भीतर टूटे हुए लिंक उस पार्शियल फ़ाइल के विरुद्ध रिपोर्ट किए जाते हैं, न कि उन पृष्ठों के विरुद्ध जो उसे जोड़ते हैं, ताकि आप उन्हें वहीं ठीक करें जहाँ वे मौजूद हैं।

:::note
पार्शियल्स सभी लोकेल्स के बीच साझा होते हैं और `blume translate` द्वारा अनूदित नहीं किए जाते — पार्शियल्स को भाषा-निरपेक्ष रखें (कोड, तालिकाएँ, आरेख), या प्रति-लोकेल पार्शियल्स बनाएँ और उन्हें प्रत्येक लोकेल के पृष्ठों से इनक्लूड करें।
:::

---

# आइलैंड्स
Source: https://useblume.dev/hi/docs/content/islands

Blume आपके डॉक्स को डिफ़ॉल्ट रूप से **शून्य JavaScript** के साथ स्टैटिक HTML के रूप में रेंडर करता है। जब आपको कुछ इंटरैक्टिव चाहिए — एक लाइव डेमो, एक चार्ट, एक प्लेग्राउंड — तो आप एक **आइलैंड** जोड़ते हैं: एक फ्रेमवर्क कंपोनेंट जो JS केवल अपने लिए भेजता है, और केवल उन पेजों पर जो उसका उपयोग करते हैं।

## `islands/` परिपाटी

अपने प्रोजेक्ट के रूट में एक `islands/` फ़ोल्डर में कोई कंपोनेंट रखें। इसका फ़ाइल नाम एक ऐसा कंपोनेंट बन जाता है जिसे आप **किसी भी** `.mdx` पेज में, बिना इंपोर्ट किए, इस्तेमाल कर सकते हैं:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Clicked {count}</button>;
}
```

```mdx page.mdx
Here's a live counter: <Counter />
```

फ़ाइल नाम ही कंपोनेंट का नाम है, इसलिए यह **एक PascalCase आइडेंटिफ़ायर होना चाहिए** — केवल अक्षर, अंक और अंडरस्कोर (`Counter.tsx` → `<Counter />`)। लोअरकेस फ़ाइल नाम, डैश/डॉट/स्पेस वाले नाम (जैसे `Time-Picker.tsx`), और ऐसे दो आइलैंड्स जो एक ही नाम पर पहुँचते हैं, बिल्ड चेतावनी के साथ छोड़ दिए जाते हैं।

:::note
आइलैंड्स **इंटरैक्टिव** UI के लिए हैं। ऐसे स्टैटिक कंपोनेंट के लिए जिसे आप कई पेजों में दोबारा इस्तेमाल करते हैं (एक स्टाइल किया हुआ कॉलआउट, एक प्राइसिंग टेबल), इसके बजाय [MDX ओवरराइड](/docs/configuration/customization) का उपयोग करें — यह कोई JavaScript नहीं भेजता।
:::

## `components.ts` में आइलैंड्स रजिस्टर करना

यदि आप आइलैंड्स को अपने बाकी कंपोनेंट्स के साथ रखना चाहें — या उन्हें फ़ाइल से अलग नाम देना चाहें — तो उन्हें `defineComponents` के साथ रजिस्टर करें। `islands` समूह बिल्कुल `islands/` फ़ोल्डर जैसा ही है: प्रत्येक एंट्री हर MDX पेज में उपलब्ध होती है और हाइड्रेट होती है (डिफ़ॉल्ट `client: "visible"` के साथ)।

```ts components.ts
import { defineComponents } from "blume";
import Counter from "./widgets/Counter.tsx";

export default defineComponents({
  islands: {
    Counter, // <Counter /> in any MDX page, hydrated
  },
});
```

कंपोनेंट को इंपोर्ट के ज़रिए या पाथ स्ट्रिंग के ज़रिए रेफ़र करें, और डिस्क्रिप्टर फ़ॉर्म के साथ प्रति आइलैंड एक हाइड्रेशन मोड सेट करें:

```ts components.ts
export default defineComponents({
  islands: {
    Chart: { component: "./widgets/Chart.tsx", client: "only" },
  },
});
```

## हाइड्रेशन

डिफ़ॉल्ट रूप से एक आइलैंड `client:visible` का उपयोग करता है: यह तब हाइड्रेट होता है जब पाठक इसे स्क्रॉल करके दृश्य में लाता है, इसलिए आइलैंड्स से भरा पेज भी तुरंत लोड होता है। आइलैंड फ़ाइल में `export const client` के साथ किसी दूसरी रणनीति को चुनें:

```tsx islands/Chart.tsx lineNumbers
// Skip server rendering entirely — for components that touch the DOM/window.
export const client = "only";

export default function Chart() {
  /* ... */
}
```

| `client` मान | हाइड्रेट होता है | इसके लिए उपयोग करें |
| --- | --- | --- |
| `"visible"` _(डिफ़ॉल्ट)_ | जब स्क्रॉल करके दृश्य में आए | अधिकांश आइलैंड्स |
| `"load"` | पेज लोड होते ही तुरंत | ऊपरी हिस्से का, तुरंत चाहिए वाला UI |
| `"idle"` | जब मुख्य थ्रेड निष्क्रिय हो | गैर-अत्यावश्यक इंटरैक्टिविटी |
| `"only"` | केवल क्लाइंट, कभी सर्वर-रेंडर नहीं | ऐसी लाइब्रेरीज़ जिन्हें `window`/`document` चाहिए (चार्ट, एडिटर) |

## फ्रेमवर्क

**React बिना किसी सेटअप के काम करता है** — जैसे ही आपके प्रोजेक्ट में कोई `.tsx`/`.jsx` आइलैंड होता है, Blume इसे अपने आप चालू कर देता है।

जब भी React सक्षम होता है, [React Compiler](https://react.dev/learn/react-compiler) डिफ़ॉल्ट रूप से चालू रहता है, इसलिए आपके आइलैंड्स स्वतः-मेमोआइज़्ड होते हैं — हाथ से लिखे `useMemo`/`useCallback` की ज़रूरत नहीं। यह Blume के साथ ही आता है; इंस्टॉल करने को कुछ नहीं है। `blume.config.ts` में इससे बाहर निकलें:

```ts blume.config.ts
export default defineConfig({
  react: { compiler: false },
});
```

**Vue और Svelte** भी समर्थित हैं; संबंधित Astro इंटीग्रेशन इंस्टॉल करें और जब Blume को कोई `.vue` या `.svelte` आइलैंड दिखता है, तो वह रेंडरर को जोड़ देता है:

```bash
# Vue
npm install @astrojs/vue vue

# Svelte
npm install @astrojs/svelte svelte
```

```vue islands/Toggle.vue lineNumbers
<script setup>
import { ref } from "vue";
const on = ref(false);
</script>

<template>
  <button @click="on = !on">{{ on ? "On" : "Off" }}</button>
</template>
```

MDX में आपके द्वारा पास किए गए प्रॉप्स (`<Counter start={5} />`) कंपोनेंट को फ़ॉरवर्ड कर दिए जाते हैं, और चिल्ड्रन (`<Counter>label</Counter>`) डिफ़ॉल्ट स्लॉट के रूप में पहुँचते हैं।

:::tip
आइलैंड्स क्लाइंट पर हाइड्रेट होते हैं, इसलिए जो कुछ भी आप प्रॉप के रूप में पास करते हैं वह सीरियलाइज़ेबल होना चाहिए — स्ट्रिंग्स, संख्याएँ, सादे ऑब्जेक्ट्स; फ़ंक्शन नहीं।
:::

## हुक्स

आइलैंड्स अपने आप हाइड्रेट होते हैं, इसलिए प्रोजेक्ट डेटा को पिरोने के लिए कोई React कॉन्टेक्स्ट नहीं होता। इसके बजाय, `blume/hooks` एक छोटा स्नैपशॉट पढ़ता है जिसे लेआउट पेज में सीरियलाइज़ करता है — कोई प्रॉप ड्रिलिंग नहीं:

```tsx islands/PageInfo.tsx lineNumbers
import { useBlume, usePage } from "blume/hooks";

export default function PageInfo() {
  const blume = useBlume();
  const page = usePage();
  if (!(blume && page)) {
    return null;
  }
  return (
    <p>
      You're reading <strong>{page.title}</strong> on {blume.config.title}.
    </p>
  );
}
```

| हुक | क्या लौटाता है |
| --- | --- |
| `useBlume()` | साइट के लिए `{ config, navigation }`, या माउंट से पहले `null` |
| `usePage()` | मौजूदा पेज के लिए `{ route, title }`, या माउंट से पहले `null` |
| `useSearch()` | `{ search, results, loading }` — कॉन्फ़िगर किए गए सर्च प्रोवाइडर से क्वेरी करें |
| `useAskAI()` | `{ ask, messages, loading, reset }` — Ask AI एंडपॉइंट से स्ट्रीम करें |

`useBlume()` और `usePage()` तब तक `null` लौटाते हैं जब तक आइलैंड माउंट नहीं हो जाता (ताकि सर्वर और क्लाइंट एक ही पहला फ़्रेम रेंडर करें) — इसके लिए गार्ड लगाएँ। स्नैपशॉट केवल उन पेजों पर उत्सर्जित होता है जो React भेजते हैं, इसलिए पूरी तरह स्टैटिक साइट को कोई कीमत नहीं चुकानी पड़ती।

`PageLayout` से बने [कस्टम पेजों](/docs/advanced/custom-pages) पर, `clientData` पास करें ताकि वहाँ के आइलैंड्स उसे पढ़ सकें:

```astro
<PageLayout
  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
  {/* …other props… */}
/>
```

---

# फ़ोल्डर मेटा
Source: https://useblume.dev/hi/docs/content/meta

आपके कंटेंट ट्री का हर फ़ोल्डर एक साइडबार समूह बन जाता है। उस समूह की दिखावट और उसके चिल्ड्रन के क्रम को नियंत्रित करने के लिए उसके पेजों के साथ एक `meta.ts` रखें। यह पूरी तरह वैकल्पिक है: इसके बिना, समूह का लेबल फ़ोल्डर का ह्यूमनाइज़्ड नाम होता है और उसके पेज [index, न्यूमेरिक प्रीफ़िक्स, फिर वर्णानुक्रम](/docs/content/navigation#ordering) के अनुसार क्रमबद्ध होते हैं।

## मेटा परिभाषित करना

पूरी तरह टाइप किए गए कॉन्फ़िग के लिए एक `defineMeta` ऑब्जेक्ट एक्सपोर्ट करें। फ़ाइल को उस फ़ोल्डर की जड़ में रखें जिसे वह कॉन्फ़िगर करती है — `guides/meta.ts` **Guides** समूह को कॉन्फ़िगर करती है:

```ts meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});
```

हर फ़ील्ड वैकल्पिक है — केवल वही सेट करें जिसे आप ओवरराइड करना चाहते हैं।

## फ़ील्ड

| फ़ील्ड | प्रकार | विवरण |
| --- | --- | --- |
| `title` | `string` | समूह का लेबल। डिफ़ॉल्ट रूप से फ़ोल्डर का ह्यूमनाइज़्ड नाम। |
| `icon` | `string` | लेबल के बगल में दिखाया जाने वाला आइकन। |
| `order` | `number` | सहोदर समूहों और पेजों के बीच स्थिति। छोटी संख्याएँ पहले क्रमबद्ध होती हैं। |
| `collapsed` | `boolean` | [`group` डिस्प्ले मोड](/docs/content/navigation#display-modes) के तहत, क्या समूह संकुचित अवस्था में शुरू होता है। |
| `display` | `"flat" \| "group" \| "page"` | इस समूह के लिए रेंडर मोड; वैश्विक [`navigation.sidebar.display`](/docs/content/navigation#display-modes) को ओवरराइड करता है। |
| `pages` | `string[]` | समूह के चिल्ड्रन का स्पष्ट क्रम, स्लग के अनुसार। |

`pages` सरणी चिल्ड्रन को स्लग के अनुसार सूचीबद्ध करती है — फ़ोल्डर या फ़ाइल का नाम, जिसमें से न्यूमेरिक प्रीफ़िक्स और कोई भी कोष्ठक हटा दिए गए हों (इसलिए `01-quickstart.mdx` का स्लग `"quickstart"` है)। जिन चिल्ड्रन को आप छोड़ देते हैं, वे फिर भी दिखते हैं — सूचीबद्ध वालों के बाद।

समूह कैसे रेंडर होते हैं — फ़्लैट हेडर, संकुचित होने वाले डिस्क्लोज़र, या ड्रिल-इन पैनल — यह डिफ़ॉल्ट रूप से पूरे साइडबार के `navigation.sidebar.display` से तय होता है; केवल इस समूह के लिए इसे ओवरराइड करने हेतु यहाँ `display` सेट करें। किसी फ़ोल्डर का `index` पेज इसे फ्रंटमैटर से भी सेट कर सकता है, जो `meta.ts` पर भारी पड़ता है — देखें [प्रति-समूह ओवरराइड्स](/docs/content/navigation#per-group-overrides)।

## कंप्यूटेड मेटा

चूँकि `meta.ts` एक वास्तविक मॉड्यूल है, आप मेटा की गणना कर सकते हैं — स्कैन के समय इसे बनाने के लिए ऑब्जेक्ट के बजाय एक फ़ंक्शन (सिंक या `async`) पास करें। किसी बाहरी स्रोत से पेजों को क्रमबद्ध करने के लिए उपयोगी:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));
```

## समूह के भीतर क्रम

`pages` सरणी किसी समूह के चिल्ड्रन का क्रम तय करती है। जो कुछ भी यह छोड़ देती है, वह प्रत्येक पेज के फ्रंटमैटर `sidebar.order` पर वापस चला जाता है, फिर फ़ाइल सिस्टम पर (पहले एक `index` पेज, फिर न्यूमेरिक प्रीफ़िक्स, फिर वर्णानुक्रम)। पूर्ण साइडबार प्राथमिकता क्रम के लिए — जिसमें स्पष्ट कॉन्फ़िग साइडबार भी शामिल है — देखें [नेविगेशन › क्रम](/docs/content/navigation#ordering)।

URL सेगमेंट जोड़े _बिना_ पेजों को समूहबद्ध करने के लिए, आपको `meta.ts` की ज़रूरत ही नहीं है: कोष्ठक वाले फ़ोल्डर नाम का उपयोग करें — देखें [पेज › समूह फ़ोल्डर](/docs/content#group-folders)।

## अंतर्राष्ट्रीयकरण

[i18n](/docs/content/i18n) के तहत, फ़ोल्डर मेटा प्रति लोकेल रिज़ॉल्व होता है: फ़्रेंच समूह को स्वतंत्र रूप से क्रमबद्ध करने के लिए `fr/guides/` के अंतर्गत एक `meta.ts` रखें।

ऐसे फ़ोल्डर मेटा के लिए जो हर भाषा में समान है, एक `$` मार्कर जोड़ें ताकि एक ही फ़ाइल बिना डुप्लिकेशन के सभी लोकेल्स के लिए काम करे:

```txt
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

किसी विशिष्ट लोकेल का `meta.ts` उस भाषा के लिए साझा `meta.$.ts` को फिर भी ओवरराइड करता है।

## आगे कहाँ जाएँ

**[नेविगेशन](/docs/content/navigation)**

साइडबार, ब्रेडक्रंब और टैब कैसे बनाए जाते हैं।

**[फ्रंटमैटर](/docs/reference/frontmatter)**

प्रति-पेज मेटाडेटा, जिसमें `sidebar` ओवरराइड्स शामिल हैं।

---

# नेविगेशन
Source: https://useblume.dev/hi/docs/content/navigation

Blume फ़ाइल सिस्टम से आपका साइडबार बनाता है, फिर आपको उसे जितना चाहें — या जितना कम चाहें — परिष्कृत करने देता है: पेज दर पेज, फ़ोल्डर दर फ़ोल्डर, या एक स्पष्ट कॉन्फ़िग के साथ। ब्रेडक्रंब, पिछला/अगला लिंक, और पेज पर मौजूद आउटलाइन सभी उसी मॉडल से निकलते हैं, कुछ भी जोड़ने की ज़रूरत नहीं।

## जेनरेट किया गया साइडबार

डिफ़ॉल्ट रूप से साइडबार आपके कंटेंट ट्री का प्रतिबिंब होता है:

- फ़ोल्डर **समूह** बन जाते हैं, फ़ाइलें **पेज** बन जाती हैं
- एक पेज का लेबल उसका फ्रंटमैटर `title` होता है; एक समूह का लेबल मानव-पठनीय बनाया गया फ़ोल्डर नाम होता है
- आइटम [संख्यात्मक उपसर्ग](/docs/content) के अनुसार क्रमबद्ध होते हैं, फिर वर्णानुक्रम में, और एक फ़ोल्डर का `index` पेज सबसे पहले आता है

कई साइटों के लिए इतना ही काफ़ी है — नीचे दी गई हर चीज़ वैकल्पिक है।

## पेज लेबल, आइकन, और बैज

एक ही पेज साइडबार में कैसे दिखे, इसे उसके फ्रंटमैटर में `sidebar` के अंतर्गत समायोजित करें:

```yaml lineNumbers
sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group
```

पूरे पेज स्कीमा के लिए [फ्रंटमैटर](/docs/reference/frontmatter) देखें।

## फ़ोल्डर समूह

हर फ़ोल्डर एक साइडबार समूह बन जाता है। समूह का शीर्षक, आइकन, क्रम, और उसके चाइल्ड आइटम्स का क्रम तय करने के लिए उसके पेजों के साथ एक [`meta.ts`](/docs/content/meta) रखें:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

हर फ़ील्ड और स्कैन के समय मेटा की गणना करने के लिए [फ़ोल्डर मेटा](/docs/content/meta) देखें।

एक फ़ोल्डर का `meta.title` और उसके अपने `index` पेज का फ्रंटमैटर `title` स्वतंत्र रूप से हल किए जाते हैं — i18n के अंतर्गत एक का अनुवाद करना और दूसरे को भूल जाना एक सही साइडबार दिखाता है, लेकिन लैंडिंग पेज पर ही पुराना `<title>`/शीर्षक रह जाता है। जब ये अलग हो जाते हैं तो Blume एक `BLUME_NAV_INDEX_TITLE_MISMATCH` चेतावनी देता है। फ़ॉलबैक लोकेल से भरे गए अअनुवादित पेज इससे मुक्त हैं — उनका शीर्षक फ़ॉलबैक लोकेल का है, और समाधान पेज का अनुवाद करना है, उसका फ्रंटमैटर संपादित करना नहीं।

URL सेगमेंट जोड़े _बिना_ पेजों को समूहबद्ध करने के लिए, कोष्ठक वाले फ़ोल्डर नाम का उपयोग करें — देखें [पेज](/docs/content#group-folders)।

## डिस्प्ले मोड

`navigation.sidebar.display` तय करता है कि हर साइडबार समूह कैसे रेंडर हो:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`** (डिफ़ॉल्ट) — एक ऐसा हेडर जो संकुचित नहीं होता, जिसके नीचे उसके पेज सूचीबद्ध होते हैं। जो पेज किसी समूह में नहीं हैं वे हमेशा पहले, समूह अनुभागों के ऊपर सूचीबद्ध होते हैं, ताकि उन्हें किसी समूह के चाइल्ड आइटम न समझा जाए।
- **`group`** — प्रति समूह एक संकुचित होने वाला `<details>` प्रकटीकरण। समूह डिफ़ॉल्ट रूप से संकुचित अवस्था में शुरू होते हैं; वर्तमान पेज वाला समूह हमेशा खुला शुरू होता है, ताकि केवल वही अनुभाग विस्तृत हो जिसमें आप हैं। किसी समूह को हर हाल में खुला रखने के लिए [फ़ोल्डर मेटा](/docs/content/meta) में `collapsed: false` सेट करें।
- **`page`** — हर समूह एक ही पंक्ति होती है, जिस पर क्लिक करने से साइडबार एक उप-पैनल में सरक जाता है जिसमें केवल उस समूह के आइटम दिखते हैं, और ऊपर एक पीछे जाने वाला तीर होता है। यह पैनल रूट-अवेयर है, इसलिए समूह के अंदर किसी पेज पर सीधे पहुँचने पर वह सीधे उसी पर खुलता है।

:::tip
`page` मोड गहरे अनुभागों को व्यवस्थित रखता है — जब समूहों में बहुत सारे चाइल्ड आइटम हों और आप उन्हें स्क्रॉल करके पार करने के बजाय उनमें गहराई से जाना पसंद करें, तब इसका उपयोग करें।
:::

### प्रति-समूह ओवरराइड

जेनरेट किया गया कोई भी समूह ग्लोबल मोड से बाहर निकल सकता है — इसके लिए किसी स्पष्ट साइडबार की ज़रूरत नहीं। फ़ोल्डर के [`meta.ts`](/docs/content/meta) में `display` सेट करें, या — जब फ़ोल्डर में कोई `index` पेज हो — उस पेज के फ्रंटमैटर में `sidebar` के अंतर्गत, और केवल वही समूह बदलता है:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

जेनरेट किए गए किसी समूह का प्रभावी मोड सबसे उच्च प्राथमिकता से हल किया जाता है:

1. समूह के अपने `index` पेज के फ्रंटमैटर में `sidebar.display`
2. फ़ोल्डर के `meta.ts` में `display`
3. ग्लोबल `navigation.sidebar.display`
4. Blume का डिफ़ॉल्ट (`flat`)

किसी समूह का `display` केवल उसी समूह पर लागू होता है — नेस्टेड उपसमूह अपना स्वयं का मान इसी शृंखला के माध्यम से हल करते हैं। इंडेक्स पेज वाला `page`-मोड समूह फिर भी अपने उप-पैनल में गहराई तक जाता है: इंडेक्स पेज पैनल के पहले आइटम के रूप में सूचीबद्ध होता है, और उसके URL पर पहुँचने पर पैनल सीधे खुल जाता है।

`sidebar.display` का कहीं और कोई अर्थ नहीं है — किसी गैर-इंडेक्स पेज पर, कंटेंट रूट के अपने `index` पेज पर (रूट कोई समूह नहीं है; `navigation.sidebar.display` का उपयोग करें), या किसी भी पेज पर जब एक [स्पष्ट साइडबार](#explicit-sidebar) कॉन्फ़िगर किया गया हो (उसके आइटम हर समूह के मोड के स्वामी होते हैं) — इसलिए Blume उसे चुपचाप छोड़ देने के बजाय एक `BLUME_SIDEBAR_DISPLAY_IGNORED` चेतावनी देता है। `collapsed` `group` मोड के लिए विशिष्ट बना रहता है; जब कोई समूह `flat` या `page` पर हल होता है तो वह निष्क्रिय रहता है।

एक [स्पष्ट साइडबार](#explicit-sidebar) में मौजूद समूह अपने स्वयं के `display` से ग्लोबल मोड को ओवरराइड करता है, ठीक पहले की तरह।

## क्रम निर्धारण

जब साइडबार जेनरेट होता है, तो क्रम सबसे उच्च प्राथमिकता से हल किया जाता है:

1. **कॉन्फ़िग साइडबार**

    एक स्पष्ट `navigation.sidebar` जेनरेट किए गए ट्री को पूरी तरह से बदल देता
    है।

2. **फ़ोल्डर मेटा**

    `meta.ts` में मौजूद `pages` ऐरे एक समूह को क्रमबद्ध करता है।

3. **फ्रंटमैटर**

    किसी पेज पर `sidebar.order`।

4. **फ़ाइल सिस्टम**

    पहले एक `index` पेज, फिर संख्यात्मक उपसर्ग, फिर लेबल के अनुसार वर्णानुक्रम।

एक ही स्पष्ट या संख्यात्मक क्रम पर पहुँचने वाले दो सहोदर आपस में वर्णानुक्रम पर लौट आते हैं — Blume एक `BLUME_DUPLICATE_SIDEBAR_ORDER` चेतावनी देता है ताकि यह टकराव अनदेखा न रह जाए।

## छिपे हुए पेज

किसी पेज को साइडबार से — और पिछला/अगला पेजिनेशन से — छिपाएँ, जबकि वह बना रहे और अपने URL से पहुँच योग्य रहे:

```yaml
sidebar:
  hidden: true
```

## टैब

शीर्ष-स्तरीय अनुभागों को हेडर में टैब के रूप में रेंडर करें, जो एक बड़ी साइट को अलग-अलग क्षेत्रों में बाँटने के लिए उपयोगी है — जैसे अडैप्टर, एक API, और AI गाइड। जब वर्तमान रूट किसी टैब के `path` के अंतर्गत आता है तो वह टैब हाइलाइट हो जाता है:

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

एक सक्षम किया गया [OpenAPI या AsyncAPI रेफ़रेंस](/docs/advanced/api-reference) अपने रूट पर माउंट होता है लेकिन अपने आप कोई टैब नहीं जोड़ता — उसे हेडर में सामने लाने के लिए (और, नेटिव रेंडरर के लिए, उसके ऑपरेशंस साइडबार को सीमित करने के लिए) एक टैब को उस रूट पर इंगित करें, जो भी लेबल आपको पसंद हो उसके साथ:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

एक टैब का `path` उसका अनुभाग उपसर्ग होता है, और वही लिंक टारगेट का भी काम करता है। जिस अनुभाग का `path` अपने आप में कोई पेज नहीं है — बिना `index.mdx` वाला फ़ोल्डर — वह एक 404 पर ले जाता, इसलिए टैब इसके बजाय अनुभाग के पहले पेज पर लौट आता है। जब आप चाहते हैं कि वह कहीं और पहुँचे तो `href` सेट करें:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

यह उन रूट्स के लिए मायने रखता है जो कंटेंट ट्री का हिस्सा नहीं हैं, क्योंकि फ़ॉलबैक उन्हें देख नहीं सकता: जेनरेट किया गया [चेंजलॉग](/docs/advanced/changelog) इंडेक्स, या `pages/` के अंतर्गत आपके द्वारा जोड़ा गया कोई [कस्टम पेज](/docs/advanced/custom-pages)। `href` के बिना, एक `/changelog` टैब इंडेक्स के बजाय सबसे नई प्रविष्टि पर पहुँचता है। जो टैब `href` सेट नहीं करते, वे अप्रभावित रहते हैं।

एक [i18n](/docs/content/i18n) साइट पर, एक टैब का `label` (और एक ड्रॉपडाउन आइटम का) स्ट्रिंग के बजाय प्रति-लोकेल मैप हो सकता है — सक्रिय लोकेल की प्रविष्टि जीतती है, फिर डिफ़ॉल्ट लोकेल की:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}
```

टैब **साइडबार को भी सीमित करते हैं**: जब वर्तमान रूट किसी टैब के `path` के अंतर्गत आता है, तो साइडबार केवल उसी अनुभाग के पेज दिखाता है — इसलिए `/adapters/*` अडैप्टर सूचीबद्ध करता है और कुछ नहीं। टैब के `path` पर मौजूद फ़ोल्डर अनुभाग बन जाता है, इसलिए इसके लिए टैब्स के अलावा किसी अतिरिक्त कॉन्फ़िग की ज़रूरत नहीं; अपने कंटेंट को प्रति टैब एक फ़ोल्डर में व्यवस्थित करें और हर टैब को उस पर इंगित करें।

ऐसे रूट पर जो किसी टैब के अंतर्गत नहीं है (या जिस टैब का `path` `/` है), साइडबार वे पेज दिखाता है जो किसी टैब से संबंधित _नहीं_ हैं — हर टैब का फ़ोल्डर उससे छिपा रहता है, क्योंकि उस अनुभाग के पास पहले से ही हेडर में अपना टैब है। इसलिए एक रूट लैंडिंग पेज आपके ढीले शीर्ष-स्तरीय पेज सूचीबद्ध करता है जबकि अनुभागों में बँटा कंटेंट अपने टैब के पीछे रहता है, जो Fumadocs के रूट फ़ोल्डरों जैसा है। यदि किसी रूट के पास इस तरह दिखाने के लिए अपने कोई पेज नहीं हैं, तो इसके बजाय पूरा ट्री दिखाया जाता है, ताकि साइडबार कभी खाली न रहे।

## सिलेक्टर

किसी साइट के पूरे विभाजनों के बीच स्विच करने के लिए — एक प्रोडक्ट, एक वर्शन, या गंतव्यों का कोई भी समूहबद्ध सेट — एक `selector` जोड़ें। हर एक हेडर में ड्रॉपडाउन के रूप में रेंडर होता है, और वह विकल्प दिखाता है जिसका `path` वर्तमान रूट से मेल खाता है:

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

हर आइटम एक `label`, एक `path`, और वैकल्पिक `icon`, `description`, और `tag` लेता है। `kind` (`dropdown`, `product`, `version`, या `language`) इस बारे में एक संकेत है कि सिलेक्टर का उपयोग कैसे किया जा रहा है; सभी एक ही ड्रॉपडाउन रेंडर करते हैं।

[वर्शनिंग](/docs/content/versioning) कॉन्फ़िगर होने पर, Blume स्वतः एक वर्शन सिलेक्टर रेंडर करता है — यहाँ अपना स्वयं का `kind: "version"` सिलेक्टर घोषित करना स्वचालित वाले की जगह ले लेता है, इसलिए हाथ से बनाए गए सेटअप काम करते रहते हैं।

## फ़ीचर्ड लिंक

लिंक को साइडबार के सबसे ऊपर, हर अनुभाग के ऊपर पिन करें — एक ब्लॉग, एक चेंजलॉग, एक संपर्क या सहायता पेज जो हमेशा एक क्लिक की दूरी पर होना चाहिए। जेनरेट किए गए ट्री के विपरीत, फ़ीचर्ड लिंक **टैब द्वारा सीमित नहीं** होते: वे हर रूट पर, हर ब्रेकपॉइंट पर दिखते हैं।

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

हर लिंक एक `label`, एक `href`, और एक वैकल्पिक `icon` लेता है (एक [बिल्ट-इन आइकन](/docs/content/components#icon) नाम, इमेज पाथ/URL, या इनलाइन SVG — बाकी हर जगह की तरह)। एक `href` कहीं भी इंगित कर सकता है: एक बाहरी URL नए टैब में खुलता है, जबकि एक आंतरिक रूट (`/contact`) बिल्ड समय पर आपके पेजों के विरुद्ध सत्यापित किया जाता है, और कुछ भी मेल न खाने पर आपको चेतावनी देता है।

## स्पष्ट साइडबार

पूर्ण नियंत्रण के लिए, `navigation.sidebar` में स्पष्ट आइटम सूचीबद्ध करें — एक सादा ऐरे `sidebar.items` का संक्षिप्त रूप है, और ऑब्जेक्ट रूप उन्हें एक ग्लोबल [`display`](#display-modes) के साथ जोड़ता है। जब आइटम सेट होते हैं, तो Blume उन्हें ज्यों का त्यों उपयोग करता है और फ़ाइल-सिस्टम जेनरेशन छोड़ देता है:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}
```

हर आइटम एक पेज रूट (एक स्ट्रिंग), एक समूह (`label` + `items`), या एक लिंक (`label` + `href`) होता है। समूह नेस्ट हो सकते हैं, ग्लोबल [`display` मोड](#display-modes) को ओवरराइड कर सकते हैं, और `collapsed` अवस्था में शुरू हो सकते हैं।

## हेडर क्रियाएँ

`navigation.actions` हेडर में, आइकन बटनों के बाईं ओर सादे लिंक रखता है, और `navigation.cta` वह एकमात्र भरा हुआ बटन है:

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

`cta` जानबूझकर एकवचन है — एक डॉक्स हेडर में ठीक एक ऐसी चीज़ के लिए जगह होती है जो पाठक से करने को कही जा रही हो, और बटनों की एक कतार कुछ भी नहीं कहती। द्वितीयक लिंक `actions` में होने चाहिए, या [`featured`](#featured-links) में यदि उन्हें साइडबार के साथ रहना चाहिए।

कोई `http(s)` या प्रोटोकॉल-सापेक्ष href नए टैब में खुलता है; एक रूट उसी टैब में रहता है, और एक `featured` लिंक की तरह बिल्ड समय पर आपके पेजों के विरुद्ध सत्यापित किया जाता है — इसलिए उसी होस्ट पर किसी अन्य ऐप द्वारा परोसा जाने वाला पेज (जैसे प्रोडक्ट पर `/signup`) एक पूर्ण URL के रूप में लिखा जाना चाहिए। `actions` `sm` ब्रेकपॉइंट से नीचे छिपे रहते हैं, जहाँ हेडर में लोगो और नेविगेशन टॉगल के अलावा और किसी चीज़ के लिए जगह नहीं होती। `cta` भी वहाँ छिपता है, सिवाय ऐसे पेज पर जिसमें कोई नेविगेशन टॉगल न हो — बिना टैब वाला `PageLayout` पर एक लैंडिंग पेज — जहाँ वह बना रहता है, क्योंकि फ़ोन पर उसे सामने लाने वाली और कोई चीज़ नहीं है।

## रिपॉज़िटरी लिंक

जब आप अपने कॉन्फ़िग में [`github`](/docs/configuration) सेट करते हैं, तो Blume हेडर में — थीम टॉगल के बगल में — एक GitHub आइकन दिखाता है जो आपकी रिपॉज़िटरी से लिंक होता है। यह डिफ़ॉल्ट रूप से चालू है; इसे `navigation.repo` से छिपाएँ:

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // hide the header GitHub link (default: true)
}
```

यह लिंक तभी दिखता है जब `github` कॉन्फ़िगर किया गया हो, इसलिए बिना रिपॉज़िटरी वाले प्रोजेक्ट किसी भी तरह अप्रभावित रहते हैं।

`repo` एक पूर्ण URL भी लेता है, जो हेडर के चिह्न को GitHub पर कहीं भी इंगित करता है:

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

यह ऐसे प्रोजेक्ट के लिए है जिसकी डॉक्स रिपॉज़िटरी निजी है। `github` प्रति-पेज संपादन लिंक, हेडर के चिह्न और [एजेंट मैनिफ़ेस्ट](/docs/configuration/ai) की रिपॉज़िटरी — तीनों को एक साथ चलाता है, इसलिए ऐसे प्रोजेक्ट को `github` अनसेट छोड़ना पड़ता है — और एक URL ही वह चीज़ है जो उसे फिर भी कहीं सार्वजनिक की ओर इंगित करता चिह्न दिखाने देती है। आइकन GitHub का चिह्न ही रहता है, इसलिए किसी अन्य होस्ट का लिंक [`actions`](#header-actions) में होना चाहिए।

## ब्रेडक्रंब और पेजिनेशन

ये साइडबार ट्री से मुफ़्त में मिलते हैं — कोई कॉन्फ़िगरेशन नहीं:

- **ब्रेडक्रंब** शीर्षक के ऊपर वर्तमान पेज का पैरेंट समूह दिखाते हैं।
- हर पेज के नीचे **पिछला और अगला** लिंक साइडबार के क्रम का अनुसरण करते हैं, और छिपे हुए पेजों को छोड़ देते हैं।

## इस पेज पर

हर पेज के `##` और `###` शीर्षकों से एक दायाँ-रेल आउटलाइन स्वतः जेनरेट होता है, ताकि लंबे पेज भी आसानी से स्कैन किए जा सकें। सँकरी स्क्रीन पर, जहाँ दायाँ रेल छिपा होता है, यह कंटेंट के ऊपर एक "इस पेज पर" ड्रॉपडाउन में सिमट जाता है।

## पेज क्रियाएँ

विषय-सूची के नीचे, हर पेज त्वरित क्रियाओं का एक सेट दिखाता है:

- **GitHub पर संपादित करें** — सीधे स्रोत फ़ाइल से लिंक करता है। आपके कॉन्फ़िग में [`github`](/docs/configuration) सेट करने पर दिखता है।
- **ऊपर स्क्रॉल करें** — लंबे पेजों के शीर्ष पर सहजता से लौटाता है।
- **फ़ीडबैक दें** — एक वैकल्पिक प्रतिक्रिया और नोट के साथ पहले से भरा हुआ GitHub इशू खोलता है (इसके लिए भी `github` ज़रूरी है)।

अन्य क्रियाएँ पेज को AI टूल्स को सौंपती हैं — **Markdown के रूप में कॉपी करें** और **चैट में खोलें** — जिन्हें [AI](/docs/configuration/ai#copy-as-markdown) में कवर किया गया है।

[`export`](/docs/configuration/export) चालू होने पर, एक **एक्सपोर्ट** क्रिया पाठकों को पेज को PDF या EPUB के रूप में डाउनलोड करने की सुविधा भी देती है।

---

# कंटेंट स्रोत
Source: https://useblume.dev/hi/docs/content/sources

डिफ़ॉल्ट रूप से Blume `.md`/`.mdx` फ़ाइलों का एक फ़ोल्डर पढ़ता है। **कंटेंट स्रोत** आपको कहीं और से पेज लाने देते हैं — किसी रिमोट रिपॉज़िटरी, किसी CMS, या किसी भी कस्टम बैकएंड से — और कई स्रोतों को एक ही साइट में मिलाने देते हैं। स्रोत बिल्ड टाइम पर पढ़े जाते हैं; Blume स्टैटिक-फ़र्स्ट ही रहता है।

## डिफ़ॉल्ट

बिना किसी कॉन्फ़िगरेशन के, Blume आपके कंटेंट रूट (डिफ़ॉल्ट रूप से `docs`) को एक निहित फ़ाइलसिस्टम स्रोत के रूप में स्कैन करता है। टॉप-लेवल `content.root`/`include`/`exclude` विकल्प पहले की तरह ही काम करते हैं — कुछ भी बदलने की ज़रूरत नहीं।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: { root: "docs" },
});
```

## कई स्रोत

स्रोतों को जोड़ने के लिए एक `content.sources` ऐरे जोड़ें। हर एंट्री एक वैकल्पिक `prefix` से नेमस्पेस की जाती है, इसलिए उसके रूट `/<prefix>/…` के अंदर नेस्ट होते हैं। जब `sources` मौजूद होता है, तो यह निहित डिफ़ॉल्ट की जगह ले लेता है, इसलिए अपने लोकल डॉक्स के लिए एक `filesystem` एंट्री शामिल करें।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      // Local docs at the site root
      { type: "filesystem", root: "docs" },

      // Remote MDX from a GitHub repo, mounted under /sdk
      {
        type: "mdx-remote",
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      },
    ],
  },
});
```

अगर दो स्रोत एक ही रूट पर पहुँचते हैं, तो Blume एक `BLUME_DUPLICATE_ROUTE` बिल्ड एरर रिपोर्ट करता है — हर स्रोत को एक अलग `prefix` दें।

## Obsidian

बिल्ट-इन `obsidian` स्रोत किसी [Obsidian](https://obsidian.md) वॉल्ट को उसी जगह पढ़ता है। कोई एक्सपोर्ट चरण नहीं है और आपके रिपॉज़िटरी में कुछ भी जेनरेट नहीं होता: वॉल्ट ही सत्य का स्रोत बना रहता है, और Blume लोड करते समय Obsidian की बोली को Markdown में उतार देता है।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "obsidian",
        prefix: "notes",
        vault: "vault",
        // Vault folder names to skip at any depth, on top of dot-folders
        exclude: ["Templates", "Daily"],
      },
    ],
  },
});
```

`[[Wikilinks]]` रूट लिंक बन जाते हैं, जिन्हें पथ के बजाय पूरे वॉल्ट में नोट के नाम से संबोधित किया जाता है — ठीक उसी तरह जैसे Obsidian नोट्स को संबोधित करता है। कस्टम लिंक टेक्स्ट (`[[Note|label]]`), शीर्षक ऐंकर (`[[Note#Install]]`), पूरे पथ (`[[folder/Note]]` और `[[folder/Note.md]]`), वे आंशिक पथ जो Obsidian की डिफ़ॉल्ट "shortest path when possible" सेटिंग लिखती है (`[[guides/Note]]`), और `[[Note\|label]]` रूप जो Obsidian किसी टेबल सेल के अंदर लिखता है — ये सभी काम करते हैं, और जो नोट अपने फ़्रंटमैटर में `slug` सेट करता है, उसे उस रूट पर लिंक किया जाता है जिस पर वह slug प्रकाशित होता है। जब दो नोट्स का नाम एक ही होता है, तो वह नोट जीतता है जिसका पूरा वॉल्ट पथ ठीक वही नाम है — Obsidian किसी लिंक को नाम से पहले पथ के रूप में हल करता है — उसके बाद वॉल्ट क्रम में पहला (नोट्स से पहले फ़ोल्डर, केस-असंवेदनशील रूप से, Obsidian के फ़ाइल एक्सप्लोरर की तरह)। Blume केवल तभी चेतावनी देता है जब कोई विकिलिंक वास्तव में ऐसी टकराहट से होकर हल होता है; अस्पष्टता दूर करने के लिए एक लंबा पथ लिखें। कोई ब्लॉक रेफ़रेंस (`[[Note#^id]]`) अपने नोट से बिना ऐंकर के लिंक होता है: ब्लॉक बिना किसी ऐसी id के रेंडर होते हैं जिस पर पहुँचा जा सके। कोई शीर्षक ऐंकर लक्ष्य नोट के वास्तविक शीर्षकों के सापेक्ष हल होता है, जिनका मिलान उसी तरह किया जाता है जैसे Obsidian का ऑटोकम्प्लीट उन्हें लिखता है (`**bold**`, `` `code` `` और लिंक सिंटैक्स हटाकर) और जिन्हें उसी `extractHeadings` पास द्वारा slug किया जाता है जो पेज मैनिफ़ेस्ट भरता है — इसलिए `#Install` का लिंक शीर्षक पर पहुँचता है, न कि किसी ऐसी id पर जो कोई पेज उत्सर्जित ही नहीं करता। `[[#Install]]` उस नोट के किसी शीर्षक को संबोधित करता है जिसे आप लिख रहे हैं। किसी ऐसे शीर्षक का लिंक जो मौजूद नहीं है, पेज लिंक बनाए रखता है, ऐंकर हटा देता है, और चेतावनी देता है।

फ़्रंटमैटर वही रखता है जो Blume का [पेज स्कीमा](/docs/reference/frontmatter) स्वीकार करता है, साथ ही वह हर कुंजी जिसे आप [`frontmatter.extend`](/docs/reference/frontmatter#custom-keys) में घोषित करते हैं (या, उस `type` के नोट्स के लिए, किसी कंटेंट टाइप का `frontmatter`); हर दूसरी Obsidian प्रॉपर्टी — Dataview फ़ील्ड्स, Templater तिथियाँ, `publish`, और Obsidian की अपनी `tags`, `aliases` और `cssclasses` — नोट के उतारे जाने पर हटा दी जाती है, इसलिए Properties UI से लिखा गया वॉल्ट बिना फ़्रंटमैटर एरर के बिल्ड होता है। `aliases` को हल करने के बजाय हटा दिया जाता है — उपनाम लिंक लक्ष्य अभी समर्थित नहीं हैं। किसी नोट के बगल में मौजूद कोई सापेक्ष Markdown इमेज (`![chart](./chart.png)`) वॉल्ट से परोसी जाती है, और जब वॉल्ट आपकी git रिपॉज़िटरी के अंदर रहता है, तो वॉल्ट पेजों को किसी भी अन्य पेज की तरह git से प्राप्त ["Last updated" तिथियाँ](/docs/configuration#last-modified) मिलती हैं। "Edit this page" लिंक `github.dir` के ज़रिए हल होते हैं, इसलिए किसी मोनोरेपो में डॉक्स ऐप के बगल में बैठा वॉल्ट भी अपनी फ़ाइल से लिंक होता है; रिपॉज़िटरी के बाहर मौजूद वॉल्ट को कोई लिंक नहीं मिलता।

वॉल्ट के अंदर लोकेल डायरेक्टरियाँ और वर्ज़न स्नैपशॉट उसी तरह पढ़े जाते हैं जैसे फ़ाइलसिस्टम स्रोत उन्हें पढ़ता है: [i18n](/docs/content/i18n) कॉन्फ़िगर होने पर `fr/Note.md` `/fr/` के अंतर्गत प्रकाशित होता है, [वर्ज़न](/docs/content/versioning) के साथ `v1.0/Note.md` `/v1.0/` के अंतर्गत, और उन नोट्स के विकिलिंक उस रूट की ओर इशारा करते हैं जिस पर हर एक प्रकाशित होता है।

:::note
जिस शीर्षक में स्वयं कोई लिंक होता है, उसका मैनिफ़ेस्ट ऐंकर शीर्षक के Markdown से आता है और उसका रेंडर किया गया `id` उसके टेक्स्ट कंटेंट से। उस शीर्षक के लिए ये दोनों भिन्न होते हैं, इसलिए उसका कोई विकिलिंक सेक्शन के बजाय पेज पर पहुँच सकता है।
:::

किसी `index` नोट का लिंक किसी काल्पनिक `/index` के बजाय उसके फ़ोल्डर के रूट पर पहुँचता है। **कोई अनसुलझा विकिलिंक बिल्ड को विफल करने के बजाय एक बिल्ड चेतावनी के साथ सादे टेक्स्ट तक सीमित हो जाता है**, इसलिए रीफ़ैक्टर के बीच का वॉल्ट भी प्रकाशित होता रहता है। एकल-पंक्ति `%%comments%%` हटा दिए जाते हैं, किसी HTML कमेंट के अंदर का विकिलिंक (`<!-- [[Draft]] -->`) वैसा ही छोड़ दिया जाता है क्योंकि Obsidian भी उसे छिपाता है, और जिस नोट के फ़्रंटमैटर में `title` नहीं होता उसका शीर्षक उसकी फ़ाइल के नाम से बनता है — वही नियम जो Obsidian स्वयं लागू करता है। `index` नोट एकमात्र अपवाद है: यह किसी नोट के बजाय किसी रूट का नाम बताता है, इसलिए उसका शीर्षक Blume की सामान्य व्युत्पत्ति पर चला जाता है (पहला शीर्षक, फिर मानवीकृत सेगमेंट)। फ़ेंस्ड, इंडेंटेड और इनलाइन कोड हूबहू पास हो जाता है, इसलिए इस सिंटैक्स का दस्तावेज़ीकरण करने वाला नोट बच जाता है।

डॉट-फ़ोल्डर छोड़ दिए जाते हैं, जिनमें Obsidian की अपनी `.obsidian` कॉन्फ़िग डायरेक्टरी और `.trash` शामिल हैं — जिन्हें डेव वॉचर भी अनदेखा करता है, इसलिए ऐप में कोई पैन हिलाने या किसी नोट को ट्रैश में डालने से आपकी साइट दोबारा बिल्ड नहीं होती। किसी नोट को संपादित करने से होती है। वे डायरेक्टरियाँ जिन्हें कोई भी कंटेंट स्कैन नहीं पढ़ता (`node_modules`, `dist`, `.git`, …) भी छोड़ दी जाती हैं, इसलिए प्रोजेक्ट में ही रूट किया गया वॉल्ट डिपेंडेंसी README प्रकाशित नहीं करता। वॉल्ट के अंदर के सिमलिंक का अनुसरण किया जाता है, उसी तरह जैसे फ़ाइलसिस्टम स्रोत उनका अनुसरण करता है, इसलिए वॉल्ट में लिंक किया गया कोई शेयर्ड फ़ोल्डर उसके साथ प्रकाशित होता है। `content.root` के अंदर बैठे वॉल्ट को फ़ाइलसिस्टम स्रोत से बाहर रखा जाना चाहिए (`exclude: ["vault/**"]`); तब `blume version cut` उसे स्नैपशॉट से बाहर छोड़ देता है, क्योंकि वॉल्ट अपने नोट्स को वर्तमान के रूप में प्रकाशित करता रहता है।

अभी तक नहीं उतारा गया: कॉलआउट (`> [!note]`) सादे ब्लॉककोट के रूप में रेंडर होते हैं, एम्बेड (`![[image.png]]`) अछूते पास हो जाते हैं, बहु-पंक्ति `%%comments%%` जहाँ के तहाँ छोड़ दिए जाते हैं, और कोई बैकलिंक ग्राफ़ नहीं है।

## रिमोट MDX

बिल्ट-इन `mdx-remote` स्रोत HTTP पर रॉ `.md`/`.mdx` फ़ेच करता है। फ़ाइलों की सूची या तो किसी GitHub रिपॉज़िटरी सबट्री (`github`) से बनाएँ या किसी रॉ बेस URL के सापेक्ष स्पष्ट रूप से (`url` + `files`):

```ts blume.config.ts
{
  type: "mdx-remote",
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
}
```

किसी प्राइवेट रिपॉज़िटरी का टोकन `GITHUB_TOKEN` एनवायरनमेंट वेरिएबल से पढ़ा जाता है — यह कभी भी आपके कॉन्फ़िग या जेनरेट किए गए आउटपुट में इनलाइन नहीं किया जाता, और यह केवल GitHub के अपने होस्ट (`api.github.com`, `raw.githubusercontent.com`) पर ही भेजा जाता है, किसी कस्टम `url` बेस पर कभी नहीं।

रिमोट पेज पूरी MDX-प्लस-कंपोनेंट सटीकता के साथ रेंडर होते हैं: उनकी बॉडी एक छिपी हुई स्टेजिंग डायरेक्टरी में मटीरियलाइज़ की जाती है और आपके लोकल डॉक्स के साथ Astro के ज़रिए रेंडर की जाती है, इसलिए कॉलआउट, टैब और हर दूसरा Blume कंपोनेंट काम करता रहता है।

### कैशिंग और ऑफ़लाइन बिल्ड

हर रिमोट स्रोत `.blume/cache/<source>/` के अंतर्गत एक स्नैपशॉट रखता है। अगर कोई फ़ेच विफल हो जाता है — कोई नेटवर्क गड़बड़ी या CMS आउटेज — तो Blume बिल्ड को विफल करने के बजाय चेतावनी के साथ आखिरी ज्ञात-अच्छा स्नैपशॉट परोसता है। कैश `.blume/` के अंदर रहता है और फिर से जेनरेट होता है, कभी कमिट नहीं किया जाता।

डेव में, रिमोट कंटेंट एक बार फ़ेच किया जाता है और सेशन के लिए फ़्रीज़ कर दिया जाता है; इसे रीफ़्रेश करने के लिए डेव सर्वर को पुनः आरंभ करें। लोकल फ़ाइलसिस्टम स्रोत हमेशा की तरह हॉट-रीलोड होते हैं। इसके बजाय किसी रिमोट स्रोत में बदलावों के लिए पोल करने के लिए, उस पर `pollInterval` (सेकंड में) सेट करें — डेव सर्वर उस अंतराल पर फिर से फ़ेच करता है और तभी रीलोड करता है जब कंटेंट वास्तव में बदलता है। काम करते समय API पर बार-बार अनुरोध भेजने से बचने के लिए इसे अनसेट छोड़ दें।

## GitHub रिलीज़

बिल्ट-इन `github-releases` स्रोत किसी रिपॉज़िटरी की रिलीज़ को एक चेंजलॉग में बदल देता है: हर रिलीज़ एक `type: changelog` एंट्री बन जाती है, इसलिए आपके रिलीज़ नोट्स _ही_ आपका चेंजलॉग हैं — दो बार लिखने की ज़रूरत नहीं। जेनरेट की गई [चेंजलॉग टाइमलाइन](/docs/advanced/changelog) के साथ मिलकर, एक GitHub रिलीज़ प्रकाशित करना एक चेंजलॉग एंट्री भेज देता है।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // include prereleases (default off)
        // drafts: false,       // include drafts (needs a write token)
        // limit: 100,          // cap releases, newest-first
      },
    ],
  },
});
```

हर रिलीज़ अपने आप चेंजलॉग फ़ील्ड्स से मैप हो जाती है: उसका नाम (या टैग) शीर्षक बन जाता है, उसकी प्रकाशन तिथि टाइमलाइन क्रम तय करती है, टैग `changelog.version` बन जाता है, और प्रीरिलीज़ को `Prerelease` टैग किया जाता है (बाकी को `Release`)। नोट्स एंट्री की बॉडी के रूप में रेंडर होते हैं। स्रोत को एक `prefix` दें ताकि उसके रिलीज़ पेज `/changelog/v1-2-0` जैसे रूट के अंदर नेस्ट हों।

एक प्राइवेट रिपॉज़िटरी `GITHUB_TOKEN` एनवायरनमेंट वेरिएबल से प्रमाणित होती है — वही टोकन जो अन्य GitHub फ़ीचर इस्तेमाल करते हैं, कभी भी आपके कॉन्फ़िग में इनलाइन नहीं किया जाता। हर रिमोट स्रोत की तरह यह भी `.blume/cache/<source>/` के अंतर्गत कैश होता है और API अनुपलब्ध होने पर ऑफ़लाइन परोसा जाता है। चूँकि चेंजलॉग पूरक होता है, इसलिए बिना कैश के फ़ेच विफलता (मान लीजिए बिना टोकन वाला कोई CI बिल्ड) बिल्ड को विफल करने के बजाय चेतावनी के साथ एक खाली चेंजलॉग तक सीमित हो जाती है — इसे भरने के लिए अपने CI और डिप्लॉय एनवायरनमेंट में `GITHUB_TOKEN` सेट करें।

## Sanity

बिल्ट-इन `sanity` स्रोत एक GROQ क्वेरी चलाता है और हर डॉक्युमेंट के फ़ील्ड्स को फ़्रंटमैटर से तथा उसकी Portable Text बॉडी को Markdown से मैप करता है। `@sanity/client` पैकेज एक वैकल्पिक पीयर डिपेंडेंसी है — इसे तभी इंस्टॉल करें जब आप इस स्रोत का उपयोग करें।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "sanity",
        prefix: "guides",
        projectId: "abc123",
        dataset: "production",
        query: `*[_type == "guide"]`,
        // Field paths default to title / slug.current / body / _updatedAt
        fields: { slug: "slug.current", body: "content" },
      },
    ],
  },
});
```

किसी प्राइवेट डेटासेट के लिए रीड टोकन `SANITY_TOKEN` एनवायरनमेंट वेरिएबल से आता है। कस्टम Portable Text ब्लॉक टाइप एडैप्टर के `serializers` विकल्प के ज़रिए Blume कंपोनेंट्स से मैप होते हैं, जो तब उपलब्ध होता है जब आप [कस्टम स्रोत](#custom-sources) के माध्यम से सीधे `sanitySource` बनाते हैं।

## Notion

बिल्ट-इन `notion` स्रोत किसी Notion डेटाबेस को एक कलेक्शन में बदल देता है: हर पंक्ति एक पेज बन जाती है, उसकी प्रॉपर्टीज़ फ़्रंटमैटर बन जाती हैं, और उसका ब्लॉक ट्री MDX बन जाता है। कॉलआउट, टॉगल, कॉलम और कोड ब्लॉक संबंधित Blume कंपोनेंट्स से मैप होते हैं। `@notionhq/client` (v5 या उसके बाद का) एक वैकल्पिक पीयर डिपेंडेंसी है; Blume डेटाबेस को उसके पहले डेटा स्रोत के ज़रिए पढ़ता है।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "notion",
        prefix: "handbook",
        database: process.env.NOTION_DB_ID,
        // Property names default to the title-typed prop / Description / Slug / Order
        // Set publishedValue to treat Status as a publish gate (opt-in)
        publishedValue: "Published",
      },
    ],
  },
});
```

इंटीग्रेशन टोकन `NOTION_TOKEN` एनवायरनमेंट वेरिएबल से आता है (डेटाबेस को अपने इंटीग्रेशन के साथ शेयर करें)। डिफ़ॉल्ट रूप से हर पेज इंपोर्ट होता है; `Status` प्रॉपर्टी को एक पब्लिश गेट बनाने के लिए `publishedValue` सेट करें — तब कोई भी दूसरा मान `draft: true` से मैप होता है, जिसे प्रोडक्शन बिल्ड हटा देते हैं। **Notion इमेज URL साइन किए हुए होते हैं और समाप्त हो जाते हैं**, इसलिए एडैप्टर उन्हें बिल्ड टाइम पर साइट की एसेट्स में डाउनलोड कर लेता है और रेफ़रेंस दोबारा लिख देता है — कोई CMS इमेज कभी किसी स्टैटिक बिल्ड को खराब नहीं करती। API कॉल एक छोटे रिक्वेस्ट पूल के ज़रिए नियंत्रित गति से किए जाते हैं (एक बार में 3, जो Notion की प्रति-इंटीग्रेशन रेट लिमिट से मेल खाता है) ताकि सैकड़ों पेज वाले डेटाबेस `429` प्रतिक्रियाओं में फँसे बिना इंपोर्ट हो जाएँ; इसे ट्यून करने के लिए स्रोत पर `concurrency` सेट करें।

## प्रीव्यू और सिंक

दो फ़्लैग यह नियंत्रित करते हैं कि रिमोट कंटेंट कैसे फ़ेच किया जाता है और क्या-क्या शामिल होता है:

- **`--preview`** — `blume dev` या `blume build` पर यह ड्राफ़्ट रेंडर करता है और अप्रकाशित CMS कंटेंट खींचता है — Sanity अपने `previewDrafts` परिप्रेक्ष्य पर स्विच कर जाता है, और Notion `Status` के आधार पर फ़िल्टर करना बंद कर देता है। इस फ़्लैग के बिना प्रोडक्शन बिल्ड हमेशा की तरह ड्राफ़्ट को बाहर रखते हैं, इसलिए प्रीव्यू बिल्ड अप्रकाशित काम को शिप होने से पहले समीक्षा करने का एक सुरक्षित तरीका है।
- **`blume sync`** हर रिमोट स्रोत को फिर से फ़ेच करता है और रनटाइम को दोबारा जेनरेट करता है। डेव कैश-फ़र्स्ट है — कोई रिमोट स्रोत एक बार फ़ेच किया जाता है और पुनः आरंभ पर `.blume/cache` से परोसा जाता है (तेज़ और ऑफ़लाइन-सहिष्णु), इसलिए `blume sync` वह तरीका है जिससे आप डेव सर्वर को पुनः आरंभ किए बिना नवीनतम CMS कंटेंट खींचते हैं (चल रहा सर्वर हॉट-रीलोड करता है)। पहले कैश हटाने के लिए `--force` जोड़ें, या अपने आप रीफ़्रेश करने के लिए किसी स्रोत पर `pollInterval` सेट करें।

```sh
blume dev --preview      # author workflow: see drafts live
blume build --preview    # render a full preview build
blume sync               # refresh remote content now
blume sync --force       # ...ignoring any cached snapshot
```

## कस्टम स्रोत

`ContentSource` इंटरफ़ेस को लागू करने वाला कोई भी ऑब्जेक्ट सीधे पास किया जा सकता है, और इसी तरह कस्टम सीरियलाइज़र वाला कोई एडैप्टर — या कोई भी ऐसा बैकएंड जो बिल्ट-इन नहीं है — बिना अपने SDK को कोर इंस्टॉल तक पहुँचाए जुड़ जाता है:

```ts blume.config.ts
import { defineConfig } from "blume";
import { sanitySource } from "blume/sources/sanity.ts";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "custom",
        source: sanitySource({
          name: "guides",
          prefix: "guides",
          projectId: "abc123",
          dataset: "production",
          query: `*[_type == "guide"]`,
          // Map custom Portable Text blocks to Blume components
          serializers: {
            callout: (block) => `<Callout>${block.text}</Callout>`,
          },
        }),
      },
    ],
  },
});
```

एक स्रोत अपने नेटिव आकार (Portable Text, Notion ब्लॉक, रिमोट HTML) को Markdown/MDX टेक्स्ट में नॉर्मलाइज़ कर देता है, इसलिए पेज चाहे कहीं से भी आए, वही कंपोनेंट और मार्कडाउन फ़ीचर लागू होते हैं।

लोकल फ़ाइलें पढ़ने वाले किसी कस्टम स्रोत को हर एंट्री पर `sourcePath` और स्वयं स्रोत पर `contentRoot` सेट करना चाहिए। `sourcePath` डायग्नोस्टिक्स में फ़ाइल का नाम बताता है और उसके बगल की सापेक्ष इमेज हल करता है; `contentRoot` उस git `log` की सीमा तय करता है जो पेजों को तिथि देता है, इसलिए इसके बिना स्रोत के पेजों को git से प्राप्त कोई ["Last updated" तिथि](/docs/configuration#last-modified) नहीं मिलती।

---

# सिंटैक्स
Source: https://useblume.dev/hi/docs/content/syntax

Blume मानक Markdown और MDX को एक सुव्यवस्थित, GitHub-फ़्लेवर्ड फ़ीचर सेट के साथ रेंडर करता है — कोई इम्पोर्ट नहीं, कोई कॉन्फ़िगरेशन नहीं। कंटेंट उसी तरह लिखें जैसे आप पहले से लिखते हैं; यह पेज वह सब कुछ दिखाता है जो समर्थित है, हर एक के लाइव प्रीव्यू और सोर्स के साथ।

## शीर्षक

शीर्षकों से पेज को संरचित करें। Blume आपके फ़्रंटमैटर के `title` को पेज शीर्षक के रूप में रेंडर करता है, इसलिए अपना कंटेंट `##` से शुरू करें — `##` और `###` विषय-सूची में प्रविष्टियाँ बन जाते हैं। हर `##`–`######` शीर्षक अपने ही एंकर के लिंक में लपेटा जाता है, ताकि पाठक किसी शीर्षक पर क्लिक करके सीधे उस अनुभाग का परमालिंक कॉपी, बुकमार्क या साझा कर सकें (`#` दिखाने के लिए होवर करें)। इसे बंद करने के लिए `blume.config.ts` में `markdown: { headingAnchors: false }` सेट करें।

```md
## Section

### Subsection

#### Detail
```

### कस्टम एंकर

एंकर आईडी शीर्षक के पाठ से उत्पन्न होती हैं, इसलिए शब्द बदलने पर शीर्षक को नई एंकर मिल जाती है। इसके बजाय एंकर को स्थिर करने के लिए `[#custom-id]` जोड़ें — यह मार्कर कभी रेंडर नहीं होता, और शीर्षक चाहे जैसा भी पढ़ा जाए, लिंक काम करते रहते हैं। स्थिर की गई एंकर [अनूदित लोकेल](/docs/content/i18n) में भी एक जैसी रहती हैं, जबकि स्वतः उत्पन्न आईडी हर भाषा में अलग-अलग होतीं।

```md
## Getting started [#setup]
```

इसे `/page#setup` के रूप में लिंक करें। यह सिंटैक्स Fumadocs से मेल खाता है, इसलिए माइग्रेट किया गया कंटेंट ज्यों का त्यों काम करता है।

Pandoc, kramdown, और Markdown-आधारित विनिर्देश टूलचेन द्वारा उपयोग किया जाने वाला `{#custom-id}` रूप `.md` फ़ाइलों में समकक्ष के रूप में स्वीकार किया जाता है। `.mdx` में, अकेला `{…}` एक JSX एक्सप्रेशन होता है और पेज कंपाइल होने में विफल हो जाता है — `blume check` इस मार्कर को `BLUME_MDX_CURLY_ANCHOR` के रूप में रिपोर्ट करता है — इसलिए वहाँ `[#custom-id]` लिखें, या ब्रेसेस को एस्केप करें। एस्केप किया गया रूप दोनों फ़ॉर्मैट में एक ही एंकर स्थिर करता है, जिससे यह उस पार्शियल के लिए सही वर्तनी बन जाता है जिसे `.mdx` पेज [इनक्लूड](/docs/content/includes) करते हैं:

```md
## Getting started \{#setup\}
```

फ़्रैगमेंट लिंक `id` वाले किसी रॉ HTML एलिमेंट (`<a id="setup"></a>`) को भी लक्षित कर सकते हैं; `blume validate` उन्हें शीर्षक एंकर के साथ-साथ स्वीकार करता है।

### विषय-सूची मार्कर

दो और अनुगामी मार्कर यह नियंत्रित करते हैं कि कोई शीर्षक विषय-सूची में कैसे दिखे। `[!toc]` शीर्षक को पेज पर रखता है पर TOC से बाहर; `[toc]` इसका उलटा करता है — शीर्षक केवल TOC में दिखता है, एक अदृश्य एंकर लक्ष्य के रूप में, जो गद्य के बजाय कंपोनेंट्स से बने अनुभागों को लेबल करने के लिए उपयोगी है। मार्कर किसी भी क्रम में जोड़े जा सकते हैं। एक अपवाद, जो CommonMark से विरासत में मिला है: ऐसा अनुगामी ब्रैकेट जिसके लेबल की कोई लिंक-रेफ़रेंस परिभाषा पेज पर कहीं भी मौजूद हो (`[toc]: /url`), वह मार्कर नहीं बल्कि एक शॉर्टकट रेफ़रेंस लिंक होता है और शीर्षक के पाठ में बना रहता है।

```md
## Appears on the page only [!toc]

## Appears in the TOC only [toc]

## Both markers together [toc] [#custom-id]
```

मार्कर हमेशा पार्स होते हैं — ऐसा शीर्षक जो शाब्दिक रूप से मार्कर-जैसे पाठ पर समाप्त होता है, चिह्नित माना जाएगा। बैकस्लैश-एस्केपिंग से मदद नहीं मिलती (मार्कर पार्स चलने से पहले Markdown `\[` को `[` में हल कर देता है); किसी शीर्षक के अंत में शाब्दिक मार्कर पाठ दिखाने के लिए, उसे इनलाइन कोड में लपेटें: `` ## Using `[toc]` ``।

## ज़ोर

शब्दों पर ज़ोर देने, विलोपन चिह्नित करने, और वाक्य के बीच में कोड या कीस्ट्रोक दिखाने के लिए इनलाइन फ़ॉर्मेटिंग।

**बोल्ड**, _इटैलिक_, ~~स्ट्राइकथ्रू~~, और `inline code`।

```md
**Bold**, _italic_, ~~strikethrough~~, and `inline code`.
```

## सुपरस्क्रिप्ट और सबस्क्रिप्ट

फ़ुटनोट चिह्नों, क्रमवाचक संख्याओं, और इनलाइन वैज्ञानिक या रासायनिक संकेतन के लिए।

E = mc^2^ और H~2~O।

{/* prettier-ignore */}
```md
E = mc^2^ and H~2~O.
```

## ब्लॉककोट

किसी उद्धरण, कॉलआउट टिप्पणी, या संपादकीय नोट को आसपास के पाठ से अलग करें।

> दस्तावेज़ीकरण जो तेज़, AI-रेडी, और शून्य-कॉन्फ़िग है — टेम्पलेट तक।

```md
> Documentation that's fast, AI-ready, and zero-config — down to the template.
```

## सूचियाँ

अक्रमित समूहों के लिए अक्रमित सूचियाँ, अनुक्रमों के लिए क्रमित सूचियाँ, और चेकलिस्ट व रोडमैप के लिए टास्क सूचियाँ इस्तेमाल करें।

- Markdown-पहले लेखन
- डिफ़ॉल्ट रूप से स्टैटिक
  - सर्वर फ़ीचर्स को चुनकर सक्षम करें
- अपने आउटपुट के मालिक बनें

1. Blume इंस्टॉल करें
2. एक पेज लिखें
3. उसे शिप करें

- [x] प्रोजेक्ट स्कैफ़ोल्ड करें
- [ ] पहली गाइड लिखें

```md
- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide
```

## टेबल

संरचित डेटा को सारणीबद्ध करें — कॉन्फ़िग विकल्प, तुलना मैट्रिक्स, पैरामीटर सूचियाँ। कॉलम संरेखित करने के लिए विभाजक पंक्ति में कोलन का उपयोग करें।

| कमांड         | विवरण               | आउटपुट  |
| ------------- | ------------------- | :-----: |
| `blume dev`   | डेव सर्वर शुरू करें |    —    |
| `blume build` | स्टैटिक साइट बनाएँ  | `dist/` |

```md
| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |
```

हेडर पंक्ति के बिना टेबल के लिए — जैसे कुंजी–मान जोड़े — हेडर सेल्स खाली छोड़ दें। Markdown को सिंटैक्स के लिहाज़ से हेडर और विभाजक पंक्तियाँ चाहिए, लेकिन Blume रेंडर की गई टेबल से खाली हेडर हटा देता है।

```md
|                |          |
| -------------- | -------- |
| Current status | E-3 visa |
```

## लिंक और इमेज

दूसरे पेजों या बाहरी साइटों से लिंक करें। इमेज आपके कंटेंट के बगल में मौजूद फ़ाइल का सापेक्ष पथ, `public/` के अंतर्गत कोई भी पथ (जो साइट रूट पर सर्व होता है), या कोई रिमोट URL स्वीकार करती हैं।

शुरू करने के लिए [क्विकस्टार्ट](/docs/quickstart) पढ़ें।

```md
Read the [quickstart](/docs/quickstart) to get started.

![Alt text](./screenshot.png)
```

**स्थानीय इमेज के लिए सापेक्ष पथ को प्राथमिकता दें** — वे बिल्ड समय पर ऑप्टिमाइज़ होती हैं: कंप्रेस, WebP में परिवर्तित, और अंतर्निहित `width`/`height` के साथ अंकित, ताकि लोड होते समय पेज खिसके नहीं। इमेज को उसी पेज के बगल में रखें जो उसका उपयोग करता है (या अपनी कंटेंट डायरेक्टरी के भीतर किसी साझा फ़ोल्डर में) और उसे सापेक्ष रूप से संदर्भित करें:

```md
![Build output](./images/build-output.png)
```

`public/` के अंतर्गत निरपेक्ष पथ (`![Alt text](/screenshot.png)`) बिना किसी ऑप्टिमाइज़ेशन के ज्यों का त्यों सर्व होते हैं — उन्हें उन फ़ाइलों के लिए इस्तेमाल करें जिनके बाइट्स और URL बिल्कुल वैसे ही रहने चाहिए, जैसे आपके डॉक्स के बाहर से संदर्भित कोई लोगो। रिमोट इमेज भी बिना छेड़छाड़ के पास कर दी जाती हैं, बशर्ते उनका होस्ट [`image` कॉन्फ़िग](/docs/configuration#images) में अधिकृत न हो।

कंटेंट इमेज डिफ़ॉल्ट रूप से क्लिक-टू-ज़ूम होती हैं — पाठक किसी भी इमेज पर क्लिक करके उसे लाइटबॉक्स में खोल सकते हैं। इसे `blume.config.ts` में `markdown: { imageZoom: false }` से बंद करें, या किसी एक इमेज को `data-no-zoom` से बाहर रखें।

## क्षैतिज रेखा

एक लंबे पेज के भीतर विषय के बड़े बदलावों को अलग करें।

---

```md
---
```

## कोड ब्लॉक

फ़ेंस किए गए कोड ब्लॉक सिंटैक्स-हाइलाइट होते हैं, जिनके हेडर में भाषा दिखती है — पहचानी गई भाषाओं के लिए ब्रांड आइकन के साथ — और एक कॉपी बटन होता है। भाषा के बाद एक **शीर्षक** जोड़ें — आमतौर पर फ़ाइल नाम — और यह हेडर में भाषा लेबल की जगह ले लेता है।

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```

````md
```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```
````

इनलाइन कोड को भी हाइलाइट किया जा सकता है: बैकटिक स्पैन के भीतर एक `{:lang}` मार्कर जोड़ें और वह किसी छोटे कोड ब्लॉक की तरह रंगीन हो जाता है — `useState(){:js}` या `T extends object{:ts}`। यह तभी सक्रिय होता है जब आप मार्कर जोड़ें, इसलिए सादा इनलाइन कोड अछूता रहता है — चालू करने के लिए कुछ नहीं।

हाइलाइटिंग डिफ़ॉल्ट रूप से `github-light`/`github-dark` थीम का उपयोग करती है। `markdown.codeBlocks.theme` से प्रति कलर मोड कोई भी [बंडल की गई Shiki थीम](https://shiki.style/themes) बदलें — यह एक साथ हर कोड सतह को रंगती है (फ़ेंस, इनलाइन स्निपेट, `<CodeBlock>`, और `<Diff>`):

```ts blume.config.ts
export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: "vesper" },
    },
  },
});
```

आप सीधे एक कस्टम [Shiki थीम परिभाषा](https://shiki.style/guide/load-theme) भी दे सकते हैं। VS Code-संगत थीम JSON फ़ाइल इम्पोर्ट करें (यदि आपके रनटाइम को आवश्यक हो तो इम्पोर्ट एट्रिब्यूट के साथ) और उसे किसी भी कलर मोड को असाइन करें; बंडल किए गए नाम और कस्टम परिभाषाएँ मिलाई जा सकती हैं:

```ts blume.config.ts
import darkTheme from "./themes/acme-dark.json" with { type: "json" };

export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: darkTheme },
    },
  },
});
```

### लाइन नंबर

लाइन-नंबर गटर रेंडर करने के लिए `lineNumbers` जोड़ें — अकेले या किसी शीर्षक के साथ:

```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```

````md
```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```
````

### हाइलाइटिंग

लाइनों, शब्दों और बदलावों पर ध्यान खींचने के लिए कोड को GitHub-शैली की टिप्पणियों से एनोटेट करें। ये टिप्पणियाँ रेंडर किए गए आउटपुट से हटा दी जाती हैं, इसलिए कोड कॉपी-पेस्ट के लिए साफ़ रहता है। चारों डिफ़ॉल्ट रूप से चालू हैं — कोई कॉन्फ़िगरेशन नहीं।

किसी लाइन को हाइलाइट की गई पृष्ठभूमि देने के लिए उसे `// [!code highlight]` से चिह्नित करें:

```ts
const config = defineConfig({
  title: "My docs", // [!code highlight]
});
```

जोड़ के लिए `// [!code ++]` और हटाने के लिए `// [!code --]` से बदलाव दिखाएँ, जो हरे/लाल डिफ़ के रूप में रेंडर होते हैं:

```ts
export default defineConfig({
  title: "My docs", // [!code --]
  title: "Blume docs", // [!code ++]
});
```

किसी लाइन में किसी शब्द की हर आवृत्ति को `// [!code word:serve]` से हाइलाइट करें:

```ts
import { serve } from "blume"; // [!code word:serve]

serve({ port: 3000 });
```

`// [!code focus]` से चिह्नित लाइनों को छोड़कर बाकी सब धुँधला कर दें (होवर करने पर बाकी स्पष्ट हो जाता है):

```ts
export default defineConfig({
  title: "My docs", // [!code focus]
  description: "Built with Blume",
});
```

या टिप्पणियों के बजाय **नंबर** से लाइनें हाइलाइट करें — तब उपयोगी जब आप कोड संपादित न कर सकें। भाषा के बाद एक ब्रेस रेंज रखें; एकल लाइनें, अल्पविराम से अलग सूचियाँ, और `start-end` स्पैन — सभी काम करते हैं:

```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```

````md
```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```
````

### डिस्प्ले प्रकार

कंपाइलर से सीधे असली टाइप दिखाने के लिए किसी TypeScript ब्लॉक को `twoslash` से चिह्नित करें — [Twoslash](https://shiki.style/packages/twoslash) द्वारा संचालित। किसी भी टोकन पर होवर करके उसका अनुमानित टाइप देखें, और लाइन के नीचे कोई टाइप पिन करने के लिए इनलाइन `^?` क्वेरी जोड़ें।

```ts twoslash
const config = {
  title: "My docs",
  version: 1,
};

config.title;
//     ^?
```

````md
```ts twoslash
const config = { title: "My docs", version: 1 };

config.title;
//     ^?
```
````

### TypeScript और JavaScript टैब

किसी `ts` या `tsx` ब्लॉक को `ts2js` से चिह्नित करें ताकि वह टैब जोड़ी के रूप में रेंडर हो: आपका TypeScript और उसके साथ स्वतः उत्पन्न JavaScript संस्करण, ताकि आप एक ही स्निपेट संभालें और पाठक अपनी बोली चुन लें। यह रूपांतरण टाइप सिंटैक्स और केवल-टाइप इम्पोर्ट हटा देता है, जबकि आपकी फ़ॉर्मेटिंग, टिप्पणियाँ, और JSX ठीक वैसे ही रखता है जैसे लिखे गए हैं — और टैब सिंक होते हैं, इसलिए एक बार JavaScript चुनने से पेज की हर जोड़ी बदल जाती है। डायग्राम और गणित की तरह, यह भी केवल-MDX फ़ीचर है — किसी `.md` फ़ाइल में यह ब्लॉक एक सादे TypeScript फ़ेंस के रूप में रेंडर होता है।

```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```

````md
```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```
````

अन्य फ़ेंस मेटा भी साथ काम करता है: `title="..."` दोनों टैब पर दिखता है, जबकि `{1,4-5}` लाइन रेंज केवल TypeScript टैब पर लागू होती हैं (टाइप हटने के बाद लाइन नंबर खिसक जाते हैं)। एकमात्र अपवाद `twoslash` है — होवर टाइप उत्पन्न कोड तक नहीं ले जाए जा सकते, इसलिए दोनों से चिह्नित फ़ेंस एक सादा Twoslash ब्लॉक ही रहता है।

:::note
`blume.config.ts` में `markdown: { code: { icons: false, wrap: true } }` से भाषा आइकन छिपाएँ या लंबी लाइनों को स्क्रॉल करने के बजाय रैप करें।
:::

## पैकेज इंस्टॉल

एक `package-install` ब्लॉक एकल इंस्टॉल कमांड को npm, pnpm, yarn, और bun के लिए टैब वाले स्निपेट में बदल देता है — ताकि पाठक वही कॉपी करें जो उनके सेटअप से मेल खाता है। डायग्राम और गणित की तरह, यह भी केवल-MDX फ़ीचर है — किसी `.md` फ़ाइल में यह ब्लॉक एक सादे कोड फ़ेंस के रूप में रेंडर होता है।

```package-install
npm i blume
```

````md
```package-install
npm i blume
```
````

## डायग्राम

एक `mermaid` ब्लॉक सीधे टेक्स्ट से [Mermaid](https://mermaid.js.org) डायग्राम रेंडर करता है। फ़ेंस की सामग्री ज्यों की त्यों Mermaid को दी जाती है, इसलिए Mermaid द्वारा समर्थित हर डायग्राम प्रकार यहाँ काम करता है। डायग्राम सक्रिय कलर थीम का अनुसरण करते हैं और थीम बदलने पर फिर से रेंडर होते हैं। सोर्स को `mermaid` से फ़ेंस करके कोई डायग्राम लिखें:

````md
```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```
````

डायग्राम क्लाइंट पर रेंडर होते हैं, इसलिए यह केवल-MDX फ़ीचर है, और Mermaid लाइब्रेरी केवल उन्हीं पेजों पर लोड होती है जिनमें कोई डायग्राम हो। इस अनुभाग का बाकी हिस्सा सामान्य प्रकारों की एक गैलरी है — पूरी सूची के लिए [Mermaid डॉक्स](https://mermaid.js.org/intro/) देखें।

### फ़्लोचार्ट

```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```

### सीक्वेंस डायग्राम

```mermaid
sequenceDiagram
  participant R as Reader
  participant B as Blume
  R->>B: Request /docs
  B-->>R: Prerendered HTML
```

### क्लास डायग्राम

```mermaid
classDiagram
  class Page {
    +string title
    +string route
    +render()
  }
  Page <|-- Doc
  Page <|-- Changelog
```

### स्टेट डायग्राम

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: build
  Published --> [*]
```

### एंटिटी रिलेशनशिप

```mermaid
erDiagram
  PAGE ||--o{ HEADING : contains
  PAGE {
    string title
    string route
  }
```

### यूज़र जर्नी

```mermaid
journey
  title Publishing a page
  section Write
    Draft MDX: 5: Author
  section Ship
    blume build: 4: Author
    Deploy: 3: Author
```

### गैंट

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Docs
    Draft   :a1, 2026-01-01, 7d
    Review  :after a1, 3d
```

### गिट ग्राफ़

```mermaid
gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit
```

### पाई चार्ट

```mermaid
pie title Content types
  "Docs" : 70
  "Blog" : 20
  "Changelog" : 10
```

### माइंडमैप

```mermaid
mindmap
  root((Blume))
    Content
      MDX
      Markdown
    Build
      Static HTML
      llms.txt
```

### टाइमलाइन

```mermaid
timeline
  title Blume milestones
  2025 : Prototype
  2026 : 1.0 release
```

## कॉलआउट

कॉलआउट पाठक का ध्यान संदर्भ, सलाह, या जोखिम की ओर खींचते हैं। उन्हें `:::type` डायरेक्टिव के रूप में लिखें; ब्रैकेट में शीर्षक जोड़ें, जैसे `:::warning[Heads up]`। डायरेक्टिव केवल-MDX फ़ीचर हैं — किसी `.md` फ़ाइल में `:::note` लाइन शाब्दिक पाठ ही रहती है।

### नोट

तटस्थ, सहायक संदर्भ जिसे पाठक को ध्यान में रखना चाहिए।

:::note
Blume हर रन पर `.blume/` को फिर से बनाता है — इसे कभी हाथ से संपादित न करें।
:::

```md
:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::
```

### टिप

एक उपयोगी शॉर्टकट या सर्वोत्तम अभ्यास जो अनिवार्य नहीं है पर जीवन आसान बना देता है।

:::tip
`deployment.site` सेट करें ताकि साइटमैप और Open Graph इमेज निरपेक्ष URL का उपयोग करें।
:::

```md
:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::
```

### सफलता

किसी सकारात्मक परिणाम की पुष्टि करें या यह कि कोई चरण अपेक्षा के अनुसार पूरा हुआ।

:::success
आपके डॉक्स सफलतापूर्वक बन गए और डिप्लॉय के लिए तैयार हैं।
:::

```md
:::success
Your docs built successfully and are ready to deploy.
:::
```

### चेतावनी

ऐसी किसी बात को चिह्नित करें जिसमें गलती या अप्रत्याशित व्यवहार से बचने के लिए सावधानी चाहिए।

:::warning[ध्यान दें]
`output: "server"` पर स्विच करने के लिए डिप्लॉय करने से पहले एक एडाप्टर चाहिए।
:::

```md
:::warning[Heads up]
Switching to `output: "server"` requires an adapter before you can deploy.
:::
```

### ख़तरा

ऐसी विध्वंसक या भंजक कार्रवाई को उजागर करें जिसे आसानी से पलटा नहीं जा सकता।

:::danger
`blume eject` एकतरफ़ा कदम है — उत्पन्न Astro प्रोजेक्ट आपका हो जाता है।
:::

```md
:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::
```

### जानकारी

एक सूचनात्मक टिप्पणी; एक उपनाम-अनुकूल डिफ़ॉल्ट जो तटस्थ लगता है।

:::info
कोर थीम कोई क्लाइंट फ़्रेमवर्क JS शिप नहीं करती।
:::

```md
:::info
The core theme ships no client framework JS.
:::
```

`caution`, `error`, `important`, और `warn` नाम क्रमशः `warning`, `danger`, `note`, और `warning` के उपनाम के रूप में स्वीकार किए जाते हैं।

## गणित

KaTeX के साथ LaTeX को केंद्रित ब्लॉक के रूप में रेंडर करें — गणित-प्रधान या वैज्ञानिक डॉक्स के लिए उपयोगी। किसी सूत्र को `$$…$$` में लपेटें:

$$
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

```md
$$
a^2 + b^2 = c^2
$$
```

:::note
गणित केवल ब्लॉक-स्तर पर है और स्वतः चालू है — `$$…$$` लिखें और यह रेंडर हो जाता है; न लिखें तो KaTeX की स्टाइलशीट कभी शिप नहीं होती। इनलाइन `$…$` गणित नहीं है: अकेला `$` (मुद्रा, शेल वेरिएबल, कोड) हमेशा शाब्दिक पाठ ही रहता है, इसलिए न कोई डीलिमिटर एस्केप करना है और न कोई सेटिंग टॉगल करनी है। गणित एक केवल-MDX फ़ीचर है। रेंडर किए गए मार्कअप के भीतर के क्लास नाम (`.katex-html`, `.katex-base`, …) KaTeX के अपने आंतरिक विवरण हैं, कोई ऐसा स्टाइलिंग अनुबंध नहीं जिसे Blume बनाए रखता हो — KaTeX के अपग्रेड होने पर वे बदल सकते हैं, इसलिए कस्टम स्टाइल के लिए `.katex-display` रैपर को लक्षित करें।
:::

## स्मार्ट विराम-चिह्न

Blume लिखते समय सीधे उद्धरण चिह्नों और डैश को टाइपोग्राफिक समकक्षों में बदल देता है, ताकि गद्य ऐसा पढ़ा जाए जैसे उसे टाइपसेट किया गया हो — किसी विशेष वर्ण की ज़रूरत नहीं।

"उद्धरण" घुमावदार हो जाते हैं, -- एन डैश बन जाता है, --- एम डैश, और ... एक दीर्घवृत्त।

```md
"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
```

---

# संस्करणीकरण
Source: https://useblume.dev/hi/docs/content/versioning

Blume आपके दस्तावेज़ों को उसी तरह संस्करणित करता है जैसे रिलीज़ वास्तव में काम करती हैं: नवीनतम दस्तावेज़ीकरण आपके कंटेंट रूट पर स्वच्छ, उपसर्ग-रहित URL के साथ रहता है, और प्रत्येक पिछला संस्करण अपने स्वयं के फ़ोल्डर में एक फ़्रीज़ किया गया स्नैपशॉट होता है। जब आप शिप करें तब एक स्नैपशॉट काटें, और Blume आपके लिए स्विचर, "पुराना संस्करण" सूचना, खोज की परिधि, SEO और एजेंट सतह को जोड़ देता है। यह ऑप्ट-इन है: `versions` ब्लॉक के बिना कुछ भी नहीं बदलता।

## इसे सक्षम करें

एक `versions` ब्लॉक जोड़ें जो वर्तमान दस्तावेज़ों और किसी भी संग्रहीत स्नैपशॉट का नाम बताए:

```ts blume.config.ts lineNumbers
versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}
```

`current` स्विचर में उपसर्ग-रहित ट्री को लेबल करता है (एक वैकल्पिक `badge` के साथ)। प्रत्येक संग्रहीत प्रविष्टि का `id` स्नैपशॉट की डायरेक्टरी का नाम भी है और उसका URL खंड भी — id का आरंभ किसी अक्षर से होना चाहिए (`v1.0`, न कि `1.0`) ताकि वे कभी भी [संख्यात्मक क्रम उपसर्गों](/docs/content/navigation#ordering) से न टकराएँ। संग्रहीत संस्करणों को नवीनतम पहले के क्रम में सूचीबद्ध करें; वही क्रम स्विचर का क्रम होता है।

## एक संस्करण काटें

जब आप रिलीज़ करें, तो वर्तमान दस्तावेज़ों को एक ही कमांड से फ़्रीज़ करें:

```bash
blume version v1.0
```

यह आपके कंटेंट ट्री को `docs/v1.0/` में कॉपी करता है (मौजूदा स्नैपशॉट छोड़कर), कॉपी के भीतर रूट-निरपेक्ष लिंक को फिर से लिखता है ताकि वे स्नैपशॉट के भीतर ही रहें (`/guides/x` बन जाता है `/v1.0/guides/x`, फेंस्ड और इनलाइन कोड अछूता रहता है), और id को `blume.config.ts` में पंजीकृत करता है — या जब आपका कॉन्फ़िग ऐसी संरचना में हो जिसे यह छुएगा नहीं, तब चिपकाने हेतु प्रविष्टि प्रिंट कर देता है। जो पृष्ठ कॉपी किए गए ट्री का हिस्सा नहीं हैं, उनके लिंक — उत्पन्न API संदर्भ, चेंजलॉग जैसे दूरस्थ स्रोत — लाइव पृष्ठों की ओर ही संकेत करते रहते हैं, क्योंकि स्नैपशॉट के पास उनकी कोई प्रति नहीं होती। कॉन्फ़िगर किए गए संस्करणों की सूची देखने के लिए `blume version` को बिना id के चलाएँ।

नई डायरेक्टरी की समीक्षा करें और उसे किसी भी अन्य कंटेंट की तरह कमिट करें। इसे उठाने के लिए `blume dev` को पुनः आरंभ करें।

```txt
docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart
```

**संग्रहीत का अर्थ है फ़्रीज़ किया हुआ।** भविष्य के संपादन लाइव ट्री में होने चाहिए; स्नैपशॉट वे दस्तावेज़ हैं जैसे वे उस समय थे। Blume इसी पर निर्भर करता है: स्नैपशॉट अपना स्वयं का फ़ोल्डर मेटा और अनुवाद रखते हैं, [`blume translate`](/docs/reference/translate) उन्हें कभी पुनः अनुवादित नहीं करता, और कॉन्फ़िगर किया गया स्पष्ट साइडबार केवल वर्तमान दस्तावेज़ों पर लागू होता है — स्नैपशॉट का साइडबार हमेशा उसकी अपनी फ़ाइलों से आता है।

## स्विचर और सूचना

संस्करण कॉन्फ़िगर होने पर, हेडर में स्वतः एक संस्करण ड्रॉपडाउन जुड़ जाता है। स्विच करने पर आप लक्षित संस्करण में उसी पृष्ठ पर पहुँचते हैं यदि वह मौजूद हो, और न होने पर उस संस्करण के रूट पर (हमेशा रूट पर पहुँचने के लिए `switcher.redirect: "root"` सेट करें)। यदि आप [`navigation.selectors`](/docs/content/navigation#selectors) में अपना स्वयं का `kind: "version"` सिलेक्टर घोषित करते हैं, तो वह स्वचालित सिलेक्टर को प्रतिस्थापित कर देता है।

प्रत्येक संग्रहीत पृष्ठ पर एक न हटाई जा सकने वाली सूचना भी दिखती है, जिसमें "नवीनतम पर जाएँ" लिंक उस पृष्ठ के लाइव समकक्ष की ओर संकेत करता है। इसे प्रति संस्करण अनुकूलित या निष्क्रिय करें:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0", banner: "These docs cover the 1.x SDK." },
    { id: "v0.9", banner: false },
  ],
}
```

## SEO

पुराने दस्तावेज़ खोज इंजनों का प्रिय जाल होते हैं: बासी पृष्ठ लाइव पृष्ठ से ऊपर रैंक कर जाता है, या दोनों प्रतिस्पर्धा करते हैं। Blume वही उत्तर डिफ़ॉल्ट रूप से अपनाता है जिसकी SEO मार्गदर्शिकाएँ सिफ़ारिश करती हैं और जिसे कोई अन्य दस्तावेज़ फ़्रेमवर्क स्वचालित नहीं करता — संग्रहीत पृष्ठ इंडेक्स-योग्य बने रहते हैं परंतु **नवीनतम समकक्ष को अपना कैनोनिकल** घोषित करते हैं, जिससे लाइव पृष्ठ आधिकारिक रहता है जबकि केवल-संस्करण कंटेंट (ऐसा पृष्ठ जो नवीनतम दस्तावेज़ों में अब मौजूद नहीं है) स्व-कैनोनिकल के साथ खोजने योग्य बना रहता है।

प्रति संस्करण आप एक भिन्न व्यवहार चुन सकते हैं:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0" }, // canonical → latest (default)
    { id: "v0.9", canonical: "self" }, // every page authoritative
    { id: "v0.8", noindex: true }, // deindexed entirely
  ],
}
```

साइटमैप भी यही अनुसरण करता है: वे संग्रहीत पृष्ठ जिनका कैनोनिकल किसी लाइव समकक्ष की ओर संकेत करता है, छोड़ दिए जाते हैं, `noindex` संस्करण पूरी तरह छोड़ दिए जाते हैं, और केवल-संस्करण पृष्ठ सूचीबद्ध रहते हैं। किसी पृष्ठ का अपना `seo.canonical` फ़्रंटमैटर हमेशा प्रभावी रहता है।

## खोज

खोज डायलॉग परिणामों को देखे जा रहे संस्करण तक सीमित रखता है, और भाषा टॉगल के बगल में एक "सभी संस्करण" टॉगल (प्रति पाठक याद रखा जाने वाला) देता है। क्रॉस-संस्करण परिणाम अपनी पंक्ति पर अपने संस्करण का नाम बताते हैं। Orama (डिफ़ॉल्ट), FlexSearch, Algolia और Typesense सभी इस परिधि का पालन करते हैं — होस्टेड रिकॉर्ड एक `version` फ़ेसेट रखते हैं, जिसमें वर्तमान दस्तावेज़ `"current"` के रूप में अपलोड होते हैं — जबकि Pagefind अपरिधित रहता है, जो उसके लोकेल व्यवहार से मेल खाता है।

## एजेंट

एजेंट सतह संस्करण-सजग है — ऐसा कुछ जो कोई अन्य दस्तावेज़ फ़्रेमवर्क नहीं करता:

- MCP के `search_docs` और `list_pages` टूल डिफ़ॉल्ट रूप से वर्तमान दस्तावेज़ों पर काम करते हैं और `version` स्वीकार करते हैं: एक संग्रहीत id (`"v1.0"`) या `"all"`। `get_navigation` अनुरोध पर किसी संग्रहीत स्नैपशॉट का ट्री लौटाता है।
- `llms.txt` संग्रहीत संस्करणों को वर्तमान दस्तावेज़ों के बाद अनुभागों में रखता है, `1.0 (archived)` के रूप में लेबल करके, ताकि इंडेक्स पढ़ने वाला एजेंट जान सके कि कौन-से दस्तावेज़ फ़्रीज़ किए गए हैं।
- `llms-full.txt` केवल-वर्तमान रहता है — यह सपाट डंप एक ही पृष्ठ की फ़्रीज़ की गई प्रतियों को कभी आपस में नहीं मिलाता।
- हर संस्करण के पृष्ठों के लिए रॉ Markdown मिरर (`.md` URL) मौजूद रहते हैं, जैसे किसी भी रूट के लिए होते हैं।

## i18n के साथ

संस्करणीकरण [अंतर्राष्ट्रीयकरण](/docs/content/i18n) के साथ संयोजित होता है। डिस्क पर संस्करण फ़ोल्डर सबसे बाहर होता है — एक स्नैपशॉट स्वाभाविक रूप से अपने लोकेल फ़ोल्डर समाहित करता है — जबकि URL में लोकेल सबसे बाहर रहता है, जो शेष साइट से मेल खाता है:

```txt
docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
```

लोकेल फ़ॉलबैक प्रत्येक संस्करण के भीतर काम करता है: कोई अअनूदित स्नैपशॉट पृष्ठ स्थानीयकृत URL पर फ़ॉलबैक लोकेल का कंटेंट रेंडर करता है, और `hreflang` विकल्प प्रति संस्करण समूहित होते हैं। कोई संस्करण id किसी कॉन्फ़िगर किए गए लोकेल कोड से नहीं टकरा सकता — Blume ऐसे कॉन्फ़िग को सीधे अस्वीकार कर देता है।

## क्या असंस्करणित रहता है

संस्करणीकरण दस्तावेज़ कंटेंट ट्री को कवर करता है। ब्लॉग, चेंजलॉग, OpenAPI विनिर्देशों से उत्पन्न API संदर्भ, और कस्टम पृष्ठ हमेशा वर्तमान रहते हैं। दो और व्यवहार जानने योग्य हैं: हेडर टैब वर्तमान दस्तावेज़ों के सापेक्ष परिभाषित होते हैं, इसलिए किसी संग्रहीत ट्री के भीतर साइडबार टैब द्वारा अपरिधित रेंडर होता है; और बड़ी साइटों को ध्यान देना चाहिए कि प्रत्येक स्नैपशॉट एक पूर्ण प्रति है — कंटेंट, खोज इंडेक्स प्रविष्टियाँ, और नेविगेशन डेटा सभी प्रति संस्करण बढ़ते हैं।

---

# परिनियोजन
Source: https://useblume.dev/hi/docs/deployment

## कहीं भी परिनियोजित करें (स्टैटिक)

`blume build` आपके डॉक्स को सादे HTML, CSS, और `dist/` में एक स्थानीय खोज इंडेक्स में संकलित करता है। चलाने के लिए कोई सर्वर नहीं है — बस किसी भी स्टैटिक होस्ट को उस फ़ोल्डर की ओर इंगित करें।

| सेटिंग            | मान           |
| ----------------- | ------------- |
| बिल्ड कमांड       | `blume build` |
| आउटपुट डायरेक्टरी | `dist`        |
| Node संस्करण      | 22.12 या नया  |

ये सेटिंग्स Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, या किसी भी बकेट या CDN पर काम करती हैं। सुनिश्चित करें कि `blume` एक डिपेंडेंसी है ताकि होस्ट बिल्ड चला सके।

एक स्टैटिक बिल्ड में शामिल है:

- हर डॉक्स और कस्टम पेज स्टैटिक HTML के रूप में
- एक स्थानीय खोज इंडेक्स (डिफ़ॉल्ट रूप से Orama, Pagefind वैकल्पिक)
- जब `deployment.site` सेट हो तो एक [`sitemap.xml`](/docs/configuration/seo#sitemap) और [`robots.txt`](/docs/configuration/seo#robots)
- AI टूल्स के लिए `llms.txt` और `llms-full.txt`
- रीडायरेक्ट पेज
- जब `seo.og.enabled` चालू हो तो प्रीरेंडर की गई [Open Graph छवियाँ](/docs/configuration/seo#open-graph-images)

### अपना साइट URL सेट करें

साइटमैप, कैनोनिकल टैग, RSS, और Open Graph छवियों को एक निरपेक्ष ऑरिजिन की आवश्यकता होती है। **Vercel**, **Netlify**, और **Cloudflare Pages** पर, Blume इसे बिल्ड समय पर प्लेटफ़ॉर्म के परिवेश से पहचान लेता है — किसी कॉन्फ़िग की आवश्यकता नहीं।

पहचाने गए मान को ओवरराइड करने के लिए, या उन होस्ट्स पर मान उपलब्ध कराने के लिए जो इसे उजागर नहीं करते (GitHub Pages, S3, एक कस्टम CDN), `deployment.site` सेट करें:

```ts blume.config.ts lineNumbers
deployment: {
  site: "https://docs.example.com",
}
```

स्वचालित रूप से पहचान करते समय, Blume प्रति-डिप्लॉय प्रीव्यू URL की तुलना में आपके स्थिर प्रोडक्शन डोमेन को प्राथमिकता देता है, ताकि कैनोनिकल ऑरिजिन डिप्लॉय-दर-डिप्लॉय एक जैसा बना रहे।

`blume dev` के दौरान, जब कोई सेट न हो तो साइट URL आपके स्थानीय डेव सर्वर (जैसे `http://localhost:4321`) पर वापस चला जाता है, ताकि साइट-आधारित सुविधाएँ — Open Graph छवियाँ, कैनोनिकल, साइटमैप — बिना किसी अतिरिक्त सेटअप के काम करें। बिल्ड कभी इस फ़ॉलबैक का उपयोग नहीं करते, इसलिए प्रोडक्शन आउटपुट कभी localhost की ओर इंगित नहीं होता।

## स्थानीय रूप से पूर्वावलोकन करें

शिप करने से पहले, प्रोडक्शन बिल्ड का ठीक वैसे ही पूर्वावलोकन करें जैसे एक स्टैटिक होस्ट इसे परोसेगा:

```bash
blume build
blume preview
```

## सबपाथ परिनियोजन

डॉक्स को `example.com/docs` जैसे पथ के अंतर्गत परोस रहे हैं? `deployment.base` सेट करें — GitHub Pages प्रोजेक्ट साइटों के लिए यह सामान्य है। पूरी साइट, रूट सहित, बेस के अंतर्गत चली जाती है, और आंतरिक लिंक व एसेट्स को इसे शामिल करने के लिए पुनर्लिखित किया जाता है।

```ts blume.config.ts lineNumbers
deployment: {
  base: "/docs",
}
```

## डॉक्स को किसी पथ के अंतर्गत माउंट करें

`basePath` हर जनरेट किए गए रूट को एक सेगमेंट (`/docs/getting-started`) के अंतर्गत माउंट करता है जबकि साइडबार को अछूता छोड़ देता है — शीर्ष स्तर आपके सेक्शन हैं, कोई रैपर समूह नहीं। इसका उपयोग तब करें जब डॉक्स `/docs/*` पर रहें लेकिन साइट रूट आपका ही बना रहे (जैसे Docusaurus का `routeBasePath` या Fumadocs का `baseUrl`)।

```ts blume.config.ts lineNumbers
basePath: "/docs",
```

लिंक ऐसे लिखें मानो वे रूट पर माउंट हों (`/getting-started`); Blume उन्हें, साथ ही रीडायरेक्ट, साइटमैप, कैनोनिकल URL, Open Graph छवियाँ, `llms.txt`, और खोज इंडेक्स को पुनर्लिखित करता है। सार्वजनिक एसेट्स (छवियाँ, `public/` के अंतर्गत फ़ाइलें) साइट रूट पर ही रहती हैं।

यह ऊपर दी गई दो अवधारणाओं से अलग है:

- प्रति-स्रोत [`prefix`](/docs/content/sources#multiple-sources) **एक** स्रोत को नेमस्पेस देता है और एक साइडबार समूह **जोड़ता है**।
- `deployment.base` वह होस्ट सबडायरेक्टरी है जहाँ से **पूरा** ऐप परोसा जाता है। दोनों साथ मिलकर काम करते हैं — दोनों सेट होने पर, एक पेज `{deployment.base}/{basePath}/page` पर पहुँचता है।

## सर्वर रेंडरिंग

स्टैटिक आउटपुट अधिकांश डॉक्स के लिए पर्याप्त है। जब आपको अनुरोध-समय की सुविधाओं की आवश्यकता हो तो सर्वर आउटपुट पर स्विच करें — विशेष रूप से [Ask AI](/docs/configuration/ai) एंडपॉइंट के लिए:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

`vercel` और `node` एडाप्टर Blume के साथ आते हैं — इनमें से किसी एक को चुनना ही काफ़ी है। `netlify` और `cloudflare` एडाप्टर आपके प्रोजेक्ट में इंस्टॉल करने होंगे (जैसे `bun add -d @astrojs/netlify`); पैकेज गायब होने पर CLI आपको चेतावनी देता है:

| एडाप्टर      | पैकेज                 | किसके लिए उपयोग करें                  |
| ------------ | --------------------- | ------------------------------------- |
| `vercel`     | `@astrojs/vercel`     | Vercel — सबसे परिष्कृत रास्ता         |
| `netlify`    | `@astrojs/netlify`    | Netlify Functions                     |
| `node`       | `@astrojs/node`       | स्वयं-होस्ट किए गए Node सर्वर, कंटेनर |
| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers और Pages           |

**Vercel**, **Netlify**, और **Cloudflare Pages** पर, Blume सर्वर आउटपुट के लिए मेल खाने वाला एडाप्टर स्वतः चुन लेता है — बस `output: "server"` सेट करें और परिनियोजित करें (Netlify और Cloudflare पर, एडाप्टर पैकेज भी इंस्टॉल करें)। पहचाने गए मान को ओवरराइड करने के लिए, या `node` के साथ स्वयं-होस्टिंग करते समय, `adapter` को स्पष्ट रूप से सेट करें।

एक सर्वर बिल्ड में वह सब कुछ शामिल होता है जो एक स्टैटिक बिल्ड में होता है, साथ ही आपके द्वारा जोड़े गए कोई भी Astro एंडपॉइंट या मिडलवेयर। `node` एडाप्टर एक स्वतंत्र सर्वर बनाता है जिसे आप सीधे चला सकते हैं।

Vercel और Cloudflare पर, एक सर्वर बिल्ड [`Accept: text/markdown` कंटेंट नेगोशिएशन](/docs/configuration/ai#content-negotiation) को भी चालू कर देता है, ताकि उस हेडर के साथ किसी भी कंटेंट पेज का अनुरोध करने वाले एजेंट को उसी URL पर उसका रॉ-Markdown मिरर मिले। Vercel पर, Blume डिप्लॉय के रूटिंग कॉन्फ़िग में हेडर-सशर्त रीराइट्स जोड़ देता है; Cloudflare पर, यह Astro वाले Worker के आगे एक छोटा Worker उत्पन्न करता है और `assets.run_worker_first` को कंटेंट रूट्स तक सीमित कर देता है, क्योंकि अन्यथा प्लेटफ़ॉर्म कोई भी सर्वर कोड चलने से पहले ही प्रीरेंडर किए गए पेज परोस देता — अन्य एसेट्स अपना शून्य-Worker तेज़ रास्ता बनाए रखते हैं।

:::note
सर्वर सुविधाओं का अपना कॉन्फ़िगरेशन होता है — उदाहरण के लिए, Ask AI को एक मॉडल API कुंजी की आवश्यकता होती है। सेटअप के लिए [AI गाइड](/docs/configuration/ai) देखें।
:::

## रीडायरेक्ट

`blume.config.ts` में पुराने URL को नए URL से मैप करें:

```ts blume.config.ts
redirects: [{ from: "/old", to: "/new", status: 301 }];
```

`status` `301`, `302`, `307`, या `308` स्वीकार करता है (डिफ़ॉल्ट `301`)। सर्वर बिल्ड रीडायरेक्ट को अनुरोध-समय पर संभालते हैं। स्टैटिक बिल्ड रीडायरेक्ट पेज **और** प्लेटफ़ॉर्म फ़ाइलें दोनों उत्पन्न करते हैं ताकि आपका होस्ट एक वास्तविक HTTP रीडायरेक्ट जारी करे: `_redirects` (Netlify, Cloudflare Pages), `vercel.json` (Vercel), और `blume-redirects.json` — बाकी सब कुछ के लिए एक संरचित मैनिफ़ेस्ट (nginx/Apache नियम, एक एज वर्कर)। `public/` में आपके द्वारा शिप की गई `_redirects` या `vercel.json` फ़ाइल अछूती छोड़ दी जाती है।

:::note
`from` का मिलान एक सटीक पथ के रूप में किया जाता है — वाइल्डकार्ड और पैटर्न मिलान (जैसे `/blog/:slug` या `/old/*`) समर्थित नहीं हैं। यदि आपको पैटर्न-आधारित नियमों की आवश्यकता है, तो उन्हें इसके बजाय `vercel.json` जैसी इन्फ़्रास्ट्रक्चर फ़ाइल (जो वाइल्डकार्ड `source` पैटर्न का समर्थन करती है) या अपने होस्ट के रीडायरेक्ट कॉन्फ़िग में संभालें। `public/` में आपके द्वारा शिप की गई `vercel.json` जस की तस संरक्षित रहती है।
:::

:::note
`from` और `to` दोनों को ऐसे लिखें मानो वे रूट पर माउंट हों — [`deployment.base`](#subpath-deploys) और [`basePath`](#mount-the-docs-under-a-path) दोनों के अंतर्गत, Blume आपके लिए दोनों पक्षों को पुनर्लिखित कर देता है, ताकि रीडायरेक्ट बेस के भीतर ही पहुँचे। जो बेस आपने `to` में पहले से हाथ से लिख दिया है, वह दोहराया नहीं जाता बल्कि संरक्षित रखा जाता है।
:::

## कंटेंट प्रकार

एक स्टैटिक बिल्ड एक `_headers` फ़ाइल भी उत्पन्न करता है जो रॉ AI-तैयार एंडपॉइंट्स — `/<route>.md`, `/<route>.mdx`, और `.txt` फ़ाइलों (`llms.txt`, `llms-full.txt`) — पर `charset=utf-8` निर्धारित करती है। वे प्रतिक्रियाएँ वैध UTF-8 होती हैं, लेकिन कई स्टैटिक होस्ट उन्हें **बिना** किसी charset के `text/markdown` / `text/plain` के रूप में परोसते हैं, और तब ब्राउज़र Windows-1252 पर वापस चले जाते हैं — इसलिए गैर-ASCII डॉक्स (जापानी, उच्चारण-चिह्न वाली लैटिन, …) रॉ URL सीधे खोलने पर मोजिबाके के रूप में दिखते हैं। HTML पेज इससे अप्रभावित रहते हैं क्योंकि उनमें `<meta charset>` होता है। Netlify और Cloudflare (Pages/Workers स्टैटिक एसेट्स) `_headers` पढ़ते हैं; जो होस्ट नहीं पढ़ते (Vercel, S3) वे इस फ़ाइल को हानिरहित रूप से अनदेखा कर देते हैं। `public/` में आपके द्वारा शिप की गई `_headers` फ़ाइल अछूती छोड़ दी जाती है।

## परिवेश चर

जब किसी सुविधा को रनटाइम सीक्रेट की आवश्यकता होती है, तो Blume `blume dev`/`build` पर चेतावनी देता है यदि वह गायब है — ताकि समस्या पहले अनुरोध के बजाय पहले ही सामने आ जाए:

| सुविधा | चर |
| --- | --- |
| Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (या Vercel OIDC) |
| Ask AI (अन्य प्रदाता) | प्रदाता का डिफ़ॉल्ट कुंजी एन्व चर (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), या आपका कॉन्फ़िगर किया गया `apiKeyEnv` |
| Mixedbread खोज | `MIXEDBREAD_API_KEY` |

स्थानीय डेव के लिए इन्हें `.env.local` में और प्रोडक्शन के लिए अपने होस्ट के परिवेश में सेट करें। खोज-इंडेक्स सिंक (Algolia, Orama Cloud, Typesense) के लिए बिल्ड-समय के सीक्रेट्स के बारे में सिंक चरण के दौरान अलग से चेतावनी दी जाती है।

## बिल्ड सारांश

हर बिल्ड एक सारांश प्रिंट करता है — आउटपुट मोड, एडाप्टर, हल किया गया साइट URL, खोज प्रदाता, रीडायरेक्ट संख्या, साइटमैप और `llms.txt` की स्थिति, और कोई भी सक्षम सर्वर सुविधाएँ — ताकि परिनियोजित करने से पहले आप पुष्टि कर सकें कि क्या शिप हुआ (स्वतः पहचानी गई हर चीज़ सहित)।

---

# सामान्य प्रश्न (FAQ)
Source: https://useblume.dev/hi/docs/faq

अक्सर पूछे जाने वाले प्रश्नों के उत्तर। कोई प्रश्न छूट गया? [कोई issue खोलें](https://github.com/haydenbleasel/blume/issues) या पेज पर मौजूद असिस्टेंट से पूछें।

## Blume, Mintlify, Fumadocs और अन्य से किस तरह अलग है?

अधिकांश डॉक्यूमेंटेशन टूल दो में से किसी एक छोर पर होते हैं। Mintlify जैसे **मैनेज्ड प्लेटफ़ॉर्म** आपको तेज़ी से एक परिष्कृत परिणाम देते हैं, लेकिन बिल्ड और होस्टिंग उनकी सेवा है — आप उनके सिस्टम के भीतर लिखते हैं और उनके इन्फ़्रास्ट्रक्चर पर डिप्लॉय करते हैं। Fumadocs, Nextra या Docusaurus जैसी **कंपोनेंट लाइब्रेरीज़ और स्टार्टर्स** ओपन-सोर्स और लचीले हैं, लेकिन वे आपको एक एप्लिकेशन (एक Next.js या React प्रोजेक्ट) सौंप देते हैं जिसे आपको एक शब्द लिखने से पहले और बाद में स्कैफ़ोल्ड करना, जोड़ना और मेंटेन करना पड़ता है।

Blume एक तीसरा रास्ता अपनाता है: **फ़्रेमवर्क ही टेम्पलेट है।** आप इसे Markdown के एक फ़ोल्डर की ओर इंगित करते हैं और यह पूरी साइट को जनरेट और संचालित करता है — नेविगेशन, सर्च, थीमिंग, Open Graph इमेजेज़, SEO और AI एंडपॉइंट्स — बिना किसी ऐप के स्वामित्व के। यह पूरी तरह ओपन-सोर्स और सेल्फ़-होस्टेबल है, इसलिए न कोई मैनेज्ड सेवा है और न ही कोई वेंडर लॉक-इन, लेकिन साथ ही मेंटेन करने के लिए कोई बॉयलरप्लेट भी नहीं है।

|  | Blume | Mintlify | Fumadocs / Nextra / Docusaurus |
| --- | --- | --- | --- |
| **मॉडल** | ज़ीरो-कॉन्फ़िग फ़्रेमवर्क; केवल कंटेंट | होस्टेड प्लेटफ़ॉर्म | लाइब्रेरी + वह ऐप जिसे आप स्कैफ़ोल्ड करते हैं |
| **स्रोत** | ओपन-सोर्स (MIT) | क्लोज़्ड कोर | ओपन-सोर्स |
| **होस्टिंग** | कहीं भी — स्टैटिक या सर्वर फ़ंक्शन | उनका मैनेज्ड इन्फ़्रास्ट्रक्चर | कहीं भी; आप बिल्ड और डिप्लॉय करते हैं |
| **आप क्या मेंटेन करते हैं** | आपका Markdown | आपका Markdown + प्लेटफ़ॉर्म कॉन्फ़िग | आपका Markdown + उसके इर्द-गिर्द का ऐप |
| **रेंडरिंग** | Astro; कोर थीम शून्य क्लाइंट JS भेजती है | उनका रनटाइम | React/Next.js रनटाइम |
| **AI फ़ीचर्स** | `llms.txt`, रॉ Markdown, Ask AI, MCP — बिल्ट इन, कोई होस्टेड सेवा नहीं | बिल्ट इन (होस्टेड) | अपना खुद का लाएँ |

कुछ परिणाम जिनका उल्लेख करना ज़रूरी है:

- **आउटपुट आपका है।** `blume build` एक सादी साइट बनाता है जिसे आप Vercel, Netlify, Cloudflare, S3, या अपने खुद के सर्वर पर होस्ट करते हैं। कुछ भी वापस रिपोर्ट नहीं करता।
- **कोई लॉक-इन नहीं, बाहर निकलने के दो रास्ते।** आपका कंटेंट पोर्टेबल Markdown है, और `blume eject` प्रोजेक्ट को एक स्टैंडअलोन Astro ऐप में बदल देता है जो पूरा नियंत्रण चाहने पर भी `blume` पैकेज का ही उपयोग करता है।
- **डिफ़ॉल्ट रूप से तेज़।** कोर थीम React-मुक्त है और स्टैटिक HTML रेंडर करती है, इसलिए पेज बिना ट्यूनिंग के Core Web Vitals पर अच्छा स्कोर करते हैं। सर्वर फ़ीचर्स (Ask AI, MCP) आप तभी चुनते हैं जब आपको उनकी ज़रूरत हो।
- **टाइप-सेफ़ कॉन्फ़िगरेशन।** `blume.config.ts` और हर `meta.ts` असली TypeScript हैं जिन्हें एक स्कीमा द्वारा वैलिडेट किया जाता है — न कि ढीले-ढाले टाइप वाला YAML।

:::note
यह "हर चीज़ से बेहतर" होने का दावा नहीं है — मैनेज्ड प्लेटफ़ॉर्म और पूर्ण फ़्रेमवर्क तब सही विकल्प हैं जब आपको एक होस्टेड प्रोडक्ट चाहिए या ऐप पर अधिकतम नियंत्रण चाहिए। Blume उन टीमों के लिए है जो प्लेटफ़ॉर्म या प्लंबिंग में से किसी का भी स्वामित्व लिए बिना एक प्रोडक्शन-ग्रेड डॉक्स साइट चाहती हैं।
:::

विस्तृत संस्करण के लिए [Blume क्यों मौजूद है](/docs) देखें।

## क्या Blume मुफ़्त और ओपन-सोर्स है?

हाँ — Blume MIT-लाइसेंस्ड और मुफ़्त है। आप `blume` पैकेज इंस्टॉल करते हैं, अपना कंटेंट अपनी ही रिपॉज़िटरी में रखते हैं, और बिल्ड को जहाँ चाहें होस्ट करते हैं। कोई पेड टियर नहीं, कोई प्रति-सीट मूल्य निर्धारण नहीं, और साइन अप करने के लिए कोई अकाउंट नहीं। सोर्स [GitHub](https://github.com/haydenbleasel/blume) पर मौजूद है।

## क्या मुझे Astro, React या Tailwind जानना ज़रूरी है?

नहीं। Markdown का एक फ़ोल्डर ही एक संपूर्ण साइट है — नेविगेशन, सर्च और थीमिंग या तो अनुमानित होते हैं या मुट्ठी भर टोकन्स से सेट किए जाते हैं। आप अंतर्निहित स्टैक तक तभी पहुँचते हैं जब आप कस्टमाइज़ करना चाहते हैं: [इंटरैक्टिव आइलैंड्स](/docs/content/islands) (React), [कंपोनेंट ओवरराइड्स](/docs/configuration/customization), या [थीम टोकन्स](/docs/configuration/theming) (Tailwind)। तब भी, [`blume.config.ts`](/docs/configuration) टाइप्ड है, इसलिए आपका एडिटर आपका मार्गदर्शन करता है।

## क्या मैं React कंपोनेंट्स और MDX का उपयोग कर सकता हूँ?

हाँ। कोई भी पेज `.md` या `.mdx` हो सकता है, और MDX आपको बिना किसी import के [बिल्ट-इन कंपोनेंट्स](/docs/content/components) डालने देता है। आप अपने खुद के `.tsx`/`.jsx` [आइलैंड्स](/docs/content/islands) भी जोड़ सकते हैं — Blume केवल उन्हीं पेजों के लिए React को स्वतः सक्षम करता है जो उनका उपयोग करते हैं, इसलिए कोर थीम बाकी हर जगह JavaScript-मुक्त रहती है।

## मैं इसे कहाँ डिप्लॉय कर सकता हूँ?

कहीं भी। `blume build` डिफ़ॉल्ट रूप से स्टैटिक HTML आउटपुट करता है, जिसे आप किसी भी स्टैटिक होस्ट या CDN से सर्व कर सकते हैं — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, या अपना खुद का सर्वर। केवल-सर्वर फ़ीचर्स (Ask AI, MCP सर्वर, ऑन-डिमांड रेंडरिंग) Vercel, Node, Netlify या Cloudflare के लिए एक अडैप्टर के ज़रिए बिल्ड को सर्वर फ़ंक्शन में बदल देते हैं। [डिप्लॉयमेंट](/docs/deployment) देखें।

## क्या सर्च के लिए किसी होस्टेड सेवा की ज़रूरत है?

नहीं। [Orama](/docs/configuration/search) एक लोकल इंडेक्स बनाता है जो dev और production दोनों में काम करता है, और इसके लिए कुछ भी होस्ट या भुगतान नहीं करना पड़ता। बहुत बड़ी साइटों के लिए, [Pagefind](/docs/configuration/search) बस एक फ़्लैग की दूरी पर है। दोनों ही स्थितियों में इंडेक्स आपकी साइट के हिस्से के रूप में भेजा जाता है।

## मैं लुक कैसे कस्टमाइज़ करूँ?

[थीम टोकन्स](/docs/configuration/theming) से शुरू करें — एक्सेंट रंग, फ़ॉन्ट्स, रेडियस, और बाकी हर उस चीज़ के लिए एक `theme.css` जिसे Tailwind व्यक्त कर सकता है। आगे बढ़ने के लिए [बिल्ट-इन कंपोनेंट्स को ओवरराइड करें](/docs/configuration/customization) या [कस्टम पेज](/docs/configuration/customization#custom-pages) जोड़ें। जब आपको Astro प्रोजेक्ट ही चाहिए, तो [`blume eject`](/docs/reference/cli) आपको एक स्टैंडअलोन ऐप सौंप देता है जो फिर भी `blume` पैकेज का उपयोग करता है।

## oxfmt / Ultracite मेरे डायरेक्टिव्स को क्यों समेट रहा है?

यदि आप अपने Markdown को [Ultracite](https://www.ultracite.ai) से फ़ॉर्मैट करते हैं (जो oxlint + [oxfmt](https://oxc.rs) चलाता है) — जैसा कि Blume खुद करता है — तो आप देख सकते हैं कि फ़ॉर्मैट पास के बाद कंटेनर डायरेक्टिव्स एक ही लाइन में सिमट जाते हैं:

```md
:::note
Regenerate the project with blume dev.
:::
```

बन जाता है

```md
:::note Regenerate the project with blume dev. :::
```

एक बार जब शुरुआती `:::note` फ़ेंस प्रोज़ से जुड़ जाता है, तो वह डायरेक्टिव नहीं रह जाता, इसलिए वह [callout](/docs/content/syntax#callouts) के बजाय शाब्दिक टेक्स्ट के रूप में रेंडर होता है।

### यह क्यों होता है

यह oxfmt के Markdown फ़ॉर्मैटर में एक बग है (जो Prettier के Markdown प्रिंटर से विरासत में मिला है — देखें [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040))। जब यह प्रोज़ को रैप करता है, तो यह `:::` फ़ेंस लाइनों को सामान्य टेक्स्ट मानता है और उन्हें बगल की लाइन से जोड़ देता है, जिससे डायरेक्टिव टूट जाता है। यह हर कंटेनर डायरेक्टिव प्रकार को प्रभावित करता है — `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::success`।

हमने इसे अपस्ट्रीम [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096) में रिपोर्ट किया है; जब तक वहाँ इसे ठीक नहीं किया जाता, नीचे दिया गया पैच ही समाधान है।

### समाधान

oxfmt को इस तरह पैच करें कि वह उस लाइन ब्रेक को संरक्षित रखे जो सीधे किसी `:::` फ़ेंस से सटी हुई है। Blume अपनी ही रिपॉज़िटरी में यही फ़िक्स भेजता है, और आप इसे किसी भी प्रोजेक्ट में लागू कर सकते हैं।

1. पैच को `patches/oxfmt@0.66.0.patch` के रूप में सेव करें:

   ```diff patches/oxfmt@0.66.0.patch
   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
   --- a/dist/markdown-BgZGxhM2.js
   +++ b/dist/markdown-BgZGxhM2.js
   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
    		case "sentence": return Oh(e, r);
    		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
    		case "whitespace": {
   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   +			let { next: a, 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(":::");
   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
   +			// linkReference between two sentence nodes at the paragraph level: the
   +			// fence word ends the sentence before the reference, and the body's
   +			// leading newline opens the sentence after it. So when this whitespace
   +			// starts its sentence, climb to the paragraph and check whether the two
   +			// preceding siblings are a (link) reference and a sentence ending in a
   +			// `:::` fence word.
   +			let oxfmtPrevIsTitledFence = !1;
   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
   +				if (oxfmtSentIdx >= 2) {
   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
   +				}
   +			}
   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
   +			// words, so the whole directive is one sentence. For a newline
   +			// whitespace, walk back to the start of its visual line within the
   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
   +				let oxfmtLineFirst = null;
   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
   +					let oxfmtSib = e.parent.children[oxfmtJ];
   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
   +					oxfmtLineFirst = oxfmtSib;
   +				}
   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
   +			}
   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
    			return ou(e, n.value, u, !1, t);
    		}
    		case "emphasis": {
   ```

2. इसे अपने पैकेज मैनेजर के `patchedDependencies` में रजिस्टर करें। Bun या pnpm के साथ, `package.json` में जोड़ें:

   ```json package.json
   {
     "patchedDependencies": {
       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
     }
   }
   ```

3. पैच लागू होने के लिए फिर से इंस्टॉल करें:

   ```package-install
   bun install
   ```

:::warning[संस्करण-निर्धारित]
यह पैच एक विशिष्ट oxfmt बिल्ड को लक्षित करता है — इसका diff एक ऐसी फ़ाइल का संदर्भ देता है जिसका नाम हर रिलीज़ पर हैश किया जाता है (`dist/markdown-*.js`)। जब आप oxfmt को अपग्रेड करें, तो पैच को फिर से जनरेट करें (उदाहरण के लिए `bun patch oxfmt`) या जाँचें कि क्या अपस्ट्रीम फ़िक्स आ चुका है और पैच की अब ज़रूरत नहीं है।
:::

---

# क्विकस्टार्ट
Source: https://useblume.dev/hi/docs/quickstart

कुछ ही कमांड में एक खाली फ़ोल्डर से चलती हुई डॉक्स साइट तक पहुँचें। Blume को **Node.js 22.12 या नया** और कम से कम एक `.md` या `.mdx` फ़ाइल वाले `docs/` फ़ोल्डर की आवश्यकता होती है — सेट अप करने के लिए और कुछ नहीं है।

## इंस्टॉल करें और चलाएँ

1. **Blume इंस्टॉल करें**

    पैकेज को किसी नए या मौजूदा प्रोजेक्ट में जोड़ें।

    ```package-install
    npm i blume
    ```

2. **प्रोजेक्ट स्कैफ़ोल्ड करें**

    `blume init` कुछ सवाल पूछता है — प्रोजेक्ट कहाँ बनाना है, आपकी
    डॉक्स साइट का नाम क्या है, कौन सा टेम्पलेट, और आपका कंटेंट कहाँ रहता है — फिर
    न्यूनतम सतह स्कैफ़ोल्ड करता है: एक कंटेंट फ़ोल्डर और एक कॉन्फ़िग फ़ाइल। प्रॉम्प्ट छोड़ने
    और डिफ़ॉल्ट अपनाने के लिए `--yes` पास करें।

    ```bash
    blume init
    ```

    ```txt
    docs/
      index.mdx
    blume.config.ts
    ```

3. **डेव सर्वर शुरू करें**

    Blume रनटाइम जनरेट करता है और आपके डॉक्स को हॉट रीलोड के साथ सर्व करता है।

    ```bash
    blume dev
    ```

4. **प्रोडक्शन के लिए बिल्ड करें**

    स्टैटिक HTML `dist/` में लिखा जाता है, और उसके ऊपर एक लोकल सर्च इंडेक्स बनाया जाता है।

    ```bash
    blume build
    ```

:::tip
Blume किसी भी पैकेज मैनेजर के साथ काम करता है और आपसे कभी Astro या Tailwind खुद सेट अप करने की अपेक्षा नहीं करता।
:::

## अपना पहला पेज लिखें

हर पेज थोड़े फ़्रंटमैटर के साथ Markdown या MDX होता है — `title` और `description` स्वतः पेज हेडिंग और परिचय के रूप में रेंडर होते हैं। इसे `docs/index.mdx` में डालें:

```mdx docs/index.mdx lineNumbers
---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::
```

इसे सेव करें, और डेव सर्वर तुरंत रीलोड हो जाता है। जैसे-जैसे आप फ़ाइलें जोड़ते हैं, नेविगेशन, सर्च, और पेज मेटाडेटा उनसे अनुमानित होते जाते हैं — लिखते रहें, और साइट साथ चलती रहेगी।

## अगले कदम

**[कॉन्फ़िगरेशन](/docs/configuration)**

टाइटल, थीम, सर्च, और डिप्लॉयमेंट को ट्यून करें।

**[कंपोनेंट्स](/docs/content/components)**

बिल्ट-इन कंपोनेंट लाइब्रेरी को एक्सप्लोर करें।

**[AI](/docs/configuration/ai)**

`llms.txt` और एक Ask AI असिस्टेंट शिप करें।

**[डिप्लॉयमेंट](/docs/deployment)**

किसी भी स्टैटिक होस्ट पर लाइव जाएँ।

---

# CLI
Source: https://useblume.dev/hi/docs/reference/cli

```bash
blume <command> [options]
```

## कमांड

| कमांड | विवरण |
| --- | --- |
| `blume init [dir]` | एक प्रोजेक्ट स्कैफ़ोल्ड करें (डिफ़ॉल्ट रूप से इंटरैक्टिव)। |
| `blume dev` | हॉट रीलोड के साथ डेव सर्वर शुरू करें। |
| `blume build` | स्टैटिक (या सर्वर) साइट बनाएँ। |
| `blume preview` | पिछले बिल्ड का पूर्वावलोकन करें। |
| `blume add <item>` | रजिस्ट्री से एक सोर्स कंपोनेंट इंस्टॉल करें। |
| `blume sync` | रिमोट कंटेंट स्रोतों को दोबारा लाएँ और फिर से जनरेट करें। |
| `blume eject` | रनटाइम को एक स्वतंत्र Astro ऐप में बदलें। |
| `blume check` | `astro check` से साइट की टाइप-जाँच करें। |
| `blume doctor` | कॉन्फ़िग और कंटेंट की समस्याओं का निदान करें। |
| `blume validate` | अपने कंटेंट में मौजूद लिंक की जाँच करें। |
| `blume audit` | बनी हुई साइट का SEO और स्वास्थ्य संबंधी समस्याओं के लिए ऑडिट करें। |
| `blume eval` | डॉक्स की जाँच करें: एक एजेंट केवल दस्तावेज़ों का उपयोग करके आपके प्रश्नों के उत्तर देता है। |
| `blume translate` | एक लोकल एजेंट CLI की मदद से डॉक्स को कॉन्फ़िगर किए गए लोकेल में अनूदित करें। |
| `blume version [id]` | मौजूदा डॉक्स को एक [संग्रहित संस्करण](/docs/content/versioning) के रूप में फ़्रीज़ करें (बिना id दिए कॉन्फ़िगर किए गए संस्करणों की सूची मिलती है)। |

## सामान्य फ़्लैग

- `blume init` — टर्मिनल में, यह आपसे कुछ प्रश्न पूछता है (प्रोजेक्ट कहाँ बनाना है, साइट का नाम, टेम्पलेट, कंटेंट स्रोत); नीचे दिया गया हर फ़्लैग अपने प्रश्न का उत्तर पहले से दे देता है।
- `blume init --yes` — प्रॉम्प्ट छोड़ें और डिफ़ॉल्ट के साथ स्कैफ़ोल्ड करें (CI में या जब stdin टर्मिनल न हो, तब भी यही व्यवहार होता है)।
- `blume init --content-dir <dir>` — कंटेंट फ़ोल्डर सेट करें (डिफ़ॉल्ट `docs`)।
- `blume init --template docs|api|sdk|changelog` — किसी स्टार्टर से स्कैफ़ोल्ड करें (सादे docs सीड के बजाय API रेफ़रेंस, SDK, या चेंजलॉग)।
- `blume init --package-manager npm|pnpm|yarn|bun` — प्रिंट किए जाने वाले अगले-चरण आपके पैकेज मैनेजर के अनुसार ढालें।
- `blume init --eject` — स्कैफ़ोल्ड करें, फिर एक स्वतंत्र Astro प्रोजेक्ट में eject करें (जब डिपेंडेंसी अभी इंस्टॉल न हों, तो यह आपको `blume eject` के ज़रिए मार्गदर्शन देने पर लौट आता है)।
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — `blume.config.ts` संपादित किए बिना किसी अलग कंटेंट फ़ोल्डर को स्कैन करें।
- `blume dev --debug` — समस्या-निवारण के लिए विस्तृत Astro/Vite लॉगिंग।
- `blume dev --preview` / `blume build --preview` — ड्राफ़्ट और अप्रकाशित CMS कंटेंट शामिल करें।
- `blume build --no-strict` — डायग्नोस्टिक त्रुटियों के बावजूद बिल्ड करें। डिफ़ॉल्ट रूप से `blume build` किसी भी error डायग्नोस्टिक पर विफल हो जाता है (exit 1), क्योंकि जो पेज फ्रंटमैटर वैलिडेशन में विफल होते हैं वे आउटपुट से हटा दिए जाते हैं; `--no-strict` के साथ बिल्ड सफल होता है और बताता है कि कितने पेज गायब हैं। `blume dev --strict` डेव को भी उसी fail-fast व्यवहार में ले आता है।
- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — `blume.config.ts` से डिप्लॉयमेंट आउटपुट, अडैप्टर, और बेस पाथ को ओवरराइड करें।
- `blume build --analyze` — बिल्ड के बाद क्लाइंट JavaScript बंडल के आकार (सबसे बड़े पहले) प्रिंट करें।
- `blume build --budget-js <kb> --budget-css <kb>` — जब कुल क्लाइंट JavaScript/CSS बजट से अधिक हो जाए तो बिल्ड विफल करें, जिससे एक प्रदर्शन लक्ष्य CI गेट बन जाता है।
- `blume build --isolated` — `.blume/` के बजाय एक अस्थायी `.blume-verify/` रनटाइम (और उसका अपना `dist/`) में बिल्ड करें, ताकि चल रहा `blume dev` सर्वर और आपका असली `dist/` अछूते रहें। देखें [डेव सर्वर चलते समय सत्यापन करना](#verifying-while-the-dev-server-runs)।
- `blume preview --host --port <n>` — प्रीव्यू सर्वर को बाइंड करें।
- `blume sync --force` — कैश किए गए स्नैपशॉट को पहले हटाकर रिमोट स्रोतों को दोबारा लाएँ।
- `blume add <item> --force` — पहले से मौजूद फ़ाइलों को अधिलेखित करें।
- `blume check --preview` — जाँच करते समय ड्राफ़्ट और अप्रकाशित CMS कंटेंट शामिल करें।
- `blume check --strict` — टाइप त्रुटियों के साथ-साथ कंटेंट डायग्नोस्टिक्स पर भी विफल हों।
- `blume check --isolated` — एक अस्थायी `.blume-verify/` रनटाइम में टाइप-जाँच करें ताकि चल रहा `blume dev` सर्वर अछूता रहे। देखें [डेव सर्वर चलते समय सत्यापन करना](#verifying-while-the-dev-server-runs)।
- `blume eject --yes` — पुष्टिकरण प्रॉम्प्ट छोड़ें।
- `blume validate --external` — नेटवर्क के ज़रिए बाहरी लिंक की भी जाँच करें।
- `blume validate --strict` — चेतावनियों पर भी नॉन-ज़ीरो कोड के साथ बाहर निकलें।
- `blume validate --json` / `blume doctor --json` — CI और एडिटर इंटीग्रेशन के लिए डायग्नोस्टिक्स को stdout पर JSON के रूप में उत्सर्जित करें (`code`, `severity`, `file`, `line`/`column`, और `docsUrl` के साथ)।
- `blume audit --fail-on error|warning|info` — CI गेट; डिफ़ॉल्ट `error` है। `--strict`, `--fail-on warning` का उपनाम है।
- `blume audit --url <origin>` — स्टेटस कोड, रिस्पॉन्स हेडर, और रीडायरेक्ट चेन के लिए किसी लाइव डिप्लॉयमेंट की भी जाँच करें।
- `blume audit --external` — नेटवर्क के ज़रिए बाहर जाने वाले लिंक की जाँच करें।
- `blume audit --only <check|category>` / `--skip <check|category>` — रिपोर्ट पर काम करते समय उसे सीमित करें (कॉमा से अलग किया हुआ)।
- `blume audit --list-checks` — ऑडिट जो भी जाँच रिपोर्ट कर सकता है, वह सब प्रिंट करें।
- `blume audit --verbose` — हर प्रभावित पेज को प्रत्येक निष्कर्ष के पूरे विवरण के साथ सूचीबद्ध करें, जैसे कि कौन-सा लिंक टारगेट टूटा हुआ है।
- `blume audit --json` — रिपोर्ट को stdout पर JSON के रूप में उत्सर्जित करें।
- `blume audit --claude` / `--codex` — निष्कर्षों को इंटरैक्टिव रूप से ठीक करने के लिए Claude Code या Codex को सौंपें।
- `blume eval` — `evals.yaml` के प्रश्नों को एक ऐसे एजेंट के ज़रिए चलाएँ जो केवल आपके डॉक्स पढ़ता है; देखें [Evals](/docs/reference/eval)।
- `blume eval init` — एजेंट से अपने डॉक्स के आधार पर एक शुरुआती `evals.yaml` तैयार करवाएँ।
- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — हर फ़्लैग के लिए देखें [Evals](/docs/reference/eval)।
- `blume translate --claude` / `--codex` — गायब और पुराने पड़ चुके पेजों को आपके कॉन्फ़िगर किए गए लोकेल में अनूदित करें; देखें [Translate](/docs/reference/translate)।
- `blume translate --check` — एजेंट चलाए बिना अनुवाद के अंतर की रिपोर्ट दें और नॉन-ज़ीरो कोड के साथ बाहर निकलें (CI गेट)।
- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — हर फ़्लैग के लिए देखें [Translate](/docs/reference/translate)।

## डेव सर्वर चलते समय सत्यापन करना

`blume dev` एक लाइव Astro सर्वर चलाता है जिसकी जड़ जनरेट किया गया `.blume/` रनटाइम होता है, और हर बदलाव पर उसे दोबारा जनरेट करता है। `blume build` और `blume check` _उसी_ `.blume/` को दोबारा जनरेट करते हैं, इसलिए डेव सर्वर के लाइव रहते इनमें से कोई भी चलाने पर वह भ्रष्ट हो जाएगा — दोनों ही एक त्रुटि के साथ मना कर देते हैं और नॉन-ज़ीरो कोड के साथ बाहर निकल जाते हैं:

```
A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

`--isolated` फ़्लैग इसका निकास द्वार है। यह पूरे जनरेट किए गए रनटाइम को (और, `build` के लिए, उसके आउटपुट `dist/` को) एक समकक्ष `.blume-verify/` डायरेक्टरी में स्थानांतरित कर देता है, ताकि सत्यापन कभी भी ऐसा कुछ न लिखे जिस पर डेव सर्वर — या आपका असली `dist/` — निर्भर है:

```bash
# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist
```

`check --isolated` तेज़ रास्ता है (Astro टाइप + टेम्पलेट डायग्नोस्टिक्स, कोई `dist/` नहीं); `build --isolated` भारी विकल्प है जो रनटाइम रेंडर त्रुटियों को भी पकड़ता है। आइसोलेटेड बिल्ड डिप्लॉय के बाद वाले चरण छोड़ देते हैं (सर्च इंडेक्स, होस्टेड-प्रोवाइडर सिंक, `llms.txt`, साइटमैप/robots, रीडायरेक्ट) — एक सत्यापन को केवल यह पुष्टि करनी होती है कि साइट कंपाइल और रेंडर होती है, उसे प्रकाशित नहीं करना होता। `--analyze` और `--budget-js`/`--budget-css` गेट फिर भी चलते हैं, और आइसोलेटेड आउटपुट के सापेक्ष मापे जाते हैं। Blume आपकी `.gitignore` में `.blume-verify/` अपने आप जोड़ देता है।

यह खासकर तब उपयोगी है जब किसी कोडिंग एजेंट को बदलाव सत्यापित करने हों और आप डेव सर्वर खुला रखना चाहते हों। सादे `blume build`/`blume check` को बिना फ़्लैग के आइसोलेट कराने के लिए — उदाहरण के लिए किसी एजेंट के शेल में — `BLUME_RUNTIME_DIR` को उस रनटाइम डायरेक्टरी पर सेट करें जिसका उपयोग करना है:

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## टाइप-जाँच

`blume check` आपके प्रोजेक्ट पर [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) चलाता है। यह `.blume` रनटाइम को दोबारा जनरेट करता है, Astro के कंटेंट टाइप सिंक करता है, फिर किसी भी TypeScript त्रुटि की रिपोर्ट देता है — आपके `blume.config.ts` में, कस्टम `.astro` पेजों में, और उनके द्वारा इम्पोर्ट किए गए कंपोनेंट में। त्रुटियाँ होने पर यह नॉन-ज़ीरो कोड के साथ बाहर निकलता है, इसलिए यह CI में `typecheck` चरण के रूप में काम करता है:

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

अपने प्रोजेक्ट रूट में Astro के कॉन्फ़िग को एक्सटेंड करने वाली `tsconfig.json` जोड़ें ताकि लिखे गए पेज `blume/*` इम्पोर्ट और `blume:data` जैसे वर्चुअल मॉड्यूल हल कर सकें:

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}
```

प्रोजेक्ट `tsconfig.json` के बिना, केवल जनरेट किए गए रनटाइम की जाँच होती है।

## लिंक की जाँच

`blume validate` आपके कंटेंट में मिले हर लिंक की जाँच करता है:

- **आंतरिक पेज लिंक** (`/guides/intro`, `./sibling`) किसी वास्तविक पेज पर हल होने चाहिए — टूटे हुए लिंक त्रुटियों के रूप में रिपोर्ट किए जाते हैं।
- **एंकर लिंक** (`#section`, `/guides/intro#setup`) लक्षित पेज के किसी एंकर से मेल खाने चाहिए — किसी शीर्षक की id (जनरेट की गई या [पिन की गई](/docs/content/syntax#custom-anchors)) या किसी रॉ HTML एलिमेंट का `id` एट्रिब्यूट — और न मिलने पर चेतावनी मिलती है। कोड ब्लॉक, इनलाइन कोड, HTML कमेंट, और `<Prompt>` ब्लॉक के अंदर मौजूद id गिनती में नहीं आतीं।

- **एसेट लिंक** की जाँच वहीं होती है जहाँ फ़ाइल रहती है: एक निरपेक्ष पाथ (`/logo.png`) की जाँच `public/` डायरेक्टरी के सापेक्ष, और एक सापेक्ष इमेज एम्बेड (`![](./diagram.png)`) की जाँच पेज के अपने फ़ोल्डर के सापेक्ष। किसी सापेक्ष पाथ का सादा लिंक फिर भी एक साइट रूट के रूप में हल होता है — केवल इमेज एम्बेड ही इमेज पाइपलाइन से होकर जाते हैं।
- **बाहरी लिंक** की जाँच केवल `--external` के साथ होती है (डिफ़ॉल्ट रूप से बंद, क्योंकि इसके लिए नेटवर्क चाहिए); मृत लिंक (404/410/अनुपलब्ध) त्रुटियाँ हैं, जबकि रेट-लिमिटेड या अस्थायी प्रतिक्रियाएँ (403/429/5xx/टाइमआउट) चेतावनियाँ हैं।

## बनी हुई साइट का ऑडिट

`blume validate` आपका _कंटेंट_ पढ़ता है; `blume audit` _बनी हुई साइट_ पढ़ता है। यह बिल्ड के बाद `dist/` में मौजूद HTML को क्रॉल करता है और SEO तथा साइट-स्वास्थ्य संबंधी समस्याएँ बताता है — टाइटल, मेटा डिस्क्रिप्शन, canonical, Open Graph और X कार्ड, शीर्षक, hreflang, इमेज, साइटमैप, `robots.txt`, और स्ट्रक्चर्ड डेटा।

चूँकि साइट Blume ने बनाई है, हर निष्कर्ष सोर्स फ़ाइल **और उस फ्रंट मैटर लाइन** का नाम बताता है जो इसे ठीक करती है, केवल वह URL नहीं जो किसी क्रॉलर को दिखता:

```
⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.
```

इसे बिल्ड के बाद चलाएँ:

```bash
blume build
blume audit
```

निष्कर्षों को प्रति पेज सूचीबद्ध करने के बजाय जाँच के अनुसार समूहित किया जाता है, ताकि रिपोर्ट एक to-do सूची की तरह पढ़ी जा सके। हर प्रभावित पेज को उसके पूरे विवरण के साथ विस्तृत करने के लिए `--verbose` का उपयोग करें, और एक बार में एक श्रेणी पर काम करने के लिए `--only`/`--skip` का। `blume audit --list-checks` पूरा कैटलॉग प्रिंट करता है।

### CI विफल करना

एग्ज़िट कोड ही अनुबंध है। डिफ़ॉल्ट रूप से `blume audit` केवल त्रुटियों पर विफल होता है — ऐसी चीज़ें जो निश्चित रूप से टूटी हुई हैं, जैसे किसी ऐसे पेज का लिंक जो कभी बना ही नहीं, एक रीडायरेक्ट लूप, या एक अमान्य साइटमैप। सलाहकारी निष्कर्ष (छोटा विवरण, डुप्लिकेट टाइटल) चेतावनियाँ हैं और बिल्ड को विफल नहीं करतीं:

```bash
blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings
```

### लाइव डिप्लॉयमेंट की जाँच

कुछ बातें केवल असली सर्वर ही बता सकता है: क्या `dist/` में मौजूद कोई पेज किसी ख़राब rewrite के पीछे वास्तव में 404 देता है, क्या प्रतिक्रियाएँ कंप्रेस्ड हैं, और क्या कोई `X-Robots-Tag` हेडर चुपचाप ऐसे पेज को डीइंडेक्स कर रहा है जिसका HTML बिल्कुल ठीक दिखता है। ये जाँचें जोड़ने के लिए ऑडिट को किसी डिप्लॉयमेंट की ओर इंगित करें:

```bash
blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links
```

बाहर जाने वाले लिंक को सीधे विफल करने के बजाय श्रेणीबद्ध किया जाता है: 404 एक टूटा हुआ लिंक है जिसे आप ठीक कर सकते हैं, जबकि 403 या 5xx आमतौर पर रेट लिमिटिंग या किसी और की सेवा बाधा होती है और उसे चेतावनी के रूप में रिपोर्ट किया जाता है।

### किसी एजेंट के साथ निष्कर्ष ठीक करना

यदि आप [Claude Code](https://claude.com/claude-code) या [Codex](https://developers.openai.com/codex/cli) का उपयोग करते हैं, तो ऑडिट अपने निष्कर्ष सीधे उसे सौंप सकता है:

```bash
blume audit --claude   # or --codex
```

यह पूरी JSON रिपोर्ट — हर प्रभावित पेज, न कि टर्मिनल का तीन-पेज का पूर्वावलोकन — एक फ़ाइल में लिखता है और एजेंट को एक ऐसे प्रॉम्प्ट के साथ इंटरैक्टिव रूप से खोलता है जो उसे निष्कर्षों से होकर ले जाता है: हर निष्कर्ष जिस सोर्स फ़ाइल का नाम बताता है उसे संपादित करें, उसका सुझाया गया सुधार लागू करें, फिर `blume build` और `blume audit` दोबारा चलाएँ जब तक रिपोर्ट साफ़ न हो जाए। सत्र जानबूझकर इंटरैक्टिव है: आप एजेंट के अपने अनुमति प्रवाह के ज़रिए संपादनों की समीक्षा करते हैं, और एजेंट को बताया जाता है कि वह कभी भी कंटेंट हटाकर किसी निष्कर्ष को ठीक न करे।

`--only` और `--skip` इस हस्तांतरण को उसी तरह सीमित करते हैं जैसे वे रिपोर्ट को सीमित करते हैं, इसलिए आप एक बार में एक श्रेणी भेज सकते हैं।

### यह क्या जाँचता है और क्या नहीं

जाँचों का सेट जानबूझकर एक सामान्य-उद्देश्य SEO क्रॉलर की तुलना में संकीर्ण है। ऐसा क्रॉलर जो बहुत कुछ रिपोर्ट करता है, वह Blume साइट के साथ हो ही नहीं सकता — यह कभी `rel=nofollow` उत्सर्जित नहीं करता, और Vite के कंटेंट-हैश्ड बंडल कभी गायब या रीडायरेक्ट होते नहीं — और उन्हें स्थायी शून्य के रूप में रिपोर्ट करना आपको बस रिपोर्ट को नज़रअंदाज़ करना सिखाएगा।

दो सीमाएँ स्पष्ट रूप से बताने योग्य हैं:

- **स्ट्रक्चर्ड डेटा** की जाँच सुगठितता के लिए की जाती है (मान्य JSON, एक `@context`, हर नोड पर एक `@type`)। Blume पूरे schema.org शब्दकोश या Google के रिच-रिज़ल्ट्स नियमों के विरुद्ध सत्यापन नहीं करता।
- **Core Web Vitals** की जाँच नहीं होती। उनके लिए एक असली ब्राउज़र चाहिए, और एक ऐसा फ़्लैग जो चुपचाप कुछ भी न मापे, उसके न होने से भी बुरा होगा — इसलिए `blume audit` लेआउट-शिफ़्ट के वही कारण बताता है जो वह ऑफ़लाइन _देख_ सकता है (बिना `width`/`height` वाली इमेज, ज़रूरत से बड़े एसेट) और बाकी को फ़िलहाल छोड़ देता है।

ऑडिट ने जो कुछ नहीं चलाया, उसे चुपचाप पास करने के बजाय छोड़ा गया (skipped) बताया जाता है:

```
⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)
```

---

# मूल्यांकन (Evals)
Source: https://useblume.dev/hi/docs/reference/eval

`blume audit` आपको बताता है कि क्रॉलर आपके डॉक्स ढूँढ़ सकते हैं या नहीं। `blume eval` आपको बताता है कि क्या कोई वास्तव में उनका _उपयोग_ कर सकता है: एक AI एजेंट आपके दस्तावेज़ों को उसी तरह पढ़ता है जैसे कोई अनजान व्यक्ति पढ़ेगा और उनसे उपयोगकर्ताओं के असली प्रश्नों के उत्तर देने की कोशिश करता है। जब डॉक्स में उत्तर नहीं लिखा होता, तो रन विफल हो जाता है और उस पेज का नाम बताता है जिसमें वह उत्तर होना चाहिए।

```bash
blume eval
```

```
blume eval  3 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: the adapter is auto-detected
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
```

## यह कैसे काम करता है

हर प्रश्न दो एजेंट सत्रों से होकर गुज़रता है, और इसके लिए वही एजेंट CLI इस्तेमाल होता है जो आपके पास पहले से इंस्टॉल है — डिफ़ॉल्ट रूप से [Claude Code](https://claude.com/claude-code), या `--agent codex` के साथ [Codex](https://developers.openai.com/codex/cli)। Blume कोई API की नहीं रखता और स्वयं किसी मॉडल को कॉल नहीं करता।

1. **रीडर** केवल _और केवल_ आपके दस्तावेज़ों का उपयोग करके प्रश्न का उत्तर देता है। यह एक खाली डायरेक्टरी में चलता है, जिसमें उसके फ़ाइल, शेल और वेब टूल बंद कर दिए जाते हैं, और यह एक निजी [MCP सर्वर](/docs/configuration/ai) से जुड़ा होता है जो आपके डॉक्स परोसता है — वही `search_docs`/`get_page` टूल जो एक असली एजेंट आपकी डिप्लॉय की गई साइट पर इस्तेमाल करता है। यह आपका रेपो नहीं पढ़ सकता, इसलिए यह डॉक्स को ठीक वैसे ही अनुभव करता है जैसे कोई नया उपयोगकर्ता: जो लिखा नहीं है, उसका अस्तित्व नहीं है।
2. **जज** उत्तर को आपके द्वारा सूचीबद्ध तथ्यों के आधार पर आँकता है, बिना किसी टूल के। भावार्थ में कहा गया उत्तर पास होता है; कोई तथ्य छूट जाए या उसका खंडन हो तो फेल — और "दस्तावेज़ों में यह नहीं लिखा है" भी फेल ही है।

MCP स्नैपशॉट सीधे आपके कंटेंट स्रोतों से बनाया जाता है, इसलिए पहले `blume build` चलाने की ज़रूरत नहीं है, और कहीं कुछ भी डिप्लॉय या अपलोड नहीं किया जाता।

ऐसा उत्तर जिसे डॉक्स समर्थन _नहीं_ कर सकते, तब भी फेल होता है जब एजेंट का पूर्व ज्ञान संयोग से सही हो — यही तो मुद्दा है। आपके डॉक्स ही एकमात्र स्रोत हैं जो शिप होता है।

## मूल्यांकन लिखना

प्रश्न प्रोजेक्ट रूट में `evals.yaml` में रहते हैं। आपके मौजूदा डॉक्स से एजेंट द्वारा एक शुरुआती फ़ाइल तैयार करवाने के लिए:

```bash
blume eval init
```

या इसे हाथ से लिखें:

```yaml
questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - the output directory is dist
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - pagefind is the default
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped
```

- `expected` उन तथ्यों को सूचीबद्ध करता है जो एक सही उत्तर में सारभूत रूप से मौजूद होने चाहिए — जज भावार्थ स्वीकार करता है और खंडन अस्वीकार करता है।
- `routes` उस पेज (या पेजों) का नाम बताता है जिसे प्रश्न का उत्तर देना चाहिए। तब रिपोर्ट में विफलता उस पेज की स्रोत फ़ाइल से जोड़ दी जाती है; और जो संकेत अब किसी पेज से मेल नहीं खाता, उसके बारे में चुपचाप अनदेखा करने के बजाय चेतावनी दी जाती है।
- `severity: warning` किसी प्रश्न को CI विफल किए बिना रिपोर्ट में बनाए रखता है; `skip: true` किसी प्रश्न को पूरी तरह बाहर बैठा देता है।

ऐसे प्रश्न लिखें जो आपके उपयोगकर्ता वास्तव में पूछते हैं — सपोर्ट थ्रेड्स, GitHub इश्यूज़ और ऑनबोर्डिंग कॉल्स वाले प्रश्न। सर्वोत्तम मूल्यांकन आपके डॉक्स द्वारा किए गए किसी वादे ("शून्य-कॉन्फ़िग डिप्लॉय") को ऐसे प्रश्न के रूप में दर्ज करते हैं जो तब टूट जाता है जब कोई PR उस वादे को तोड़ता है।

## CI को विफल करना

एग्ज़िट कोड ही अनुबंध है: कोई भी विफल प्रश्न ग़ैर-शून्य एग्ज़िट देता है। जब आप किसी बैकलॉग से बाहर निकल रहे हों, तो `--threshold` इस द्वार को एक पासिंग अंश तक ढीला कर देता है:

```bash
blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout
```

JSON रिपोर्ट का वही `diagnostics` + `summary` आकार होता है जो `blume validate --json` और `blume audit --json` का है, साथ में प्रति-प्रश्न परिणाम (उत्तर, स्कोर, छूटे हुए तथ्य, लागत) भी होते हैं।

चूँकि हर प्रश्न दो मॉडल सत्र होता है, एक eval रन में असली पैसा और मिनट खर्च होते हैं — प्रति-प्रश्न खर्च चलते-चलते प्रिंट होता रहता है। एक समझदार CI सेटअप `blume eval` को हर पुश पर नहीं, बल्कि डॉक्स में बदलाव होने पर चलाता है।

## निष्कर्षों को ठीक करना

हर विफलता छूटे हुए तथ्यों और उस पेज का नाम बताती है जिसे उन्हें बताना चाहिए। इसके बजाय पूरी रिपोर्ट एजेंट को सौंपने के लिए:

```bash
blume eval --fix
```

यह पूरी JSON रिपोर्ट एक फ़ाइल में लिखता है और एजेंट को एक ऐसे प्रॉम्प्ट के साथ इंटरैक्टिव रूप से खोलता है जो उसे हर विफल प्रश्न से होकर ले जाता है: नामित पेज पढ़ो, छूटे हुए तथ्यों को पेज की अपनी शैली में जोड़ो, और तब तक `blume eval` दोबारा चलाओ जब तक सब कुछ पास न हो जाए। यह सत्र जान-बूझकर इंटरैक्टिव है — आप एजेंट के अपने अनुमति-प्रवाह के ज़रिए संपादनों की समीक्षा करते हैं — और एजेंट को कह दिया जाता है कि ग्रीन तक पहुँचने के लिए वह कभी भी प्रश्न न हटाए और न ही अपेक्षित तथ्यों को कमज़ोर करे।

## फ़्लैग्स

- `--agent claude|codex` — कौन-सा एजेंट CLI रीडर और जज चलाता है। डिफ़ॉल्ट `claude` है।
- `--file <path>` — evals फ़ाइल। डिफ़ॉल्ट `evals.yaml` है।
- `--threshold <0..1>` — रन के ग़ैर-शून्य एग्ज़िट देने से पहले न्यूनतम पासिंग अंश। डिफ़ॉल्ट `1` है।
- `--timeout <seconds>` — प्रति प्रश्न रीडर की समय-सीमा। डिफ़ॉल्ट `180` है।
- `--json` — रिपोर्ट को stdout पर JSON के रूप में देता है।
- `--fix` — विफल रन के बाद, डॉक्स को इंटरैक्टिव रूप से ठीक करने के लिए रिपोर्ट एजेंट को सौंप देता है।
- `--verbose` — हर विफलता के नीचे रीडर का पूरा उत्तर शामिल करता है।

---

# फ्रंटमैटर
Source: https://useblume.dev/hi/docs/reference/frontmatter

हर पृष्ठ निम्नलिखित फ्रंटमैटर स्वीकार करता है। सभी फ़ील्ड वैकल्पिक हैं।

| Prop | Type | Default | Description |
| - | - | - | - |
| `title?` | `string` | - | पृष्ठ का शीर्षक। |
| `description?` | `string` | - | पृष्ठ का सारांश। |
| `type?` | `string` | `doc` | सामग्री का प्रकार। blog/changelog फ़ीड्स को संचालित करते हैं। |
| `date?` | `string` | - | blog/changelog फ़ीड्स के लिए प्रकाशन तिथि (ISO या YAML तिथि)। |
| `authors?` | `string \| string[] \| object[]` | - | blog/changelog सामग्री के लिए पोस्ट के लेखक — एक नाम, या ऐसे ऑब्जेक्ट जिनमें नाम के साथ वैकल्पिक avatar/url और कोई भी अतिरिक्त फ़ील्ड हों। ज्यों का त्यों सुरक्षित रखा जाता है। |
| `slug?` | `string` | - | जनरेट किए गए slug को ओवरराइड करें। |
| `draft?` | `boolean` | `false` | प्रोडक्शन बिल्ड से बाहर रखें। |
| `lastModified?` | `string` | - | पृष्ठ की "अंतिम अपडेट" तिथि निश्चित करें (ISO या YAML तिथि); यह git से प्राप्त तिथि को ओवरराइड करती है। |

## साइडबार

```yaml lineNumbers
sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page
```

`display` पृष्ठ के फ़ोल्डर समूह का रेंडर मोड निर्धारित करती है ([प्रति-समूह ओवरराइड](/docs/content/navigation#per-group-overrides)) और यह केवल जनरेट किए गए साइडबार के अंतर्गत किसी फ़ोल्डर के `index` पृष्ठ पर ही सार्थक है — अन्यत्र कहीं भी (किसी गैर-index पृष्ठ पर, सामग्री रूट के अपने `index` पृष्ठ पर, या किसी स्पष्ट `navigation.sidebar` के अंतर्गत आने वाले किसी पृष्ठ पर) इसके पास कॉन्फ़िगर करने के लिए कोई समूह नहीं होता, और Blume `BLUME_SIDEBAR_DISPLAY_IGNORED` के साथ चेतावनी देता है।

## SEO

```yaml lineNumbers
seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
```

## खोज

```yaml lineNumbers
search:
  exclude: false
  tags: [api]
```

## चेंजलॉग

चेंजलॉग प्रविष्टियाँ (`type: changelog`) समृद्ध फ़ीड और डिस्प्ले मेटाडेटा के लिए एक वैकल्पिक `changelog` ऑब्जेक्ट स्वीकार करती हैं:

```yaml lineNumbers
type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features
```

`date` यहाँ रह सकती है या शीर्ष स्तर पर — दोनों ही [चेंजलॉग RSS फ़ीड](/docs/content#feeds) को संचालित करती हैं। जनरेट किए गए टाइमलाइन पृष्ठ और फ़ीड के लिए [चेंजलॉग](/docs/advanced/changelog) देखें।

## कस्टम कुंजियाँ

इस संदर्भ से बाहर की कोई भी कुंजी बिल्ड को विफल कर देती है, जिससे टाइपो जल्दी पकड़ में आ जाते हैं। जो प्रोजेक्ट अपना स्वयं का मेटाडेटा रखते हैं, वे `blume.config.ts` में [`frontmatter.extend`](/docs/configuration#frontmatter) के माध्यम से अतिरिक्त कुंजियाँ शामिल कर सकते हैं, जिनमें से प्रत्येक को प्रोजेक्ट द्वारा उपलब्ध कराए गए स्कीमा से मान्य किया जाता है:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

```yaml page.mdx
---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---
```

स्कीमा [Standard Schema](https://standardschema.dev) इंटरफ़ेस के ज़रिए स्वीकार किए जाते हैं, इसलिए Zod (आपका प्रोजेक्ट जो भी संस्करण इंस्टॉल करता है), Valibot, और ArkType सभी काम करते हैं। घोषित की गई हर कुंजी हर पृष्ठ पर मान्य की जाती है — अनुपस्थित कुंजियाँ भी शामिल — इसलिए एक आवश्यक स्कीमा उस कुंजी को पूरी साइट पर लागू करता है; इसे केवल वहीं मान्य करने के लिए जहाँ यह मौजूद है, इसे `.optional()` चिह्नित करें। अन्य सभी कुंजियाँ सख़्ती से मान्य की जाती रहती हैं, और अंतर्निहित फ़ील्ड्स को पुनः घोषित नहीं किया जा सकता।

### प्रति-प्रकार कुंजियाँ

कुंजियों को केवल एक सामग्री प्रकार पर आवश्यक बनाने के लिए — किसी RFC का `status`, किसी घटना रिपोर्ट का `severity` — उन्हें इसके बजाय [`content.types`](/docs/configuration#content) के अंतर्गत घोषित करें, जो उस फ्रंटमैटर `type` से कुंजीबद्ध हों जिस पर वे लागू होती हैं:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

```yaml rfcs/openapi-request-schemas.mdx
---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---
```

प्रति-प्रकार कुंजियाँ `extend` के समान ही मान्यता नियमों का पालन करती हैं, जो उन पृष्ठों तक सीमित होती हैं जिनका हल किया गया `type` मेल खाता है — उन पृष्ठों सहित जो कोई `type` निर्धारित नहीं करते, जब घोषणा [`content.defaultType`](/docs/configuration#content) के लिए हो। एक कुंजी किसी एक ही घोषणा से संबंधित होती है, साइट-व्यापी या प्रति-प्रकार, दोनों से नहीं। और जो कुंजी केवल किसी अन्य प्रकार के लिए घोषित की गई हो, वह अन्यत्र अज्ञात ही रहती है, इसलिए किसी सामान्य doc पृष्ठ पर भटका हुआ `status` अब भी बिल्ड को विफल कर देता है।

जो पृष्ठ मान्यता में विफल होता है, वह `blume build` को एक ऐसे डायग्नोस्टिक के साथ विफल कर देता है जो फ़ाइल और कुंजी का नाम बताता है। [`--no-strict`](/docs/reference/cli#common-flags) के साथ, बिल्ड फिर भी सफल होता है और विफल पृष्ठ आउटपुट से हटा दिए जाते हैं — बिल्ड सारांश बताता है कि कितने।

एडिटर और माइग्रेशन टूलिंग के लिए स्कीमा `blume/schema` से एक्सपोर्ट किए जाते हैं।

---

# अनुवाद
Source: https://useblume.dev/hi/docs/reference/translate

एक बार [i18n](/docs/content/i18n) चालू हो जाने पर, किसी स्रोत पेज में किया गया हर संपादन चुपचाप उसके अनुवादों को पुराना कर देता है। `blume translate` इस चक्र को पूरा करता है: यह ठीक-ठीक गणना करता है कि हर लोकेल में कौन-से पेज गायब या बासी हैं, उन्हें एक स्थानीय एजेंट CLI के ज़रिए हेडलेस तरीके से अनुवाद करता है, और जो किया उसे एक कमिट किए गए लेजर में दर्ज करता है ताकि अगला रन — और CI — जान सके कि क्या मौजूदा है।

```bash
blume translate --claude
```

```
blume translate  3 item(s) · 2 locale(s) · Claude Code

  ✔ docs/guides/install.mdx → fr 24.2s $0.11
  ✔ docs/guides/install.mdx → de 22.8s $0.10
  ✔ meta titles (2) → de 4.1s $0.01

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
```

## यह कैसे काम करता है

पाइपलाइन Blume के अधीन है; एजेंट सिर्फ़ टेक्स्ट का अनुवाद करता है। जिस भी फ़ाइल पर काम ज़रूरी है, उसके लिए Blume एक अनुवाद प्रॉम्प्ट बनाता है, एजेंट CLI को उसके फ़ाइल, शेल और वेब टूल्स बंद करके हेडलेस चलाता है, उत्तर की संरचना को मान्य करता है, और लक्ष्य फ़ाइल खुद लिखता है — `--claude` के साथ [Claude Code](https://claude.com/claude-code), या `--codex` के साथ [Codex](https://developers.openai.com/codex/cli)। Blume के पास कोई API कुंजी नहीं होती और वह खुद किसी मॉडल को कॉल नहीं करता।

हर मान्य लेखन प्रोजेक्ट रूट में `blume.translations.json` में दर्ज होता है: हर स्रोत फ़ाइल और लोकेल के लिए, अनुवाद के समय स्रोत का एक हैश। **इस फ़ाइल को कमिट करें।** इसी से दोबारा चलाने पर "पहले से अनुवादित" और "अनुवादित, लेकिन उसके बाद स्रोत बदल गया" के बीच का अंतर पता चलता है — और यही CI गेट को संभव बनाता है।

लेजर हर पूरी हुई फ़ाइल के बाद फ़्लश किया जाता है, इसलिए किसी लंबे रन को रोकने (Ctrl+C) पर ज़्यादा से ज़्यादा वही अनुवाद खोते हैं जो चल रहे थे — अगला रन वहीं से उठा लेता है जहाँ आपने छोड़ा था। डिफ़ॉल्ट रूप से एक साथ 4 फ़ाइलें चलती हैं; अगर आपकी मशीन और एजेंट की रेट लिमिट अनुमति दें तो `--concurrency` से इसे बढ़ाएँ।

दोबारा चलाना इंक्रीमेंटल होता है: जो स्रोत अपने पिछले अनुवाद के बाद से नहीं बदला, उसे छोड़ दिया जाता है, इसलिए एक पेज संपादित करने के बाद `blume translate` चलाने पर हर लोकेल के लिए एक ही पेज का अनुवाद होता है। जब किसी बासी पेज का दोबारा अनुवाद होता है, तो एजेंट को मौजूदा अनुवाद दिखाया जाता है और उसके रजिस्टर, बोली और शब्दावली से मेल खाने को कहा जाता है — स्रोत में एक अनुच्छेद का संपादन अनुवाद में एक अनुच्छेद का ही अंतर पैदा करता है, शुरुआत से पुनर्लेखन नहीं।

पहले अनुवाद के पास मेल खाने के लिए कोई पूर्व उदाहरण नहीं होता, इसलिए यह चुनाव पहले ही [लोकेल पर `style`](/docs/content/i18n) से तय कर दें (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`)। यह मार्गदर्शन हर अनुवाद प्रॉम्प्ट के साथ जाता है, और जहाँ कोई मौजूदा अनुवाद इससे असहमत हो, वहाँ `style` की ही चलती है — इसलिए दोबारा अनुवाद पुराने पेजों को भी कॉन्फ़िगर की गई शैली की ओर ले जाता है।

## क्या अनुवादित होता है

- **पेज** — डिफ़ॉल्ट लोकेल की `.md`/`.mdx` फ़ाइलें। एजेंट गद्य और केवल मनुष्य को दिखने वाले फ्रंटमैटर मानों (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`) का अनुवाद करता है। लक्ष्य आपके पार्सर के अनुसार होते हैं: `dir` के तहत `fr/guides/install.mdx`, `dot` के तहत `guides/install.fr.mdx`।
- **फ़ोल्डर नेविगेशन शीर्षक** — `dir` पार्सर के तहत, हर लोकेल के लिए आवश्यक [`meta.ts`](/docs/content/meta) शीर्षक एक ही बैच कॉल में अनुवादित होते हैं, और उत्पन्न प्रति-लोकेल `meta.ts` बाकी हर कुंजी (`order`, `pages`, `icon`, `collapsed`) को हूबहू कॉपी करता है ताकि उस लोकेल का साइडबार अपना क्रम बनाए रखे।

आपके हाथ से लिखे अनुवाद **अपनाए जाते हैं, कभी अधिलेखित नहीं होते**: जो अनुवाद मौजूद है पर जिसकी कोई लेजर प्रविष्टि नहीं है, उसे मौजूदा के रूप में चिह्नित कर छोड़ दिया जाता है। केवल `--force` उसका दोबारा अनुवाद करता है।

## मान्यता जाँच

संरचना के लिए एजेंट पर कभी भरोसा नहीं किया जाता। लिखने से पहले, Blume हर उत्तर की जाँच करता है और फ़ाइल को स्रोत से फिर से बनाता है:

- फ्रंटमैटर स्रोत फ़ाइल के डेटा से पुनर्निर्मित होता है, जिसमें केवल छह अनुवाद-योग्य मान ऊपर से लगाए जाते हैं — एजेंट द्वारा गढ़ी गई कुंजियाँ हटा दी जाती हैं, हटाई गई कुंजियाँ बहाल कर दी जाती हैं, और `slug`, `icon`, `order` तथा तिथियाँ रचना के स्तर पर ही स्रोत के अनुरूप हूबहू रहती हैं।
- कोड फ़ेंस की संख्या स्रोत से मेल खानी चाहिए, बॉडी खाली नहीं होनी चाहिए, और फ्रंटमैटर पार्स होना चाहिए।

जो उत्तर मान्यता जाँच में विफल होता है वह कुछ नहीं लिखता — उस आइटम को विफल बताया जाता है और रन आगे बढ़ जाता है। जो कुछ भी सफल हुआ वह लेजर में चिह्नित रहता है, इसलिए दोबारा चलाने पर केवल विफलताओं का ही पुनः प्रयास होता है।

## CI को फेल कराना

`blume translate --check` केवल-पढ़ने वाला गेट है: यह हर गायब और बासी जोड़ी की रिपोर्ट देता है और अंतर होने पर नॉन-ज़ीरो के साथ बाहर निकलता है, बिना कोई एजेंट चलाए या कुछ लिखे।

```bash
blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

JSON रिपोर्ट में वही `diagnostics` + `summary` आकार होता है जो `blume validate --json`, `blume audit --json`, और `blume eval --json` में है, जिसमें अंतर प्रति लोकेल समूहीकृत होता है। हाथ से लिखे (अनट्रैक किए गए) अनुवाद गेट को कभी विफल नहीं करते।

## सीमाएँ

- मेटा शीर्षक अनुवाद केवल `dir` पार्सर के लिए है — `dot` पार्सर में प्रति-लोकेल `meta.ts` की कोई व्यवस्था नहीं है। जो `meta.ts` डिफ़ॉल्ट रूप से किसी फ़ंक्शन को एक्सपोर्ट करता है उसे चेतावनी के साथ छोड़ दिया जाता है; उस लोकेल की प्रति हाथ से लिखें।
- रिमोट और CMS-आधारित स्रोत छोड़ दिए जाते हैं: अनुवाद लिखने के लिए कोई स्थानीय फ़ाइल ही नहीं होती।
- हेडर टैब लेबल कंटेंट में नहीं, `blume.config.ts` में रहते हैं — उन्हें वहीं [प्रति-लोकेल लेबल मैप](/docs/content/navigation#tabs) से स्थानीयकृत करें।
- अनुवाद की गुणवत्ता एजेंट की है। आउटपुट की समीक्षा किसी भी अन्य योगदान की तरह करें — लेजर केवल ताज़गी की गारंटी देता है, प्रवाह की नहीं।

## फ़्लैग

- `--claude` / `--codex` — कौन-सा एजेंट CLI अनुवाद करता है। ठीक एक ज़रूरी है (`--check` के साथ छोड़कर)।
- `--check` — अंतर की रिपोर्ट दें और नॉन-ज़ीरो के साथ बाहर निकलें, बिना कुछ लिखे।
- `--concurrency <n>` — समानांतर एजेंट सत्र। डिफ़ॉल्ट `4`, अधिकतम `16`।
- `--locale <codes>` — कॉमा से अलग किए गए लक्ष्य लोकेल (डिफ़ॉल्ट रूप से हर गैर-डिफ़ॉल्ट लोकेल)।
- `--force` — सब कुछ दोबारा अनुवाद करें, अद्यतन और हाथ से लिखी फ़ाइलों सहित।
- `--timeout <seconds>` — प्रति फ़ाइल एजेंट समय सीमा। डिफ़ॉल्ट `600`; यह सीमा अटके हुए एजेंट पकड़ने के लिए है, इसलिए बड़े पेजों को पूरा होने की गुंजाइश मिलती है।
- `--json` — दोनों मोड में रिपोर्ट को stdout पर JSON के रूप में दें।

---

# はじめに
Source: https://useblume.dev/ja/docs

Markdown または MDX をフォルダに置いて `blume dev` を実行すれば、本番品質のドキュメントサイトが手に入ります。ナビゲーション、検索、テーマ設定、Open Graph 画像、充実したコンポーネントライブラリまで揃い、アプリのボイラープレートを書いたり保守したりする必要はありません。

**[クイックスタート](/docs/quickstart)**

Blume をインストールして、数分で最初のページを公開しましょう。

**[設定](/docs/configuration)**

タイトル、テーマ、検索、デプロイを調整しましょう。

## Blume が存在する理由

ドキュメントは高速で、AI に対応し、ゼロコンフィグであるべきです。スターターテンプレートすら不要なほどに。ドキュメントツールの中には、一文字も書かないうちに保守すべきコードベース一式を渡してくるものがあります。一方、コンテンツに合わせてテンプレートを構築してくれるものもありますが、その場合はマネージドサービスに縛られてしまいます。

Blume は両者の良いところを取り入れています。フレームワーク自体がテンプレートなので、あなたが触れるのはコンテンツだけです。カスタマイズしたくなったら、組み込みコンポーネントを差し替えたり、単一の設定ファイルを変更したり、Astro サイトを直接扱いたければ eject することもできます。[FAQ](/docs/faq) では、Mintlify や Fumadocs などとの比較を詳しく説明しています。

## Blume の違い

### デフォルトで高速

Blume は Astro と Vite の上に構築され、デフォルトで静的 HTML をレンダリングします。高速で、キャッシュしやすく、ホスティングも安価です。コアテーマはクライアントフレームワークの JS を一切出力しないため、ページは最初から Core Web Vitals で高いスコアを記録します。開発サーバーの起動とホットリロードは Vite ネイティブの快適さで、サーバー機能は必要になったときだけオプトインできます。

### すぐに使える AI 対応

すべての Blume サイトは機械にも流暢に語りかけます。[`llms.txt` と `llms-full.txt`](/docs/configuration/ai) を出力し、URL に `.md` を付けるだけで任意のページの生の Markdown を提供し、[OpenAPI で記述された JSON API](/docs/configuration/ai#json-api) を公開し、すべてのページで **Copy as Markdown** と **Open in chat** のアクションを読者に提供します。オプションのページ内 **Ask AI** アシスタントを追加したり、[**MCP サーバー**](/docs/configuration/ai#mcp-server) をホストすれば、Claude Code や Cursor などのコーディングエージェントがドキュメントを直接検索して読み取れます。スクレイピングも、ホスト型サービスも不要です。あなたの Markdown が、人間にとってもモデルにとっても信頼できる唯一の情報源になります。

### ゼロコンフィグ — テンプレートさえも

ドキュメントの入ったフォルダが、そのまま完全なプロジェクトです。クローンすべきスターターも、セットアップすべき Astro や Tailwind も、保守すべきテンプレートもありません。ナビゲーションはファイルから推論され、[検索](/docs/configuration/search)はホスト型サービスなしで開発環境でも本番環境でも動作し、テーマ設定はわずかなトークンで済みます。すべてに適切なデフォルトがあります。設定は最初に取り組むものではなく、必要になったときに手を伸ばすものです。

### 芯まで型安全

あなたの [`blume.config.ts`](/docs/configuration) とすべての [`meta.ts`](/docs/content/meta) は本物の TypeScript です。スキーマによって検証され、`defineConfig` と `defineMeta` を使って記述します。エディタはすべてのオプションを補完し、タイプミス、不正な値、欠けているフィールドを、ビルドのはるか前、入力中に検出します。設定は、緩い型付けの YAML ではなく、リファクタリングでき、計算でき、信頼できるコードです。

## すべて同梱

- **コンポーネント** — コールアウト、カード、ステップ、タブ、アコーディオン、バッジ、ファイルツリー、パラメータテーブルが、MDX で[インポート不要](/docs/content/components)で使えます。
- **ローカル検索** — Orama が開発環境でも本番環境でも動作します。大規模サイト向けには Pagefind がフラグ 1 つで利用できます。ホスト型インデックスは不要です。
- **AI** — [`llms.txt`、生の Markdown URL、OpenAPI 記述付きの JSON API、Copy as Markdown、Open in chat、Ask AI アシスタント、ホスト型 MCP サーバー](/docs/configuration/ai)。
- **ナビゲーション** — ファイルから推論され、`meta.ts` や設定で調整できます。
- **SEO** — メタデータ、Open Graph 画像、RSS フィード、JSON-LD を[標準搭載](/docs/configuration/seo)。
- **カスタマイズ** — コンポーネントのオーバーライド、React アイランド、カスタムページ、テーマトークン、そして `blume add` によるソースコンポーネントレジストリ。
- **Eject** — `blume eject` は、`blume` パッケージを引き続き利用するスタンドアロンの Astro プロジェクトを生成します。

## 仕組み

Blume CLI はコンテンツを検出し、コンテンツグラフを構築して、`.blume/` 配下に隠し Astro プロジェクトを生成し、それを開発とビルドで駆動します。生成されたランタイムは実装の詳細です。あなたは Markdown を書き、残りは Blume が処理します。eject して自分のものにすると決めるまでは。

## 次のステップ

**[設定](/docs/configuration)**

タイトル、テーマ、検索、デプロイを調整しましょう。

**[コンポーネント](/docs/content/components)**

組み込みのコンポーネントライブラリを見てみましょう。

**[AI](/docs/configuration/ai)**

`llms.txt` と Ask AI アシスタントを提供しましょう。

**[CLI](/docs/reference/cli)**

すべての `blume` コマンドとフラグ。

---

# OpenAPI / AsyncAPI
Source: https://useblume.dev/ja/docs/advanced/api-reference

Blume に OpenAPI 仕様を指定すると、ネイティブな API リファレンスを生成します。**操作ごとに 1 つの実ページ**が作られ、タブスコープのサイドバーでタグごとにグループ化され、スキーマの表、リクエスト/レスポンスの例、生成されたコードサンプル、そしてインタラクティブな [Try it](#try-it-プレイグラウンド) パネルが付きます。各操作は正真正銘の Blume ページなので、独自の URL を持ち、**サイト検索**や `llms.txt` に現れ、Open Graph 画像も生成されます — 手書きのドキュメントとまったく同じです。以下の設定では、例として公開されている Petstore 仕様を Blume に指定しています。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}
```

これでリファレンスが `/reference`（概要ページ）にマウントされ、各操作は `/reference/<tag>/<operation>` に配置されます。`spec` は `http(s)` の URL か、プロジェクト内のローカルファイルへのパスのいずれかです。Blume は [Scalar の OpenAPI パーサー](https://github.com/scalar/scalar)で解析します — Swagger 2.0 および OpenAPI 3.0 の仕様は自動的に 3.1 へアップグレードされます。代わりに GraphQL API をドキュメント化しますか？ [GraphQL リファレンス](/docs/advanced/graphql)をご覧ください。

リファレンスはそれ自体ではヘッダータブを追加しません。表に出すには、[ナビゲーションタブ](/docs/content/navigation#tabs)をそのルートに向けてください — これによりネイティブレンダラーの操作サイドバーのスコープも設定されます。

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
操作は**サマリーとタグ**によって検索用にインデックスされます。レンダリングされたスキーマの表やコードサンプルは全文インデックスされません。検索は操作のタイトルとセクションにマッチし、その操作自身のページへリンクします。
:::

## ローカルの仕様

相対パスはプロジェクトルートを基点に解決され、ビルド時に読み込まれます。JSON と YAML のどちらも利用できます。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}
```

## ルート

`route` はリファレンスのマウント先を制御します — 概要ページと、すべての操作ルートのプレフィックス（およびナビゲーションタブを向ける先のルート）です。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}
```

## コードサンプルとスキーマ

`codeSamples` は操作ごとにどの言語をレンダリングするかを選びます（組み込み: `curl`、`js`、`python`）。`expandSchemas` はネストしたスキーマの行を折りたたまずに展開した状態で開始します。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}
```

## Try it プレイグラウンド

ネイティブにレンダリングされた操作ページには、デフォルトでインタラクティブな **Try it** パネルが付属します。Blume は操作そのものからフォームを生成します。パス、クエリ、ヘッダーの各パラメーターごとの入力欄、リクエストボディのスキーマから構築されたボディエディター、そしてそのすべてが仕様の例で事前入力されます。サーバーピッカーには仕様の `servers` が一覧表示され、それ以外のベース URL 用に自由入力欄も用意されています。認証の入力欄は操作の[解決されたセキュリティ](#認可)に一致します — ベアラートークン、API キー、ベーシック資格情報、そして OAuth2 はトークンの貼り付け欄として提供されます（アクセストークンはご自身でご用意ください。Blume はフローを実行しません）。

パネルとコードサンプルは常に同期します。フォームに入力した値は生成されるサンプルにリアルタイムで反映されるため、コピーした curl コマンドは **Send** の動作と常に完全に一致します。しかも邪魔になりません。パネルは折りたたまれた状態でサーバーレンダリングされ、その JavaScript は読者が最初に開いたときにのみ読み込まれます。一度も触れない読者は、そのいずれもダウンロードしません。

`playground: false` がオフスイッチのすべてです。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}
```

### 資格情報

認証の入力欄に入力された資格情報はメモリー上に留まり、再読み込みで消えます。**Remember on this device** をチェックすると、ドキュメントのオリジンにスコープされた `localStorage` に保存されます — 呼び出し対象の API 以外へ送信されることは決してありません。読者が **Include my values in samples** を切り替えない限り、コードサンプルには何を入力してもプレースホルダー（`YOUR_TOKEN` など）が表示され続けます。

### CORS とプロキシ

[Scalar レンダラー](#scalar-レンダラー)と同様に、リクエストは**ブラウザーから直接**対象の API へ送られるため、API はドキュメントサイトからのクロスオリジンリクエストを許可する必要があります（`Access-Control-Allow-Origin`）。それができない API には `playground.proxy` を設定してください。URL を指定すると自前でホストしたプロキシ経由でリクエストが送られ、`true` にすると組み込みの `/_api-proxy` ルートが有効になります — これはサーバービルドを必要とするため、[`deployment.output: "server"`](/docs/deployment#server-rendering) が必要です。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}
```

組み込みプロキシは、仕様が `servers` で宣言したオリジンにのみリクエストを転送します — リダイレクトをまたいだ場合も同様です — そのため、公開されたドキュメントのデプロイメントをネットワーク上の他のホストへ向けることはできません。パネルに入力された **Custom base URL** はドキュメント化されたサーバーではありません。プロキシを有効にしている場合、そこへのリクエストは 403 で拒否されます。

## 複数の仕様

複数の仕様を公開するには `sources` を使います。各ソースは独自の概要ルート、操作ページ、ヘッダータブを持ちます。それぞれに `label`（タブに使われ、ルートの導出にも使われます）を与えるか、明示的に `route` を設定してください。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}
```

`spec` はエントリが 1 つだけの `sources` の短縮形なので、`sources` を使うのは仕様が複数ある場合だけです。

### ソースごとのインデックス

生成されたページは、デフォルトで検索、`llms.txt`、クローラーのインデックスの対象になります。副次的な仕様や内容が重複する仕様は、ページを非表示にしたりナビゲーションから外したりすることなく、任意の対象から除外できます。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}
```

- `includeInSearch: false` は、そのソースの概要と操作をサイト検索から除外します。
- `includeInLlms: false` は、両方の `llms.txt` ファイルから除外します。
- `noindex: true` は、クローラー向けの noindex メタデータを追加し、サイトマップからページを削除します。

各操作ページのメタディスクリプションは、その操作自身の `description`（または `summary`）に続けて、エンドポイント名を挙げる生成された一文 — 「Reference for the `GET /pets` endpoint in the Petstore API.」 — が付いたものです。そのため、簡潔な一行のサマリーしかない仕様でも、ページごとに固有でスニペットに適した長さの説明文が出力されます。この一文は英語です。仕様の文章が英語以外で書かれているサイトでは、ソースに `seoDescriptionSuffix: false` を設定してこれを削除し、執筆された文章だけで各ページを説明してください。`description` も `summary` も持たない操作はタイトル（`GET /pets`）にフォールバックするため、説明文が空のページが出力されることはありません。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}
```

[Scalar レンダラー](#scalar-レンダラー)では `noindex` のみが適用されます — Scalar でレンダリングされたリファレンスはもともと Blume の検索や `llms.txt` の外側にあるため、2 つの `include*` 設定はそこでは作用する対象がありません。

## 認可

[セキュリティ要件](https://spec.openapis.org/oas/v3.1.0#security-requirement-object)を宣言している操作は、パラメーターの上に**認可**セクションをレンダリングし、生成されたコードサンプルはプレースホルダーの資格情報（`Authorization: Bearer YOUR_TOKEN`、API キーヘッダー、クエリキーなど、スキームが要求するもの）を送信します。設定は不要です。Blume は仕様から `security` を読み取るため、リファレンスは常に API が実際に強制している内容と一致します。

OpenAPI のセマンティクスはそのまま引き継がれます。

- 操作自身の `security` はドキュメントのルートのデフォルトを上書きします。`security: []` はその操作を**パブリック**として示し、認可セクションはレンダリングされません。
- 複数の要件エントリは選択肢を表し、「or」グループとしてレンダリングされます。1 つのエントリ内のすべてのスキームはまとめて必須です。最初の選択肢がコードサンプルに使われます。
- 空の `{}` エントリは、その操作で認証が**任意**であることを意味し、セクションにもそのように表示されます。
- OAuth2 のスコープはスキームごとに一覧表示され、`components.securitySchemes` のスキームの `description` はインラインでレンダリングされます。

## Scalar レンダラー

ネイティブレンダラーがデフォルトです — 上で説明した操作ページ、検索の統合、[Try it プレイグラウンド](#try-it-プレイグラウンド)は、すべてこのレンダラーによるものです。[Scalar](https://scalar.com) の自己完結型 API リファレンス UI — 独自のサイドバー、検索、テーマ、そして単一ルート上のリクエストクライアント — を埋め込みたい場合は、`renderer: "scalar"` を設定してください。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}
```

Scalar でレンダリングされたリファレンスは、独自のルート上にある自己完結型の埋め込みです — Blume のサイドバー、検索、`llms.txt` には組み込まれず、Blume の [`playground`](#try-it-プレイグラウンド) 設定も適用されません。ただし Blume のライト/ダークの切り替えには従います。埋め込みはマウント時にページのテーマに固定され、それに合わせて切り替わるため、Scalar 自身のテーマ切り替えは非表示になります（カラーモードを Scalar 側に戻すには `scalar.forceDarkModeState` または `scalar.darkMode` を設定してください）。Scalar は独自のリクエストクライアントを備えており、**ブラウザーから対象の API を直接**呼び出す（`playground.proxy` のルートはここでは利用できません）ため、API はドキュメントサイトからのクロスオリジンリクエストを許可する必要があります（`Access-Control-Allow-Origin`）。`theme` は Scalar レンダラーにのみ適用されます。

### Scalar のオプションを渡す

`theme` は最も多くの人が使うオプション 1 つの短縮形ですが、Scalar はさらに多くのオプションをサポートしています。`scalar` オブジェクトは、任意の [Scalar 設定](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)を埋め込みリファレンスへそのまま転送します — Blume はキーを制限しないため、Scalar が受け付けるものはすべて通過します。

```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 自身の [`i18n`](/docs/content/i18n) はドキュメントの外装を翻訳しますが、Scalar には別のローカライズ機構があります — 埋め込みリファレンスも翻訳するには `scalar.localization.locale` を設定してください。`scalar` オブジェクト内のオプションは Blume が導出した設定より優先されるため、ここで設定したもの（`theme`、`customCss`、仕様の `content`/`url` を含む）は Blume のデフォルトを上書きします。同じ `scalar` ブロックは `asyncapi` リファレンスでも機能します。

## AsyncAPI

イベント駆動 API は、同じ形をした兄弟の `asyncapi` ブロックを使います — そして同じネイティブレンダラーを使います。各 `send`/`receive` 操作は、メッセージペイロードとヘッダースキーマの表、チャネルパラメーター、プロトコルバインディング、仕様の `securitySchemes` から導出された認可セクション（サーバーレベルと操作レベルの両方、選択肢は「or」グループとして表示）、そして [Try it](#イベント向けの-try-it) メッセージコンポーザーを備えた実ページになります。異なるのはデフォルトのルートだけです（`/events`）:

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}
```

AsyncAPI **2.x の仕様は、公式の AsyncAPI コンバーターによって自動的に 3.x へ正規化されます**。そのため `publish`/`subscribe` チャネルは、安定した URL を持つ `send`/`receive` の操作ページにマッピングされます — 後から仕様ファイル自体をコンバーターでアップグレードしても、何も移動しません。操作はタグごとにグループ化され、タグのない操作はチャネルアドレスの下にグループ化されます。

コードサンプルは**プロトコル対応**で、操作のバインディング（またはそのサーバーのプロトコル）に基づいて選ばれます。WebSocket には `wscat` とブラウザーの `WebSocket` スニペット、Kafka には `kcat`、MQTT には `mosquitto_pub`/`mosquitto_sub` です。`codeSamples` は、`openapi` ブロックで言語を選ぶのと同じ方法でそのセットを絞り込みます。サポートされているツールがないプロトコルでは、でっち上げのクライアントを生成する代わりに、メッセージペイロードの例のみをレンダリングします。

上で説明した内容はすべてそのまま引き継がれます。[`playground`](#イベント向けの-try-it) も含めて: `route`、`label`/`route` 付きの `sources`、`expandSchemas`、[ソースごとのインデックス](#ソースごとのインデックス)のフラグ（`seoDescriptionSuffix` も含みます — 生成される一文はエンドポイントではなくチャネルとアクションを挙げます）、そして操作のサマリーとタグによる検索インデックスです。

`renderer: "scalar"` を設定すると埋め込みの Scalar SPA に戻れます。そこでは、OpenAPI と同様に `noindex` のみが適用されます。Scalar には独自の AsyncAPI プレイグラウンドはありません。その埋め込みはドキュメントタイプを自動検出し、チャネル、操作、メッセージ、Models セクションをレンダリングするため、この切り替えではコンポーザーを手放すことになります。

### イベント向けの Try it

ネイティブにレンダリングされた操作ページには、ここでも **Try it** パネルが付属し、[OpenAPI のパネル](#try-it-プレイグラウンド)と同じ条件が適用されます。折りたたまれた状態でサーバーレンダリングされ、その JavaScript は読者が最初に開いたときにのみ読み込まれます。

プロトコルが何であれ、パネルはメッセージの `examples` から事前入力されたペイロードエディターとともに開きます — メッセージが例を宣言していない場合は、ペイロードスキーマからサンプリングされた値が使われます — 入力中はメッセージペイロードのスキーマに対して検証されます。その下には、チャネルパラメーターごとの入力欄と、チャネルの `servers` を元にしたサーバーピッカーがあり、それ以外の URL 用に自由入力欄も用意されています。プロトコル対応のコードサンプルは、HTTP 操作における curl、js、python とまったく同じようにフォームと同期し続けます。チャネルアドレスのテンプレートには入力したパラメーターの値が埋め込まれるため、コピーした `wscat`、`WebSocket`、`kcat`、`mosquitto_pub` のスニペットはフォームの内容に一致します。

ライブ接続は WebSocket 専用です。`ws` または `wss` のバインディングでは、パネルは解決されたチャネル URL へ接続し、接続状態を表示し、すべてのフレームをタイムスタンプ付きでログに記録します。AsyncAPI 3 はアクションを API 側の視点で表現しており、パネルもそれに従います。`receive` 操作は API があなたから受け取る操作なので、作成したペイロードを送信する **Send** ボタンが付きます。`send` 操作はあなたに向けてメッセージをストリーミングするだけなので、接続してログに記録します。再接続のロジックはありません — ソケットが一度閉じると、再度接続するまで閉じたままです。Kafka、MQTT、AMQP、その他すべてのプロトコルではコンポーザーとコピー可能な CLI サンプルが提供され、パネルにもページ上でその旨が表示されます。Blume はブラウザーのタブからブローカーへの接続を偽装したりはしません。

`asyncapi.playground` は `openapi.playground` と対になっています — ネイティブレンダラーではデフォルトで有効で、`false` がオフスイッチのすべてです。

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}
```

:::note
`playground.proxy` はイベント操作には適用されません。これは HTTP リクエストを転送するものであり、WebSocket の接続はブラウザーから URL に指定されたサーバーへ直接向かうため、プロキシが前段に入る対象がありません。
:::

イベントのコンポーザーはブローカーの資格情報を一切収集しません。各操作ページの**認可**セクションはブローカーが要求する内容を説明し、WebSocket の接続は URL にすでに含まれているものだけを伝えます。イベント操作では何も永続化されません。

---

# ブログ
Source: https://useblume.dev/ja/docs/advanced/blog

Blume におけるブログとは、型を持ったコンテンツにすぎません。ページに `type: blog` を指定すれば、Blume が RSS フィードとより充実した記事メタデータを自動的に付与します。[チェンジログ](/docs/advanced/changelog)とは異なり、インデックスページは生成されません。ランディングページは自分で組み立てるため、デザインを完全に手中に収められます。

## 投稿を書く

投稿とは、フロントマターに `type: blog` を指定した通常の `.md` または `.mdx` ページです。慣例として投稿は `blog/` 配下に置かれますが、重要なのはフォルダではなく型です。

```mdx blog/introducing-blume.mdx lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
```

すべての投稿に `date` を指定してください。フィードの項目が新しい順に並び、`pubDate` が付与されます。また `description` も指定してください。フィードの概要と SEO の両方に使われます。

## RSS フィード

Blume は **`/blog/rss.xml`** にブログフィードを生成し、`date` の新しい順に並べます。フィードには絶対サイト URL が必要なので、[`deployment.site`](/docs/deployment) を設定してください。設定すると、Blume がすべてのページに `<link rel="alternate">` タグを挿入し、リーダーが自動的にフィードを検出できるようになります。

フィードはデフォルトで有効です。[`seo.rss`](/docs/configuration/seo#rss-feeds) で調整できます。

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

フィードを生成したくない場合は、`rss.types` から `"blog"` を削除してください。

## 構造化データ

[構造化データ](/docs/configuration/seo#structured-data)が有効な場合、各投稿は説明文と公開日を伴う schema.org の **`BlogPosting`** として出力されます。これは検索エンジンがブログコンテンツに期待する、より充実した記事型です。

## インデックスページを構築する

Blume は `/blog` のランディングページを生成しないため、自分で構築します。最も簡単な方法は、各投稿へのリンクを手動で記述したコンテンツページです。

```mdx blog/index.mdx lineNumbers
---
title: Blog
description: News and writing from the team.
---

<CardGroup cols={2}>
  <Card title="Introducing Blume" href="/blog/introducing-blume">
    Why we built a markdown-first docs framework.
  </Card>
</CardGroup>
```

代わりに投稿を自動的に一覧表示するには、`pages/blog/index.astro` に[カスタムページ](/docs/advanced/custom-pages)を追加し、Astro の `docs` コンテンツコレクションから読み込んで、各エントリを `blume:data` のルートと組み合わせます。

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    date: entry.data.date,
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }))
  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

これをサイト全体のレイアウトでラップする方法については、[カスタムページ](/docs/advanced/custom-pages#using-the-site-layout)を参照してください。

**[カスタムページ](/docs/advanced/custom-pages)**

ブログインデックスをマウントし、blume:data から読み込みます。

**[SEO](/docs/configuration/seo)**

フィード、Open Graph 画像、構造化データ。

---

# 変更履歴
Source: https://useblume.dev/ja/docs/advanced/changelog

Blume には変更履歴が標準で用意されています。各リリースを通常のコンテンツファイルとして書き、`type: changelog` を指定するだけで、Blume がすべてのエントリを収集して生成されたタイムラインページと RSS フィードにまとめます — レイアウトを構築する必要も、リストを管理する必要もありません。あるいはファイルを一切用意せず、[GitHub Releases から変更履歴を取得](#from-github-releases)することもできます。

## エントリを書く

変更履歴のエントリは、フロントマターに `type: changelog` を持つ通常の `.md` または `.mdx` ページです。慣例として `changelog/` 配下に配置しますが、重要なのはフォルダではなく型です:

```mdx changelog/v1-2-0.mdx lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks
```

タイムラインとフィードが新しい順に並ぶよう、すべてのエントリに `date` を指定してください。クォートなしの YAML 日付でも問題ありません — Blume が正規化します。

### `changelog` オブジェクト

任意の `changelog` オブジェクトは、タイムラインとフィードにより豊富なメタデータを追加します:

| Prop | Type | Default | Description |
| - | - | - | - |
| `changelog.version?` | `string` | - | リリースバージョン。タイトルがない場合は v 接頭辞付きのラベルにフォールバックします。 |
| `changelog.category?` | `string` | - | エントリの横にタグとして表示されます。例: Release、Features、Fixes。 |
| `changelog.date?` | `string` | - | 公開日。ここに置いてもトップレベルに置いても構いません — どちらもタイムラインと RSS フィードに反映されます。 |

## タイムラインページ

`type: changelog` のエントリが 1 つでもあれば、Blume は **`/changelog`** ページを自動的に生成します。サイドバーや目次のない、集中しやすい全幅のタイムラインとしてレンダリングされ、各エントリは新しい順に並び、コンテンツの横の左レールに日付、ラベル、`category` タグが表示されます:

- エントリの**タイトル**がそのラベルになります — タイトルがない場合は `v{version}` です。そのエントリ自身のページへリンクするため、リリースはタイムライン上の 1 行であると同時に共有可能なパーマリンクにもなります。
- `category` は日付の隣にタグとしてレンダリングされます。
- 下書きと `sidebar.hidden` のエントリはスキップされます。

このページは `/changelog` ルートが他に占有されていない場合にのみ表示されます。独自のデザインに置き換えるには、`pages/changelog.astro` に[カスタムページ](/docs/advanced/custom-pages)を追加してください — それが優先され、Blume はデフォルトのタイムラインの生成を停止します。

このページは執筆されたものではなく生成されたものであるため、コンテンツツリーの一部ではありません — したがって `/changelog` を指すヘッダーの[タブ](/docs/content/navigation#tabs)は、代わりに最新のエントリに解決されます。インデックス自体に遷移させるには、タブに `href` を指定してください:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

### メジャーバージョンごとのグループ化

バージョンが [semver](https://semver.org) に従っていて複数のメジャーにまたがる場合、Blume はタイムラインをメジャーバージョンごとにページ分割します。最新のメジャー系列のみが表示され、下部の **Show N.x releases** ボタンで、1 クリックごとに次に古いメジャーが表示されます:

- 検出は自動です — 設定は不要です。リストされたすべてのリリースが `major.minor.patch` としてパースでき、かつメジャーが複数ある場合にのみ有効になります。それ以外の場合、タイムラインはフラットのままです。
- モノレポが公開するスコープ付きタグにも対応しているため、`pkg@2.0.0` は `2.x` に、`pkg@1.4.0` は `1.x` にグループ化されます。
- これはプログレッシブエンハンスメントです: すべてのリリースはページの HTML(および RSS フィードと検索インデックス)に含まれたままなので、JavaScript のない読者 — およびクローラー — は完全な履歴を見ることができます。ボタンは、ページがハイドレートされた後にのみ古いメジャーを折りたたみます。

## GitHub Releases から

エントリを手作業で書く代わりに、組み込みの [`github-releases` ソース](/docs/content/sources#github-releases)をリポジトリに向ければ、すべてのリリースが `type: changelog` エントリになります — 同じタイムラインとフィードが、すでに公開しているリリースから直接供給されます。Blume 自身の[変更履歴](/changelog)もこの方法で構築されています:

```ts blume.config.ts
content: {
  sources: [
    { type: "filesystem", root: "content" },
    {
      type: "github-releases",
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    },
  ],
}
```

リリース名がタイトルになり、そのタグが `changelog.version` になり、公開日でタイムラインがソートされます。各リリースページには、そのノートから要約された固有のメタディスクリプションも付与されます — マークダウンを除去し、セクション見出しと changeset のコミットハッシュ接頭辞を削除し、[`blume audit`](/docs/reference/cli#auditing-the-built-site) がチェックする検索スニペットの長さに切り詰めたもので、サイトの説明にフォールバックすることはありません。プライベートリポジトリは `GITHUB_TOKEN` 環境変数で認証します。すべてのオプションについては[コンテンツソース](/docs/content/sources#github-releases)を参照してください。

## RSS フィード

Blume は **`/changelog/rss.xml`** に変更履歴フィードも構築し、`date` の新しい順にソートします。フィードには絶対的なサイト URL が必要なので、[`deployment.site`](/docs/deployment) を設定してください。その後 Blume がすべてのページに `<link rel="alternate">` タグを挿入し、読者が自動的に見つけられるようにします。

フィードはデフォルトで有効です。[`seo.rss`](/docs/configuration/seo#rss-feeds) で調整できます:

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

タイムラインを維持したままフィードだけをスキップするには、`rss.types` から `"changelog"` を削除してください。

## 構造化データ

[構造化データ](/docs/configuration/seo#structured-data)が有効な場合、各変更履歴エントリは説明と公開日を伴う schema.org の **`TechArticle`** として出力されるため、検索エンジンがリリースを日付付きの記事としてインデックスできます。

**[フロントマター](/docs/reference/frontmatter#changelog)**

変更履歴のフロントマタースキーマの全体。

**[カスタムページ](/docs/advanced/custom-pages)**

生成されたタイムラインを独自のレイアウトに置き換えます。

---

# カスタムページ
Source: https://useblume.dev/ja/docs/advanced/custom-pages

Blume サイトの大部分は Markdown ですが、ドキュメント*ではない* ルートが必要になることもあります — ランディングページ、料金ページ、手作りのブログやチェンジログのインデックス、あるいはインタラクティブなダッシュボードなどです。**pages** フォルダに `.astro` ファイルを置けば、Blume がそれをコンテンツと並ぶ実際のルートとしてマウントします。

## ページを追加する

プロジェクトルートに `pages/` フォルダを作成し、`.astro` ファイルを追加します:

```astro pages/pricing.astro lineNumbers
---
import data from "blume:data";
---

<h1>Pricing for {data.config.title}</h1>
```

`blume dev` はこれを即座に検出し、`blume build` は静的 HTML にプリレンダリングします。フォルダ名は [`content.pages`](/docs/configuration#content) で設定できます（デフォルトは `"pages"`）。

カスタムページはディスク上の元の場所を保持するため、相対インポート、コンポーネントのインポート、[`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) はすべて、素の Astro プロジェクトとまったく同じように動作します — Blume は各ファイルをコピーするのではなく、それがある場所にマウントします。

## ファイルとルート

pages フォルダ配下の各ファイルのパスがそのルートになります。`index` は親フォルダに対応し、動的な `[param]` セグメントはそのまま保持されます:

| ファイル                  | ルート        |
| ------------------------- | ------------- |
| `pages/pricing.astro`     | `/pricing`    |
| `pages/blog/index.astro`  | `/blog`       |
| `pages/blog/[slug].astro` | `/blog/:slug` |
| `pages/changelog.astro`   | `/changelog`  |

同じパスに生成されたルートがある場合、カスタムページが**優先されます**。たとえば `pages/changelog.astro` を追加すると、Blume の[生成されるチェンジログのタイムライン](/docs/advanced/changelog)が自作のものに置き換わります。

## サイトデータの読み取り

`blume:data` をインポートすると、サイトの他の部分が使っているのと同じ解決済みの設定、ナビゲーション、ルート、フィードを読み取れます:

```astro pages/all-pages.astro lineNumbers
---
import data from "blume:data";
---

<h1>All pages</h1>
<ul>
  {
    data.routes
      .filter((route) => route.indexable)
      .map((route) => (
        <li>
          <a href={route.path}>{route.title}</a>
        </li>
      ))
  }
</ul>
```

Blume プロジェクト内では、このモジュールは自動的に型付けされます。型付きヘルパー、props、あるいは独自の tsconfig のために、`import type { BlumeData } from "blume"` で型を明示的に取り込むこともできます:

```ts
import type { BlumeData, BlumeRoute } from "blume";

const indexable = (data: BlumeData): BlumeRoute[] =>
  data.routes.filter((route) => route.indexable);
```

このモジュールが公開するもの:

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `BlumeDataConfig` | - | 解決済みのサイト設定: title、description、logo、favicon、appleIcon、banner、theme、site、repoUrl、github（owner、repo、host、および REST api のベース — 未設定の場合は null）、search、i18n、mcp、ask、og、analytics、feedback、structuredData、toc、codeThemes、codeWrap、imageZoom。 |
| `navigation` | `Navigation` | - | コンテンツから推論されたサイドバー、タブ、セレクター（デフォルトロケール）。 |
| `navigationByLocale` | `Record<string, Navigation>` | - | ロケールコードをキーとする、ロケールごとのナビゲーションツリー。i18n が設定されていない限り空です。 |
| `routes` | `BlumeRoute[]` | - | すべてのコンテンツページ: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }。 |
| `feeds` | `BlumeFeed[]` | - | 生成された RSS フィード: { href, title }。 |
| `fontCssVars` | `string[]` | - | 設定されたフォントの CSS 変数名（Astro の <Font> インテグレーション）。 |
| `ui` | `UIStrings` | - | デフォルトロケール向けの解決済み UI クローム文字列（検索、サイドバー、フッターのラベル）。 |
| `uiByLocale` | `Record<string, UIStrings>` | - | ロケールコードをキーとする、ロケールごとの UI 文字列。i18n が設定されていない限り空です。 |

`routes` はページのメタデータを持ちますが、`type` や `date` のようなフロントマターは含みません。コンテンツタイプでフィルタリングしたリスト — ブログやチェンジログのインデックス — を作るには、フロントマターを保持している Astro の `docs` コンテンツコレクションと組み合わせてください:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

// Each route's id matches its collection entry id.
const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

## ランタイムヘルパー

`blume/runtime` は一般的なデータパターンをまとめて提供するため、`blume:data` の内部に手を伸ばす必要がありません。

**`getBlumeCollection(data, query?)`** はコンテンツルートを選択します — コレクション、ロケール、パスのプレフィックスでフィルタリングし、下書きと非表示ページを除外し、結果をパス順にソートします — これはまさにカスタムインデックスに必要なものです:

```astro pages/blog/index.astro lineNumbers
---
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const posts = getBlumeCollection(data, { prefix: "/blog" });
---

<ul>
  {posts.map((post) => (
    <li><a href={post.path}>{post.title}</a></li>
  ))}
</ul>
```

**`<BlumePage>`** はコンテンツエントリの本文をカスタムページ内でレンダリングし、Blume 組み込みの MDX コンポーネント（コールアウト、カード、ステップなど）があらかじめ組み込まれた状態になります — ランディングページでドキュメントを目立たせたり、実際のコンテンツを表示する独自のインデックスを構築したりするのに使えます:

```astro pages/index.astro lineNumbers
---
import BlumePage from "blume/components/BlumePage.astro";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const [intro] = getBlumeCollection(data, { prefix: "/docs" });
---

{intro && <BlumePage id={intro.entryId} />}
```

独自のオーバーライドやアイランド（生成されたランタイム内に存在し、デフォルトではインポートされません）を追加するには `components` を、`"docs"` 以外のコレクションから読み取るには `collection` を渡します。

## サイトレイアウトを使う

`RootLayout` は、生成されたページが使うのと同じ 3 カラムグリッドでラップすることで、カスタムページに完全なドキュメントのクローム — ヘッダー、サイドバー、検索、目次、テーマ — を与えます。ランディングページやマーケティングページではそのグリッドが邪魔になるので、代わりに **`PageLayout`** を使いましょう: これはドキュメントのシェル、ヘッダー、テーマ、フォントに加えて、単一の全幅 `<slot />` を提供します（サイドバーなし、prose なし、目次なし）。オプションの `footer` スロットは `<main>` の後にレンダリングされます:

```astro pages/index.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
import Footer from "./_home/Footer.astro";

const { config } = data;
---

<PageLayout
  site={{ title: config.title, description: config.description }}
  logo={config.logo}
  banner={config.banner}
  analytics={config.analytics}
  navigation={data.navigation}
  favicon={config.favicon}
  fontCssVars={data.fontCssVars}
  themeMode={config.theme.mode}
  searchEnabled={config.search.enabled}
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  page={{ title: "Acme — the fastest docs", description: config.description }}
>
  <section class="mx-auto max-w-5xl px-6 py-24">
    <h1>Build docs that fly</h1>
  </section>
  <Footer slot="footer" />
</PageLayout>
```

カスタムページが得るヘッダーはドキュメントページのものと同じなので、そこにあるクロームも一緒についてきます: 検索、テーマ切り替え、言語スイッチャー、そして [Ask AI](/docs/configuration/ai) が設定されている場合は Ask AI のトリガーです。どれもページごとに配線する必要はありません。あるページだけ Ask トリガーを無効にし、他のすべてでは有効なままにするには `askEnabled={false}` を渡します。

`siteUrl`（と `ogEnabled`）を渡すと、そのページの `canonical` と生成された `og:image` が自動的に導出されます: Blume はすべての静的カスタムページ — 最も共有されやすい URL であるホームを含む — に対して Open Graph カードをレンダリングし、`/og/<route>.png`（`/` の場合は `/og/index.png`）で配信します。ホームのカードはサイトタイトルを使い、description をアイブロウにします。より深い階層のページはパスの最後のセグメントからタイトルが付けられます。どちらも上書きするには `ogImage` または `canonical` を明示的に設定してください。`ogImage` はルート相対パス — `public/` 内のファイルで、[`deployment.site`](/docs/deployment) を基準にクローラーが必要とする絶対 URL へ解決されます — または外部 URL を受け取り、後者はそのまま通されます:

```astro pages/index.astro lineNumbers
<PageLayout
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  ogImage="/opengraph-image.png"
  ogImageAlt="Acme — the fastest docs"
  ogImageSize={{ width: 1200, height: 630 }}
  page={{ title: config.title }}
>
  <!-- page content -->
</PageLayout>
```

変わるのはこのページだけで、他のすべてのルートは生成されたカードのままです — つまりこれが、ホームページだけに独自の共有画像を与える方法です。生成されたカードは自身のサイズと代替テキストをクローラーに対して自動的に宣言します。独自の `ogImage` を使う場合は、共有カードが同じ扱いを受けられるよう `ogImageAlt` と `ogImageSize` を併せて渡してください。

このページは schema.org の JSON-LD も出力します — ドキュメントページが持つのと同じ `WebSite` グラフなので、（多くの場合カスタムページである）ホームページだけが構造化データのない URL になることはありません。[`structuredData`](/docs/configuration/seo) の設定と同期させるには `structuredDataEnabled={config.structuredData}` を、特定のページだけ無効にするには `structuredDataEnabled={false}` を渡します。

`page.title` はドキュメントタイトルとしてそのまま使われます（`- siteTitle` のサフィックスは付きません）。マーケティングページは通常、自前のタイトルを設定するためです。代わりにカスタムページへ完全なドキュメントのクローム — サイドバー、目次、すべて — を与えるには、生成されたページが使うレイアウトである `RootLayout` でラップします。必要な props は `blume:data` から直接取得できます:

```astro pages/pricing.astro lineNumbers
---
import RootLayout from "blume/components/layout/RootLayout.astro";
import data from "blume:data";
---

<RootLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  banner={data.config.banner}
  navigation={data.navigation}
  page={{ title: "Pricing", route: "/pricing" }}
  headings={[]}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  indexable={true}
>
  <h1>Pricing</h1>
</RootLayout>
```

:::note
`RootLayout` は生成されるランタイムの一部であるため、その props はリリース間で変更される可能性があります。完全に自分のものとなるレイアウトが欲しい場合は、[`blume eject`](/docs/configuration/customization#eject) で `.blume/` を完全に自分が所有する標準の Astro プロジェクトに変換できます。
:::

## 404 ページ

Blume はデフォルトの **not found** ページを標準で同梱しています: サイトのクローム（ヘッダー、検索、テーマ）でラップされた中央揃えの「404」メッセージで、マッチしないあらゆる URL に対して配信されます。`blume build` はこれを `404.html` に書き出し、静的ホストが自動的に配信します。また `blume dev` は不明なルートに対してこれを表示します。メッセージの下には **Where to look next** のリストがあり、すべてのトップレベルセクションに加えて、存在する場合は `sitemap.xml` と [`llms.txt`](/docs/configuration/ai#llmstxt) のインデックスへのリンクが並ぶため、読者 — あるいは古い URL をたどったエージェント — が戻る道を持てます。

このページには `/404.md` という Markdown の対応版と、`/404.json` という JSON の対応版（[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の problem details）もあり、同じ復帰用リンク（[`deployment.site`](/docs/deployment) が設定されていれば絶対 URL になります）に加えて、JSON API が有効な場合は [`openapi.json`](/docs/configuration/ai#json-api) の記述も備えています。[Vercel のサーバービルド](/docs/deployment#server-rendering)では、存在しないページへのリクエストが [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation) を送る場合、あるいはどのページにも裏付けられていない `.md` URL を要求する場合、HTML のシェルではなく `404` ステータス付きでその Markdown の本文が返されます。`Accept: application/json` を送る場合、あるいはどのファイルにも裏付けられていない `.json` URL を要求する場合は problem ドキュメントが返されます — つまりエージェントは、次にどこへ行くべきかを知るためにクロームだらけのページを解析する必要がまったくありません。

これを自作のものに置き換えるには、`pages/404.astro` を追加します。`pages/changelog.astro` がチェンジログを引き継ぐのと同じように、このファイルが `/404` ルートを所有します — あなたのページが優先され、デフォルトは破棄されます。他のカスタムページと同様に、`PageLayout` または `RootLayout` で構築してください:

```astro pages/404.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
---

<PageLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  navigation={data.navigation}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  page={{ title: "Page not found", route: "/404" }}
  noindex={true}
>
  <section class="mx-auto max-w-2xl px-6 py-24 text-center">
    <h1>This page took a wrong turn</h1>
    <a href="/">Back to home</a>
  </section>
</PageLayout>
```

デフォルトのデザインは保ちつつ文言だけを変更する場合 — 他の言語向けも含めて — は、`i18n.ui` で `notFound` の [UI 文字列](/docs/content/i18n)（`title`、`description`、`home`）を上書きしてください。

## インタラクティブなページ

カスタムページは通常の Astro なので、ハイドレーションディレクティブを付けて React（や任意のフレームワーク）の[アイランド](/docs/configuration/customization#interactive-islands)を組み込めます。プロジェクトに `.tsx` または `.jsx` ファイルが含まれた時点で、React は自動的に有効になります。

**[カスタマイズ](/docs/configuration/customization)**

コンポーネントのオーバーライド、React アイランド、レジストリ、eject。

**[ブログ](/docs/advanced/blog)**

記事を執筆し、カスタムのブログインデックスを構築します。

---

# GraphQL
Source: https://useblume.dev/ja/docs/advanced/graphql

Blume に GraphQL スキーマを指定すると、ネイティブな API リファレンスが生成されます。**ルートフィールドごとに実際のページ** が 1 つずつ（クエリ、ミューテーション、サブスクリプション）、さらに **名前付き型ごとにページ** が 1 つずつ（オブジェクト、入力オブジェクト、列挙型、インターフェース、ユニオン、カスタムスカラー）作成されます。各ページには引数、デフォルト値、非推奨情報、利用箇所へのバックリンクが表示され、生成された操作例、コードサンプル、インタラクティブな [Try it](#try-it-playground) パネルも併せて掲載されます。それぞれが正真正銘の Blume ページであるため、独自の URL を持ち、**サイト内検索** や `llms.txt` に表示され、Open Graph 画像も生成されます。手書きのドキュメントとまったく同じ扱いです。

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
}
```

これにより、リファレンスが `/graphql`（概要ページ）にマウントされ、ルートフィールドは `/graphql/queries/<field>`、`/graphql/mutations/<field>`、`/graphql/subscriptions/<field>` に、型は種類別にグループ化されて `/graphql/objects/<type>`、`/graphql/enums/<type>` などに配置されます。

`spec` にはプロジェクト内のローカルファイルへのパスか `http(s)` URL を指定でき、次の 2 つの形式に対応しています。

- **SDL テキスト** — 型定義を含む `.graphql` ファイル。
- **イントロスペクション結果** — 標準のイントロスペクションクエリを実行して生成された JSON。生の `{ "__schema": … }` 形式でも、完全な `{ "data": { "__schema": … } }` レスポンスエンベロープ形式でも構いません。

`endpoint` は稼働中の GraphQL API の URL です。スキーマは OpenAPI ドキュメントとは異なりサーバーを指定しないため、Try it パネルと生成されたコードサンプルが対象とする先がこのエンドポイントになります。省略した場合、サンプルは読者が置き換えるためのプレースホルダー URL でレンダリングされます。

リファレンスが自動的にヘッダータブを追加することはありません。表示するには、[ナビゲーションタブ](/docs/content/navigation#tabs) をそのルートに向けてください。これによりリファレンスのサイドバーのスコープも設定されます。

```ts blume.config.ts
navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}
```

## 生成される例

すべての操作ページには、完全で有効な操作例が掲載されます。引数ごとに 1 つの変数がスキーマに基づいて型付けされ、戻り値の型に対して深さを制限した選択セットが付きます。さらに、対応する変数の例と、同じ選択セットを反映したレスポンスの例も掲載されます。コードサンプルは、設定された各言語で正確な HTTP リクエスト（`{ query, variables }` の JSON `POST`）を表示します。

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  codeSamples: ["curl", "js"],   // built in: curl, js, python
}
```

## 型ページ

名前付き型には、ディープリンク可能な専用ページが用意され、サイドバーでは種類別にグループ化されます。フィールドと入力フィールドは型がリンクされた状態で表示され、列挙値、ユニオンメンバー、インターフェースの実装、そしてその型を返すまたは受け取る操作と、その型を参照する他の型を一覧する **Used by** セクションが含まれます。仕様で定義されたスカラー（`String`、`Int` など）にはページは作成されませんが、カスタムスカラーには `specifiedBy` URL を含めて作成されます。

## 複数のスキーマ

`sources` の各エントリは、1 つのスキーマをそれぞれ独自のルートでレンダリングします。ソースごとの `endpoint` はブロックレベルの設定を上書きします。

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  endpoint: "https://api.example.com/graphql",
  sources: [
    { label: "Public API", spec: "./schema.graphql" },
    {
      label: "Admin API",
      route: "/graphql-admin",
      spec: "./admin.graphql",
      endpoint: "https://admin.example.com/graphql",
    },
  ],
}
```

各ソースは OpenAPI ブロックと同じ [ソース単位の制御項目](/docs/advanced/api-reference#per-source-indexing) を受け付けます: `includeInSearch`、`includeInLlms`、`noindex`、`seoDescriptionSuffix`（この場合、生成される文はクエリ、ミューテーション、または型の名前を含みます —「Reference for the `pets` query in the GraphQL API.」）。

## Try it プレイグラウンド

クエリとミューテーションのページにはインタラクティブなパネルが表示されます。リクエストボディ（クエリと変数）を編集し、エンドポイントまたは任意の URL を指定して送信できます。コードサンプルはリアルタイムで更新されるため、コピーした内容は送信された内容とバイト単位で一致します。無効にするには `playground: false` を指定します。サブスクリプションのページでは、代わりに生成された操作とイベントの例が表示されます。サブスクリプションはステートフルなトランスポート（WebSocket または SSE）上で動作し、プレイグラウンドの単一の HTTP `POST` では対応できないためです。

GraphQL API がドキュメントサイトからのクロスオリジンリクエストを許可していない場合は、送信を CORS プロキシ経由でルーティングしてください。独自の URL を指定するか、組み込みの `/_api-proxy` エンドポイントを使う場合は `true` を指定します（`deployment.output: "server"` が必要です）。組み込みプロキシは、ドキュメント化された仕様が宣言しているオリジン（設定された各 GraphQL `endpoint` と、ドキュメント化された [OpenAPI 仕様](/docs/advanced/api-reference) の絶対 URL である `servers[].url`）にのみ転送します。そのため、公開されたドキュメントのデプロイを他のホストに向けることはできません。したがって、プロキシを機能させるには `endpoint` が必須です。指定がないと、プロキシはこのリファレンスに対して許可すべきオリジンを持たず、すべての送信を拒否します（ビルド時に警告が表示されます）。

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
  playground: { proxy: true },
}
```

---

# スキル
Source: https://useblume.dev/ja/docs/advanced/skills

Blume は[エージェントスキル](https://docs.claude.com/en/docs/claude-code/skills)を提供しています。これは、コーディングエージェント（Claude Code、Codex、Cursor）に対して、あなたが説明しなくても Blume 特有の作業のやり方を教えるプレイブックです。スキルは GitHub 上のリポジトリの `skills/` フォルダーに置かれ、インストール済みパッケージにも `skills/` 配下にバンドルされているため、どのエージェントにも `SKILL.md` を直接指定できます。

## Blume

中核となるスキルです。Blume とは何か、そしてサイトをどのようにスキャフォールド・執筆・設定するか（ファイルシステムから導出されるナビゲーション、設定スキーマ、コンテンツコンポーネント）をエージェントに教え、インストール済みパッケージにバンドルされた完全なドキュメント（`blume` 内の `docs/` ディレクトリ。パッケージマネージャーがインストールした場所から解決されます。pnpm モノレポではリポジトリのルートではなく、依存しているワークスペースの `node_modules` です）へ誘導します。エージェントがドキュメント構築を手伝うプロジェクトにインストールしてください。

```bash
npx skills add haydenbleasel/blume
```

## 自己更新するドキュメント

`blume-update-docs` は、ドキュメントを、それが説明している製品と同期した状態に保ちます。実行のたびに（通常はエージェントランナーで設定したスケジュールから）、最近マージされた PR、変更履歴、設定スキーマ、CLI ヘルプをドキュメントの内容と照合し、事実として古くなったページのみを更新し（フィーチャーフラグ配下の作業は無視されます）、`blume build` で検証したうえで、`blume/*` プルリクエストを作成または更新します。ずれが何もなければ、無用な PR を作成せず、変更なしとして報告します。

```bash
npx skills add haydenbleasel/blume --skill blume-update-docs
```

Blume は自動化をホストしません。リポジトリ履歴の読み取りと PR 作成の権限を与えたうえで、Claude Code のスケジュールタスク、Codex や Cursor の自動化、あるいは単純な cron にスキルを組み込んでください。週次プロンプトの例:

```text
Use the blume-update-docs skill. Review the PRs merged within the last 7 days and compare them to the docs content. Ignore work behind feature flags. If docs need updates, make them, verify the docs build, and open a blume/* PR. If not, report what you checked and do not open a PR.
```

---

# 設定ファイル
Source: https://useblume.dev/ja/docs/configuration

Blume はプロジェクトルートの `blume.config.ts` を読み込みます。設定を `defineConfig` でラップすると、オートコンプリートと型チェックが有効になります。すべてのフィールドは任意で、適切なデフォルト値が用意されています。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});
```

## 完全な例

最もよく使われるオプションを一通り含んだ、より広範な例です（残りは各機能のガイドを参照してください）:

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [sitemap()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — see the Search guide
  search: {
    provider: "orama",
  },

  // Markdown features
  markdown: {
    imageZoom: true,
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
    },
    codeBlocks: {
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // AI — see the AI guide
  ai: {
    llmsTxt: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — see the Deployment guide
  deployment: {
    output: "static",
    site: "https://docs.example.com",
  },
});
```

## サイト

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `title` | `"Documentation"` | サイト名 — ヘッダー、ページタイトル、OG カードに表示されます。 |
| `description` | — | デフォルトの meta description。SEO と OG に使用されます。 |
| `logo` | — | ヘッダーに表示されるブランドマークやワードマーク。 |
| `banner` | — | ヘッダー上部に表示されるサイト全体のお知らせバー。 |

### ロゴ

`logo` に SVG を指定すると Blume がインライン展開するため、`currentColor` を使ったロゴはライトテーマとダークテーマに自動で追従します:

```ts blume.config.ts
logo: "/logo.svg",
```

SVG はプロジェクトルートまたは `public/` に配置できます。ブランドはマーク（`image`）とワードマーク（`text`）で構成され、オブジェクト形式ならそれぞれを個別に設定できます:

```ts blume.config.ts lineNumbers
logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},
```

`image` は省略形と同じ値を取ります。単一のパス、またはライト/ダークで別々のアートワークを使う場合は `{ light, dark, alt }` です（ラスター画像は `public/` に配置する必要があります）。

`text` はマークとは独立してワードマークを制御します:

- **`text` を省略**すると、ブランドにはサイトの `title` が使われます（デフォルト）。
- **`text: ""` を設定**するとマークのみを表示します。ロゴ画像にすでにワードマークが含まれている場合に便利です。
- **`image` なしで `text` を設定**すると、テキストのみのロゴになります。

### ファビコン

ファビコンのオプションはありません。Blume は Next.js と同じようにファイル名から自動検出します。`icon` または `favicon` というファイル（`.svg`、`.png`、`.ico`）をプロジェクトルートまたは `public/` ディレクトリに置くと、ブラウザのタブアイコンになります:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/
```

複数存在する場合は SVG が PNG より、PNG が ICO より優先され、ルート直下のファイルよりも `public/` 内のファイルが優先されます。アイコンが見つからない場合、Blume は自身のマークにフォールバックします。

暗い色のマークは暗いブラウザ UI の中では見えなくなってしまうため、ダークモード用に 2 つ目のファイルを用意できます。アイコンファイルの `-dark` 兄弟ファイル — 同じ名前・同じディレクトリで、拡張子の前に `-dark` を付けたもの（`icon.png` → `icon-dark.png`）— を追加すると、Blume は `prefers-color-scheme` メディアクエリを介して両方のアイコンを出力し、あわせてアイコンのメディアクエリを無視するブラウザやクローラー向けにライト用のプレーンなタグも出力します:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/
```

使われるのは Blume が選択したアイコンの兄弟ファイルだけです。名前が異なる `-dark` ファイルは無視されるため、無関係なファイルが誤ってマークと組み合わされることはありません。ダーク用ファイルは任意で、アイコンが 1 つだけの場合、Blume はこれまでどおり単一のタグを出力します。Blume 自身のフォールバックマークは両方のバリエーションを備えています。

### Apple タッチアイコン

サイトをホーム画面に追加したときに iOS が使うアイコンも、同じ方法で検出されます。`apple-icon` というファイル（`.png`、`.jpg`、`.jpeg`）— あるいは、多くのファビコン生成ツールが出力する名前である `apple-touch-icon.png` — をプロジェクトルートまたは `public/` ディレクトリに置くと、Blume が `<link rel="apple-touch-icon">` を設定します。デフォルトはありません。ファイルが見つからない場合、タグは出力されません。

```
my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/
```

このファイルはプロジェクトルートではなく `public/` に置いてください。ルート直下のアイコンに対して Blume が使うインラインのデータ URI は iOS では無視されるため、`public/` に置いたファイル（`/apple-icon.png` で配信されます）だけが確実にホーム画面に反映されます。ファビコンとは異なり、ここでは `-dark` 兄弟ファイルはありません。iOS はホーム画面アイコンのメディアクエリを無視するため、ダーク用のバリエーションを配信することはそもそもできないからです。

### バナー

ヘッダーの上にサイト全体のお知らせバーを表示します。文字列を渡すか、リンクと閉じるボタンを含むオブジェクトを渡します:

```ts blume.config.ts
banner: "Docs are in beta — expect changes.",
```

```ts blume.config.ts lineNumbers
banner: {
  content: "Blume v1 is here!",
  link: { text: "Read more", href: "/blog/v1" },
  dismissible: true,
  id: "v1",
},
```

`dismissible` を有効にすると、バーに閉じるボタンが表示され、それ以降その訪問者には非表示のままになります。閉じた状態を記録するキーはデフォルトで本文テキストになるため、メッセージを編集するとバナーが再び表示されます。編集後も閉じたままにするには、安定した `id` を設定してください。

## コンテンツ

コンテンツの置き場所と、Blume がそれをどう検出するかです。ファイルがどのようにルートになるかは [ページ](/docs/content) を参照してください。

```ts blume.config.ts lineNumbers
content: {
  root: "docs",
}
```

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `root` | `"docs"` | Blume がコンテンツを走査するフォルダ。 |
| `include` | `["**/*.{md,mdx}"]` | コンテンツファイルにマッチする glob。 |
| `exclude` | `["**/_*", "**/.*"]` | 無視する glob（アンダースコアおよびドットで始まるファイル）。 |
| `pages` | `"pages"` | カスタム `.astro` ページ用のフォルダ。 |
| `defaultType` | `"doc"` | フロントマターで指定がない場合に使われるページの `type`。 |
| `types` | `{}` | タイプごとのコンテンツ定義 — 特定の `type` のページにのみ適用されるカスタムフロントマターキー。[フロントマター](#frontmatter) を参照してください。 |

静的アセットは `public/` に置きます。`public/logo.png` にあるファイルは `/logo.png` で配信されるため、`![](/images/create.png)` のような参照は `public/images/create.png` に解決されます。**相対パス**で参照される画像（`![](./diagram.png)`）はコンテンツの隣に配置し、[ビルド時に最適化されます](/docs/content/syntax#links-and-images)。

## 画像

相対パスで参照されるローカル画像は、ビルド時に自動的に最適化されます。圧縮され、WebP に変換され、読み込み中にレイアウトがずれないよう本来の `width`/`height` 属性が付与されます。設定は不要です。執筆時のガイダンスは [リンクと画像](/docs/content/syntax#links-and-images) を参照してください。

リモート画像はデフォルトでは手を加えずに配信されます。Blume にビルド時のダウンロードと最適化も行わせるには、そのホストを許可してください:

```ts blume.config.ts lineNumbers
image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}
```

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `domains` | `[]` | リモート画像の最適化を許可するホスト名。 |
| `remotePatterns` | `[]` | パターンベースの許可設定（`protocol`、`hostname`、`port`、`pathname`）。ホスト名は `*.`（1 階層）と `**.`（任意の深さ）のワイルドカードを受け付けます。 |

## フロントマター

ページのフロントマターは厳格に検証され、未知のキーがあるとビルドが失敗するため、タイプミスを早期に発見できます。プロジェクト固有のメタデータ（担当者、レビュー日など）を持たせるには、追加のキーを `frontmatter.extend` の下に宣言し、それぞれに用意したスキーマを対応付けます:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

任意の [Standard Schema](https://standardschema.dev) ライブラリが利用できます — Zod（プロジェクトがインストールしているバージョンを問わず）、Valibot、ArkType など。拡張の外側のキーは引き続き厳格に検証されるため、タイプミスの検出はこれまでどおりです。検証のセマンティクスについては [カスタムキー](/docs/reference/frontmatter#custom-keys) を参照してください。

`extend` の下のキーはサイト全体に適用されます。特定のコンテンツタイプのページにだけキーを必須にしたい場合 — RFC の `status`、ランブックの `service` など — は、代わりに `content.types` の下でタイプごとに宣言してください:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

1 つのキーはサイト全体かタイプごとのどちらかで宣言でき、両方はできません。スコープがどう解決されるかは [タイプごとのキー](/docs/reference/frontmatter#per-type-keys) を参照してください。

`facets` は、その値がフィルタ可能なメタデータになるカスタムキーを指定します。これらは検索ドキュメント（`blume-search.json` と MCP インデックス）に付随し、[MCP ツール](/docs/configuration/ai#mcp-server) はそれらに対して照合を行う `filters` 入力を受け付けます。そのため、エージェントは例えば `architecture` ドメインの `enforced` な RFC だけを取得できます。各ファセットは宣言済みのカスタムキー（タイプごと、またはサイト全体）である必要があり、ファセットになるのは文字列（あるいは文字列化された数値・真偽値）の値のみです。

## GitHub

`github` で Blume にリポジトリを指定します。これはヘッダーの [リポジトリリンク](/docs/content/navigation#repository-link) と、**Edit on GitHub** および **Give feedback** の [ページアクション](/docs/content/navigation#page-actions) を有効にします:

```ts blume.config.ts lineNumbers
github: {
  owner: "acme",
  repo: "docs",
}
```

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `owner` | — | リポジトリを所有する GitHub アカウントまたは組織。 |
| `repo` | — | リポジトリ名。 |
| `branch` | `"main"` | 編集リンクが指すブランチ。 |
| `dir` | — | リポジトリルートからプロジェクトルートまでのパス（モノレポ向け）。 |
| `host` | `"https://github.com"` | Enterprise 環境向けの、GitHub インスタンスのオリジン。HTTP(S) である必要があり、オリジンに正規化されます。 |
| `api` | `host` から導出 | Enterprise インスタンスに対して `<GithubInfo>` を使うための REST API のベース。HTTP(S) である必要があり、オリジンとパスに正規化されます。 |

### GitHub Enterprise

リポジトリが GitHub Enterprise インスタンスにあるドキュメントでは `host` を設定します。すると、リポジトリから導出されるすべてのリンク — ヘッダーのマーク、編集リンク、エージェントマニフェスト — が、公開サイトではなくそのインスタンスを指すようになります:

```ts blume.config.ts lineNumbers
github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}
```

[`<GithubInfo>`](/docs/content/components) が問い合わせる REST API のベースは `host` から導出されます。データレジデンシーを備えた Enterprise Cloud テナント（`acme.ghe.com`）はその `api.` サブドメインから配信され、それ以外のホストは Enterprise Server（`/api/v3`）として扱われます。インスタンスがそれ以外の場所にある場合は、`api` を明示的に設定してください。

:::warning
プレーンな HTTP でしか到達できないインスタンスでもカウントは描画されますが、`GITHUB_TOKEN` は平文で送信される代わりにリクエストから除外されます。そのため、プライベートリポジトリのカードはカウントなしで返ってきます。
:::

:::note
`host` は Blume が `github` から導出するリンクに適用されます。ヘッダーのマークだけを別の場所 — 例えばドキュメントのリポジトリ自体がプライベートな場合の組織ページなど — に向けたい場合は、絶対 URL を指定した [`navigation.repo`](/docs/content/navigation#repository-link) を使ってください。
:::

## 最終更新日

各ページの下部に「Last updated on …」の行を表示します。デフォルトは無効です。`lastModified` を `true` に設定すると、各ページの日付が git 履歴から算出されます:

```ts blume.config.ts
lastModified: true,
```

| 値 | 説明 |
| --- | --- |
| `false` | 無効（デフォルト）。 |
| `true` | git 履歴（コミット日時）から日付を読み取ります。 |
| `{ type: "git" }` | `true` と同じことを明示的に書いたもの。 |
| `{ type: "frontmatter" }` | git を実行せず、フロントマターの `lastModified` フィールドのみを使用します。 |

git ソースは各ファイルに触れた最新のコミットを読み取るため、モノレポを含むあらゆる git リポジトリで機能し、ビルド時にリポジトリの履歴が必要です。CI プラットフォームは通常シャロークローンでチェックアウトするため、ほとんどの日付が黙って失われます（その場合、ビルドは `BLUME_SHALLOW_GIT_HISTORY` で警告します）。Vercel では `VERCEL_DEEP_CLONE=true` 環境変数を設定し、`actions/checkout` では `fetch-depth: 0` を設定してください。ページ自身の `lastModified` フロントマターが常に優先されるので、日付を固定したい場合や、まだコミットされていないファイルに便利です:

```mdx page.mdx
---
title: My page
lastModified: 2026-06-20
---
```

有効にすると、この日付はページの構造化データに schema.org の `dateModified` としても出力されます。

## 日付フォーマット

「Last updated」のスタンプと [チェンジログ](/docs/advanced/changelog) のタイムラインは、どちらも同じ `dateFormat` を通して日付を描画するため、表記が揃います。日付は常にサイトのロケールで描画され、`dateFormat` は*形式*を制御します。デフォルトは長い形式です（`July 21, 2026`、`2026年7月21日`）:

```ts blume.config.ts
dateFormat: { dateStyle: "long" },
```

`dateFormat` は [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) のオプションへのパススルーです。長さを指定するには `dateStyle` のプリセットを使います:

```ts blume.config.ts
dateFormat: { dateStyle: "medium" },
```

あるいは、`2026/07/21` のような数値中心のハウススタイルにするには、個別のコンポーネントフィールドを使います:

```ts blume.config.ts
dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
```

| オプション | 説明 |
| --- | --- |
| `dateStyle` | 長さのプリセット: `"full"`、`"long"`、`"medium"`、`"short"`。コンポーネントフィールドとの併用はできません。 |
| `weekday`、`era`、`year`、`month`、`day` | 個別のコンポーネント。例: `year: "numeric"`、`month: "2-digit"`。 |
| `timeZone` | IANA タイムゾーン。デフォルトは `UTC` なので、サイトをどこでビルドしても日付は同じに表示されます。 |
| `calendar`、`numberingSystem` | 暦法（例: `"japanese"`）と記数法（例: `"arab"`）。 |

## SEO

Open Graph 画像、RSS フィード、JSON-LD 構造化データを `seo` にまとめています。メタデータ、フロントマターによる上書き、完全なリファレンスは [SEO ガイド](/docs/configuration/seo) を参照してください。

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}
```

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `og.enabled` | 自動 | ページごとの Open Graph 画像 — サイト URL が設定されていると有効になります。 |
| `rss.enabled` | `true` | ブログとチェンジログのコンテンツ用にフィードをビルドします。 |
| `rss.types` | `["blog", "changelog"]` | それぞれフィードを持つコンテンツタイプ。 |
| `rss.limit` | `50` | 1 フィードあたりの最大アイテム数。 |
| `sitemap` | `true` | sitemap.xml を生成します（deployment.site が必要）。 |
| `robots` | `true` | Sitemap リンク付きの robots.txt を生成します。 |
| `structuredData` | `true` | 各ページの head に schema.org の JSON-LD を出力します。 |

これらは、完全な URL を得るために絶対パスの [`deployment.site`](/docs/deployment) と組み合わせると最も効果的です。

## 目次

このページの見出し一覧はデフォルトで有効になっており、`H2`〜`H3` の見出しを掲載します。`toc` で無効にしたり、見出しの範囲を変更したりできます:

```ts blume.config.ts
export default defineConfig({
  toc: false, // hide it everywhere
});
```

あるいは、見出しの範囲を絞り込みます:

```ts blume.config.ts
export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});
```

## 機能ごとのオプション

以下にはそれぞれ専用のガイドがあります。設定フィールドがその入口です:

| フィールド | 設定する内容 | ガイド |
| --- | --- | --- |
| `theme` | アクセントカラー、角の丸み、フォント、ライト/ダークモード | [テーマ](/docs/configuration/theming) |
| `navigation` | サイドバーとヘッダータブの明示的な指定 | [ナビゲーション](/docs/content/navigation) |
| `search` | プロバイダー（Orama、Pagefind、Algolia など）とインデックス作成 | [検索](/docs/configuration/search) |
| `markdown` | Markdown のレンダリングオプション — コードブロック、見出しアンカー、画像ズーム | [構文](/docs/content/syntax) |
| `ai` | `llms.txt`、Ask AI、コーディングエージェント向けのホスト型 MCP サーバー | [AI](/docs/configuration/ai) |
| `analytics` | Vercel、PostHog、カスタムスクリプト | [アナリティクス](/docs/configuration/analytics) |
| `seo` | メタデータ、OG 画像、フィード、構造化データ | [SEO](/docs/configuration/seo) |
| `deployment` | 出力モード、アダプター、サイト URL | [デプロイ](/docs/deployment) |
| `redirects` | 恒久的および一時的なリダイレクト | [デプロイ](/docs/deployment#redirects) |
| `integrations` | Blume の組み込み機能の後に追加される Astro インテグレーション | [カスタマイズ](/docs/configuration/customization#astro-integrations) |

## 優先順位

設定は優先度の低いものから高いものへと解決されるため、必要な部分だけを上書きすれば済みます:

1. **Blume のデフォルト**

    すべてのフィールドに適切なデフォルト値があります。

2. **blume.config.ts**

    プロジェクト全体の設定。

3. **フォルダの meta**

    セクションのタイトルと並び順を指定する [`meta.ts`](/docs/content/meta)。

4. **ページのフロントマター**

    ページごとの上書きが優先されます。

---

# AI
Source: https://useblume.dev/ja/docs/configuration/ai

Blume にはいくつかの AI 機能があります。外部ツール向けの機械可読ドキュメント（`llms.txt` と、OpenAPI の記述を伴う [JSON API](#json-api)。どちらも既定で有効）、ページ内の **Ask AI** アシスタント、そしてコーディングエージェント向けのホスト型 **MCP サーバー** です。Ask AI と MCP はオプトインで、機能を有効にするまで静的ドキュメントは完全に静的なままです。

## llms.txt

Blume は、コーディングエージェントやチャットアシスタントが利用できる機械可読版のドキュメントを出力します。これは既定で有効です。無効にするには `llmsTxt: false` を設定します。

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: false,
}
```

有効な間、`blume build` はサイトのルートに 2 つのファイルを書き出します。

- **`/llms.txt`** — コンパクトな索引です。サイトのタイトルと説明に続いて、各ページの要約付きリンク一覧を、サイドバーを反映したセクションに整理して並べます。フォルダーやグループが見出しになるため、エージェントは 1 枚のフラットな塊ではなくドキュメントの構造を把握できます。
- **`/llms-full.txt`** — コーパス全体です。各ページの完全な Markdown 本文を、ソース URL とともに 1 つのファイルにまとめます。

下書きページは除外されます。リンクとソース URL が絶対アドレスに解決されるように [`deployment.site`](/docs/deployment) を設定してください。

`llmsTxt` は、ファイルに含める内容を調整するつまみを備えたオブジェクト形式も受け付けます。[API リファレンス](/docs/advanced/api-reference)がプレースホルダーやサンプルの仕様をドキュメント化している場合は、`openapi: false` を設定して、生成されたページを両方のファイルから除外できます。

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    enabled: true, // default
    openapi: false, // exclude generated API reference pages
  },
}
```

オブジェクト形式は `details` も受け付けます。これは `llms.txt` のタイトルと要約の直後、ページセクションの前に配置される Markdown で、[llms.txt 仕様](https://llmstxt.org)における自由形式の「details」ブロックです。読みやすさをスキャンするツールが明示的に探す箇所でもあり、*どんなときに*あなたの製品を使うべきか、どう呼び出すのかをエージェントに伝える場所です。インストールコマンドやパッケージ名もここに書きます。

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    details: [
      "## When to use Acme",
      "",
      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
    ].join("\n"),
  },
}
```

`llms.txt` は、設定不要で生成される 2 つのセクションで締めくくられます。**Agent skills** は [`ai.skills`](#skills-discovery) を通じて公開された各スキルを、その説明（スキルがいつ使うべきかを述べている箇所）とともに列挙します。**Agent resources** は、ビルドが出力するあらゆる機械可読の成果物へのリンクを並べます。`llms-full.txt`、ページごとの[生の Markdown](#raw-markdown) ミラー、[MCP サーバー](#mcp-server)とそのディスカバリー文書、スキル索引、[API カタログ](#api-catalog)、[`agent-readability.json`](#agent-readability)、[サイトマップ](/docs/configuration/seo#sitemap)で、いずれも存在する場合にのみ含まれます。そのため `llms.txt` しか読まないエージェントでも、この面のすべてを見つけられます。

個々のページを両方のファイルから除外するには、そのページのフロントマターで `ai.exclude` を設定します。

```mdx
---
title: Internal notes
ai:
  exclude: true
---
```

そのページは引き続きレンダリングされ、検索にも残り、サイトマップ上の位置も保たれます。スキップされるのは `llms.txt` ファイルだけです。

どちらかのファイルを完全に自分で制御したい場合は、独自の `llms.txt` または `llms-full.txt` を `public/` フォルダーに追加してください。カスタムファビコンと同様に自動的に検出され、生成されたファイルの代わりに配信されます。一方を上書きしても、もう一方は Blume が生成し続けます。

## 生の Markdown

任意のページの URL に `.md` または `.mdx` を付け加えると、その生の Markdown ソースを取得できます。LLM、コーディングエージェント、「Markdown としてコピー」ワークフローに最適です。設定不要で、開発環境でも本番環境でも、すべてのページで利用できます。

| URL               | 返される内容                                |
| ----------------- | ------------------------------------------- |
| `/quickstart`     | レンダリングされたページ                    |
| `/quickstart.md`  | コンポーネントを変換したプレーンな Markdown |
| `/quickstart.mdx` | 記述されたままの生の MDX ソース             |

ネストされたルートも同様に動作し（`/content/syntax.md`）、ホームページは `/index.md` で配信されます。

`.md` 版は、JSX を解釈できない利用者のためにコンポーネントをプレーンな Markdown へ*ダウンレベル*します。`<TypeTable>` は Markdown のテーブルに、`<Callout>` はラベル付き引用に、`<Steps>` は順序付きリストに、`<Tabs>` は太字ラベルのセクションに、`<Card>` は本文の上にタイトルをリンクとして置いたものに（`<CardGroup>` はそれが保持するカード群に）、`<YouTube>` はリンクになります。props はページの `frontmatter` をスコープに入れて評価されるため、`title={frontmatter.status}` のような prop はレンダリングされたページと同じ値に解決されます。忠実に変換できないもの（カスタムコンポーネントや、import から算出される prop）はそのまま残され、フェンス付きコードブロック内のコンポーネントのマークアップには一切手を加えません。同じ変換は `llms-full.txt` と MCP サーバーの `get_page` ツールにも適用されるため、エージェントに向けたあらゆる面がきれいな Markdown として読めます。変換前のソースが必要なときは `.mdx` 版を使ってください。

### コンテントネゴシエーション

エージェントが `.md` の規約を知っている必要はありません。ページ自身の URL を [`Accept: text/markdown`](https://acceptmarkdown.com) ヘッダー付きでリクエストすると、同じアドレスで Markdown 版が配信され、キャッシュが両者を区別できるように `Vary: Accept` が付きます。開発サーバーは標準でこのヘッダーを尊重し、[Vercel または Cloudflare のサーバービルド](/docs/deployment#server-rendering)では同じネゴシエーションがデプロイに自動的に組み込まれます（Vercel ではルーティングルール、Cloudflare では生成された Worker 経由）。設定は不要です。ホームページは、コンテンツページではなくカスタムのランディングページであっても常にネゴシエーションを行います。その Markdown ミラーは [`llms.txt`](#llmstxt) の索引にフォールバックするため、サイトルートに Markdown を求めたエージェントはサイトの機械可読なマップを得られます。Markdown のレスポンスには `x-markdown-tokens` ヘッダー（トークン数の推定値。1 トークンあたり約 4 文字）も付きます。これは [Cloudflare の Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) の慣習に従ったもので、Blume がレスポンスヘッダーを制御できるすべての面（開発サーバー、サーバーレンダリングされたレスポンス、Vercel および Cloudflare 上でネゴシエーションされるホームページ）に付与されます。それ以外のデプロイ先はリクエスト時のフックを持たない静的レイヤーからプリレンダリング済みページを配信するため、そこではエージェントが `.md` の URL を直接取得します。[エージェント可読性マニフェスト](#agent-readability)は、ヘッダーを尊重するデプロイでのみ `contentNegotiation` を告知します。

存在しないページもネゴシエーションを行います。すべてのビルドは `/404.md` に Markdown 版の [404 ページ](/docs/advanced/custom-pages#404-page)を出力し（not-found のメッセージに続いて、すべてのトップレベルセクション、サイトマップ、`llms.txt` への復帰リンクが並びます）、Vercel では、Markdown を優先する存在しない URL へのリクエスト、または背後にページのない `.md` URL に対して、HTML のシェルではなく本物の `404` ステータス付きでその本文が返されます。

### カスタムコンポーネントのシリアライザー

`ai.markdownComponents`（JSX 名からシリアライザーへのマップ）を使うと、独自のコンポーネントに Markdown 表現を与えられます。各シリアライザーは、コンポーネントの `props`（MDX の属性から静的に評価され、ページの `frontmatter` がスコープに入ります）、`children`（すでに Markdown へダウンレベル済み）、およびページの `frontmatter` データを受け取り、置き換える内容を返します。JSX をそのまま残すには `null` を返します。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import type { ComponentMarkdown } from "blume";

const chart: ComponentMarkdown = ({ props }) =>
  `![${props.title}](/charts/${props.slug}.png)`;

export default defineConfig({
  ai: {
    markdownComponents: {
      Chart: chart,
    },
  },
});
```

コンテナー系のコンポーネントでは、`childComponents("Name")` がタグごとに直下の子要素を抽出します。組み込みの `<Steps>` シリアライザーが `<Step>` 項目を集めるのと同じ仕組みです。また `childBlocks()` は、コンポーネントか散文かを問わず直下のすべての子要素を順番に返し、それぞれはすでに Markdown のブロックへダウンレベル済みです（組み込みの `<CardGroup>` シリアライザーは、そのブロック群を空行で連結しているだけです）。同名のエントリーは組み込みシリアライザーを置き換えるため、`<Callout>` のダウンレベルの見え方を作り替えたり、`null` を返して完全にオプトアウトしたりできます。

シリアライザーは `components.tsx` ではなく `blume.config.ts` に置きます。設定ファイルはビルド時に実行されますが、コンポーネントファイルは静的に解析されるだけだからです（`.astro` ファイルを import する可能性があり、それはサイトのビルド外では実行できません）。コンポーネント自体はこれまでどおり `components.tsx` に登録したままです。`markdownComponents` は、そのエージェント向けの Markdown 表現を追加するだけです。

## Copy as Markdown

すべてのページには、目次の下の[ページアクション](/docs/content/navigation#page-actions)に **Copy as Markdown** アクションがあり、そのページの生の Markdown をクリップボードにコピーします。これは上記の [`.md` URL](#raw-markdown) で配信されるものと同じソースで、LLM や Issue、メモにそのまま貼り付けられます。設定不要で、開発環境でも本番環境でも、すべてのページで利用できます。

Clipboard API が利用できない場合やブラウザーがそれを拒否した場合（アプリ内ブラウザー、WebView、安全でないオリジンなど）、このアクションは従来のコピーコマンドにフォールバックし、それでもクリップボードに何も入らなければ、ボタンは黙ったままにせず **Copy failed**（`actions.copyFailed` でローカライズされます）と表示します。同じフォールバックが、Blume がレンダリングするすべてのコピーボタンを支えています。

## Open in chat

**Open in chat** アクションは、現在のページを AI アシスタント（v0、ChatGPT、Claude、T3 Chat、Scira、Cursor）で開き、そのページの生の Markdown を指すプロンプトをあらかじめ入力しておくため、読んでいる内容について質問できます。

> Read `https://your-site/this-page.md` so I can ask you questions about this page.

Copy as Markdown と同様、セットアップは不要です。アシスタントは公開 URL 経由でページを取得するため、ページがデプロイされればすぐに機能します。

このプロンプトは [UI 辞書](/docs/content/i18n#translated-ui)の一部（`actions.openInChatPrompt`）なので、ローカライズされたサイトはその言語で送信し、`i18n.ui` で文言を上書きできます。`{url}` プレースホルダーはそのまま残してください。ページの生の Markdown の URL に置き換えられます。

このアクションを調整するには `ai.openInChat` を設定します。`false` にすると完全に非表示になり、プロバイダーキーの配列（`"v0"`、`"chatgpt"`、`"claude"`、`"t3"`、`"scira"`、`"cursor"`）を指定すると、列挙した順序でそれらのプロバイダーだけが表示されます。

```ts blume.config.ts lineNumbers
ai: {
  openInChat: ["claude", "chatgpt", "cursor"],
}
```

ページ全体のアクションではなく、コンテンツ内にコピーしてすぐ使えるプロンプトを埋め込みたい場合は、[Prompt コンポーネント](/docs/content/components#prompt)を使ってください。**Copy prompt** ボタンと、任意で Cursor で開くリンクを備えたラベル付きの行をレンダリングします。

## Ask AI

読者の質問にページ内のチャットパネルで答えるアシスタントを追加します。ストリーミング対応のサーバーエンドポイントと [AI SDK](https://ai-sdk.dev) がバックエンドです。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "gateway", // default
    model: "openai/gpt-5.5",
  },
}
```

### 質問候補

空の状態にいくつかのスターター用プロンプトを用意できます。それぞれクリック可能な候補として表示され（クリックすると送信されます）、ラベルの横に任意で [Lucide アイコン](/docs/content/components#icon)を添えられます。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    suggestions: [
      { label: "What is Blume?", icon: "rocket" },
      { label: "How do I write a docs page?", icon: "file-text" },
      { label: "How do I configure the theme?", icon: "settings" },
    ],
  },
}
```

`label` は実際に送信される質問で、`icon` は任意です。`suggestions` を未設定（または空）のままにすると、パネルはシンプルな入力欄で開きます。

### カスタム指示

`instructions` で独自のシステムプロンプト文を追加できます。アシスタントに意識してほしいアイデンティティ、言語、トーン、その他何でも指定できます。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    instructions:
      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
  },
}
```

指定した文は組み込みの指示を置き換えるのではなく、その**後ろに追加**されます。組み込み部分は[グラウンディング](#grounding)の取り決め（取得したページのみから回答する、Markdown リンクとして引用する）を担っており、チャットパネルの引用表示はこれに依存しているため、何を追加しても損なわれずに残ります。

### グラウンディング

Ask AI は**ドキュメントにグラウンディングされています**。質問ごとに最も関連性の高いページを取得し（ページ内検索を支えるのと同じ字句ベースの [Orama](/docs/configuration/search) インデックスを使用）、モデルのシステムプロンプトに注入するため、回答はモデル自身の知識ではなくあなたのコンテンツから生成されます。アシスタントは、取得したページのみから回答すること、カバーされていない事柄はそう伝えること、参照したページを引用することを指示されています。

読者が現在開いているページが最初にコンテキストへ追加され、そのページの言語に検索範囲を絞るために使われるため、回答はドキュメント内の現在地に沿った内容になります。取得処理はビルドに埋め込まれたスナップショットからリクエスト時に実行されるため、[検索](/docs/configuration/search)プロバイダーに関係なく（検索が `none` に設定されていても）動作し、設定は不要です。

グラウンディングは **[Inkeep](#backends)** 以外のすべてのバックエンドで有効です。Inkeep はダッシュボードでインデックスしたコンテンツに対して独自の取得処理を行います。

### 取得サイズ

1 つの質問がどれだけのドキュメントを運ぶかは、読者が最初の 1 語を待つ時間を左右する最大の要因です。モデルは注入された文字をすべて読んでからトークンを出力し始めます。ホスト型のフロンティアモデルではこれは目に見えませんが、セルフホストのバックエンドでは支配的になります。`retrieval` でそのサイズを調整します。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    retrieval: {
      maxResults: 3, // fewer pages retrieved per question
      excerptChars: 1200, // shorter excerpt from each one
      contextBudget: 3000, // smaller total injection
    },
  },
}
```

| オプション      | 既定値  | 説明                                         |
| --------------- | ------- | -------------------------------------------- |
| `maxResults`    | `6`     | 質問ごとに取得するドキュメント数。           |
| `excerptChars`  | `2000`  | 取得した各ページから残す文字数。             |
| `contextBudget` | `10000` | すべての抜粋を合わせた、注入される総文字数。 |

この 3 つは互いに置き換えられるものではありません。`contextBudget` は注入全体に上限を設け、`excerptChars` は 1 つの長いページのどこまで深く抜粋するかを決め（1 ページに答えのすべてが収まっているのに抜粋が途中で切れてしまう場合に上げてください）、`maxResults` は取得処理が追加するページ数に上限を設けます。読者が閲覧しているページは取得したページに加えて注入されるため、回答は `maxResults` より 1 ページ多く引用することがあります。

既定値はホスト型モデルに適しています。自前のハードウェアから配信していて、再現率よりも最初のトークンまでの時間が重要な場合は、これらを下げてください。いずれの場合も回答はグラウンディングされたままで、アシスタントはカバーされていない事柄について、隙間を埋めるのではなくそう伝えるよう指示されています。

### 外部エンドポイント

すでに AI 用の API バックエンドをお持ちですか。パネルをそこに向ければ、ドキュメントのビルドは静的なままにできます。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}
```

Blume は組み込みのルートと同じ `POST` ボディを送信します。

```json
{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}
```

ボディがプレーンな UTF-8 テキストストリームである成功レスポンスを返してください。エンドポイントが別オリジンにある場合は、CORS でドキュメントのオリジンを許可します。`OPTIONS` と `POST` を受け付け、`content-type` リクエストヘッダーを許可し、プリフライトとストリーミングレスポンスの両方で CORS ヘッダーを返してください。`endpoint` を設定すると、Blume はチャット UI を生成しますが、サーバールート、グラウンディング用スナップショット、プロバイダーの依存関係、プロバイダーのシークレットに関する警告は生成しません。取得処理、認証、レート制限、モデルへのアクセス、引用はあなたのバックエンドが担います。

### サーバー出力が必要

Blume 組み込みの Ask AI バックエンドはサーバールート（`POST /api/ask`）なので、静的ビルドでは動作しません。サーバー出力に切り替えてアダプターを選択してください。

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

Ask AI が有効で外部 `endpoint` がない静的ビルドは、`deployment.output` を `server` に設定するよう促すメッセージとともに即座に失敗します。アダプターについては[デプロイ](/docs/deployment)を参照してください。

### バックエンド

既定では、Ask AI は **Vercel AI Gateway** を経由します。`model` は `provider/model` 形式の文字列なので、それを変更するだけでモデルを切り替えられ（`openai/gpt-5.5`、`anthropic/claude-sonnet-4-5` など）、プロバイダーの SDK をインストールする必要はありません。ゲートウェイは環境から `AI_GATEWAY_API_KEY` を読み取り、Vercel にデプロイすると自動的に設定されます。

Ask AI を別の場所に向けるには `provider` を設定します。各バックエンドは環境変数から API キーを読み取り、プロジェクトにインストールしたプロバイダーの SDK を通じてストリーミングします。インストールするのは実際に使うものだけです。

| `provider` | `model` | API キーの環境変数 | インストールする SDK |
| --- | --- | --- | --- |
| `gateway`（既定） | AI Gateway 経由の `provider/model` 形式の文字列 | `AI_GATEWAY_API_KEY` | 不要 — Blume に同梱 |
| `openrouter` | 任意の [OpenRouter](https://openrouter.ai) モデル | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
| `llmgateway` | 任意の [LLMGateway](https://llmgateway.io) モデル | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
| `inkeep` | [Inkeep](https://inkeep.com) の QA モデル | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
| `openai-compatible` | エンドポイントが提供するもの | `apiKeyEnv` で設定 | `@ai-sdk/openai-compatible` |

これらの SDK は任意のピア依存関係なので、バックエンドに必要なものをプロジェクトに追加してください（例: `npm install @openrouter/ai-sdk-provider`）。不足している場合は、Vite が import の解決に失敗する前に、ビルドが正確なパッケージ名を添えて警告します。

たとえば OpenRouter を使うには次のようにします。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openrouter",
    model: "anthropic/claude-sonnet-4-5",
  },
}
```

OpenAI 互換のエンドポイントはすべて `openai-compatible` で利用できます。`baseUrl` と、キーを保持する環境変数を指定してください。

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openai-compatible",
    baseUrl: "https://my-gateway.example.com/v1",
    apiKeyEnv: "MY_GATEWAY_API_KEY",
    model: "gpt-4o",
  },
}
```

どのバックエンドでも `apiKeyEnv`（および、名前付きプロバイダーでは `baseUrl`）を設定すれば、別の環境変数やプロキシを指せます。

:::note
**Inkeep** は Inkeep のダッシュボードでインデックスしたコンテンツから回答し、独自の取得処理を行うため、Blume はグラウンディングを行いません。それ以外のバックエンドはすべて、このサイトのページに[グラウンディング](#grounding)されます。
:::

キーは `process.env` で読み取られ、Node、Vercel、Netlify の各アダプターがこれに該当します。Cloudflare では、プラットフォームの[ランタイムバインディング](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets)経由でキーを公開してください。Ask AI を有効にすると、ページ内アイランドのために React も有効になります。[カスタマイズ](/docs/configuration/customization#interactive-islands)を参照してください。

### レート制限

`POST /api/ask` エンドポイントは**認証されていません**。ページ内アシスタントが呼び出せる必要があるため、そうならざるを得ません。Blume は各リクエストを検証し（不正なボディを拒否し、メッセージ数を 1〜40 に制限し、`user`/`assistant` のロールのみを受け付けることで、呼び出し元が独自のシステムプロンプトを注入してこのルートを汎用の LLM プロキシに転用できないようにします）、1 回の呼び出しがモデルに対して消費できる量を抑えますが、誰かが繰り返しエンドポイントを呼び出すことは防げません。コストの悪用が懸念される場合は、ホスト（たとえば Vercel）のエッジのレート制限、ミドルウェア、あるいはモデルプロバイダーのキー単位の支出上限などで、このルートをレートリミッターの背後に置いてください。

## MCP サーバー

[Model Context Protocol](https://modelcontextprotocol.io) サーバーをホストすれば、コーディングエージェント（Claude Code、Cursor、VS Code、claude.ai のコネクター）がスクレイピングなしで直接ドキュメントを検索・閲覧できます。

```ts blume.config.ts lineNumbers
ai: {
  mcp: {
    enabled: true,
    route: "/mcp", // where the server is mounted
  },
}
```

| オプション | 既定値 | 説明 |
| --- | --- | --- |
| `enabled` | `false` | MCP サーバーを生成してホストします。 |
| `route` | `/mcp` | Streamable-HTTP エンドポイントをマウントするパスです。 |
| `name` | title | クライアントに表示されるサーバー名（既定はタイトル）。 |
| `instructions` | — | 接続するエージェントに渡す任意のシステムヒント。 |

サーバーは読み取り専用のツール（`search_docs`、`get_page`、`list_pages`、`get_navigation`）と、すべてのページを MCP リソースとして公開します（`resources/list` は配信 URL でページを `text/markdown` タイプとともに列挙し、`resources/read` はそのページのエージェント向け Markdown、つまり `get_page` と同じ出力を返します）。そのため、URI でコンテキストを添付するクライアントは、ツールを呼び出さずにドキュメントを閲覧できます。さらに `/.well-known/mcp.json` と `/.well-known/mcp/server-card.json` にディスカバリー文書を公開します。サーバーカードは [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) の Server Card 拡張スキーマ（逆引き DNS 形式の `name`、`remotes` トランスポートエンドポイント）に従い、提案の以前の版に合わせて作られたスキャナー向けに initialize 形式の互換フィールド（`serverInfo`、`capabilities`、`transports`）も備えています。各ページの **Connect to MCP** メニューでは、Claude Code、Cursor、VS Code、Codex 向けにコピーしてすぐ使えるインストール手順を提供します（[`deployment.site`](/docs/deployment) を設定すると表示されます）。

`search_docs` は独自の全文インデックスで動作するため、[検索](/docs/configuration/search)プロバイダーに関係なく（検索が `none` に設定されていても）機能します。MCP サーバーはページ内検索とは別の機能です。

`search_docs` と `list_pages` はどちらも任意の `contentTypes` フィルターを受け付け、指定したフロントマターの [`type`](/docs/reference/frontmatter) を持つページに結果を絞り込めます（`["rfc"]`、`["blog", "changelog"]` など）。そのため、ドキュメントに RFC、ランブック、ポリシーが混在するサイトを相手に作業するエージェントは、必要な種類のページに取得範囲を絞れます。すべての結果にはそのコンテントタイプが明記され、`list_pages` の出力には使用中のタイプが表示されます。

両ツールは、サイトがコンテントタイプごとに宣言するファセット（[`content.types.<type>.facets`](/docs/configuration#frontmatter)）に対して照合する `filters` オブジェクトも受け付けます。ファセットとは、値がフィルター可能なメタデータになるカスタムのフロントマターキーです。

```json
{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}
```

`filters` の各エントリーはすべて一致する必要があります（結果にはファセットの値が含まれ、`list_pages` は各ページの値を表示します）。これにより、ナレッジベースは独自のサーバーを一切持たずに、段階的開示のエージェントワークフロー（強制されている標準を列挙し、その中だけを検索する、など）を駆動できます。

### サーバー出力が必要

MCP サーバーはライブのエンドポイント（`/mcp`）なので、静的ビルドでは動作しません。サーバー出力に切り替えてアダプターを選択してください。

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "node", // or "vercel" | "netlify" | "cloudflare"
  site: "https://docs.example.com",
}
```

`ai.mcp.enabled` が設定された静的ビルドは、`deployment.output` を `server` に設定するよう促すメッセージとともに即座に失敗します。アダプターについては[デプロイ](/docs/deployment)を参照してください。デプロイ後は、次のコマンドで Claude Code から接続できます。

```bash
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

## JSON API

すべての Blume サイトは、ドキュメントを小さな読み取り専用の **JSON API** としても配信します。これは [MCP サーバー](#mcp-server)のツールの REST 版で、同じページスナップショットの上に構築され、MCP ではなく素の HTTP を話すエージェントや関数呼び出しフレームワーク向けのものです。既定で有効で、設定は不要です。

| エンドポイント | 返される内容 |
| --- | --- |
| `/api/docs/pages.json` | すべてのページを、そのルート、タイトル、説明、コンテントタイプ、ロケール、ファセット、そしてレンダリング版・Markdown 版・JSON 版の URL とともに返します。 |
| `/api/docs/pages/{route}.json` | 1 ページ分。索引エントリーに加えてエージェント向け Markdown（`get_page` が返すのと同じ本文）を返します。`{route}` は先頭のスラッシュを除いたページのルートで、ホームは `index` です。 |
| `/api/docs/navigation.json` | ナビゲーションツリー（ヘッダーのタブとサイドバーの階層）。 |
| `/api/docs/search?q=` | 全文検索。`search_docs` と同じ `limit`、`contentTypes`、`locale`、`version`、`filters[key]` によるスコープ指定に対応します。サーバー出力でのみ利用可能です。 |
| `/openapi.json` | 機械可読な面全体を記述する OpenAPI 3.1 の記述。 |

ページ索引、ページごとのドキュメント、ナビゲーションはプリレンダリングされるため、静的サイトはどのホストからでもそれらをファイルとして配信できます。検索はライブのエンドポイントで、[サーバー出力](/docs/deployment#server-rendering)でのみ存在し、そこでは `search_docs` と同じインデックスで動作します。エラーは [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の problem details（`application/problem+json`）で、安定した `code`、`detail`、そしてエージェントに次の行き先を伝える `resolution` ヒントを備えています。存在しないページ、空の検索クエリ、そしてサーバー出力ではどのエンドポイントも応答しない `/api/…` の URL が対象です。

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

`/openapi.json` の **OpenAPI 文書**は設定からビルドごとに生成されるため、デプロイされたサイトが実際に配信するものだけを記述します。一意な `operationId`、型付きのパラメーター、レスポンススキーマを備えたすべての JSON エンドポイントに加えて、隣り合うテキストの面（[`.md` ミラー](#raw-markdown)、[`llms.txt`](#llmstxt) と `llms-full.txt`、[`agent-readability.json`](#agent-readability)）、そして有効な場合は [MCP エンドポイント](#mcp-server)も含まれます。OpenAPI の記述からツールを組み立てるフレームワークは、MCP クライアントと同じ範囲に到達できます。この文書は [API カタログ](#api-catalog)、[可読性マニフェスト](#agent-readability)、ホームページの `Link` ヘッダー（`rel="service-desc"`）、そして `llms.txt` からリンクされます。

これらはあなた自身の [API リファレンス](/docs/advanced/api-reference)には一切影響しません。ドキュメント化された仕様はページとしてレンダリングされ、`/openapi.json` で配信されることはなく、カタログには両方が掲載されます。自分で用意した `public/openapi.json` はそのルートを引き継ぎます（JSON エンドポイントはそのまま残ります）。`/api/…` のキャッチオールは、ドキュメントのセクションが `/api` 名前空間から配信される場合（`content/api/overview.md`）や、カスタムページが `/api/` 配下の残りのルートを保持している場合には道を譲るため、それらのページが引き続き優先されます。これらを一切公開しないようにするには `ai.api` を `false` に設定します。

```ts blume.config.ts lineNumbers
ai: {
  api: false,
}
```

## エージェント可読性

Blume はサイトのルートに **`/agent-readability.json`** マニフェストを書き出し、このページで説明したエージェント向けの機能を索引化します。これにより、エージェントは規約を推測したり HTML をスクレイピングしたりせずに、1 回の取得で発見できます。`llms.txt` と同様、既定で有効です。

```ts blume.config.ts lineNumbers
seo: {
  agentReadability: true,
}
```

マニフェストには有効にしたものだけが列挙されます。[生の Markdown](#raw-markdown) ミラーのパターン、[JSON API](#json-api) とその OpenAPI の記述、[`llms.txt`](#llmstxt) と `llms-full.txt`、[MCP サーバー](#mcp-server)とそのディスカバリー文書、[Ask AI](#ask-ai) のエンドポイント、[サイトマップ](/docs/configuration/seo#sitemap)、[RSS フィード](/docs/configuration/seo#rss-feeds)に加えて、サイト名、説明、ソースリポジトリ、[コンテントシグナル](/docs/configuration/seo#content-signals)の利用ポリシーが含まれます。URL は [`deployment.site`](/docs/deployment) が設定されていれば絶対 URL に、そうでなければルート相対になります。

```json agent-readability.json
{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "https://docs.example.com/{route}.md"
    },
    "api": {
      "openapi": "https://docs.example.com/openapi.json",
      "pages": "https://docs.example.com/api/docs/pages.json",
      "search": "https://docs.example.com/api/docs/search"
    },
    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
    "llmsTxt": "https://docs.example.com/llms.txt",
    "mcp": {
      "discovery": "https://docs.example.com/.well-known/mcp.json",
      "url": "https://docs.example.com/mcp"
    }
  },
  "description": "Docs for the Acme API.",
  "generator": "blume@1.0.0",
  "name": "Acme Docs",
  "site": "https://docs.example.com",
  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
  "repository": "https://github.com/acme/docs"
}
```

`contentNegotiation` フィールドは、デプロイされたサイトが実際に `Accept: text/markdown` ヘッダーを尊重する場合にのみ現れます（[コンテントネゴシエーション](#content-negotiation)を参照）。それ以外のデプロイでは、マニフェストは `.md` ミラーのパターンのみを告知します。

`seo.agentReadability` を `false` にすると生成をスキップできます。独自の `public/agent-readability.json` を用意して置き換えることも可能です。Blume が `public/` に置いたファイルを上書きすることはありません。

### ディスカバリー用 Link ヘッダー

サイトを探索するエージェントは、マニフェストを探すべきだと知りません。そこで Blume は、IANA 登録済みのリレーションタイプを用いて、ホームページの [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` レスポンスヘッダーでもマニフェストを告知します。

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
  </openapi.json>; rel="service-desc"; type="application/json",
  </agent-readability.json>; rel="describedby"; type="application/json",
  </llms.txt>; rel="describedby"; type="text/plain",
  </index.md>; rel="alternate"; type="text/markdown"
```

各エントリーは、その機能が有効な場合にのみ現れます。`alternate` リンクはホームページの Markdown ミラーを指します。ホームのルートがコンテンツページであればそのページ自身の[生の Markdown](#raw-markdown)、ランディングページであれば合成された `llms.txt` フォールバックです。`service-desc` リンク（[RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)）は [JSON API](#json-api) の OpenAPI の記述を、`api-catalog` は[生成された API カタログ](#api-catalog)を指します。このヘッダーは、Blume が制御するすべての面に付与されます。開発サーバー（`curl -I localhost:4321` で確認できます）、出力される `_headers` ファイル経由の静的ビルド（Netlify と Cloudflare）、そしてデプロイのルーティングルール経由の Vercel サーバービルドです。

とはいえ、すべてのエージェントがルートから入ってくるわけではありません。検索結果や共有リンクをたどってきたエージェントは深い階層のページに着地し、ホームページのヘッダーを目にすることはありません。そこで、レンダリングされるすべてのページも、同じ IANA 登録済みのリレーションを用いて、HTML の `<head>` に同じディスカバリーリンクを備えています。

```html
<link
  rel="describedby"
  href="/agent-readability.json"
  type="application/json"
/>
<link rel="describedby" href="/llms.txt" type="text/plain" />
<link rel="alternate" href="/docs/example.md" type="text/markdown" />
```

ここでの `alternate` リンクは*そのページ自身*の[生の Markdown ミラー](#raw-markdown)を指すため、エージェントは着地した HTML からトークン効率の良い版へ直接移動できます。head のリンクはプリレンダリングされた HTML とともに配信されるため、`_headers` を無視しカスタムのレスポンスヘッダーをまったく送信できないホスト（GitHub Pages、S3）でも機能します。エージェントがどのページから入ってきても同じです。

### API カタログ

サイトが API を公開している場合、Blume は `/.well-known/api-catalog` に [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) の API カタログを生成します。これは[リンクセット](https://www.rfc-editor.org/rfc/rfc9264)で、エージェントがドメインだけから API を列挙できるようにするもので、登録済みの `application/linkset+json` メディアタイプで、あらゆるビルド面において配信されます。設定は不要で、カタログは `blume.config.ts` にすでにある情報から導出されます。各 [OpenAPI または AsyncAPI リファレンス](/docs/advanced/api-reference)は、レンダリングされたドキュメントのルートをアンカーとするエントリーになり、`service-doc` がそのドキュメントを、`service-desc` が仕様（取得可能な URL にある場合）を指します。サイト自身の [JSON API](#json-api) は、その `/openapi.json` によって記述されるエントリーになります。そして [MCP サーバー](#mcp-server)は、ディスカバリー文書をサービス記述とするエントリーになります。

```json .well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://docs.example.com/reference",
      "service-doc": [
        { "href": "https://docs.example.com/reference", "type": "text/html" }
      ],
      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
    },
    {
      "anchor": "https://docs.example.com/api/docs",
      "service-desc": [
        {
          "href": "https://docs.example.com/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://docs.example.com/mcp",
      "service-desc": [
        {
          "href": "https://docs.example.com/.well-known/mcp.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    }
  ]
}
```

API リファレンスも MCP サーバーもなく、[JSON API](#json-api) も無効にしているサイトではカタログは出力されません。中身が何もないからです。他と同じく、自分で用意した `public/.well-known/api-catalog` ファイルは生成されたものより優先されます。

### WebMCP

[WebMCP](https://webmachinelearning.github.io/webmcp/) は、ページがエージェント型ブラウザーに直接ツールを登録できるようにする新しいブラウザー API で、別途サーバー接続を必要としません。Blume のすべてのページは、ドキュメントの読み取り専用の機能をページのモデルコンテキストに登録します。`search_docs`（サイト検索）、`get_page`（ページの[生の Markdown](#raw-markdown)）、`list_pages`（[`llms.txt`](#llmstxt) の索引）です。スクリプトは非常に小さく、ツールが実際に呼び出されるまで検索の仕組みを読み込まず、この API がないブラウザーでは何もしません。現時点では [Chrome の早期プレビュー](https://developer.chrome.com/blog/webmcp-epp)以外のすべてのブラウザーが該当します。登録は、流動的な仕様が公開しているいずれかの面（`navigator.modelContext` または `document.modelContext`）に対して、`provideContext` またはツールごとの `registerTool` 経由で行われます。

既定で有効です。オプトアウトするには `webmcp: false` を設定します。

```ts blume.config.ts lineNumbers
ai: {
  webmcp: false,
}
```

### スキルのディスカバリー

プロジェクトが[エージェントスキル](https://agentskills.io)を同梱している場合（[Blume のリポジトリ自体もそうです](#agent-skill)）、それらを格納しているディレクトリを `ai.skills` に指定すると、ビルドが [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) に従ってディスカバリー用に公開します。

```ts blume.config.ts lineNumbers
ai: {
  skills: "./skills",
}
```

パスはプロジェクトルートからの相対で解決され、`SKILL.md` を含む各サブディレクトリが公開されるスキルになります。`SKILL.md` 単体のスキルは `/.well-known/agent-skills/<name>/SKILL.md` にそのままコピーされます（`type: "skill-md"`）。補助リソース（`scripts/`、`references/`、`assets/`）を伴うスキルは決定的な `.tar.gz` にまとめられ（`type: "archive"`）、展開後に相対参照が解決されるようにし、スクリプトの実行ビットも保持されます。`/.well-known/agent-skills/index.json` のディスカバリー索引には v0.2.0 の `$schema` と、スキルごとの名前、タイプ、説明（`SKILL.md` のフロントマターから）、成果物の URL、クライアントがダウンロードを検証するための SHA-256 ダイジェストが含まれます。

`name`/`description` が欠けていたり仕様に反していたりするスキルは、壊れた状態で公開する代わりにビルド警告を出してスキップされます。また、自分で用意した `public/.well-known/agent-skills/index.json` があれば、この面全体を置き換えます。

### DNS ベースのディスカバリー（DNS-AID）

[DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) は策定中の IETF ドラフトで、well-known な DNS のエントリーポイントにある ServiceMode の [SVCB/HTTPS レコード](https://www.rfc-editor.org/rfc/rfc9460)を照会することで、エージェントが HTTP リクエストを 1 度も送らずにサイトの AI 関連機能を発見できるようにします。DNS レコードはビルドではなくあなたのゾーンにあるため、これは Blume が代わりに公開できない唯一のディスカバリー面です。DNS プロバイダー側でレコードを追加してください。

```txt
_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
```

プロバイダーが提供していれば `HTTPS` レコードタイプを使い（Vercel DNS は対応していますが、素の `SVCB` タイプには対応していません）、そうでなければ `alpn` と `port` パラメーターを持つ ServiceMode の `SVCB` レコードを使ってください。ドラフトは、検証を行うリゾルバーが認証済みの応答を返せるように、DNSSEC でゾーンに署名することも推奨しています。Cloudflare のようなプロバイダーはワンクリックで有効化できますが、まったく対応していないところ（Vercel DNS を含む）もあります。

`blume audit --url <origin>` がこれを代わりに確認します。[`deployment.site`](/docs/deployment) が設定されている場合、ネットワーク層が DNS-over-HTTPS 経由でエントリーポイントを照会し、レコードが存在しなければ公開すべき正確なレコードを、加えて応答が DNSSEC で認証されているかどうかを報告します。ネットワークがパブリックなリゾルバー（Google、Cloudflare）をブロックしている場合は、`BLUME_DOH_URL` を設定して独自のリゾルバーを参照させてください。

### Web Bot Auth

[Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) は逆方向に働きます。エージェントがあなたのドキュメントを読むためのものではなく、**あなたの組織のエージェントが**他所へリクエストを送るときに**自らを識別する**ためのものです。エージェントは [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421) でリクエストに署名し、受信側のサイトはあなたのドメインで公開された公開鍵ディレクトリに照らして検証します。組織がエージェントを運用していて、Blume のサイトがそのエージェントが名乗るドメインにあるなら、公開鍵を公開してください。

```ts blume.config.ts lineNumbers
ai: {
  webBotAuth: {
    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
  },
}
```

すると Blume は、あらゆるビルド面で `/.well-known/http-message-signatures-directory` に登録済みのメディアタイプで JWKS を配信します。このディレクトリは定義上公開されるものなので、設定は公開鍵しか受け付けません。秘密情報（`d`、`p`、`q` など）を含む JWK は、漏洩した資格情報を配信する代わりにエラーで検証に失敗します。Ed25519 の鍵ペアは次のように生成します。

```bash
node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
```

公開 JWK は上記の設定に入れ、秘密鍵は署名を行うエージェントが動作する場所（シークレットマネージャー。リポジトリには決して置かないでください）に配置します。組織がエージェントを運用していない場合は、これをスキップしてください。空のディレクトリは、検証する価値のあるものを何も告知しません。

`blume.config.ts` はビルド時に実行されるため、鍵をハードコードする必要はありません。ビルド時の環境変数から読み込めば、設定ファイルに鍵の塊を含めずに済み、コミットなしでローテーションできます。

```ts blume.config.ts lineNumbers
const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;

export default defineConfig({
  ai: {
    webBotAuth: {
      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
    },
  },
});
```

この変数がない環境ではディレクトリは公開されず、この方法で読み込まれた鍵もインラインの鍵とまったく同じように検証されます（秘密情報のチェックを含みます）。（公開鍵は秘密ではないので、インラインでコミットしても同じく問題ありません。環境変数は使い勝手の選択であって、セキュリティ上の選択ではありません。）

## エージェントスキル

コーディングエージェントの助けを借りて Blume サイトを構築していますか。Blume の[エージェントスキル](https://docs.claude.com/en/docs/claude-code/skills)をインストールすれば、あなたが説明しなくてもエージェントが Blume の仕組みを理解できます。

```bash
npx skills add haydenbleasel/blume
```

このスキルは、Blume とは何か、サイトのスキャフォールド・執筆・設定をどう行うかをエージェントに教え、インストール済みパッケージに同梱された完全なドキュメント（パッケージマネージャーがインストールした場所にある `blume` 内の `docs/` ディレクトリ）を参照させます。

これは [Blume が同梱するエージェントスキル](/docs/advanced/skills)の 1 つで、スケジュール実行されるエージェントによってドキュメントを製品と同期させ続けるスキルも併せて提供されています。

---

# アナリティクス
Source: https://useblume.dev/ja/docs/configuration/analytics

Blume は `blume.config.ts` の単一の `analytics` ブロックからアナリティクスを注入します。Vercel Web Analytics と PostHog はファーストクラスでサポートされ、`scripts` というエスケープハッチによって他のあらゆるプロバイダー（Plausible、Fathom、Google Analytics、Umami など）に対応できます。

アナリティクスが読み込まれるのは**本番ビルドのみ**です。スクリプトは `blume build` によって出力され、`blume dev` では決して出力されません。そのため、ローカルのトラフィックがダッシュボードに届くことはなく、別途「開発用」プロジェクトを用意する必要もありません。

:::note
アナリティクスはオプトインです。`analytics` ブロックがない場合、Blume は何も注入しません。
:::

## Vercel Web Analytics

[Vercel Web Analytics](https://vercel.com/docs/analytics) を追加するには `vercel: true` を設定します。Blume は Vercel のファーストパーティスクリプトを注入します。このスクリプトは、Vercel ダッシュボードでプロジェクトの Web Analytics を有効にすると、あなた自身のドメインから配信されます。

```ts blume.config.ts lineNumbers
analytics: {
  vercel: true,
}
```

キーは不要です — スクリプトはデプロイ先のプロジェクトにレポートします。これは `/_vercel/insights` エンドポイントが存在する Vercel のデプロイでのみデータを収集します。

## PostHog

[PostHog](https://posthog.com) を追加するには、**プロジェクト API キー**を指定します。ホストのデフォルトは PostHog Cloud US です。EU Cloud（`https://eu.i.posthog.com`）やセルフホストのインスタンスを使う場合は `host` を設定してください。

```ts blume.config.ts lineNumbers
analytics: {
  posthog: {
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // optional, this is the default
  },
}
```

プロジェクト API キーはブラウザに配信しても安全です — これは公開用の書き込み専用キーです。

## カスタムスクリプト

他のアナリティクスプロバイダーを読み込むには `scripts` を使用します。各エントリは 1 つの `<script>` タグをレンダリングし、`src`（外部）または `content`（インライン）の**どちらか一方だけ**を設定する必要があります。

```ts blume.config.ts lineNumbers
analytics: {
  scripts: [
    // Plausible
    {
      src: "https://plausible.io/js/script.js",
      strategy: "defer",
      attributes: { "data-domain": "example.com" },
    },
    // Fathom
    {
      src: "https://cdn.usefathom.com/script.js",
      strategy: "defer",
      attributes: { "data-site": "ABCDEFG" },
    },
    // An inline snippet
    {
      content: "console.log('analytics ready')",
    },
  ],
}
```

`attributes` はタグに展開される追加の HTML 属性（`data-*`、`id` など）のマップで、`strategy` は外部スクリプトに `async` または `defer` を追加します。

## オプション

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `vercel` | `false` | Vercel Web Analytics を追加します（Vercel のデプロイのみ）。 |
| `posthog.key` | — | PostHog のプロジェクト API キー。設定すると PostHog が有効になります。 |
| `posthog.host` | `https://us.i.posthog.com` | PostHog の取り込みホスト（EU Cloud またはセルフホスト）。 |
| `scripts[].src` | — | 外部スクリプトの URL。`content` とは排他的です。 |
| `scripts[].content` | — | インラインスクリプトの本文。`src` とは排他的です。 |
| `scripts[].strategy` | — | 外部スクリプトに対する `async` または `defer`。 |
| `scripts[].attributes` | — | `<script>` タグに展開される追加の HTML 属性。 |

3 つすべてを組み合わせることもできます — Vercel、PostHog、カスタムスクリプトを同時に有効にできます。ビルドしたサイトのデプロイについては、[デプロイ](/docs/deployment)を参照してください。

---

# カスタマイズ
Source: https://useblume.dev/ja/docs/configuration/customization

## コンポーネントの上書き

プロジェクトルートに `components.ts`（または `components.tsx`）を追加し、`defineComponents` をエクスポートします。`mdx` マップは組み込みコンポーネントを**置き換える**か、新しいコンポーネントを**追加**します — インポートなしですべての `.mdx` ページで利用できます。

```ts components.ts lineNumbers
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";
import Pricing from "./components/Pricing.astro";

export default defineComponents({
  mdx: {
    Callout, // replace the built-in Callout
    Pricing, // add a new <Pricing /> component
  },
});
```

キーは MDX 内で記述する名前です（`<Callout>`、`<Pricing>`）。React コンポーネントをインポートする場合は `.tsx` のファイル名を使用してください。

### 参照の形式

`mdx`、`layout`、`islands` のいずれにおいても、すべての上書きは 3 つの形式を受け付けます。

```ts components.ts
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";

export default defineComponents({
  mdx: {
    Callout, // 1. an imported component
    Note: "./components/Note.astro", // 2. a path string (resolved from the project root)
    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. a descriptor
  },
});
```

**ディスクリプタ**形式ではハイドレーションモードを追加できるため、インタラクティブな React／Vue／Svelte コンポーネントが JavaScript を配信し、クライアント側で動作するようになります。`client` モードがない場合、フレームワークコンポーネントは静的な HTML としてレンダリングされます。これは通常ミスであるため、Blume はそうしたケースを検出するとビルド警告を出力します。

| `client` | ハイドレーションのタイミング |
| --- | --- |
| `"load"` | ページ読み込み時に即座に |
| `"idle"` | メインスレッドがアイドル状態になったとき |
| `"visible"` | スクロールして表示領域に入ったとき |
| `"media"` | `media` クエリが一致したとき（`media: "(min-width: 40rem)"` を追加します） |
| `"only"` | クライアントのみ、サーバーレンダリングは行われません |

多くのページで使用するインタラクティブなコンポーネントについては、[`islands` グループ](/docs/content/islands#registering-islands-in-componentsts) が `client: "visible"` を指定したディスクリプタ形式の省略記法になります。

### 上書きの型付け

組み込みコンポーネントを置き換える際は、`blume/components` からそのプロップ型をインポートして、コンポーネントが契約に適合するようにしてください。型はコンポーネント自体から導出されるため、乖離することはありません。

```tsx components/Callout.tsx
import type { CalloutProps } from "blume/components";

export default function Callout(props: CalloutProps) {
  // …your own callout, same props as the built-in
}
```

プロップ型はコンテンツコンポーネント向けにエクスポートされています（`CalloutProps`、`CardProps`、`TabsProps`、`StepsProps`、`BadgeProps` など）。

## レイアウトスロット

`layout` マップは Blume のクロム（外枠 UI）の一部を独自のコンポーネントに置き換えます。各上書きは置き換え対象の組み込みコンポーネントと同じプロップを受け取るため、デフォルトをラップすることも、ゼロから作ることもできます。

```ts components.ts
import { defineComponents } from "blume";
import Footer from "./components/Footer.astro";
import Logo from "./components/Logo.astro";

export default defineComponents({
  layout: {
    Logo, // brand mark + title in the header
    Footer, // site-wide footer (no built-in — renders only when set)
  },
});
```

配線済みのスロット:

| スロット | 置き換え対象 | プロップ |
| --- | --- | --- |
| `Layout` | ページシェル全体（`RootLayout`） | 組み込みレイアウトが受け取るすべて、加えて `layout` マップ |
| `Header` | 上部のナビゲーションバー | `site`、`logo`、`navigation`、`route`、`searchEnabled` など |
| `Logo` | ヘッダー内のブランドリンク（マーク＋タイトル） | `site`、`logo` |
| `Search` | ヘッダーの検索トリガー＋モーダル | `navigation`、`strings`、`locale`、`askEnabled` |
| `Sidebar` | 主要なナビゲーションツリー | `items`、`currentRoute` |
| `MobileNav` | モバイルドロワー内のナビゲーション（デフォルトは `Sidebar`） | `items`、`currentRoute` |
| `Breadcrumbs` | パンくずリスト | `crumbs` |
| `TableOfContents` | このページの目次 | `headings`、`title`、`variant` |
| `Pagination` | 前後のページへのフッターリンク | `prev`、`next`、`strings` |
| `PageHeader` | 記事の上部への挿入ポイント（組み込みなし） | `page`、`headings`、`route` |
| `PageFooter` | 記事の下部への挿入ポイント（組み込みなし） | `page`、`headings`、`route` |
| `Footer` | コンテンツグリッドの後に配置されるサイト全体のフッター（組み込みなし） | `site`、`navigation`、`ui` |

`PageHeader`、`PageFooter`、`Footer` には組み込みコンポーネントがありません。設定するまで何もレンダリングされないため、プロモーションバナー、「最終更新日」の注記、マーケティング用フッターなどの便利な挿入ポイントになります。

レイアウトスロットは MDX の上書きと同じ[3 つの参照形式](#reference-form)を受け付けます。そのため、インタラクティブなヘッダーやフッターが必要な場合は、スロットにパス文字列やハイドレーション付きのディスクリプタ（`{ component, client }`）を指定できます。

## インタラクティブなアイランド

インタラクティブな UI（React、Vue、Svelte）については、コンポーネントを `islands/` フォルダーに配置すれば、任意の MDX ページで使用できます。Blume が自動的にハイドレートするため、ラッパーや登録は不要です。

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}
```

```mdx page.mdx
Use it anywhere: <Counter />
```

ハイドレーション戦略とフレームワークのセットアップについては [アイランド](/docs/content/islands) を参照してください。

## カスタムページ

`pages/` フォルダー配下に `.astro` ファイルを追加すると、ドキュメントと並んで完全なカスタムルートをマウントできます — ランディングページ、価格ページ、手作りのインデックスなどです。これらは配置場所を維持するため、相対インポートや `getStaticPaths` は通常どおり機能し、`blume:data` モジュールから設定、ナビゲーション、ルートを読み取ることができます。

完全なガイドは [カスタムページ](/docs/advanced/custom-pages) を参照してください。

## レジストリ

`blume add` は Blume がメンテナンスするコンポーネントを**ソース**としてプロジェクトにコピーします — そのコードはあなたのものであり、自由に編集できます。引数なしで実行すると、利用可能なものが一覧表示されます。

```bash
blume add
```

レイアウトスロット（ヘッダー、サイドバー、パンくずリスト、目次、ページネーション、フィードバック）や任意のコンテンツコンポーネント（コールアウト、カード、タブ、ステップ、アコーディオンなど）をインストールできます。

```bash
blume add callout
blume add pagination
```

コピーされたコンポーネントはフレームワークの残りの部分を `blume/*` からインポートするため、変更を加えるまでは組み込みのものとまったく同じようにレンダリングされます。`blume add` は登録用の `defineComponents` スニペットを出力します — コンテンツコンポーネントは `mdx` 配下、レイアウト部品は `layout` 配下です。

## Astro インテグレーション

`blume.config.ts` のトップレベルの `integrations` 配列から、任意の Astro インテグレーションを追加できます。まずサイトにインテグレーションをインストールしてください。Blume は生成されるランタイムの依存関係にそれを追加せず、Astro との互換性も管理しません。

```bash
npm install @astrojs/sitemap
```

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  integrations: [
    sitemap({
      filter: (page) => !page.includes("/drafts/"),
    }),
  ],
});
```

Blume は組み込みのインテグレーションを既存の順序のまま保持し、その後に宣言順であなたのエントリを追加します。並べ替えや重複排除は行わないため、同じ `name` を持つ 2 つのインテグレーションは両方とも実行されます。Blume は `integrations` が配列であることを検証し、各エントリの検証と無効なインテグレーションの報告は Astro が行います。

Blume はインスタンスをコピーするのではなく、生成された Astro 設定から `blume.config.ts` を再インポートすることでインテグレーションを読み込むため、設定モジュールは 1 回の実行につき 2 回評価されます — Blume が設定を読み込むときと、Astro がそれを読み込むときです。2 回目の評価が無害であるように、インテグレーションのファクトリは副作用のない状態に保ってください（インテグレーションを返すだけにし、構築時にファイルを書き込んだり接続を開いたりしないこと）。

同じインテグレーションが `blume dev` と `blume build` の両方で実行されます。`blume dev` の実行中に `blume.config.ts` を編集すると、隠れた Astro 設定が再生成され、設定の再起動がトリガーされます。編集したインテグレーションが反映されない場合は、`blume dev` を再起動してください。Blume はどの設定編集がインテグレーションに影響するかを判別できないため、`integrations` が空でなくなると、`blume.config.ts` へのすべての編集は — 無関係なフィールドへの編集であっても — ホットに適用されるのではなく開発サーバーを再起動します。Blume は `blume.config.ts` の内容のみを追跡するため、そこからインポートされる別ファイルを編集しても、それだけでは再生成はトリガーされません。そのような編集の後は `blume dev` を再起動してください。イジェクトした場合、所有することになる `astro.config.mjs` が `blume.config.ts` への相対的なブリッジを保持するため、設定されたインテグレーションは引き続き実行されます。完全な所有権を引き受ける一環として、後から Astro 設定へ直接移動することもできます。

## イジェクト

完全な制御が必要な場合は、生成されたランタイムを独立した Astro プロジェクトへイジェクトできます。

```bash
blume eject --yes
```

イジェクトは一方向のステップです。隠れた `.blume/` ランタイムが、あなたが所有し直接変更できる通常の Astro アプリになります。`blume` パッケージは引き続きインポート可能なので、そのコンポーネント、テーマ、Markdown プロセッサはそのまま使えます。

### イジェクトで失われるもの

イジェクト後、`build` スクリプトは素の `astro build` を実行します — サイト自体のビルド結果は同じですが、`blume build` が上に重ねていた成果物はもう生成されません。eject コマンドは、実際に設定で使用されているものについて警告します。それらを維持するには:

- **Pagefind 検索インデックス** — `search.provider: "pagefind"` を使用している場合、検索 UI はビルド済みサイトからインデックスを読み込むため、自分でインデックスを作成するまで本番環境で検索が機能しなくなります。`pagefind` を devDependency としてインストールし、各ビルドの後にインデックスを作成してください: `"build": "astro build && pagefind --site dist"`。
- **ホスト型検索の同期** — ホスト型プロバイダーのインデックスはビルド時にプッシュされなくなります。各ビルドの後に、プロバイダーの API または CLI で検索レコードを再アップロードしてください。
- **sitemap.xml** — 標準の [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) インテグレーションで再作成してください。
- **robots.txt** — 独自のものを `public/robots.txt` として配置してください。
- **llms.txt / llms-full.txt および agent-readability.json** — 手動で作成するか（もしくは独自のビルドステップで生成し）、`public/` から配信してください。
- **プラットフォームのリダイレクトファイル** — 静的ビルドで `_redirects` と `vercel.json` が出力されなくなります。リダイレクト自体は Astro が生成する meta-refresh ページとして引き続き機能しますが、ホスティング先の設定に移すこともできます。

---

# エクスポート
Source: https://useblume.dev/ja/docs/configuration/export

Blume は目次の下にある[ページアクション](/docs/content/navigation#page-actions)に **エクスポート** アクションを追加でき、読者が閲覧中のページを **PDF** または **EPUB** として保存できるようになります。デフォルトでは無効で、完全にクライアントサイドで動作します。サーバーは不要で、[静的](/docs/deployment)ビルドは静的なままです。

## 有効化する

ひとつのトグルで両方の形式を有効にできます。

```ts blume.config.ts
export: true,
```

片方の形式だけを提供したい場合は、代わりにオブジェクトを渡します。

```ts blume.config.ts
export: {
  pdf: true,
  epub: false,
},
```

省略した形式（または `false` に設定した形式）はメニューから除外されます。両方を無効にした場合（デフォルト）、**エクスポート** アクション自体が表示されません。

## PDF

**PDF にエクスポート** は、ヘッダー・サイドバー・ナビゲーションといったサイトのクロームを取り除いて記事本文だけにする印刷用スタイルシートを適用した状態で、ブラウザの印刷ダイアログを開きます。**PDF として保存** を選ぶと完了です。

実際にスタイルが適用されたライブページを印刷するため、結果として鮮明で選択可能なテキスト、本物のフォント、シンタックスハイライトされたコードがそのまま保たれます。依存関係は不要で、開発環境でも本番環境でも静的ホスティングでも同じように動作します。

:::note
PDF エクスポートはブラウザのネイティブな印刷ダイアログを経由するため、「PDF として保存」の正確な文言やオプションはブラウザによって異なります。コードブロックやコールアウトの背景を保持するには、ダイアログで **背景のグラフィック** を有効にしてください。
:::

## EPUB

**EPUB にエクスポート** は、現在のページの自己完結型 `.epub` をブラウザ内で生成してダウンロードします。Apple Books、Calibre、その他あらゆる電子書籍リーダーですぐに読めます。ジェネレーターは読者がエクスポートをクリックしたときにのみ読み込まれるため、サイトの他の部分に負荷をかけることはありません。

スタイルシートや JavaScript を持たないデバイス上でも読みやすいファイルにするため、Blume はページをクリーンで独立した HTML に書き換えます。シンタックスハイライトされたコードはプレーンな等幅テキストになり、装飾用のアイコンやコピーボタンは削除され、組み込みの電子書籍リーダー用スタイルシートが余白・コードブロック・テーブルを処理します。

## エクスポートされる範囲

どちらの形式も、読者が閲覧している **単一のページ** をエクスポートします。サイト全体ではありません。これは、アクションが配置されている場所、つまりそのページの目次の下という位置づけと一致しています。

:::note
EPUB にはタブを切り替えるための JavaScript がないため、[package-install](/docs/content/syntax) ブロックやコードグループなどのタブ付きコンテンツは、すべてのパネルが同時に表示されるように展開されます。Mermaid ダイアグラムのようなクライアントサイドでレンダリングされる埋め込みは含まれません。
:::

---

# 検索
Source: https://useblume.dev/ja/docs/configuration/search

Blume は、ホストされたインフラも API キーも不要なローカル検索を標準搭載しています。ブラウザ内で動作し、`blume dev` と `blume build` の両方で機能し、実際のコンテンツのみをインデックス化します — ナビゲーションの装飾部分や除外されたページはスキップされます。ローカル検索では足りなくなったら、検索の見た目や挙動を変えることなく、ホスト型やセマンティックのバックエンドに切り替えられます — 変わるのは設定する `search.provider` だけです。

Blume は Fumadocs のプロバイダー群と同等の対応範囲を実現しています: **Orama**、**FlexSearch**、**Algolia**、**Orama Cloud**、**Typesense**、**Mixedbread**(さらに **Pagefind**)。設定したプロバイダーの SDK だけがプロジェクトにインストールされるため、あるバックエンドを選んでも他のバックエンドが取り込まれることはありません。

## 検索の使い方

<Badge variant="accent">⌘K</Badge>(または `Ctrl
K`)で検索を開くか、入力フィールドにフォーカスしていないときに `/`
を押します。`Esc` で閉じ、`⌘J`(または `Ctrl
J`)で結果のプレビューペインを切り替えます。

クエリはページの**タイトル**、**説明**、**本文**にマッチし、タイトルへのマッチが最も高くランク付けされ、説明が本文より上位になります。

## 人気ページ

読者がクエリを入力する前に、検索ダイアログには**人気**リストが表示されます。デフォルトではサイドバーの最初の 6 ページですが、複数タブのサイトでは意図しないセクションが表示されがちです。代わりに表示したいリンクを固定しましょう:

```ts blume.config.ts lineNumbers
search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},
```

各エントリは `href`(内部ルートまたは外部 URL)と `label` を取り、オプションで `icon` を指定できます — [組み込みアイコン](/docs/content/components#icon)名、画像パス/URL、またはインライン SVG(ナビアイコンと同じ*入力形式*)で、デフォルトはファイルのグリフです。`popular` を省略するか空のままにすると、サイドバーのフォールバックが維持されます。

`href` はサイトがルートにマウントされているかのように書いてください — `basePath` は自動的に適用され、`navigation.featured` と同じ扱いです。外部 URL はそのまま通されます。

> **Warning**
>
> キュレーションされたリストは、すべての言語で共有される単一のリンク集です。
> `i18n`
> が設定されたサイトでは、サイドバーのフォールバックは読者のロケールに従いますが、
> `popular` のエントリはその `href` が指す場所にリンクします —
> そのため、すべての読者を その 1
> つの言語に送りたい場合にのみ、ロケールプレフィックス付きのルートを固定してください。

## インデックス化される内容

Orama、FlexSearch、Algolia、Orama Cloud、Typesense — そして MCP サーバーの `search_docs` ツール — については、Blume は各ページのタイトル、説明、そしてプレーンテキストに変換された本文をインデックス化します: コードブロック、画像、マークアップは取り除かれるため、検索結果の関連性が保たれます。これらのインデックスはソースファイルから構築されるため、開発環境と本番環境で同一です。Pagefind は代わりにビルドされた HTML をインデックス化し、Mixedbread は生の Markdown を同期するため、どちらも常にコードも検索対象になります。

オプション名、メソッド名、エラー名といった検索可能な用語をコード例に頼っているドキュメントでは、フェンス付きコードをソースから構築されるインデックスにオプトインしてください:

```ts blume.config.ts lineNumbers
search: {
  indexing: {
    includeCodeBlocks: true,
  },
},
```

各フェンスの本文とタイトル(上記の `blume.config.ts`)が検索可能になります。言語やフェンスのマーカーは対象外です。`.mdx` ページでは、インデックスはコンポーネントを表示されるテキストとして読み取ります — Card のタイトル、Tab のラベル、TypeTable の説明 — これには[エージェント向けの出力](/docs/configuration/ai)と同じシリアライザーが使われるため、`ai.markdownComponents` のエントリは独自のコンポーネントにも適用されます。このオプションは Pagefind と Mixedbread には影響しません。フェンス付きコンテンツが増えるにつれてインデックスも大きくなることに注意してください — クライアントインデックスはすべての読者に配信され、ホスト型プロバイダーにはレコードサイズの上限があり(Algolia は 1 ページのレコードがプランの上限を超えると同期バッチを拒否し、以前のインデックスが有効なまま残ります)、フェンス内でのヒットは検索結果の抜粋にフラット化されたコードとして表示されます。

[バージョン管理された](/docs/content/versioning)サイトでは、結果はデフォルトで閲覧中のバージョンに絞り込まれ、ダイアログのフッターに「すべてのバージョン」の切り替えが表示されます(読者ごとに記憶されます)。他バージョンのヒットは行にそのバージョン名が表示されます。Orama、FlexSearch、Algolia、Typesense はこの絞り込みに対応しています — ホスト型のレコードは `version` ファセットを持ち、現在のドキュメントは `"current"` としてアップロードされます — 一方 Pagefind は、そのロケールの挙動と同様に絞り込みなしのままです。

## タグ

ページのフロントマターに `search.tags` を追加すると、検索ダイアログのフィルターの下にそのページがグループ化されます — 読者はクリック 1 つで結果をタグで絞り込めます。タグはホスト型プロバイダーではファセットにもなります。

```yaml
search:
  tags: [api, reference]
```

## プロバイダー

クライアントサイドのプロバイダーはキー不要で、追加の設定は必要ありません。ホスト型のプロバイダーは `blume.config.ts` に**公開**クレデンシャル(ブラウザに配布しても安全)を受け取り、ビルド時に環境変数から**シークレット**の管理キーを読み取ります — シークレットが設定ファイルやクライアントバンドルに含まれることはありません。

### Orama(デフォルト)

Blume のデフォルトエンジンです。`/blume-search.json` で配信される JSON インデックスを構築し、ブラウザ内でクエリを実行します — 即座に動作するクライアントサイド検索で、`blume dev` では編集に合わせてライブで更新されます。キーもサービスも不要です。

```ts blume.config.ts lineNumbers
search: {
  provider: "orama", // default
}
```

#### 非ラテン文字の文字体系

Orama の標準トークナイザーは、基本的なラテン文字、数字、そしてわずかなアクセント付き母音しか保持しないため、それ以外の文字体系のテキスト — 日本語、中国語、韓国語、タイ語はもちろん、同様にロシア語、ギリシャ語、ヘブライ語、ヒンディー語も — は本来まったくマッチしません。Blume はこれを自動的に処理します: [`i18n.defaultLocale`](/docs/content/i18n) が非ラテン文字の文字体系に解決される場合、インデックスは単語分割トークナイザー(ブラウザと Node にネイティブな `Intl.Segmenter` をベースに構築)に切り替わります。サイトの言語を宣言するだけで済みます:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}
```

同じトークナイザーが検索ダイアログ、MCP サーバーの `search_docs` ツール、Ask AI のグラウンディングにも使われます。判断の基準になるのは言語名ではなく文字体系です — `az-Cyrl` は分割され、`sr-Latn` は分割されません — そしてインデックス全体を決めるのはデフォルトロケールです: 複数言語が混在するサイトでは、すべてのページがデフォルトロケールのトークナイザーを共有します。デフォルトが非ラテン文字であれば、これは安全です。ラテン文字の単語は分割処理を経ても無傷で残るため、英語のページはデフォルト言語のページと並んで検索可能なままです。逆は成り立ちません: デフォルトがラテン文字のサイトでは、非ラテン文字の翻訳は検索できません。ダイアクリティカルマークを多用するラテン文字の言語(ベトナム語や、ラテン文字表記のセルビア語)も標準トークナイザーでは不利になります — わずかなアクセント付き母音しか正規化せず、それ以外では単語を分割してしまうためです。

日本語と中国語はさらに一歩進んだ処理が行われます。分割だけでは複合語がその構成要素としてインデックス化されてしまいます — 資金決済法が 資金、決済、法 になる — その結果、各構成要素をどこかで言及しているだけのページが、その用語を実際に扱っているページより上位に来てしまいます。そのため、漢字、ひらがな、カタカナはオーバーラップする文字ペアとしてインデックス化され、これらのインデックスに対するクエリは、用語のペアをまとめて含むページを優先し、すべてのペアを含むページがない場合は任意のペアのマッチに緩和されます。これにより、文全体を入力しても最も近いページが返されます。韓国語とタイ語は分割された単語のまま維持されます。

### FlexSearch

キー不要のクライアントサイドのもう 1 つの選択肢です。Orama が配信するのと同じ `/blume-search.json` インデックスを再利用し、ブラウザ内で [FlexSearch](https://github.com/nextapps-de/flexsearch) のドキュメントインデックスを構築します。`blume dev` と `blume build` の両方で動作します。

FlexSearch には同等の分割フックがないため、非ラテン文字の文字体系のサイトでは、Orama(デフォルト)か [Pagefind](#pagefind) を選ぶことをおすすめします。Pagefind の `pagefind_extended` バイナリは幅広い言語をインデックス化し、中国語、日本語、韓国語をネイティブに分割します。

```ts blume.config.ts lineNumbers
search: {
  provider: "flexsearch",
}
```

### Pagefind

非常に大規模なドキュメントには [Pagefind](https://pagefind.app) を選択できます。ビルドされた HTML をインデックス化し、インデックスをシャード単位でオンデマンドに読み込むため、サイトがどれだけ大きくなっても初期ペイロードは小さいまま保たれます。

```ts blume.config.ts lineNumbers
search: {
  provider: "pagefind",
}
```

Pagefind は `blume build` の実行中のみ動作するため、このプロバイダーでは `blume dev` で検索を利用できません。

### Algolia

ブラウザが検索専用キーで [Algolia](https://www.algolia.com) に直接クエリを実行します。`blume build` のたびに、`ALGOLIA_ADMIN_API_KEY` の管理キーを使ってインデックスが置き換えられます(未設定の場合、ビルドは警告を出してアップロードをスキップします)。同期のたびにインデックス全体が置き換えられるため、削除やリネームしたページが古い検索結果として残ることはありません。

```ts blume.config.ts lineNumbers
search: {
  provider: "algolia",
  algolia: {
    appId: "YOUR_APP_ID",
    indexName: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
  },
}
```

### Orama Cloud

ホスト型の Orama です。ブラウザは公開 API キーを使ってインデックスのエンドポイントにクエリを実行し、`blume build` は `ORAMA_PRIVATE_API_KEY` を使ってレコードをインデックスにプッシュします。同期を有効にするには `indexId` を設定してください。

```ts blume.config.ts lineNumbers
search: {
  provider: "orama-cloud",
  oramaCloud: {
    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
    apiKey: "YOUR_PUBLIC_API_KEY",
    indexId: "your-index-id", // for the build-time sync
  },
}
```

### Typesense

セルフホストまたはクラウドの [Typesense](https://typesense.org) です。ブラウザは検索専用キーでコレクションにクエリを実行し、`blume build` は `TYPESENSE_ADMIN_API_KEY` を使ってコレクションを再作成し、ドキュメントをインポートします。同期のたびにコレクションは削除・再構築されるため、削除やリネームしたページが古い検索結果として残ることはありません — コレクションの設定を手動で調整している場合は、ビルド後に再適用してください。

```ts blume.config.ts lineNumbers
search: {
  provider: "typesense",
  typesense: {
    host: "xyz.a1.typesense.net",
    collection: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
    // port + protocol default to 443 / https
  },
}
```

### Mixedbread

[Mixedbread](https://www.mixedbread.com) によるセマンティック検索です。クエリはキーを保持する生成された `/api/search` エンドポイントを経由してプロキシされるため、このプロバイダーは**サーバー出力が必須**です(`deployment.output: "server"`)。エンドポイントは `MIXEDBREAD_API_KEY` を読み取ります。ビルド時に Mixedbread CLI でコンテンツをストアに同期してください。例: `mxbai vs sync <STORE_ID> ./content --ci`

```ts blume.config.ts lineNumbers
search: {
  provider: "mixedbread",
  mixedbread: {
    storeId: "YOUR_STORE_ID",
  },
}
```

### 検索の無効化

```ts blume.config.ts lineNumbers
search: {
  provider: "none",
}
```

## ページの除外

インデックス可能なページのみが検索対象になります。フロントマターで `search.exclude` を設定したページはインデックスから除外されます:

```yaml
search:
  exclude: true
```

[非表示ページ](/docs/content/navigation#hidden-pages)もデフォルトで除外されます。それでもインデックス化したい場合は、オプトインしてください:

```ts blume.config.ts lineNumbers
search: {
  indexing: { includeHiddenPages: true },
}
```

---

# SEO
Source: https://useblume.dev/ja/docs/configuration/seo

Blume は発見性レイヤーを代わりに処理します。ページのメタデータ、ソーシャル共有画像、フィード、構造化データです。設定可能な機能は `blume.config.ts` の `seo` キーの下にあり、メタデータはコンテンツによって駆動されます。

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
  x: { handle: "@acme" },
}
```

これらの多くは絶対サイト URL があるとより効果的です。[`deployment.site`](/docs/deployment) を設定すると、フィード、OG 画像、canonical、サイトマップ、JSON-LD が完全な URL を出力できるようになります。

## メタデータ

すべてのページは、設定とフロントマターから標準的な `<head>` タグをレンダリングします。

- `<title>` — ページタイトルとサイトの `title`。
- `<meta name="description">` と `og:description` — ページの `description`。未設定の場合はサイトの `description` にフォールバックします。
- `og:title` と `og:site_name` — ページタイトルとサイトの `title`。
- `<link rel="canonical">` と `og:url` — ページの絶対 URL（`deployment.site` が設定されている場合）。
- `og:type` — ブログ記事と変更履歴エントリーでは `article`、それ以外では `website`。記事ページはページの `date` と最終更新タイムスタンプから `article:published_time` と `article:modified_time` も出力します。
- `og:image` — そのページの [OG 画像](#open-graph-images)。生成されたカードは `og:image:width`、`og:image:height`、`og:image:type`、`og:image:alt` も宣言するため、クローラーは先に取得しなくてもカードをレイアウトできます。自分で指定した `seo.image` は、サイズと形式が不明なためこれらを一切宣言しません。
- `twitter:card`、`twitter:title`、`twitter:description`、`twitter:image` — X のカード。画像のあるページはワイドな `summary_large_image` バリアントになり、画像のないページも素のリンクとして表示されるのではなくコンパクトな `summary` カードになります。

### X のアトリビューション

X はカードのその他の情報をすべて `og:*` タグから読み取るため、推測できない値はクレジットするアカウントだけです。`seo.x` の下に設定すると、Blume は `twitter:site`（サイトのアカウント）と `twitter:creator`（著者のアカウント）を出力します。`@` は省略可能で、`acme` と `@acme` のどちらでも動作します。

```ts blume.config.ts lineNumbers
seo: {
  x: { handle: "@acme", creator: "@jane" },
}
```

ページ単位で独自の著者を指定できます。ゲスト投稿にはこれが適しています。

```yaml lineNumbers
---
title: How we shipped it
seo:
  x:
    creator: "@guestauthor"
---
```

その他のタグは `seo` フロントマターでページごとに上書きできます。

```yaml lineNumbers
---
title: Pricing
description: Plans and pricing for every team size.
seo:
  title: Pricing — Acme
  canonical: https://acme.com/pricing
  noindex: false
---
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.title?` | `string` | - | このページの <title> と og:title を上書きします。 |
| `seo.description?` | `string` | - | meta と og:description を上書きします。 |
| `seo.image?` | `string` | - | カスタムのソーシャル画像（Open Graph を参照）。 |
| `seo.canonical?` | `string` | - | canonical URL を上書きします。 |
| `seo.noindex?` | `boolean` | - | robots noindex を出力し、構造化データをスキップします。 |
| `seo.x.creator?` | `string` | - | このページを特定の X アカウント（twitter:creator）にクレジットし、設定の seo.x.creator を上書きします。 |

## Open Graph 画像

Blume はビルド時にすべてのページ用の 1200×630 のソーシャルカードをレンダリングできます。[Takumi](https://takumi.kane.tw) のおかげでヘッドレスブラウザは不要で、ビルドは高速なままです。[`deployment.site`](/docs/deployment) が設定されるか自動検出されるとデフォルトで有効になり（`og:image` の URL がクローラーにとって有用であるためには絶対 URL である必要があります）、それ以外では無効です。`enabled` を設定すればどちらにも上書きできます。

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}
```

### 生成カードのブランディング

ローカルの SVG とカラーパレットを設定して、生成カードをブランドに合わせましょう。ロゴは `public/` またはプロジェクトのルートに配置できます。パレットの値を省略すると、その項目はデフォルトのままになります。

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

デフォルトでは、各カードはコンテンツとテーマから導出されます。**ページタイトル**が見出し、**ページの説明**がサブタイトル（`og:description` と同じテキストなので、`description` よりも `seo.description` が優先されます）、**サイトタイトル**がアイブロウ、テーマの**アクセント**がマークになります。画像は各ルートを反映した `/og/<slug>.png` で配信され、サーバーモードでも静的ファイルとしてプリレンダリングされます。

| ページのルート      | 画像 URL                   |
| ------------------- | -------------------------- |
| `/`                 | `/og/index.png`            |
| `/quickstart`       | `/og/quickstart.png`       |
| `/configuration/ai` | `/og/configuration/ai.png` |

任意のページで生成カードを上書きするには `seo.image` を使います。`public/` 内のファイルか外部 URL を指定できます。これは生成カードより優先され、`og` が無効でも機能するため、カスタム画像と生成画像を混在させられます。

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
パレットの各色は任意の CSS カラーを受け付けます。16 進数、`oklch(…)`、`rgb(…)` などです。アクセントは [`theme.accent`](/docs/configuration/theming#accent) と同じく、名前付きプリセット（`blue`、`teal`、…）も受け付けます。レンダラーが解析できない色は、デフォルト色のカードを黙って出荷するのではなくビルドを失敗させます。
:::

ページタイトルやサイトタイトルに含まれる絵文字は、カードのレンダリング中に CDN から取得される [Twemoji](https://github.com/jdecked/twemoji) のグリフとして表示されます。そのため、タイトルに絵文字を含むビルドにはネットワークアクセスが必要です。各グリフは、いくつのページで使われていてもビルドごとに 1 回だけ取得されます。

### カードのレイヤーを表示・非表示・上書きする

見出しに加えて、カードには 3 つのオプションレイヤーがあります。左上の**ブランドマーク**（ロゴ、またはサイトタイトルの頭文字を入れたアクセントタイル）、見出しの下の**サブタイトル**（ページの `description`、説明のないページではサイトの `description`）、そしてリポジトリのスラッグ（`github` から）とサイトの URL を含む**フッター**です。フッターの URL はデプロイサイトのホストに [`deployment.base`](/docs/deployment#subpath-deploys) を加えたもので、GitHub Pages のプロジェクトサイトなら `user.github.io/repo` と表示されます。いずれも独自の文字列で上書きするか、`false` で非表示にできます。

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}
```

### カードのフォント

デフォルトでは、カードは Takumi の組み込みフォントでレンダリングされます。このフォントはラテン文字のグリフのみをカバーしているため、他の文字体系（日本語、中国語、韓国語、アラビア語など）のタイトルは豆腐（空の四角）として表示されてしまいます。

**[`theme.fonts`](/docs/configuration/theming#fonts) を設定すればカードもそれに従います。** 設定で独自のフォントを選択すると、生成カードは自動的に見出しをディスプレイフォントで、説明とフッターをボディフォントでレンダリングするため、共有リンクがサイトと一致します。非ラテン文字のカバレッジも含めて、ここで設定するものは何もありません。（Google 以外のプロバイダーのファミリーはスキップされます — カードレンダラーは Google Fonts からしか取得できません — が、ローカルのフォントファイルは動作します。）

サイトとは異なるフォントをカードに使いたい場合や、テーマに手を加えずに文字体系のカバレッジを追加したい場合は、`og.fonts` を明示的に設定してください。これは常にテーマ由来のフォントより優先されます。

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

各エントリーは、Google Fonts のファミリー名、`weight`（数値、リスト、あるいは `"100..900"` のような可変範囲）と `style`（`"normal"`、`"italic"`、またはその両方）を固定するオブジェクト、またはローカルのフォントファイルです。`src` はプロジェクトルートからの相対で解決され、ファイル自身のメタデータに任せたくない場合は `weight` と `style` を任意で指定できます。

Google のファミリーはビルド時に取得されるため、それらを使うビルドにはネットワークアクセスが必要です。レンダラーは各タイトルが実際に使うグリフのサブセットのみを取得します。フォールバックはグリフ単位なので、ファミリーを追加しても影響するのは他のフォントで描画できないグリフだけです。

`og.fonts: []` を明示すると完全にオプトアウトになります。`theme.fonts` が設定されていても、カードは組み込みフォントのままです。

### カスタムページのタイトル

カスタムの [`.astro` ページ](/docs/advanced/custom-pages)には読み取るフロントマターがないため、生成カードのタイトルはルートの最後の URL セグメントを人間可読化したものになります。`/getting-started` は "Getting Started" になりますが、`/cli` は "Cli" になります。そうしたカードには `og.titles` でルートをキーにして明示的に名前を付けてください（`"/"` はホームを指し、そのカードは指定しない場合サイトタイトルを表示します）。

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

エントリーはカスタムページにのみ適用されます。コンテンツページのカードは常にページタイトルから見出しを取るため、そちらはフロントマターで改題してください。

`seo.image` はフロントマターなので、Markdown と MDX のコンテンツにしか適用されません。カスタムの [`.astro` ページ](/docs/advanced/custom-pages)（マーケティング用のホームやランディングページなど）に独自のソーシャル画像を設定する場合、そしてホームページだけに専用の共有画像を設定する方法としては、`PageLayout` に `ogImage` プロップを渡してください。

## RSS フィード

Blume は `rss.types` に指定された各コンテンツタイプ（デフォルトでは `blog` と `changelog`）のうち、ページが存在するものについて RSS フィードをビルドし、`/<type>/rss.xml` で配信します。日付付きのブログ記事や変更履歴エントリーの書き方については [フィード](/docs/content#feeds) を参照してください。

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

| オプション | デフォルト | 説明 |
| --- | --- | --- |
| `enabled` | `true` | フィードを生成します。 |
| `types` | `["blog", "changelog"]` | それぞれフィードを持つコンテンツタイプ。 |
| `limit` | `50` | フィードあたりの最大項目数（新しい順）。 |

Blume は `<link rel="alternate">` タグを挿入するので、ブラウザやフィードリーダーが自動的にフィードを検出します。

## 構造化データ

Blume はすべてのページの `<head>` に [schema.org](https://schema.org) の JSON-LD を出力し、検索エンジンがコンテンツを理解できるようにします。デフォルトで有効です。

```ts blume.config.ts lineNumbers
seo: {
  structuredData: true,
}
```

各ページには次のものが含まれます。

- サイトのアイデンティティを表す **WebSite** ノード、
- **article** としてのページ — ブログ記事は `BlogPosting`、変更履歴とドキュメントは `TechArticle` — その説明と公開日を伴います、
- ナビゲーションの経路から構築された **BreadcrumbList**。

`deployment.site` が設定されている場合、URL は絶対 URL になります。`seo.noindex` が指定されたページはスキップされます。

### サイトのアイデンティティ

WebSite ノードはサイトが存在することを示すだけで、それが*何*であるか、*誰*が運営しているかは示しません。しかし AI エージェントは、あなたを推薦したり引用したりする前に、まさにそれを知るために JSON-LD を読みます。2 つのオプションブロックがそれを補います。どちらも `deployment.site` を必要とします（これらのノードは絶対識別子を持つためです）。

```ts blume.config.ts lineNumbers
seo: {
  organization: {
    name: "Acme", // defaults to the site title
    email: "hello@acme.com",
    telephone: "+1 555 0100",
    address: { addressLocality: "Sydney", addressCountry: "AU" },
    logo: "/logo.svg",
    sameAs: ["https://github.com/acme", "https://x.com/acme"],
  },
  software: {
    license: "MIT",
    operatingSystem: "Node.js 22+",
    price: 0, // emitted as an Offer; 0 marks it free
    sameAs: ["https://www.npmjs.com/package/acme"],
  },
}
```

`organization` はすべてのページに **Organization** ノードを追加します。WebSite ノードと article ノードはこれを `publisher` として参照します。メールアドレスと電話番号は `ContactPoint`（`contactType` のデフォルトは `"customer support"`）として、住所は `PostalAddress` として出力されます。この 2 つのフィールドは事業者確認のチェックが探すものです。`name` と `url` はサイトのものがデフォルトになり、ルート相対の `logo` は他のページ URL と同様に絶対 URL 化されます。

`software` はホームページに **SoftwareApplication** ノードを追加します。製品の名前と説明（デフォルトはサイトのもの）、`applicationCategory`（デフォルトは `"DeveloperApplication"`）、オペレーティングシステム、ライセンス、`price` が設定されている場合は `Offer`、そして `sameAs` に含めるレジストリまたはリポジトリの URL です。`software: true` を渡すとすべてデフォルトが採用されます。organization が設定されている場合は、その `publisher` として参照されます。

## サイトマップ

Blume はビルド時に、インデックス可能なすべてのページを含む `sitemap.xml` を書き出します。絶対 URL の [`deployment.site`](/docs/deployment) が必要で、下書き、非表示、`noindex` のページを除くすべてのページを一覧します。[バージョン管理](/docs/content/versioning)されたサイトでは、canonical が公開中の同等ページを指しているアーカイブ済みのページも除外されます。インデックスすべきなのは公開中のページだからです。デフォルトで有効です。

```ts blume.config.ts lineNumbers
seo: {
  sitemap: true,
}
```

独自の `public/sitemap.xml` を配置すれば、それが使われます。Blume が `public/` に置いたファイルを上書きすることはありません。

## Robots

Blume は、すべてのクローラーを許可し、[コンテンツシグナル](#content-signals)を宣言し、サイトマップが利用可能な場合はそれを指す `Sitemap:` 行を追加した `robots.txt` を書き出します。デフォルトで有効です。

```ts blume.config.ts lineNumbers
seo: {
  robots: true,
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://docs.example.com/sitemap.xml
```

### コンテンツシグナル

`Content-Signal` 行 — 普及しつつあるコンテンツ利用の慣習 — は、AI クローラーがドキュメントをどのように再利用してよいかを宣言します。Blume は**デフォルトで有効にし、すべてのシグナルを `yes`** にして出力します。これは、ドキュメントは人間にもエージェントにも等しく開かれているという Blume の立場に沿ったものです。

- `search` — 従来型および AI による検索インデックス
- `aiInput` — 回答時のグラウンディング / RAG
- `aiTrain` — モデルの学習

いずれかのシグナルを制限するには `false` を設定します。指定しなかったものは `yes` のままです。

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: {
    aiTrain: false, // opt out of training, keep search + grounding
  },
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /
```

宣言を完全に削除するには `contentSignals: false` を設定します。

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: false,
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.contentSignals?` | `boolean \| object` | - | Content-Signal の宣言。true または省略ですべてのシグナルを yes として出力し、false で行を削除し、オブジェクトでシグナルを個別に設定します。 |
| `contentSignals.search?` | `boolean` | - | 検索インデックス（search）への利用を許可します。デフォルトは true。 |
| `contentSignals.aiInput?` | `boolean` | - | 回答時の AI グラウンディング / RAG（ai-input）への利用を許可します。デフォルトは true。 |
| `contentSignals.aiTrain?` | `boolean` | - | AI モデルの学習（ai-train）への利用を許可します。デフォルトは true。 |

コンテンツシグナルは意向を表明するものであり、アクセス制御ではありません。行儀の良いクローラーにコンテンツをどう扱ってほしいかを伝えるものであり、それを尊重するかどうかはクローラー側に委ねられます。

独自の `public/robots.txt` を配置すれば、それが使われます。

---

# テーマ設定
Source: https://useblume.dev/ja/docs/configuration/theming

Blume のテーマはトークン駆動で、ライトモードとダークモードにそのまま対応しています。必要な分だけ手を伸ばせます。よくあるケースにはいくつかの設定トークン、任意のデザイントークンを上書きするなら `theme.css`、カスタムコンポーネントには Tailwind ユーティリティを使えます。

## 設定トークン

日常的に使うつまみは、設定ファイルの `theme` の下にあります:

```ts blume.config.ts lineNumbers
theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}
```

### アクセント

アクセントカラーは、インタラクティブな要素や強調される要素に色味を加えます。ステップのマーカー、アクティブなタブ、バッジ、カードのホバーなどです。名前付きプリセット、または任意の CSS カラーを使えます:

```ts blume.config.ts lineNumbers
theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}
```

名前付きプリセット: `blue`（デフォルト）、`green`、`orange`、`pink`、`purple`、`red`、`teal`。

文字列を指定すると両方のカラーモードに適用されます。[モードごとに異なるアクセント](#dark-mode-colors)を設定したい場合はオブジェクトを渡してください。

### 角丸

`radius` は、カード、コードブロック、コールアウト、入力欄で共通して使われる角の丸みを設定します。`none`、`sm`、`md`（デフォルト）、`lg` のいずれかです。

### カラーモード

`mode` は初期のカラースキームを設定します:

- **`system`**（デフォルト） — 読者の OS の設定に従う
- **`light`** / **`dark`** — いずれかのスキームをデフォルトにする

ヘッダーのトグルで読者はいつでも切り替えられ、その選択は再訪時にも記憶されます。ダークモードは `<html>` 要素の `data-theme="dark"` 属性によって適用されます。

### フォント

`fonts` は 3 つの役割ごとに書体を設定します:

- **`display`** — 見出し（`h1`〜`h6`）
- **`body`** — 本文、UI、散文
- **`mono`** — コードブロックとインラインコード

見出しにはテーマ側でディスプレイ向けの字間（`-0.05em`）が設定されるため、`display` にどのフォントを選んでも — デフォルトの Inter のような本文向けフォントでも — フォント自体のトラッキングに頼らず、見出しサイズで正しく表示されます。

それぞれ厳選された Google Font がデフォルトになっているので、Blume は最初から意図のある見た目になります:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}
```

変更したい役割だけを設定してください。残りはデフォルトのままです:

```ts blume.config.ts lineNumbers
theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}
```

フォントは**セルフホスト**されます。Blume がビルド時にダウンロードして自分のサイトから配信するため、実行時に Google へのリクエストは発生せず、レイアウトシフトもありません（Astro がフォールバックのメトリクスに合わせた書体を自動生成します）。

素の文字列は、以下の厳選セットに含まれる Google Fonts のスラッグです:

| カテゴリ | スラッグ |
| --- | --- |
| サンセリフ | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
| セリフ | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4` |
| 等幅 | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono` |

#### 任意のプロバイダーのファミリー

厳選セットに含まれていないファミリー（たとえば非ラテン文字をカバーするもの）が必要ですか？ファミリーの正確な名前を指定したオブジェクトを渡してください。同じようにセルフホストされ、最適化されます:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}
```

- **`name`** — プロバイダーが表記しているとおりの正確なファミリー名。
- **`provider`** — ファミリーの提供元: `google`（デフォルト）、`fontsource`、`bunny`、`fontshare`。
- **`weights`** — 読み込むウェイト。数値、または `"100..900"` のような可変フォントの範囲で指定します。デフォルトは `[400, 500, 600, 700]`。
- **`subsets`** — 読み込む文字サブセット。プロバイダーの名前で指定します（`latin`、`latin-ext`、`vietnamese`、`cyrillic`、`greek` など）。デフォルトは `latin` に加えて、設定したロケールが必要とするもの — 詳しくは以下を参照してください。
- **`fallback`** — フォントの読み込み中や欠けているグリフに使われるシステムスタック: `sans`、`serif`、`mono`。mono の役割では `mono`、それ以外では `sans` がデフォルトです。

#### サブセットとロケール

Google、Bunny、Fontsource は各ファミリーを文字体系ごとのサブセットに分割しており、`@font-face` が生成されるのは読み込んだサブセットだけです。Blume はそのリストを [`i18n.locales`](/docs/content/i18n) から導き出します。ベトナム語、ポーランド語、ロシア語、ギリシャ語のロケールを持つサイトでは `latin` に加えて `vietnamese`、`latin-ext`、`cyrillic`、`greek` が読み込まれるため、ダイアクリティカルマークや非ラテン文字がシステムフォールバックではなく選んだフォントで表示されます。`i18n` ブロックがないサイトや、Latin-1 の言語だけのサイトでは `latin` のみが読み込まれます。ブラウザーはそのサブセットの文字をページが使っている場合にのみダウンロードし、プリロードも同じリストに従います。

導き出されたリストを上書きしたい場合は、ファミリーに `subsets` を設定します。たとえば、単一ロケールのサイトでコンテンツがそのロケールからは導かれない文字体系を必要とする場合です:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}
```

`inter` のような厳選スラッグもロケールから導かれたリストに従います。それらのファミリーでサブセットを固定したい場合もオブジェクト形式を使ってください。

#### ローカルのフォントファイル

自分が所有しているフォント（あるいはどのプロバイダーも配信していないフォント）は、プロジェクト内のフォントファイルを役割に指定します。各バリアントが 1 つの `@font-face` になります:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}
```

パスはプロジェクトルートからの相対で解決されます。`weight` と `style`（`normal`、`italic`、`oblique`）は省略可能です。省略した場合、Astro がフォントファイルから読み取ります。

:::note
`theme.fonts` を明示的に設定すると、display と body のフォントは生成される [Open Graph カード](/docs/configuration/seo#card-fonts)にも自動的に適用されるため、共有されたリンクがサイトと揃います。Google 以外のプロバイダーのファミリーはそこではスキップされます（カードのレンダラーは Google Fonts からしか取得できません）。ローカルファイルはどこでも動作します。
:::

システムスタックに戻したいですか？[`theme.css`](#themecss) で `--blume-font-*` トークンを直接上書きしてください。

### ダークモードの色

`accent` と `background` は 1 つのルールに従います。文字列は両方のカラーモードに適用され、`{ light, dark }` オブジェクトは各モードを個別に設定します:

```ts blume.config.ts lineNumbers
theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}
```

いずれの色も、名前付きプリセットまたは任意の CSS カラーを受け取ります。`background`（および `backgroundImage`）ではどちらのキーも省略でき、片方のモードだけを上書きできます。`background: { dark: "#0a0a0a" }` はライトモードの背景をデフォルトのままにします。

### アクションカラー

`action` は、主要なコールトゥアクションと `action` 系の Tailwind ユーティリティ（`bg-action`、`text-action`）に使われる二次的なアクセントです。デフォルトは `accent` と同じです:

```ts blume.config.ts
theme: {
  action: "#ff0066",
}
```

### 背景画像

`backgroundImage` でコンテンツの背後に背景画像を設定できます。URL か `public/` 配下のパスを指定します。色と同じく、文字列は両方のモードに適用され、`{ light, dark }` オブジェクトは各モードの画像を設定します:

```ts blume.config.ts lineNumbers
theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}
```

## theme.css

プロジェクトルートに `theme.css` を置くと、任意のデザイントークンを上書きできます。カスケードの最後のレイヤーなので、デフォルトや設定トークンよりも優先されます:

```css theme.css lineNumbers
:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}
```

ライトモード用のトークンは `:root` の下に、ダークモード用は `:root[data-theme="dark"]` の下に設定します。カラートークンにはダークセレクタのより高い詳細度で宣言された組み込みのダーク値があるため、`:root` だけで `--blume-accent`、`--blume-background` などを上書きしてもライトモードにしか適用されません。両方のモードを変えたい場合はダーク用のブロックも宣言してください。

`theme.css` はサイトの Tailwind エントリにインライン展開されるため、その中で Tailwind のディレクティブも使えます。モノレポで知っておきたいのが `@source` です。Blume はユーティリティクラスを求めてプロジェクトをスキャンしますが、兄弟のワークスペースパッケージからコンポーネントを import しているページでは、そのパッケージもスキャンする必要があります。`theme.css` からの相対パスで指定すれば — これは Tailwind の標準的なルールです — Blume がそのパスを生成されるスタイルシートに引き継ぎます:

```css theme.css lineNumbers
@source "../../packages/ui/src";
```

### デザイントークン

| トークン                    | 制御する対象                                |
| --------------------------- | ------------------------------------------- |
| `--blume-background`        | ページの背景                                |
| `--blume-foreground`        | 本文テキスト                                |
| `--blume-muted`             | 控えめな面 — コールアウト、テーブルヘッダー |
| `--blume-muted-foreground`  | 補助的なテキスト                            |
| `--blume-border`            | ボーダーと区切り線                          |
| `--blume-accent`            | アクセントカラー                            |
| `--blume-accent-foreground` | アクセント背景の上のテキストとアイコン      |
| `--blume-action`            | 二次的なアクセント（デフォルトは accent）   |
| `--blume-code-background`   | コードブロックの面                          |
| `--blume-radius`            | 角の丸み                                    |
| `--blume-font-display`      | 見出しのフォント                            |
| `--blume-font-body`         | 本文 / UI のフォント                        |
| `--blume-font-mono`         | コードのフォント                            |

厳選リスト外のフォントを使う、あるいはシステムスタックにフォールバックするには、`--blume-font-*` トークンに任意のフォントスタックを設定します:

```css theme.css lineNumbers
:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

## Tailwind ユーティリティ

Blume のテーマは内部的に Tailwind v4 で構築されており、プロジェクトの `.astro`、`.tsx`、`.jsx` ファイルもスキャンされます。そのため、Tailwind のセットアップなしで、カスタムコンポーネントやページをユーティリティクラスでスタイリングできます。すべてのトークンがユーティリティとして公開されているので、コンポーネントは自動的にテーマに追従します:

| トークン                    | ユーティリティ             |
| --------------------------- | -------------------------- |
| `--blume-background`        | `bg-background`            |
| `--blume-foreground`        | `text-foreground`          |
| `--blume-muted`             | `bg-muted`                 |
| `--blume-muted-foreground`  | `text-muted-foreground`    |
| `--blume-border`            | `border-border`            |
| `--blume-accent`            | `bg-accent`, `text-accent` |
| `--blume-accent-foreground` | `text-accent-foreground`   |
| `--blume-action`            | `bg-action`, `text-action` |
| `--blume-radius`            | `rounded-blume`            |
| `--blume-font-display`      | `font-display`             |
| `--blume-font-body`         | `font-sans`                |
| `--blume-font-mono`         | `font-mono`                |

## カスケードの順序

スタイルは 3 つのレイヤーで解決され、後のレイヤーが前のレイヤーを上書きします:

1. **ベース**

    Blume のリセット、デフォルトのトークン、コンポーネントのスタイル。

2. **設定トークン**

    `theme` から来る `--blume-accent`、`--blume-radius`、`--blume-font-*`
    トークン。

3. **theme.css**

    あなたによるトークンの上書き — 最終的な決定権を持ちます。

---

# ページ
Source: https://useblume.dev/ja/docs/content

ドキュメントは Markdown ファイルと MDX ファイルが入ったフォルダーにすぎません。Blume は各ファイルをページに変換します。ルーティング、ナビゲーション、メタデータはファイルシステムから推論されるため、同期を保つべきマニフェストは存在しません。

コンテンツは **コンテンツルート**（デフォルトは `docs/`。[`blume.config.ts`](/docs/configuration) の `content.root` で変更できます）配下に置きます。

## Markdown と MDX

Blume は 2 種類のファイルをレンダリングします。

- **`.md`** — 純粋な文章向けの Markdown: GFM、フロントマター、スマート句読点、上付き・下付き文字。
- **`.mdx`** — `.md` のすべての機能に加えて、[コンポーネント](/docs/content/components) と MDX 専用の[ディレクティブ、パッケージインストール、数式](/docs/content/syntax)。

ページが文章だけの場合は `.md` を、コンポーネントやディレクティブが必要な場合は `.mdx` を使いましょう。切り替えはファイル名を変更するだけです。

## ファイルとルート

各ファイルは、コンテンツルート配下のパスに応じてルートに対応付けられます。

| ファイル                  | ルート            |
| ------------------------- | ----------------- |
| `docs/index.mdx`          | `/`               |
| `docs/quickstart.mdx`     | `/quickstart`     |
| `docs/guides/theming.mdx` | `/guides/theming` |
| `docs/guides/index.mdx`   | `/guides`         |

ネストしたフォルダーはネストしたルートになり、フォルダー内の `index.mdx` はそのフォルダー自体のページになります。

## 数値プレフィックスによる並び替え

ファイルやフォルダーの先頭に数字を付けると、サイドバーでの順序を制御できます。プレフィックスは URL から取り除かれるため、リンクを壊さずにページを並べ替えられます。

```txt
01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation
```

並び順には複数の階層があります。優先順位の完全なルールは[ナビゲーション](/docs/content/navigation)を参照してください。

## グループフォルダー

フォルダー名を丸括弧で囲むと、URL セグメントを追加**せずに**、そのページ群をサイドバーでグループ化できます。

```txt
docs/(internal)/security.mdx  ->  /security
```

これらのページはサイドバー上で「Internal」グループを共有しますが、URL は括弧のないフラットなままです。

## 下書き

ページを下書きとしてマークすると、本番ビルドからは除外しつつ、`blume dev` ではプレビューできます。

```yaml lineNumbers
---
title: Work in progress
draft: true
---
```

`blume build` は下書きをスキップし、`blume dev` はレンダリングするので、公開前の作業を進められます。

## コンテンツタイプ

すべてのページには **タイプ** があり、フロントマターの `type` フィールドで設定します（デフォルトは `doc`）。タイプを使うと、Blume はページのグループごとに異なる扱いができます。中でも重要なのは、`blog` と `changelog` のページが[フィード](#feeds)にまとめられる点です。

```yaml lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---
```

タイプはファイルの置き場所とは独立していますが、慣例としてブログ記事は `blog/` 配下に、changelog エントリーは `changelog/` 配下に置きます。どちらも自動的に RSS フィードを取得し、changelog エントリーは生成された [`/changelog` タイムライン](/docs/advanced/changelog)にもまとめられます。それぞれの執筆方法については[ブログ](/docs/advanced/blog)と[Changelog](/docs/advanced/changelog)を参照してください。

## フィード

Blume は、[`rss.types`](/docs/configuration/seo#rss-feeds) に列挙された各コンテンツタイプ（デフォルトは `blog` と `changelog`）について、ページが 1 つ以上あれば自動的に RSS フィードを生成します。フィードは `/<type>/rss.xml` で配信されます。

| タイプ      | フィード             |
| ----------- | -------------------- |
| `blog`      | `/blog/rss.xml`      |
| `changelog` | `/changelog/rss.xml` |

各エントリーに `date` を指定すると、項目が新しい順に並び、`pubDate` が付与されます。クォートなしの YAML 日付でも問題ありません。Blume が正規化します。

```yaml lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---
```

フィードには絶対的なサイト URL が必要なので、[`deployment.site`](/docs/deployment) を設定してください。Blume はすべてのページに `<link rel="alternate">` タグを追加するため、ブラウザーやフィードリーダーが自動的にフィードを検出します。各コンテンツタイプの執筆方法については[ブログ](/docs/advanced/blog)と[Changelog](/docs/advanced/changelog)を参照してください。

## このページの内容

すべてのページには、見出しから自動的に生成される目次が付きます。画面が広い場合はコンテンツの横の固定サイドバーに表示され、狭い場合はページ上部の **このページの内容** パネルに折りたたまれます。スクロールすると、読んでいるセクションの項目がハイライトされるので、長いページでも現在位置が常に分かります。

Blume は各見出しをスラッグ化してアンカーにするため、すべての項目がそのセクションへ直接リンクします。また、URL にスラッグを付け加えることで任意の見出しへディープリンクできます（`.../my-page#getting-started`）。

目次には `##` と `###` の見出し（H2 と H3）が並びます。そのレベルの見出しがないページには、単に目次が付きません。

## 次はどこへ

**[フロントマター](/docs/reference/frontmatter)**

ページのメタデータ: タイトル、説明、サイドバー、SEO、検索。

**[構文](/docs/content/syntax)**

記述できるすべての Markdown と MDX の機能。

**[コンポーネント](/docs/content/components)**

任意の MDX ページで利用できる JSX コンポーネント。

**[ナビゲーション](/docs/content/navigation)**

サイドバー、並び順、タブを形づくる。

**[フォルダーメタ](/docs/content/meta)**

`meta.ts` ファイルでサイドバーグループを設定する。

---

# コンポーネント
Source: https://useblume.dev/ja/docs/content/components

Blume には、アクセシブルでテーマ設定可能なコンポーネントセットが同梱されており、**インポート不要**で任意の `.mdx` ページで利用できます。以下ではそれぞれをライブプレビューとソースとともに紹介します。コンポーネントはバニラ実装で React を使いません。React は独自のアイランドを追加した場合にのみ有効になります。

## Card と CardGroup

カードは、アイコン、タイトル、短い説明文とともにリンク先を示します。`CardGroup` でまとめるとレスポンシブなグリッドになります。ランディングページ、セクションのインデックス、「次のステップ」など、読者を先へ導きたい場所で活用してください。

**[クイックスタート](/docs/quickstart)**

Blume をインストールして最初のページを公開しましょう。

**[コンポーネント](/docs/content/components)**

コンポーネントライブラリを見る。

```astro lineNumbers
<CardGroup cols={2}>
  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
    Install Blume and ship your first page.
  </Card>
  <Card title="Components" href="/docs/content/components" icon="folder">
    Browse the component library.
  </Card>
</CardGroup>
```

`Card` は `title`、任意の `href`（省略するとクリックできないカードになります）、そして Blume 組み込みのアイコンセットから選ぶ `icon` を受け取ります。`CardGroup` は `cols`（デフォルトは `2`）を受け取ります。

## Steps

順序のある手順（インストール、セットアップの流れ、順番が重要なチュートリアルなど）のための、番号付きの縦方向シーケンスです。各 `Step` は `title` を受け取ります。

1. **Blume をインストール**

    パッケージをプロジェクトに追加します。

2. **ページを書く**

    コンテンツフォルダに `.mdx` ファイルを追加します。

3. **公開する**

    `blume build` を実行して `dist/` をデプロイします。

```astro lineNumbers
<Steps>
  <Step title="Install Blume">Add the package to your project.</Step>
  <Step title="Write a page">
    Drop an `.mdx` file into your content folder.
  </Step>
  <Step title="Ship it">Run `blume build` and deploy `dist/`.</Step>
</Steps>
```

## Tabs

同等の内容 — 言語ごとのバリエーション、OS 別のコマンド、代替となるアプローチなど — をその場で切り替えられます。すべてをページ上に積み上げる必要がありません。各 `Tab` は `title` を受け取ります。

**macOS**

Homebrew を使ってツールチェーンをインストールします。

**Windows**

winget を使ってツールチェーンをインストールします。

```astro lineNumbers
<Tabs>
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

`inline` を追加すると、枠線付きのボックスではなく、ボーダーレスで描画されます — 全幅の罫線上にタブストリップが並び、コンテンツはその下に本文として流れます。`param` を追加すると、アクティブなタブがハッシュではなく URL のクエリパラメータに同期され、選択状態を共有できるようになります。`?install=windows` で終わるリンクを開くと Windows タブが表示されます。各グループはそれぞれ独自の `param` に同期するため、1 ページ内に独立してディープリンク可能なグループを複数配置できます。

同じタイトルのタブを持つグループは連動して切り替わります — 1 つのグループで「macOS」を選ぶと、macOS タブを持つすべてのグループがそれに追従します。`syncKey` を追加すると、その連動の範囲を限定できます。同じキーを共有するグループだけが連動して切り替わるため、たまたまタブのタイトルが一致しただけの無関係なグループは独立したままになります。

**macOS**

Homebrew を使ってツールチェーンをインストールします。

**Windows**

winget を使ってツールチェーンをインストールします。

```astro lineNumbers
<Tabs inline param="install">
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

## Badge

ステータスやメタデータを示す小さなインラインラベルです — バージョンタグ、「new」や「beta」のマーカー、安定性レベルなど。`variant` で意味に合わせて色を調整します。

### デフォルト

特に強調のない中立的なメタデータ。

<Badge>安定版</Badge>

```astro
<Badge>Stable</Badge>
```

### アクセント

テーマのアクセントカラーで注意を引きます — 「new」や注目マーカーに適しています。

<Badge variant="accent">新機能</Badge>

```astro
<Badge variant="accent">New</Badge>
```

### 成功

肯定的、または合格を示す状態。

<Badge variant="success">合格</Badge>

```astro
<Badge variant="success">Passing</Badge>
```

### 警告

実験的機能など、注意して使うべきもの。

<Badge variant="warning">ベータ</Badge>

```astro
<Badge variant="warning">Beta</Badge>
```

### 危険

非推奨など、否定的または破壊的な状態。

<Badge variant="danger">非推奨</Badge>

```astro
<Badge variant="danger">Deprecated</Badge>
```

## Icon

名前を指定してアイコンを描画します — 同じ `icon` プロパティが、カード、ステップ、タブ、サイドバーの項目でも使われます。名前は [Lucide](https://lucide.dev/icons) 由来で、小文字のケバブケースです（`rocket`、`gauge`、`book-open`）。

<Icon icon="rocket" size={20} />

```astro
<Icon icon="rocket" size={20} />
```

Blume は Lucide 専用です — 名前だけを指定すると Lucide から解決され、他のアイコン入力との対称性のために `lucide:` を前置することもできます（`lucide:rocket`）。`size` はピクセルサイズ（デフォルトは `16`）を設定し、`color` は色を付けます（任意の CSS カラー。デフォルトは `currentColor`）。名前の代わりに生の `<svg>` 文字列、画像 URL、ローカル画像パスを渡せば独自のアートを描画でき、`label` を追加すると支援技術に公開されます。`label` がない場合、アイコンは装飾扱いになります。

アイコンはビルド時に解決され、JavaScript を伴わない SVG としてインライン展開されます。実行時に取得されるものはありません。

## ファイルツリー

プロジェクトやフォルダの構成を図示します。通常の Markdown リストをラップすると、Blume がツリーとしてスタイリングします — セットアップや設定のガイドで構造を説明するのに便利です。

<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>

```astro lineNumbers
<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>
```

## Accordion

関連する折りたたみ要素を、区切り線の入った 1 つの枠線付きコンテナにまとめます — FAQ、任意の手順、長い例などに。各子要素は `AccordionItem` です（`title`、任意の `icon`、`description`、`defaultOpen`）。単独の開閉要素には [Expandable](#expandable) を使ってください。

<Accordion>
  <AccordionItem title="MDX に対応していますか？">
    はい — すべてのページを `.md` または `.mdx` にできます。
  </AccordionItem>
  <AccordionItem title="テーマはカスタマイズできますか？">
    はい。Tailwind v4 のトークンと独自の `theme.css` を通じて可能です。
  </AccordionItem>
</Accordion>

```astro lineNumbers
<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>
```

## Expandable

入れ子の詳細（フィールドのサブプロパティの展開や補足の余談など）のための軽量なインライン開閉要素です。`title` がトグルのラベルになります（デフォルトは「Show more」）。`defaultOpen` を指定すると展開された状態で始まります。

<Expandable title="詳細オプションを表示">
  これらの設定は任意で、変更が必要になることはほとんどありません。
</Expandable>

```astro
<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>
```

## Columns

カードやブロックを、モバイルで折り返される等幅カラムのレスポンシブグリッドに配置します。`Columns` は `cols` を受け取り、各セルを `Column` でラップします。

<Columns cols={2}>
  <Column>
    **高速**

    Astro と Vite の上に構築されています。
  </Column>
  <Column>
    **テーマ設定可能**

    Tailwind v4 のデザイントークン。
  </Column>
</Columns>

```astro lineNumbers
<Columns cols={2}>
  <Column>
    <Card title="Fast" icon="rocket">
      Built on Astro and Vite.
    </Card>
  </Column>
  <Column>
    <Card title="Themeable" icon="sun">
      Tailwind v4 design tokens.
    </Card>
  </Column>
</Columns>
```

## CodeGroup

複数のコードブロックを 1 つのタブ切り替え式にまとめます — 言語ごと、ファイルごとに 1 タブ。タブのラベルは各ブロックのタイトル（言語の後に続くテキスト）になり、グループのコピーボタンはタブバーに配置され、表示中のブロックをコピーします。`dropdown` を追加すると、タブバーの代わりにメニューで切り替えます。

<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>

````astro
<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>
````

## Frame

画像や任意のビジュアルを、中央揃えの枠線付きフレームで囲みます。任意の `caption`（Markdown として描画されます）と `hint` を指定できます。

<Frame
  caption="**フレーム付き**のイラスト。"
  hint="フレームはビジュアルを中央揃えし、キャプションを付けます。"
>
  <svg
    width="160"
    height="72"
    viewBox="0 0 160 72"
    role="img"
    aria-label="サンプルフレーム"
  >
    <rect width="160" height="72" rx="8" fill="#3b82f6" />
  </svg>
</Frame>

```astro lineNumbers
<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <img src="/screenshot.png" alt="Product screenshot" />
</Frame>
```

## YouTube

YouTube 動画を、レスポンシブでプライバシーに配慮した（`youtube-nocookie.com`）16:9 のフレームに埋め込みます。クライアント JavaScript は一切含まれません。動画の `id` または完全な `url` に加え、任意の `title`（アクセシビリティ用）と秒単位の `start` 時間を渡せます。

[Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

```astro lineNumbers
<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
<YouTube url="https://youtu.be/aqz-KE-bpKQ" start={30} />
```

## Color

コピー可能な 16 進数値とともにカラースウォッチを表示します — パレットやブランドカラーを文書化するのに便利です。スウォッチのリストには `variant="compact"` を、グループ化するには `Color.Row` と併せて `variant="table"` を使います。各 `Color.Item` は `name` と `value`（16 進数の文字列、またはテーマ対応の色のための `{ light, dark }`）を受け取ります。

<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>

```astro lineNumbers
<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>
```

## Tree

展開可能なフォルダを備えた階層的なファイル／フォルダ構造を描画します。（リスト駆動の手軽な方法については [ファイルツリー](#file-tree) を参照してください。`Tree` はフォルダごとの制御が可能です。）`Tree.Folder`（`name`、任意の `defaultOpen`、`openable`）と `Tree.File`（`name`）を使います。

<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>

```astro lineNumbers
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>
```

## Panel

脇に置いておく補足的なコンテンツのための、タイトル付きコンテナです。`title` は任意です。

<Panel title="知っておくと便利">
  パネルは、本文の流れを妨げずに補足的な詳細を収められます。
</Panel>

```astro
<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>
```

## Tooltip

インラインの用語について、ホバー時に定義やヒントを表示します。`tip` がホバー時のテキストです。任意で `headline` と、フォローアップリンク用の `cta` + `href` を追加できます。

<Tooltip
  tip="ソフトウェアが通信に使う一連のプロトコル。"
  headline="API"
  cta="ガイドを読む"
  href="/docs/quickstart"
>
  API
</Tooltip>
という用語にホバーすると詳細がわかります。

```astro
Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term.
```

## Tile

ビジュアル（アイコンや画像）を前面に出し、その下にタイトルと説明を配置したクリック可能なプレビューです。ギャラリーやショーケースに適しています。`title`、`description`、`href` を受け取り、子要素がビジュアルになります。

<Tile
  title="クイックスタート"
  description="数分で最初のページを公開しましょう。"
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>

```astro
<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>
```

## Prompt

ラベルとコピーボタンからなる 1 行の要素です。`description`（Markdown）が表示されるラベルで、本文がプロンプトそのものになります。本文は非表示で、**Copy prompt** ボタンを押すとクリップボードにコピーされます。`actions` でボタンを制御します（例: `["copy", "cursor"]`）。

<Prompt
  description="エンドポイントを**ドキュメント化**するようモデルに依頼します。"
  actions={["copy"]}
>
  POST /v1/pets エンドポイントのリファレンスドキュメントを書いてください。
</Prompt>

```astro
<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>
```

## Visibility

対象読者に応じてコンテンツを表示または非表示にします。`for="web"` はサイト上にのみ描画され、`for="agents"` は AI エージェントが読むエージェント向け Markdown（`llms-full.txt` と各ページの `.md` ミラー）を対象とします。

```astro
<Visibility for="web">Shown on the site only.</Visibility>
<Visibility for="agents">Shown only in the generated Markdown.</Visibility>
```

## 型テーブル

オブジェクトのプロパティ — プロパティ、型、デフォルト値 — を文書化するためのテーブルです。`TypeTable` で行を手書きするか、`AutoTypeTable` で TypeScript のインターフェースや型エイリアスから直接生成できます。

### 型テーブル

各行を展開すると説明と詳細が現れる、**プロパティ / 型**のグリッドです。プロパティ名をキーとする `type` マップを渡します。各エントリは `type` に加えて、任意の `description`、`default`、`required` フラグ、`typeDescription`、`typeDescriptionLink` を受け取ります。省略可能なプロパティ（`required` が未設定）は、名前の後に `?` が表示されます。

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | - | ボタンに表示されるラベル。 |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | 見た目のスタイル。 |
| `disabled?` | `boolean` | - | |

```astro lineNumbers
<TypeTable
  type={{
    label: {
      type: "string",
      required: true,
      description: "The button's visible label.",
    },
    variant: {
      type: '"primary" | "ghost"',
      default: '"primary"',
      description: "Visual style.",
    },
    disabled: { type: "boolean" },
  }}
/>
```

### 自動型テーブル

TypeScript の型から型テーブルを生成し、ドキュメントをソースと同期させ続けます。`AutoTypeTable` に `path`（プロジェクトルートからの解決）と型の `name` を指定します。説明は JSDoc コメントから、デフォルト値は `@default` タグから取得され、省略可能なプロパティ（`?`）はそれに応じて示されます。

```astro
<AutoTypeTable path="./src/button.ts" name="ButtonProps" />
```

`path` の代わりに `type` で型をインラインで渡すこともできます — 小さな例に便利です。

<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>

```astro lineNumbers
<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>
```

## GitHub 情報

GitHub リポジトリへのリンクを、最新のスター数とフォーク数とともに表示するカードです。カウントはビルド時に取得され — クライアント JavaScript は不要 — API に到達できない場合でもカードは描画されます。`owner` と `repo` を渡すか、省略して `blume.config` のリポジトリを使用します。API のレート制限を緩和するには、環境変数 `GITHUB_TOKEN` を設定してください。

このカードはインスタンスを [`github.host`](/docs/configuration#github-enterprise) から読み取ります。そのため Enterprise でホストされているサイトでは、明示的に指定した `owner` / `repo` もそのインスタンスを参照します。特定のカードだけ別の場所を指すようにするには `host` を渡します — 例えば Enterprise のサイトから公開プロジェクトを示す場合などです。REST のベースは、`github.host` の場合と同じ方法でそこから導出されます。

<GithubInfo owner="haydenbleasel" repo="blume" />

```astro lineNumbers
<!-- Uses the repo from blume.config -->
<GithubInfo />

<!-- Or point it at any repository -->
<GithubInfo owner="haydenbleasel" repo="blume" />

<!-- Or at a repository on another instance -->
<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
```

## Component

`Component` は、プロジェクトの `examples/` ディレクトリにあるサンプルファイルを、ハイライトされたソースと並べてタブ形式でライブプレビューとして描画します。`path` でファイルを指定します — `examples/` 配下の位置から拡張子を除いたもの（つまり `examples/counter.tsx` なら `path="counter"`）。React、Vue、Svelte、Astro のサンプルがすべてサポートされ、フレームワークのサンプルはハイドレートされ、Astro のものは静的に描画されます。単一のファイルからプレビューとコードを同期させ続けます。

プレビューは、ドキュメントのスタイルが一切届かない独立したフレーム内で描画されます — 本文のマージン、タイポグラフィ、テーマの装飾がコンポーネントに漏れ込むことはありません。フレームには Tailwind（プリフライトと、プロジェクトおよび examples ディレクトリからスキャンされたユーティリティ）と、`bg-background` のようなクラスがデフォルトでサイトのパレットに従うようにする Blume のデザイントークンが与えられ、サイトのライト／ダーク切り替えにリアルタイムで追従します。ペインは描画されたサンプルに合わせてサイズを調整し — 読み込み後にサンプルが拡大・縮小しても追従し続けます — Preview タブと Code タブは同じ高さを共有するため、切り替えてもページがずれることはありません。

shadcn の変数など、独自のデザインシステムでプレビューをスタイリングするには、`examples.css` にスタイルシートを指定します。これは Blume のデフォルトの後に各プレビューフレームへ注入されるため、あなたのトークンが優先されます。その中で `@import "tailwindcss"` は書かないでください。フレームはすでに Tailwind を提供しています。ダークモードのオーバーライドには `.dark` と `[data-theme="dark"]` のどちらも使えます。

```ts
// blume.config.ts
export default defineConfig({
  examples: { css: "examples/theme.css" },
});
```

```css
/* examples/theme.css */
:root {
  --primary: oklch(0.6 0.2 260);
}

.dark {
  --primary: oklch(0.75 0.15 260);
}

@theme inline {
  --color-primary: var(--primary);
}
```

ディレクトリも設定可能です — サンプルが別の場所（レジストリ構成など）にある場合は `source` を設定します（または文字列の省略記法 `examples: "..."` を使います）。`path` は常にそこからの相対パスになります。

```ts
// blume.config.ts
export default defineConfig({
  examples: "registry/files-sdk",
});
```

```astro
<!-- registry/files-sdk/file-list/basic.tsx -->
<Component path="file-list/basic" />
```

`examples` には glob（`*`、`?`、`[]`、`{}`、`!` を含むもの）も指定できます。マッチしたファイルのみが検出され、`path` は glob の静的なプレフィックス（最初のワイルドカードより前の部分）からの相対パスになります。これは、各コンポーネントのソースをそのサンプルと同じ場所に置くレジストリ向けです — プレビュー用のデフォルトエクスポートを持たないソースが巻き込まれないよう、サンプルだけを指定してください。

```ts
// blume.config.ts
export default defineConfig({
  // registry/files-sdk/file-list/file-list.tsx — source, left out
  // registry/files-sdk/file-list/examples/basic.tsx — discovered
  examples: "registry/files-sdk/**/examples/*",
});
```

```astro
<!-- keyed relative to registry/files-sdk -->
<Component path="file-list/examples/basic" />
```

モノレポでは、サンプルがインポートするコンポーネントは通常、隣接するワークスペースパッケージに置かれています。Tailwind の `@source` はインポートではなくファイルをスキャンします。Blume がスキャンするのはプロジェクトと `examples` ディレクトリ（`source` が指す場所。プロジェクト外でも可）なので、その隣接パッケージ内でしか使われていないクラスは、そのパッケージをスキャン対象に加えるまで生成されません。追加するには、`examples.css`（プレビューフレーム向け）または `theme.css`（サイト向け）に `@source` ディレクティブを記述します。パスは Tailwind の標準ルールどおり、そのディレクティブが置かれたファイルからの相対で書きます。Blume はそれを生成されるスタイルシートへ引き継ぎます。

```css
/* examples/theme.css */
@source "../../../packages/ui/src";
```

```tsx
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <button
      className="rounded-blume border-border bg-background text-foreground hover:bg-muted border px-4 py-2 text-sm font-medium transition-colors"
      onClick={() => setCount((value) => value + 1)}
      type="button"
    >
      Clicked {count} {count === 1 ? "time" : "times"}
    </button>
  );
};

export default Counter;
```

```astro
<!-- examples/counter.tsx -->
<Component path="counter" />
```

Astro のサンプルは、クライアント JavaScript なしでライブに描画されます。

```astro
---
interface Props {
  title?: string;
}

const { title = "Hello from Astro" } = Astro.props;
---

<div class="rounded-blume border border-border bg-muted/30 px-5 py-4">
  <p class="m-0 font-semibold text-foreground text-sm">{title}</p>
  <p class="m-0 mt-1 text-muted-foreground text-sm">
    A static, server-rendered example — no client JavaScript ships.
  </p>
</div>
```

## CodeBlock

`CodeBlock` は、フェンス付きコードと同じ Shiki のテーマとトランスフォーマー（ライト／ダークの切り替えを含む）でコード文字列をハイライトします。ランディングページや独自のコンポーネントなど、フェンスを置けない場所のためのものです。`code` と `lang` を渡します。

<CodeBlock
  lang="ts"
  code={`export const greet = (name: string): string =>
  \`Hello, \${name}!\`;`}
/>

```astro
---
import CodeBlock from "blume/components/content/CodeBlock.astro";
---

<CodeBlock lang="ts" code={source} />
```

（独自コンポーネントの中などで）自分で HTML 文字列にハイライトしたい場合は、`blume/markdown` から基盤となるヘルパーをインポートします。

```ts
import { highlightCode } from "blume/markdown";

const html = await highlightCode(source, "ts");
```

## Diff

`Diff` は git 形式の差分を、コードブロックと同じ Shiki のテーマでハイライトして描画します。すべてビルド時に生成されるため、クライアント JavaScript は不要です。2 つのインライン文字列（`old` / `new`）、2 つのファイルパス（`before` / `after`）、または unified 形式のパッチ（インラインの `patch` 文字列か `src` ファイル）を渡します。

<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>

```astro
<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>
```

プロジェクト内の 2 つのファイルを、ルートからの相対パスで差分表示します。

<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />

```astro
<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />
```

あるいは unified 形式のパッチを描画します — `src` でファイルから読み込むか、`patch` でインラインに指定します。

<Diff src="diffs/greet.patch" />

```astro
<Diff src="diffs/greet.patch" />
```

```astro
<Diff
  patch={`--- a/greet.ts
+++ b/greet.ts
@@ -1,3 +1,4 @@
-export function greet(name) {
-  return "Hi, " + name;
+export function greet(name: string): string {
+  const greeting = "Hi, " + name + "!";
+  return greeting;
 }`}
/>
```

---

# 国際化
Source: https://useblume.dev/ja/docs/content/i18n

Blume は 1 つのプロジェクトを多言語で配信します。翻訳したファイルを適切な場所に置くだけで、Blume がルーティング、言語スイッチャー、ロケールごとのナビゲーション、SEO を自動的に設定します — 別途メンテナンスすべきルーティングレイヤーはありません。オプトイン方式なので、`i18n` ブロックがなければサイトはこれまでどおり単一言語のままです。[バージョニング](/docs/content/versioning)とも組み合わせられます — 凍結されたスナップショットは翻訳を保持し、ロケールのフォールバックは各バージョン内で機能します。

## 有効にする

ロケールの一覧とどれをデフォルトにするかを指定した `i18n` ブロックを追加します:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}
```

各ロケールは `code`(URL で使用)、`label`(言語スイッチャーに表示)、そして右から左に記述するスクリプト用の任意の `dir`(既定は `"ltr"`)を持ちます。任意の `style` は、[`blume translate`](/docs/reference/translate) にそのロケール向けの自由記述のガイダンス — 文体、方言、用語法、たとえば `"Brazilian Portuguese, informal você"` — を与えます。これにより、その選択はエージェント任せになるのではなく、最初の翻訳の時点から固定されます。

## 翻訳コンテンツを整理する

デフォルトロケールはコンテンツルートに置きます。その他のロケールはすべて、`code` を名前とするトップレベルのフォルダーとして、デフォルトの構造をミラーリングします:

```txt
docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar
```

| ファイル                        | ルート                  |
| ------------------------------- | ----------------------- |
| `docs/index.mdx`                | `/`                     |
| `docs/guides/quickstart.mdx`    | `/guides/quickstart`    |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

翻訳したいファイルだけを翻訳すれば十分です — それ以外は自動的にフォールバックします([フォールバック](#fallbacks)を参照)。

### ファイル名のサフィックス

翻訳を元のファイルの隣に置いておきたいですか? `parser: "dot"` を設定すれば、フォルダーを使う代わりにロケールのサフィックス付きのファイル名を使えます:

```txt
docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)
```

部分的な翻訳に適しています — ツリー全体をミラーリングせずに、翻訳済みの数ページだけを同じ場所に配置できます。

### 共有ファイル

変更履歴やステータスページのように、どの言語でも内容が同じコンテンツには `$` マーカーを付けると、1 つのファイルを重複なくすべてのロケールで使えます:

```txt
docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

ロケール固有の `meta.ts` は、その言語について共有版を引き続き上書きします。

## デフォルトロケールの URL

既定では、デフォルトロケールには URL プレフィックスが付かず(`/`、`/guides/quickstart`)、他のロケールにはプレフィックスが付きます(`/fr/…`)。これにより主要言語の URL がすっきりと保たれます。デフォルトを含むすべてのロケールにプレフィックスを付けるには:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## ロケールごとのナビゲーション

各言語はそのロケールのファイルから構築された独自のサイドバーを持つため、翻訳ごとに構造、並び順、ラベルを変えることができます。フォルダーの [`meta.ts`](/docs/content/meta) ファイルもロケールごとに解決されます: 既定の `dir` パーサーでは、`fr/guides/` の下に `meta.ts` を置けばフランス語のグループを独立して並べ替えられます。`dot` パーサーでは翻訳が元のファイルの隣にあるため、フォルダーの `meta.ts` はすべてのロケールに適用されます。[ナビゲーション](/docs/content/navigation)に関するその他の挙動は、言語ごとに同様に動作します。

ヘッダータブはコンテンツから導出されるのではなく設定されるものなので、そのラベルは `blume.config.ts` でローカライズします: タブの `label` は、単純な文字列形式に加えてロケールごとのマップ(`{ en: "Docs", fr: "Documentation" }`)を受け付け、記入していないロケールについてはデフォルトロケールのエントリにフォールバックします。[タブ](/docs/content/navigation#tabs)を参照してください。

## フォールバック

ページがまだ翻訳されていない場合、Blume はローカライズされた URL でフォールバックロケールのコンテンツをレンダリングします — そのためリンクは機能し、ページは完全に事前レンダリングされ、検索エンジンが行き止まりに送られることもありません。フォールバックの既定値は `defaultLocale` です:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}
```

フォールバックページは検索インデックスから除外され、`hreflang` でも実際の翻訳としては通知されません。そのため未翻訳のコンテンツがランキングを奪い合うことはありません。それでもそのロケールのサイドバーには表示されるので、ナビゲーションは完全なまま保たれます — 読者はどの言語でもすべてのページに到達できます。

:::tip
まずは最も重要なページ — ホームページ、クイックスタート、主要なガイド — から翻訳し、残りはフォールバックに任せましょう。リンクを壊すことなく、時間をかけて翻訳を埋めていけます。
:::

## エージェントによる翻訳

ロケールを手作業で埋める必要はありません。[`blume translate`](/docs/reference/translate) は各ロケールで欠落している、または古くなっているページをすべて見つけ出し、ローカルのエージェント CLI([Claude Code](https://claude.com/claude-code) または [Codex](https://developers.openai.com/codex/cli))で翻訳します:

```bash
blume translate --claude
```

Blume は各結果の構造 — フロントマター、コードフェンス、リンク — を検証し、ファイルの書き込みも自身で行います。エージェントはテキストを翻訳するだけです。コミットされる台帳(`blume.translations.json`)が、各翻訳がどのソースリビジョンに由来するかを追跡するため、再実行時には変更があったものだけが対象となり、手作業で書いた翻訳はそのまま採用され、上書きされることはありません。CI では、ソースページが翻訳より先に進んでいる場合に `blume translate --check` が失敗します。

## 言語スイッチャー

i18n を有効にすると、`locales` から生成された言語スイッチャーがヘッダーに自動的に表示されます。各ページについて、あらゆる言語の対応する翻訳へリンクし、翻訳が存在しない場合はフォールバックページへリンクして未翻訳であることを示します。設定は一切不要です。

## 翻訳された UI

Blume は自身のインターフェース回りの文言 — 「このページの内容」「検索」「GitHub で編集」など — の翻訳を標準で同梱しているため、組み込みパックのあるロケールでは初めから翻訳済みの UI が使えます。**翻訳するのはコンテンツだけです。**

パックは 30 を超える言語に対応しています — アラビア語、ベンガル語、ブルガリア語、カタルーニャ語、中国語(簡体字・繁体字)、クロアチア語、チェコ語、デンマーク語、オランダ語、フィンランド語、フランス語、ドイツ語、ギリシャ語、ヘブライ語、ヒンディー語、ハンガリー語、インドネシア語、イタリア語、日本語、韓国語、ノルウェー語、ペルシャ語、ポーランド語、ポルトガル語(およびブラジルポルトガル語)、ルーマニア語、ロシア語、セルビア語、スロバキア語、スペイン語、スウェーデン語、タイ語、トルコ語、ウクライナ語、ベトナム語。これらはコミュニティによって保守されています — ロケールの追加や翻訳の改善は PR を送ってください。

欠落している文字列や未同梱の文字列は、デフォルトロケール、次に英語へフォールバックします。文字列を上書きしたり独自の言語を提供したりするには、ロケールをキーとして `i18n.ui` を設定します:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}
```

## SEO

ローカライズされた SEO は自動的に処理されます — ページごとにメタデータを書く必要はありません:

- `<html lang>` と `dir` はアクティブなロケールから設定されます。
- `hreflang` の代替リンクはページの実際の翻訳をすべてリンクし、加えてデフォルトロケールを指す `x-default` も出力します。
- 正規 URL はロケールに応じた正しいものになり、JSON-LD には `inLanguage` が含まれます。

これらを絶対 URL として出力できるように、[`deployment.site`](/docs/deployment) を設定してください。

## 検索

検索はアクティブな言語にスコープされます: `/fr/…` のページではダイアログがフランス語の結果を返し、**すべての言語** トグルで一度にすべてのロケールを横断して検索できます。既定の(Orama)および FlexSearch のインデックスはブラウザー側でフィルタリングし、ホスト型プロバイダーは各レコードに `locale` ファセットを持たせます。

## 右から左

ロケールに `dir: "rtl"` を設定すると、Blume はインターフェース全体 — サイドバー、ヘッダー、目次、ページネーション、検索、メニュー — をミラーリングし、`<html dir>` もそれに合わせて設定します。意図的に左から右のままにしているものが 2 つあります: **コードブロック**(コードはどの言語でも LTR で読みます)と **フォールバックコンテンツ** — 未翻訳のページは実際に書かれている言語の方向を維持するため、RTL ロケールの下で表示される英語も正しく読める一方、周囲の UI はミラーリングされます。

## 次はどこへ

**[ナビゲーション](/docs/content/navigation)**

各ロケールのサイドバー、並び順、タブを設計します。

**[SEO](/docs/configuration/seo)**

サイトマップ、Open Graph、構造化データ。

---

# インクルード
Source: https://useblume.dev/ja/docs/content/includes

スニペットを一度書けば、任意のページに差し込めます。単独の行に置いた `<include>` 文は、ビルド時に別のファイルを埋め込み、その内容がインラインで書かれていたかのように扱われます — 見出しはページの目次に加わり、テキストは検索でインデックスされ、内容はページの `.md` ミラーおよび llms-full.txt にも現れます。

```mdx
<include>./_snippets/prerequisites.mdx</include>
```

パスはインクルード元のファイルからの相対で解決されます。`/` で始まるパスはコンテンツルートから解決されるため、深くネストしたページでも `../../..` の連なりなしに共有スニペットを参照できます。

```mdx
<include>/_snippets/prerequisites.mdx</include>
```

この構文は Fumadocs の include 構文と一致しているため、移行したコンテンツはそのまま動作します。

こちらが実際の動作です — 次のコールアウトは共有スニペットから差し込まれたものです。

:::tip
このコールアウトは `_snippets/include-demo.mdx` にあります — このページが `<include>` ステートメントで差し込んでいるため、ここに表示されます。
:::

## パーシャル

名前（またはフォルダー名）がアンダースコアで始まるファイルは、デフォルトでルーティング、ナビゲーション、検索、サイトマップから除外されます。この慣習は共有スニペットの置き場所として最適です。

```text
docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx
```

パーシャルは通常の Markdown または MDX ファイルです。差し込み時にフロントマターは取り除かれ（インクルード元ページのフロントマターが優先されます）、それ以外のすべて — コールアウト、コードフェンス、コンポーネント、数式 — はインラインで書いた場合とまったく同じようにレンダリングされます。パーシャルは他のパーシャルをインクルードできます。循環インクルードはエラーとして報告されます。

パーシャル内の相対画像参照はそのまま機能します。インクルード元のページを基準に再解決されるため、パーシャルの隣に配置した `![図](./diagram.png)` は、そのパーシャルがどこに差し込まれても正しく解決されます。

`blume dev` の実行中にパーシャルを編集すると、それをインクルードしているすべてのページがリロードされます。

## コードファイルのインクルード

`.md`/`.mdx` 以外のターゲットは、拡張子から推論された言語でフェンス付きコードブロックとして埋め込まれます。言語を上書きするには（または Markdown ファイルを差し込む代わりにソースとして表示するには）`lang` を使い、タイトルなどのフェンスのメタ文字列を渡すには `meta` を使います。

```mdx
<include>./examples/config.ts</include>

<include lang="ts" meta='title="blume.config.ts"'>
  ../blume.config.ts
</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>
```

## ルールと診断

include 文は単独の行を占める必要があります — インラインではなくブロックレベルの要素だからです。フェンス付きコードブロック内の文はそのまま残されるため、（このページのように）構文そのものをドキュメント化できます。

ターゲットはコンテンツルート内に存在しなければなりません。ルート外のファイルはバージョンスナップショットや eject したプロジェクトから黙って欠落してしまうため、`blume` は差し込む代わりに `BLUME_INCLUDE_OUTSIDE_ROOT` を報告します。存在しないターゲットは `BLUME_INCLUDE_NOT_FOUND`、インクルードのループは `BLUME_INCLUDE_CYCLE` となります。これら 3 つはいずれも `blume build` を失敗させ（それでもビルドするには `--no-strict` を渡します）、`blume validate` にも表示されます。

パーシャル内のリンク切れは、それを差し込んでいるページではなくパーシャルのファイルに対して報告されるため、実体のある場所で修正できます。

:::note
パーシャルはロケール間で共有され、`blume translate` では翻訳されません。パーシャルは言語に依存しない内容（コード、表、図）に保つか、ロケールごとのパーシャルを作成して各ロケールのページからインクルードしてください。
:::

---

# アイランド
Source: https://useblume.dev/ja/docs/content/islands

Blume はデフォルトでドキュメントを **JavaScript ゼロ** の静的 HTML としてレンダリングします。インタラクティブな要素が必要になったとき — ライブデモ、チャート、プレイグラウンドなど — に追加するのが **アイランド** です。アイランドとは、自分自身のための JS のみを、それを使っているページにのみ配信するフレームワークコンポーネントです。

## `islands/` の規約

プロジェクトルートの `islands/` フォルダにコンポーネントを置きます。そのファイル名がコンポーネント名となり、import なしで **任意の** `.mdx` ページで使えるようになります:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Clicked {count}</button>;
}
```

```mdx page.mdx
Here's a live counter: <Counter />
```

ファイル名がコンポーネント名になるため、**PascalCase の識別子でなければなりません** — 使えるのは英字、数字、アンダースコアのみです(`Counter.tsx` → `<Counter />`)。小文字始まりのファイル名、ダッシュ・ドット・スペースを含む名前(`Time-Picker.tsx` など)、および同じ名前に解決される 2 つのアイランドは、ビルド警告とともにスキップされます。

:::note
アイランドは **インタラクティブな** UI のためのものです。複数ページで再利用する静的なコンポーネント(スタイル付きのコールアウト、料金表など)には、代わりに [MDX オーバーライド](/docs/configuration/customization) を使ってください — こちらは JavaScript を一切配信しません。
:::

## `components.ts` でのアイランド登録

アイランドを他のコンポーネントと同じ場所に置きたい場合や、ファイル名とは異なる名前を付けたい場合は、`defineComponents` で登録します。`islands` グループは `islands/` フォルダとまったく同じです: 各エントリはすべての MDX ページで利用でき、ハイドレートされます(デフォルトは `client: "visible"`)。

```ts components.ts
import { defineComponents } from "blume";
import Counter from "./widgets/Counter.tsx";

export default defineComponents({
  islands: {
    Counter, // <Counter /> in any MDX page, hydrated
  },
});
```

コンポーネントは import 経由でもパス文字列でも参照でき、ディスクリプタ形式を使えばアイランドごとにハイドレーションモードを設定できます:

```ts components.ts
export default defineComponents({
  islands: {
    Chart: { component: "./widgets/Chart.tsx", client: "only" },
  },
});
```

## ハイドレーション

デフォルトでは、アイランドは `client:visible` を使います: 読者がスクロールしてビューに入った時点でハイドレートされるため、アイランドだらけのページでも即座に読み込まれます。別の戦略を選ぶには、アイランドのファイル内で `export const client` を指定します:

```tsx islands/Chart.tsx lineNumbers
// Skip server rendering entirely — for components that touch the DOM/window.
export const client = "only";

export default function Chart() {
  /* ... */
}
```

| `client` の値 | ハイドレートのタイミング | 用途 |
| --- | --- | --- |
| `"visible"` _(デフォルト)_ | スクロールでビューに入ったとき | ほとんどのアイランド |
| `"load"` | ページ読み込み時に即座に | ファーストビュー、即応が必須の UI |
| `"idle"` | メインスレッドがアイドルになったとき | 緊急性の低いインタラクティブ要素 |
| `"only"` | クライアントのみ、サーバーレンダリングなし | `window`/`document` を必要とするライブラリ(チャート、エディタ) |

## フレームワーク

**React はそのまま動作します** — プロジェクトに `.tsx`/`.jsx` のアイランドが含まれた瞬間、Blume が自動的に有効化します。

[React Compiler](https://react.dev/learn/react-compiler) は React が有効なときは常にデフォルトでオンになっているため、アイランドは自動的にメモ化されます — 手書きの `useMemo`/`useCallback` は不要です。Blume に同梱されているので、インストールするものはありません。オプトアウトは `blume.config.ts` で行います:

```ts blume.config.ts
export default defineConfig({
  react: { compiler: false },
});
```

**Vue と Svelte** もサポートされています。対応する Astro インテグレーションをインストールすれば、`.vue` または `.svelte` のアイランドを検出したときに Blume がレンダラーを接続します:

```bash
# Vue
npm install @astrojs/vue vue

# Svelte
npm install @astrojs/svelte svelte
```

```vue islands/Toggle.vue lineNumbers
<script setup>
import { ref } from "vue";
const on = ref(false);
</script>

<template>
  <button @click="on = !on">{{ on ? "On" : "Off" }}</button>
</template>
```

MDX で渡したプロパティ(`<Counter start={5} />`)はコンポーネントに転送され、子要素(`<Counter>label</Counter>`)はデフォルトスロットとして届きます。

:::tip
アイランドはクライアント側でハイドレートされるため、プロパティとして渡すものはシリアライズ可能でなければなりません — 文字列、数値、プレーンオブジェクトは可、関数は不可です。
:::

## フック

アイランドは独立してハイドレートされるため、プロジェクトのデータを引き回すための React コンテキストは存在しません。代わりに `blume/hooks` が、レイアウトがページ内にシリアライズした小さなスナップショットを読み取ります — props のバケツリレーは不要です:

```tsx islands/PageInfo.tsx lineNumbers
import { useBlume, usePage } from "blume/hooks";

export default function PageInfo() {
  const blume = useBlume();
  const page = usePage();
  if (!(blume && page)) {
    return null;
  }
  return (
    <p>
      You're reading <strong>{page.title}</strong> on {blume.config.title}.
    </p>
  );
}
```

| フック | 戻り値 |
| --- | --- |
| `useBlume()` | サイトの `{ config, navigation }`、マウント前は `null` |
| `usePage()` | 現在のページの `{ route, title }`、マウント前は `null` |
| `useSearch()` | `{ search, results, loading }` — 設定済みの検索プロバイダーに問い合わせます |
| `useAskAI()` | `{ ask, messages, loading, reset }` — Ask AI エンドポイントからストリーミングします |

`useBlume()` と `usePage()` は、アイランドがマウントされるまで `null` を返します(サーバーとクライアントが同じ最初のフレームをレンダリングするため) — ガードを入れてください。このスナップショットは React を配信するページでのみ出力されるため、完全に静的なサイトでは一切コストがかかりません。

`PageLayout` で構築した [カスタムページ](/docs/advanced/custom-pages) では、そこにあるアイランドが読み取れるように `clientData` を渡します:

```astro
<PageLayout
  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
  {/* …other props… */}
/>
```

---

# フォルダーメタ
Source: https://useblume.dev/ja/docs/content/meta

コンテンツツリー内のすべてのフォルダーはサイドバーグループになります。ページと同じ階層に `meta.ts` を置くと、そのグループの見た目と子要素の並び順を制御できます。これは完全に任意です。ファイルがない場合、グループのラベルはフォルダー名を人間が読みやすい形にしたものになり、ページは[インデックス、数値プレフィックス、その後アルファベット順](/docs/content/navigation#ordering)で並びます。

## メタの定義

完全に型付けされた設定にするには `defineMeta` オブジェクトをエクスポートします。設定対象のフォルダーのルートにファイルを配置してください — `guides/meta.ts` は **Guides** グループを設定します:

```ts meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});
```

すべてのフィールドは任意です — 上書きしたいものだけを設定してください。

## フィールド

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `title` | `string` | グループのラベル。デフォルトはフォルダー名を人間が読みやすい形にしたもの。 |
| `icon` | `string` | ラベルの横に表示されるアイコン。 |
| `order` | `number` | 兄弟のグループやページの中での位置。数値が小さいほど先に並びます。 |
| `collapsed` | `boolean` | [`group` 表示モード](/docs/content/navigation#display-modes)において、グループを折りたたんだ状態で開始するかどうか。 |
| `display` | `"flat" \| "group" \| "page"` | このグループの描画モード。グローバルの [`navigation.sidebar.display`](/docs/content/navigation#display-modes) を上書きします。 |
| `pages` | `string[]` | スラッグによる、グループの子要素の明示的な順序。 |

`pages` 配列は子要素をスラッグで列挙します — スラッグとは、フォルダー名またはファイル名から数値プレフィックスと括弧を取り除いたものです（つまり `01-quickstart.mdx` は `"quickstart"` になります）。省略した子要素も、列挙されたものの後に表示されます。

グループの描画方法 — フラットなヘッダー、折りたたみ可能な開閉要素、ドリルインパネル — はデフォルトでサイドバー全体の `navigation.sidebar.display` に従います。このグループだけで上書きするには、ここで `display` を設定してください。フォルダーの `index` ページもフロントマターからこれを設定でき、そちらが `meta.ts` よりも優先されます — [グループごとの上書き](/docs/content/navigation#per-group-overrides)を参照してください。

## 計算されたメタ

`meta.ts` は実際のモジュールなので、メタを計算できます — オブジェクトの代わりに関数（同期または `async`）を渡すと、スキャン時に構築されます。外部ソースからページの順序を取得する場合に便利です:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));
```

## グループ内での並び順

`pages` 配列はグループの子要素の順序を設定します。そこで省略されたものは、各ページのフロントマターの `sidebar.order`、次にファイルシステム（最初に `index` ページ、次に数値プレフィックス、その後アルファベット順）にフォールバックします。明示的な設定サイドバーを含む、サイドバーの優先順位の全体については、[ナビゲーション › 並び順](/docs/content/navigation#ordering)を参照してください。

URL セグメントを追加*せずに*ページをグループ化したい場合、`meta.ts` はまったく必要ありません。括弧付きのフォルダー名を使用してください — [ページ › グループフォルダー](/docs/content#group-folders)を参照してください。

## 国際化

[i18n](/docs/content/i18n) では、フォルダーメタはロケールごとに解決されます。`fr/guides/` の下に `meta.ts` を置くと、フランス語のグループを独立して並べ替えられます。

すべての言語で同一のフォルダーメタについては、`$` マーカーを追加すると、1 つのファイルで重複なくすべてのロケールに対応できます:

```txt
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

ロケール固有の `meta.ts` は、その言語について共有の `meta.$.ts` を引き続き上書きします。

## 次はどこへ

**[ナビゲーション](/docs/content/navigation)**

サイドバー、パンくずリスト、タブがどのように構築されるか。

**[フロントマター](/docs/reference/frontmatter)**

`sidebar` の上書きを含む、ページごとのメタデータ。

---

# ナビゲーション
Source: https://useblume.dev/ja/docs/content/navigation

Blume はファイルシステムからサイドバーを構築し、あとはページ単位、フォルダー単位、または 1 つの明示的な設定で、好きなだけ（あるいは最小限に）調整できるようにします。パンくずリスト、前後のリンク、ページ内アウトラインはすべて同じモデルから導かれるため、配線する作業は一切ありません。

## 生成されるサイドバー

デフォルトでは、サイドバーはコンテンツツリーをそのまま反映します。

- フォルダーは**グループ**に、ファイルは**ページ**になります
- ページのラベルはフロントマターの `title`、グループのラベルは人間向けに整形されたフォルダー名です
- 項目は[数値プレフィックス](/docs/content)順、次にアルファベット順に並び、フォルダーの `index` ページが最初に来ます

多くのサイトではこれで十分です — 以下はすべてオプトインです。

## ページのラベル、アイコン、バッジ

個々のページがサイドバーにどう表示されるかは、フロントマターの `sidebar` 以下で調整します。

```yaml lineNumbers
sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group
```

ページスキーマの全体については[フロントマター](/docs/reference/frontmatter)を参照してください。

## フォルダーグループ

各フォルダーはサイドバーのグループになります。ページと並べて [`meta.ts`](/docs/content/meta) を置くと、グループのタイトル、アイコン、順序、および子要素の順序を設定できます。

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

すべてのフィールドとスキャン時の meta の計算については[フォルダー meta](/docs/content/meta) を参照してください。

フォルダーの `meta.title` と、そのフォルダー自身の `index` ページのフロントマター `title` は独立して解決されます — i18n で片方だけを翻訳してもう一方を忘れると、サイドバーは正しく表示される一方で、ランディングページ自体の `<title>` や見出しが古いままになります。両者が食い違うと、Blume は `BLUME_NAV_INDEX_TITLE_MISMATCH` 警告を報告します。フォールバックロケールから補完された未翻訳のページは対象外です — そのタイトルはフォールバックロケールのものであり、修正すべきはページの翻訳であって、フロントマターの編集ではありません。

URL セグメントを追加*せずに*ページをグループ化するには、括弧付きのフォルダー名を使います — [ページ](/docs/content#group-folders)を参照してください。

## 表示モード

`navigation.sidebar.display` は、すべてのサイドバーグループの描画方法を設定します。

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`**（デフォルト）— 折りたためないヘッダーの下にページを並べます。どのグループにも属さないページは常に先頭、グループのセクションより上に並ぶため、グループの子要素と取り違えられることがありません。
- **`group`** — グループごとに折りたたみ可能な `<details>` 開閉要素になります。グループはデフォルトで折りたたまれた状態から始まりますが、現在のページを含むグループは常に開いた状態で始まるため、今いるセクションだけが展開されます。[フォルダー meta](/docs/content/meta) で `collapsed: false` を設定すると、状況にかかわらずグループを開いた状態に固定できます。
- **`page`** — 各グループが 1 行になり、クリックするとサイドバーがそのグループの項目だけを表示するサブパネルにスライドし、上部に戻る矢印が表示されます。パネルはルートを認識するため、グループ内のページに直接アクセスした場合はそのページが表示された状態で開きます。

:::tip
`page` モードは深いセクションをすっきり保ちます — グループの子要素が多く、スクロールして通り過ぎるよりも掘り下げたい場合に選んでください。
:::

### グループ単位の上書き

生成されたグループは、明示的なサイドバーを用意しなくてもグローバルなモードから外れることができます。フォルダーの [`meta.ts`](/docs/content/meta) で `display` を設定するか、そのフォルダーに `index` ページがある場合はそのページのフロントマターの `sidebar` 以下で設定すると、そのグループだけが変わります。

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

生成されたグループの実効モードは、優先度の高いものから順に解決されます。

1. グループ自身の `index` ページのフロントマターの `sidebar.display`
2. フォルダーの `meta.ts` の `display`
3. グローバルな `navigation.sidebar.display`
4. Blume のデフォルト（`flat`）

グループの `display` はそのグループにのみ適用されます — 入れ子のサブグループは、同じ連鎖を通じて自身の値を解決します。インデックスページを持つ `page` モードのグループも、これまでどおりサブパネルへ掘り下げます。インデックスページはパネルの最初の項目として並び、その URL にアクセスするとパネルが直接開きます。

`sidebar.display` は、それ以外の場所では意味を持ちません — インデックス以外のページ、コンテンツルート自身の `index` ページ（ルートはグループではありません。`navigation.sidebar.display` を使ってください）、および[明示的なサイドバー](#explicit-sidebar)が設定されている場合のあらゆるページ（その項目が各グループのモードを決めます）です。そのため Blume は、黙って無視する代わりに `BLUME_SIDEBAR_DISPLAY_IGNORED` 警告を報告します。`collapsed` は引き続き `group` モード専用で、グループが `flat` や `page` に解決される場合は効果がありません。

[明示的なサイドバー](#explicit-sidebar)内のグループは、これまでどおり自身の `display` でグローバルなモードを上書きできます。

## 並び順

サイドバーが生成されるとき、順序は優先度の高いものから順に解決されます。

1. **設定のサイドバー**

    明示的な `navigation.sidebar` は、生成されたツリーを完全に置き換えます。

2. **フォルダー meta**

    `meta.ts` の `pages` 配列がグループの順序を決めます。

3. **フロントマター**

    ページの `sidebar.order`。

4. **ファイルシステム**

    `index`
    ページが最初、次に数値プレフィックス、その後ラベルのアルファベット順。

明示的な順序または数値の順序が同じになった 2 つの兄弟要素は、その 2 つの間ではアルファベット順にフォールバックします — Blume は `BLUME_DUPLICATE_SIDEBAR_ORDER` 警告を報告するので、この重複が見過ごされることはありません。

## 非表示のページ

ページをビルドしたまま URL からアクセス可能に保ちつつ、サイドバーと前後のページネーションから隠します。

```yaml
sidebar:
  hidden: true
```

## タブ

トップレベルのセクションをヘッダーのタブとして描画します。大規模なサイトを別々の領域に分割する場合 — たとえばアダプター、API、AI ガイドなど — に便利です。現在のルートがタブの `path` の配下にある場合、そのタブがハイライトされます。

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

有効化された [OpenAPI または AsyncAPI リファレンス](/docs/advanced/api-reference)は自身のルートにマウントされますが、それ自体でタブが追加されるわけではありません — そのルートを指すタブを設定すると、好きなラベルでヘッダーに表示できます（ネイティブレンダラーの場合は、操作用サイドバーのスコープも設定されます）。

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

タブの `path` はそのセクションのプレフィックスであり、リンク先も兼ねます。`path` が自身のページを持たないセクション — `index.mdx` のないフォルダー — は 404 にリンクしてしまうため、タブは代わりにそのセクションの最初のページにフォールバックします。別の場所に遷移させたい場合は `href` を設定してください。

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

これはコンテンツツリーに含まれないルートで重要になります。フォールバックはそれらを認識できないためです。たとえば生成された[チェンジログ](/docs/advanced/changelog)のインデックスや、`pages/` 以下に追加した[カスタムページ](/docs/advanced/custom-pages)などです。`href` がないと、`/changelog` タブはインデックスではなく最新のエントリーに遷移します。`href` を設定していないタブは影響を受けません。

[i18n](/docs/content/i18n) サイトでは、タブの `label`（およびドロップダウン項目のラベル）を文字列ではなくロケールごとのマップにできます — アクティブなロケールのエントリーが優先され、次にデフォルトロケールのものが使われます。

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}
```

タブは**サイドバーのスコープも設定します**。現在のルートがタブの `path` の配下にある場合、サイドバーにはそのセクションのページだけが表示されます — つまり `/adapters/*` ではアダプターだけが並び、それ以外は表示されません。タブの `path` にあるフォルダーがそのセクションになるため、タブ自体以外の追加設定は不要です。コンテンツをタブごとのフォルダーに構造化し、各タブをそれに向けてください。

どのタブにも属さないルート（または `path` が `/` のタブ）では、サイドバーにはタブに属さ*ない*ページが表示されます — 各タブのフォルダーはそこから隠されます。そのセクションはすでにヘッダーに自身のタブを持っているからです。したがってルートのランディングページでは、セクション化されたコンテンツがタブの向こうに留まったまま、独立したトップレベルのページが並び、Fumadocs のルートフォルダーと同じ挙動になります。この方法で表示できるページがルートに 1 つもない場合は、代わりにツリー全体が表示されるため、サイドバーが空白になることはありません。

## セレクター

サイト全体のパーティション — 製品、バージョン、あるいはグループ化された任意の遷移先の集合 — を切り替えるには、`selector` を追加します。それぞれヘッダーにドロップダウンとして描画され、現在のルートに `path` が一致する選択肢が表示されます。

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

各項目は `label`、`path`、および任意の `icon`、`description`、`tag` を取ります。`kind`（`dropdown`、`product`、`version`、`language`）はセレクターの用途を示すヒントで、いずれも同じドロップダウンとして描画されます。

[バージョニング](/docs/content/versioning)を設定している場合、Blume はバージョンセレクターを自動的に描画します — ここで独自の `kind: "version"` セレクターを宣言すると自動のものが置き換えられるため、手作りの構成もこれまでどおり動作します。

## 注目リンク

リンクをサイドバーの最上部、すべてのセクションより上に固定します — ブログ、チェンジログ、常に 1 クリックで届くべき問い合わせやサポートのページなどです。生成されるツリーと異なり、注目リンクは**タブによるスコープの対象外**です。あらゆるルート、あらゆるブレークポイントで表示されます。

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

各リンクは `label`、`href`、および任意の `icon`（[組み込みアイコン](/docs/content/components#icon)名、画像のパスや URL、インライン SVG — 他の箇所と同じです）を取ります。`href` はどこを指してもかまいません。外部 URL は新しいタブで開き、内部ルート（`/contact`）はビルド時にページと照合され、一致するものがなければ警告されます。

## 明示的なサイドバー

完全に制御したい場合は、`navigation.sidebar` に明示的な項目を列挙します — 素の配列は `sidebar.items` の省略記法であり、オブジェクト形式ではそれらをグローバルな [`display`](#display-modes) と組み合わせられます。項目が設定されると、Blume はそれをそのまま使用し、ファイルシステムからの生成をスキップします。

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}
```

各項目は、ページのルート（文字列）、グループ（`label` + `items`）、またはリンク（`label` + `href`）です。グループは入れ子にでき、グローバルな [`display` モード](#display-modes)を上書きでき、`collapsed` の状態から始めることもできます。

## ヘッダーアクション

`navigation.actions` はヘッダーのアイコンボタンの左側に素のリンクを配置し、`navigation.cta` は唯一の塗りつぶしボタンです。

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

`cta` が単数なのは意図的です — ドキュメントのヘッダーには、読者に求める行動をちょうど 1 つ置く余地しかなく、ボタンが並んでいては何も求めていないのと同じです。二次的なリンクは `actions` に、あるいはサイドバー側に置きたい場合は [`featured`](#featured-links) に含めてください。

`http(s)` またはプロトコル相対の href は新しいタブで開きます。ルートは同じタブに留まり、`featured` リンクと同様にビルド時にページと照合されます — そのため、同じホスト上の別アプリが配信するページ（たとえば製品側の `/signup`）は絶対 URL として書いてください。`actions` は `sm` ブレークポイント未満では非表示になります。そこではヘッダーにロゴとナビゲーションのトグルを置く余地しかないためです。`cta` もそこでは非表示になりますが、ナビゲーションのトグルがないページ — タブのない `PageLayout` のランディングページ — では、スマートフォンで他にそれを表示する手段がないため、そのまま残ります。

## リポジトリリンク

設定で [`github`](/docs/configuration) を指定すると、Blume はヘッダーの — テーマ切り替えの隣に — リポジトリへリンクする GitHub アイコンを表示します。デフォルトで有効で、`navigation.repo` で非表示にできます。

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // hide the header GitHub link (default: true)
}
```

このリンクは `github` が設定されている場合にのみ表示されるため、リポジトリのないプロジェクトはいずれにせよ影響を受けません。

`repo` は絶対 URL も受け取ることができ、ヘッダーのマークを GitHub 上の任意の場所へ向けられます。

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

これはドキュメントのリポジトリが非公開のプロジェクト向けです。`github` はページごとの編集リンク、ヘッダーのマーク、[エージェントマニフェスト](/docs/configuration/ai)のリポジトリをまとめて制御するため、そうしたプロジェクトは `github` を未設定のままにするしかありません — そして URL があれば、公開されたどこかを指すマークを引き続き表示できます。アイコンは GitHub のマークのままなので、別のホストへのリンクは [`actions`](#header-actions) に置いてください。

## パンくずリストとページネーション

これらはサイドバーツリーから自動的に得られ、設定は不要です。

- **パンくずリスト**は、タイトルの上に現在のページの親グループを表示します。
- 各ページ末尾の**前後**のリンクはサイドバーの順序に従い、非表示のページはスキップします。

## このページの内容

右レールのアウトラインは各ページの `##` と `###` 見出しから自動生成されるため、長いページでも見通しが保たれます。右レールが隠れる狭い画面では、コンテンツの上にある「このページの内容」ドロップダウンに折りたたまれます。

## ページアクション

目次の下には、どのページにも一連のクイックアクションが表示されます。

- **GitHub で編集** — ソースファイルへ直接リンクします。設定で [`github`](/docs/configuration) を指定すると表示されます。
- **トップへスクロール** — 長いページの先頭へなめらかに戻ります。
- **フィードバックを送る** — 任意のリアクションとメモを添えて、内容が事前入力された GitHub イシューを開きます（こちらも `github` が必要です）。

そのほかに、ページを AI ツールに渡すアクション — **Markdown としてコピー**と**チャットで開く** — があり、[AI](/docs/configuration/ai#copy-as-markdown) で説明しています。

[`export`](/docs/configuration/export) を有効にすると、**エクスポート**アクションによって読者がページを PDF や EPUB としてダウンロードできるようにもなります。

---

# コンテンツソース
Source: https://useblume.dev/ja/docs/content/sources

Blume はデフォルトで `.md`/`.mdx` ファイルのフォルダーを読み込みます。**コンテンツソース**を使うと、リモートリポジトリ、CMS、任意のカスタムバックエンドなど、別の場所からページを取得し、複数のソースを1つのサイトに統合できます。ソースはビルド時に読み込まれ、Blume はスタティックファーストのままです。

## デフォルトの動作

設定を行わない場合、Blume はコンテンツルート（デフォルトでは `docs`）を1つの暗黙的なファイルシステムソースとしてスキャンします。トップレベルの `content.root`/`include`/`exclude` オプションはこれまでどおり動作するため、変更は不要です。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: { root: "docs" },
});
```

## 複数のソース

ソースを組み合わせるには `content.sources` 配列を追加します。各エントリは任意の `prefix` によって名前空間が分けられ、そのルートは `/<prefix>/…` の下にネストされます。`sources` が存在する場合は暗黙のデフォルトが置き換えられるため、ローカルドキュメント用に `filesystem` エントリを含めてください。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      // Local docs at the site root
      { type: "filesystem", root: "docs" },

      // Remote MDX from a GitHub repo, mounted under /sdk
      {
        type: "mdx-remote",
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      },
    ],
  },
});
```

2つのソースが同じルートに解決される場合、Blume は `BLUME_DUPLICATE_ROUTE` ビルドエラーを報告します。各ソースには異なる `prefix` を指定してください。

## Obsidian

組み込みの `obsidian` ソースは、[Obsidian](https://obsidian.md) の Vault をその場で読み込みます。エクスポート手順は不要で、リポジトリに何かが生成されることもありません。Vault が信頼できる唯一の情報源のままであり、Blume は読み込みの際に Obsidian の方言を Markdown へと変換します。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "obsidian",
        prefix: "notes",
        vault: "vault",
        // Vault folder names to skip at any depth, on top of dot-folders
        exclude: ["Templates", "Daily"],
      },
    ],
  },
});
```

`[[Wikilinks]]` はルートへのリンクになり、Obsidian がノートを指し示すのと同じように、パスではなく Vault 全体を通じたノート名で解決されます。カスタムのリンクテキスト（`[[Note|label]]`）、見出しアンカー（`[[Note#Install]]`）、フルパス（`[[folder/Note]]` および `[[folder/Note.md]]`）、Obsidian のデフォルト設定「可能な場合は最短のパス」が書き出す部分パス（`[[guides/Note]]`）、そして Obsidian がテーブルセル内で書き出す `[[Note\|label]]` の形式はいずれも動作し、フロントマターで `slug` を設定しているノートは、その slug が公開するルートへリンクされます。2つのノートが同じ名前を共有する場合は、Vault のフルパスがちょうどその名前と一致するノートが優先され（Obsidian はリンクを名前より先にパスとして解決します）、次に Vault の順序で最初のもの（Obsidian のファイルエクスプローラーと同じく、大文字小文字を区別せず、ノートよりフォルダーが先）が優先されます。Blume が警告を出すのは、wikilink が実際にそのような衝突を経て解決された場合のみです。曖昧さを解消するには、より長いパスを書いてください。ブロック参照（`[[Note#^id]]`）は、アンカーなしでそのノートへリンクします。ブロックは着地先となる id を持たずにレンダリングされるためです。見出しアンカーは対象ノートの実際の見出しに対して解決され、Obsidian のオートコンプリートが書き出すのと同じ方法（`**bold**`、`` `code` ``、リンク記法を取り除いた形）で照合され、ページマニフェストを埋めるのと同じ `extractHeadings` の処理によって slug 化されます。そのため `#Install` へのリンクは、どのページも出力しない id ではなく、その見出しに着地します。`[[#Install]]` は、書いているノート自身の見出しを指します。存在しない見出しへのリンクは、ページへのリンクは維持したままアンカーを削除し、警告を出します。

フロントマターは、Blume の[ページスキーマ](/docs/reference/frontmatter)が受け付けるものに加え、[`frontmatter.extend`](/docs/reference/frontmatter#custom-keys)（または、その `type` のノートについてはコンテンツタイプの `frontmatter`）で宣言したキーを保持します。それ以外の Obsidian のプロパティ — Dataview のフィールド、Templater の日付、`publish`、および Obsidian 自身の `tags`、`aliases`、`cssclasses` — は、ノートの変換時に削除されます。そのため、Properties UI で書かれた Vault もフロントマターのエラーなくビルドできます。`aliases` は解決されるのではなく削除されます。エイリアスによるリンク先はまだサポートされていません。ノートの隣にある相対パスの Markdown 画像（`![chart](./chart.png)`）は Vault から提供され、Vault が git リポジトリ内にある場合、Vault のページも他のページと同様に git 由来の[「最終更新」日付](/docs/configuration#last-modified)を取得します。「このページを編集」リンクは `github.dir` を通じて解決されるため、モノレポでドキュメントアプリの隣に置かれた Vault でもそのファイルへリンクされます。リポジトリ外の Vault にはリンクは付きません。

Vault 内のロケールディレクトリとバージョンスナップショットは、ファイルシステムソースが読み込むのと同じように読み込まれます。[i18n](/docs/content/i18n) を設定していれば `fr/Note.md` は `/fr/` 配下に、[バージョン](/docs/content/versioning)を設定していれば `v1.0/Note.md` は `/v1.0/` 配下に公開され、それらのノートへの wikilink はそれぞれが公開するルートを指します。

:::note
それ自体にリンクを含む見出しは、マニフェスト用のアンカーを見出しの Markdown から、レンダリングされる `id` をそのテキストコンテンツから取得します。その見出しについては両者が異なるため、そこへの wikilink はセクションではなくページに着地する場合があります。
:::

`index` ノートへのリンクは、実体のない `/index` ではなくそのフォルダーのルートに着地します。**解決できない wikilink は、ビルドを失敗させる代わりに、ビルド警告を出したうえでプレーンテキストに縮退します**。そのため、リファクタリング途中の Vault でも公開できます。単一行の `%%comments%%` は取り除かれ、HTML コメント内の wikilink（`<!-- [[Draft]] -->`）は Obsidian でも非表示になるためそのまま残され、フロントマターに `title` がないノートはファイル名がタイトルになります — これは Obsidian 自身が適用するのと同じルールです。唯一の例外は `index` ノートで、これはノートではなくルートを指すため、そのタイトルは Blume の通常の導出（最初の見出し、次に人間可読化したセグメント）にフォールバックします。フェンス付き、インデント付き、およびインラインのコードはそのまま通過するため、この構文を説明するノートも壊れません。

ドットフォルダーはスキップされます。これには Obsidian 自身の `.obsidian` 設定ディレクトリと `.trash` が含まれ、開発時のウォッチャーもこれらを無視するため、アプリでペインを移動したりノートをゴミ箱に削除したりしてもサイトは再ビルドされません。ノートの編集では再ビルドされます。どのコンテンツスキャンも読み込まないディレクトリ（`node_modules`、`dist`、`.git` など）もスキップされるため、プロジェクト自体をルートとする Vault が依存関係の README を公開することはありません。Vault 内のシンボリックリンクは、ファイルシステムソースがたどるのと同じようにたどられるため、Vault にリンクされた共有フォルダーも一緒に公開されます。`content.root` 内にある Vault は、ファイルシステムソースから除外する必要があります（`exclude: ["vault/**"]`）。そうすれば `blume version cut` はそれをスナップショットから除外し、Vault は自身のノートを引き続き最新版として公開します。

まだ変換されていないもの: コールアウト（`> [!note]`）はプレーンな引用ブロックとしてレンダリングされ、埋め込み（`![[image.png]]`）はそのまま通過し、複数行の `%%comments%%` はそのまま残され、バックリンクグラフはありません。

## リモート MDX

組み込みの `mdx-remote` ソースは、生の `.md`/`.mdx` を HTTP 経由で取得します。ファイルの列挙は、GitHub リポジトリのサブツリー（`github`）から行うか、raw ベース URL に対して明示的に指定（`url` + `files`）します。

```ts blume.config.ts
{
  type: "mdx-remote",
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
}
```

プライベートリポジトリのトークンは `GITHUB_TOKEN` 環境変数から読み込まれます。設定ファイルや生成された出力にインライン展開されることはなく、送信先は GitHub 自身のホスト（`api.github.com`、`raw.githubusercontent.com`）のみで、カスタムの `url` ベースに送信されることはありません。

リモートページは MDX とコンポーネントの機能をすべて備えた形でレンダリングされます。その本文は隠しステージングディレクトリに実体化され、ローカルドキュメントと並んで Astro を通してレンダリングされるため、コールアウト、タブ、その他すべての Blume コンポーネントが引き続き動作します。

### キャッシュとオフラインビルド

各リモートソースは `.blume/cache/<source>/` 配下にスナップショットを保持します。ネットワークの一時的な不調や CMS の障害などで取得に失敗した場合、Blume はビルドを失敗させる代わりに、警告を出しつつ最後に取得できた正常なスナップショットを提供します。キャッシュは `.blume/` 内に置かれ、再生成されるものであり、コミットすることはありません。

開発環境では、リモートコンテンツは一度だけ取得され、そのセッション中は固定されます。更新するには開発サーバーを再起動してください。ローカルのファイルシステムソースは通常どおりホットリロードされます。代わりにリモートソースの変更をポーリングするには、そのソースに `pollInterval`（秒）を設定します。開発サーバーはその間隔で再取得を行い、コンテンツが実際に変更された場合にのみリロードします。作業中に API へアクセスしないようにするには、未設定のままにしてください。

## GitHub Releases

組み込みの `github-releases` ソースは、リポジトリのリリースを変更履歴（changelog）に変換します。各リリースは `type: changelog` のエントリになるため、リリースノートが*そのまま*変更履歴になり、二重に書く必要はありません。生成される[変更履歴タイムライン](/docs/advanced/changelog)と組み合わせれば、GitHub リリースを公開するだけで変更履歴エントリが出荷されます。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // include prereleases (default off)
        // drafts: false,       // include drafts (needs a write token)
        // limit: 100,          // cap releases, newest-first
      },
    ],
  },
});
```

各リリースは変更履歴のフィールドへ自動的にマッピングされます。名前（またはタグ）がタイトルになり、公開日がタイムラインの並び順を決定し、タグが `changelog.version` になり、プレリリースには `Prerelease`（それ以外には `Release`）のタグが付きます。リリースノートはエントリの本文としてレンダリングされます。リリースページを `/changelog/v1-2-0` のようなルートにネストさせるには、ソースに `prefix` を指定してください。

プライベートリポジトリの認証には `GITHUB_TOKEN` 環境変数を使用します。これは他の GitHub 機能が使うものと同じトークンで、設定ファイルにインライン展開されることはありません。他のすべてのリモートソースと同様に `.blume/cache/<source>/` にキャッシュされ、API に到達できない場合はオフラインで提供されます。変更履歴は補助的なものであるため、キャッシュがない状態で取得に失敗した場合（トークンのない CI ビルドなど）は、ビルドを失敗させるのではなく、警告を出して空の変更履歴に縮退します。内容を反映させるには、CI やデプロイ環境で `GITHUB_TOKEN` を設定してください。

## Sanity

組み込みの `sanity` ソースは GROQ クエリを実行し、各ドキュメントのフィールドをフロントマターに、Portable Text の本文を Markdown にマッピングします。`@sanity/client` パッケージは任意の peer dependency です。このソースを使う場合にのみインストールしてください。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "sanity",
        prefix: "guides",
        projectId: "abc123",
        dataset: "production",
        query: `*[_type == "guide"]`,
        // Field paths default to title / slug.current / body / _updatedAt
        fields: { slug: "slug.current", body: "content" },
      },
    ],
  },
});
```

プライベートデータセット用の読み取りトークンは `SANITY_TOKEN` 環境変数から取得されます。カスタムの Portable Text ブロックタイプは、アダプターの `serializers` オプションを通じて Blume コンポーネントにマッピングできます。このオプションは[カスタムソース](#custom-sources)として `sanitySource` を直接構築する場合に利用できます。

## Notion

組み込みの `notion` ソースは、Notion のデータベースをコレクションに変換します。各行がページになり、そのプロパティがフロントマターに、ブロックツリーが MDX になります。コールアウト、トグル、カラム、コードブロックは対応する Blume コンポーネントにマッピングされます。`@notionhq/client`（v5 以降）は任意の peer dependency です。Blume はデータベースをその最初のデータソースを通じて読み込みます。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "notion",
        prefix: "handbook",
        database: process.env.NOTION_DB_ID,
        // Property names default to the title-typed prop / Description / Slug / Order
        // Set publishedValue to treat Status as a publish gate (opt-in)
        publishedValue: "Published",
      },
    ],
  },
});
```

インテグレーショントークンは `NOTION_TOKEN` 環境変数から取得されます（データベースをインテグレーションと共有してください）。デフォルトではすべてのページがインポートされます。`Status` プロパティを公開ゲートとして扱うには `publishedValue` を設定してください。その場合、それ以外の値は `draft: true` にマッピングされ、本番ビルドでは除外されます。**Notion の画像 URL は署名付きで有効期限がある**ため、アダプターはビルド時にそれらをダウンロードしてサイトのアセットに取り込み、参照を書き換えます。CMS の画像が静的ビルドを壊すことはありません。API 呼び出しは小さなリクエストプール（Notion のインテグレーションごとのレート制限に合わせて同時3件）を通してペース調整されるため、数百ページ規模のデータベースでも `429` レスポンスを引き起こすことなくインポートできます。調整するには、ソースに `concurrency` を設定してください。

## プレビューと同期

リモートコンテンツの取得方法と対象範囲は、2つのフラグで制御します。

- **`--preview`** を `blume dev` または `blume build` に付けると、下書きがレンダリングされ、未公開の CMS コンテンツが取得されます。Sanity は `previewDrafts` パースペクティブに切り替わり、Notion は `Status` によるフィルタリングを停止します。フラグなしの本番ビルドはこれまでどおり下書きを除外するため、プレビュービルドは出荷前に未公開の作業を安全に確認する手段になります。
- **`blume sync`** はすべてのリモートソースを再取得し、ランタイムを再生成します。開発環境はキャッシュ優先で、リモートソースは一度取得されると再起動時には `.blume/cache` から提供されます（高速でオフラインにも強い）。そのため、開発サーバーを再起動せずに最新の CMS コンテンツを取得する手段が `blume sync` です（起動中のサーバーはホットリロードします）。先にキャッシュを破棄するには `--force` を追加するか、ソースに `pollInterval` を設定して自動更新してください。

```sh
blume dev --preview      # author workflow: see drafts live
blume build --preview    # render a full preview build
blume sync               # refresh remote content now
blume sync --force       # ...ignoring any cached snapshot
```

## カスタムソース

`ContentSource` インターフェースを実装したオブジェクトはそのまま渡せます。これにより、カスタムシリアライザーを備えたアダプターや、組み込みでない任意のバックエンドを、その SDK をコアのインストールに持ち込むことなく組み込めます。

```ts blume.config.ts
import { defineConfig } from "blume";
import { sanitySource } from "blume/sources/sanity.ts";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "custom",
        source: sanitySource({
          name: "guides",
          prefix: "guides",
          projectId: "abc123",
          dataset: "production",
          query: `*[_type == "guide"]`,
          // Map custom Portable Text blocks to Blume components
          serializers: {
            callout: (block) => `<Callout>${block.text}</Callout>`,
          },
        }),
      },
    ],
  },
});
```

ソースは自身のネイティブな形式（Portable Text、Notion ブロック、リモート HTML）を Markdown/MDX テキストに正規化するため、ページがどこから来たものであっても、同じコンポーネントと Markdown の機能が適用されます。

ローカルファイルを読み込むカスタムソースでは、各エントリに `sourcePath` を、ソース自体に `contentRoot` を設定してください。`sourcePath` は診断メッセージ内でファイルを示し、その隣にある相対パスの画像を解決します。`contentRoot` はページの日付を求める git の `log` の範囲を限定するもので、これがないとそのソースのページは git 由来の[「最終更新」日付](/docs/configuration#last-modified)を取得できません。

---

# 構文
Source: https://useblume.dev/ja/docs/content/syntax

Blume は、標準的な Markdown と MDX を、厳選された GitHub Flavored の機能セットでレンダリングします — インポートも設定も不要です。これまでどおりの書き方でコンテンツを書いてください。このページでは、サポートされているすべての機能を、ライブプレビューと各ソースとともに紹介します。

## 見出し

見出しでページを構造化します。Blume はフロントマターの `title` をページ見出しとしてレンダリングするため、コンテンツは `##` から始めてください — `##` と `###` は目次の項目になります。`##`〜`######` のすべての見出しは、それ自身のアンカーへのリンクでも囲まれるため、読者は見出しをクリックしてそのセクションへのパーマリンクをコピー、ブックマーク、共有できます（ホバーすると `#` が表示されます）。これをオフにするには、`blume.config.ts` で `markdown: { headingAnchors: false }` を指定します。

```md
## Section

### Subsection

#### Detail
```

### カスタムアンカー

アンカーの id は見出しのテキストから生成されるため、見出しの文言を変えると新しいアンカーになります。代わりにアンカーを固定するには `[#custom-id]` を末尾に付けます — このマーカーはレンダリングされず、見出しの文言がどうなってもリンクは機能し続けます。固定したアンカーは[翻訳されたロケール](/docs/content/i18n)間でも同一のまま保たれます。自動生成された id では言語ごとに異なってしまうためです。

```md
## Getting started [#setup]
```

`/page#setup` としてリンクします。この構文は Fumadocs と一致するため、移行したコンテンツはそのまま動作します。

Pandoc、kramdown、および Markdown ベースの仕様策定ツールチェーンで使われる `{#custom-id}` 形式は、`.md` ファイルでは同等のものとして受け付けられます。`.mdx` では、裸の `{…}` は JSX 式となりページのコンパイルに失敗します — `blume check` はこのマーカーを `BLUME_MDX_CURLY_ANCHOR` として報告します — そのため、そこでは `[#custom-id]` と書くか、波括弧をエスケープしてください。エスケープした形式はどちらのフォーマットでも同じアンカーを固定するため、`.mdx` ページが[インクルード](/docs/content/includes)するパーシャルにはこの書き方が適しています：

```md
## Getting started \{#setup\}
```

フラグメントリンクは、`id` を持つ生の HTML 要素（`<a id="setup"></a>`）を対象にすることもできます。`blume validate` は見出しアンカーと並んでそれらも受け付けます。

### 目次マーカー

さらに 2 つの末尾マーカーが、見出しを目次にどう表示するかを制御します。`[!toc]` は見出しをページ上に残しつつ目次からは除外します。`[toc]` はその逆で、見出しは目次にのみ表示され、ページ上では不可視のアンカーターゲットになります — 散文ではなくコンポーネントで構成されたセクションにラベルを付けるのに便利です。マーカーは任意の順序で連結できます。CommonMark から受け継いだ例外が 1 つあります：末尾の角括弧のラベルに対して、ページ内のどこかにリンク参照定義（`[toc]: /url`）がある場合、それはマーカーではなくショートカット参照リンクとなり、見出しのテキストに残ります。

```md
## Appears on the page only [!toc]

## Appears in the TOC only [toc]

## Both markers together [toc] [#custom-id]
```

マーカーは常に解析されます — 文字どおりマーカーの形をしたテキストで終わる見出しは、マーカー付きとして扱われます。バックスラッシュによるエスケープは役に立ちません（マーカーの解析が走る前に、Markdown が `\[` を `[` に解決するためです）。見出しの末尾にマーカーそのものの文字列を表示するには、インラインコードで囲んでください：`` ## Using `[toc]` ``。

## 強調

単語を強調したり、削除を示したり、文中でコードやキー入力を表示したりするためのインライン書式です。

**太字**、_斜体_、~~取り消し線~~、そして `インラインコード`。

```md
**Bold**, _italic_, ~~strikethrough~~, and `inline code`.
```

## 上付き文字と下付き文字

脚注記号、序数、そして科学表記や化学表記をインラインで表現するために使います。

E = mc^2^ と H~2~O。

{/* prettier-ignore */}
```md
E = mc^2^ and H~2~O.
```

## 引用

引用、補足のコールアウト、編集上の注記を周囲の本文から切り離します。

> 高速で、AI に対応し、設定不要のドキュメント — テンプレートに至るまで。

```md
> Documentation that's fast, AI-ready, and zero-config — down to the template.
```

## リスト

順序のない集合には箇条書きリスト、順序のある手順には番号付きリスト、チェックリストやロードマップにはタスクリストを使います。

- Markdown ファーストの執筆
- デフォルトで静的
  - サーバー機能はオプトイン
- 出力は自分のもの

1. Blume をインストールする
2. ページを書く
3. 公開する

- [x] プロジェクトの雛形を作成
- [ ] 最初のガイドを書く

```md
- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide
```

## テーブル

設定オプション、比較表、パラメータ一覧といった構造化データを表にします。区切り行にコロンを使うと、列を揃えられます。

| コマンド      | 説明                   |  出力   |
| ------------- | ---------------------- | :-----: |
| `blume dev`   | 開発サーバーを起動する |    —    |
| `blume build` | 静的サイトをビルドする | `dist/` |

```md
| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |
```

ヘッダー行のないテーブル — 例えばキーと値の組 — が必要な場合は、ヘッダーのセルを空のままにします。Markdown は構文上ヘッダー行と区切り行を必要としますが、Blume はレンダリングされたテーブルから空のヘッダーを取り除きます。

```md
|                |          |
| -------------- | -------- |
| Current status | E-3 visa |
```

## リンクと画像

他のページや外部サイトにリンクします。画像には、コンテンツの隣にあるファイルへの相対パス、`public/` 以下の任意のパス（サイトルートで配信されます）、またはリモート URL を指定できます。

まずは[クイックスタート](/docs/quickstart)をお読みください。

```md
Read the [quickstart](/docs/quickstart) to get started.

![Alt text](./screenshot.png)
```

**ローカル画像には相対パスを推奨します** — ビルド時に最適化されるためです：圧縮され、WebP に変換され、固有の `width`/`height` が付与されるので、読み込み中にページがずれません。画像はそれを使うページの隣（またはコンテンツディレクトリ内の共有フォルダ）に置き、相対パスで参照してください：

```md
![Build output](./images/build-output.png)
```

`public/` 以下の絶対パス（`![Alt text](/screenshot.png)`）は最適化なしでそのまま配信されます — ドキュメントの外から参照されるロゴのように、バイト列と URL を厳密に保つ必要があるファイルに使ってください。リモート画像も、そのホストが [`image` 設定](/docs/configuration#images)で許可されていない限り、手を加えずにそのまま渡されます。

コンテンツ内の画像はデフォルトでクリックしてズームできます — 読者は任意の画像をクリックしてライトボックスで開けます。これをオフにするには `blume.config.ts` で `markdown: { imageZoom: false }` を指定するか、`data-no-zoom` で個別の画像だけ除外します。

## 水平線

長いページの中で、話題が大きく切り替わる箇所を区切ります。

---

```md
---
```

## コードブロック

フェンス付きコードブロックは構文ハイライトされ、言語を示すヘッダー（認識された言語にはブランドアイコン付き）とコピーボタンが表示されます。言語の後に**タイトル** — 通常はファイル名 — を追加すると、ヘッダーの言語ラベルの代わりに表示されます。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```

````md
```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```
````

インラインコードもハイライトできます：バッククォートで囲んだ範囲の中に `{:lang}` マーカーを追加すると、小さなコードブロックのように色付けされます — `useState(){:js}` や `T extends object{:ts}` のように。マーカーを追加したときだけ有効になるので、通常のインラインコードはそのままです — 何かを有効にする必要はありません。

ハイライトはデフォルトで `github-light`/`github-dark` テーマを使います。`markdown.codeBlocks.theme` を使えば、カラーモードごとに任意の[同梱 Shiki テーマ](https://shiki.style/themes)に差し替えられます — すべてのコード表示（フェンス、インラインスニペット、`<CodeBlock>`、`<Diff>`）が一度に色付けされます：

```ts blume.config.ts
export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: "vesper" },
    },
  },
});
```

カスタムの [Shiki テーマ定義](https://shiki.style/guide/load-theme)を直接指定することもできます。VS Code 互換のテーマ JSON ファイルをインポートし（ランタイムが必要とする場合はインポート属性を使います）、いずれかのカラーモードに割り当ててください。同梱テーマ名とカスタム定義を混在させることもできます：

```ts blume.config.ts
import darkTheme from "./themes/acme-dark.json" with { type: "json" };

export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: darkTheme },
    },
  },
});
```

### 行番号

`lineNumbers` を付けると行番号の余白がレンダリングされます — 単独でも、タイトルと併用しても使えます：

```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```

````md
```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```
````

### ハイライト

GitHub 形式のコメントでコードに注釈を付け、行・単語・変更点に注目を集めます。コメントはレンダリング結果から取り除かれるので、コードはコピー＆ペーストしてもきれいなままです。4 種類すべてデフォルトで有効です — 設定は不要です。

`// [!code highlight]` で行に印を付けると、その行の背景がハイライトされます：

```ts
const config = defineConfig({
  title: "My docs", // [!code highlight]
});
```

追加は `// [!code ++]`、削除は `// [!code --]` で変更を示すと、緑／赤の差分としてレンダリングされます：

```ts
export default defineConfig({
  title: "My docs", // [!code --]
  title: "Blume docs", // [!code ++]
});
```

`// [!code word:serve]` で、行内のある語のすべての出現箇所をハイライトします：

```ts
import { serve } from "blume"; // [!code word:serve]

serve({ port: 3000 });
```

`// [!code focus]` で印を付けた行以外をすべて暗くします（残りはホバーすると鮮明になります）：

```ts
export default defineConfig({
  title: "My docs", // [!code focus]
  description: "Built with Blume",
});
```

または、コメントの代わりに**行番号**で行をハイライトすることもできます — コードを編集できない場合に便利です。言語の後に波括弧で範囲を書きます。単一行、カンマ区切りのリスト、`start-end` の範囲がすべて使えます：

```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```

````md
```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```
````

### 表示タイプ

TypeScript のブロックに `twoslash` を付けると、コンパイラから直接得られた実際の型が表示されます — [Twoslash](https://shiki.style/packages/twoslash) によるものです。任意のトークンにホバーすると推論された型が表示され、インラインの `^?` クエリを追加すると、その行の下に型を固定表示できます。

```ts twoslash
const config = {
  title: "My docs",
  version: 1,
};

config.title;
//     ^?
```

````md
```ts twoslash
const config = { title: "My docs", version: 1 };

config.title;
//     ^?
```
````

### TypeScript と JavaScript のタブ

`ts` または `tsx` のブロックに `ts2js` を付けると、タブの組としてレンダリングされます：あなたの TypeScript と、自動生成された JavaScript 版が並ぶので、スニペットは 1 つだけ保守すれば、読者は自分の方言を選べます。変換では型構文と型のみのインポートが取り除かれ、書式・コメント・JSX は書いたとおりに保たれます — さらにタブは同期するため、一度 JavaScript を選ぶとページ上のすべての組が切り替わります。図表や数式と同様に、これは MDX 専用の機能です — `.md` ファイルではこのブロックは通常の TypeScript フェンスとしてレンダリングされます。

```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```

````md
```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```
````

その他のフェンスのメタ情報も組み合わせられます：`title="..."` は両方のタブに表示され、`{1,4-5}` の行範囲は TypeScript のタブにのみ適用されます（型がなくなると行番号がずれるためです）。唯一の例外は `twoslash` です — ホバー時の型は生成されたコードには引き継げないため、両方を付けたフェンスは通常の Twoslash ブロックのままになります。

:::note
言語アイコンを非表示にしたり、長い行をスクロールさせる代わりに折り返したりするには、`blume.config.ts` で `markdown: { code: { icons: false, wrap: true } }` を指定します。
:::

## パッケージインストール

`package-install` ブロックは、1 つのインストールコマンドを npm、pnpm、yarn、bun のタブ付きスニペットに変換します — 読者は自分の環境に合ったものをコピーできます。図表や数式と同様に、これは MDX 専用の機能です — `.md` ファイルではこのブロックは通常のコードフェンスとしてレンダリングされます。

```package-install
npm i blume
```

````md
```package-install
npm i blume
```
````

## 図表

`mermaid` ブロックは、テキストから直接 [Mermaid](https://mermaid.js.org) の図をレンダリングします。フェンスの内容はそのまま Mermaid に渡されるため、Mermaid がサポートするあらゆる図の種類がここで使えます。図はアクティブなカラーテーマに従い、テーマが変わると再レンダリングされます。ソースを `mermaid` でフェンスして記述します：

````md
```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```
````

図はクライアント側でレンダリングされるため、これは MDX 専用の機能であり、Mermaid ライブラリは図を含むページでのみ読み込まれます。このセクションの残りは代表的な種類のギャラリーです — 全一覧は [Mermaid のドキュメント](https://mermaid.js.org/intro/)を参照してください。

### フローチャート

```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```

### シーケンス図

```mermaid
sequenceDiagram
  participant R as Reader
  participant B as Blume
  R->>B: Request /docs
  B-->>R: Prerendered HTML
```

### クラス図

```mermaid
classDiagram
  class Page {
    +string title
    +string route
    +render()
  }
  Page <|-- Doc
  Page <|-- Changelog
```

### 状態遷移図

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: build
  Published --> [*]
```

### ER 図

```mermaid
erDiagram
  PAGE ||--o{ HEADING : contains
  PAGE {
    string title
    string route
  }
```

### ユーザージャーニー

```mermaid
journey
  title Publishing a page
  section Write
    Draft MDX: 5: Author
  section Ship
    blume build: 4: Author
    Deploy: 3: Author
```

### ガントチャート

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Docs
    Draft   :a1, 2026-01-01, 7d
    Review  :after a1, 3d
```

### Git グラフ

```mermaid
gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit
```

### 円グラフ

```mermaid
pie title Content types
  "Docs" : 70
  "Blog" : 20
  "Changelog" : 10
```

### マインドマップ

```mermaid
mindmap
  root((Blume))
    Content
      MDX
      Markdown
    Build
      Static HTML
      llms.txt
```

### タイムライン

```mermaid
timeline
  title Blume milestones
  2025 : Prototype
  2026 : 1.0 release
```

## コールアウト

コールアウトは、背景情報・助言・リスクに読者の注意を向けます。`:::type` ディレクティブとして書き、`:::warning[Heads up]` のように角括弧でタイトルを追加できます。ディレクティブは MDX 専用の機能です — `.md` ファイルでは `:::note` の行はそのまま文字列として残ります。

### Note

読者が心に留めておくべき、中立的な補足情報です。

:::note
Blume は実行のたびに `.blume/` を再生成します — 手動で編集しないでください。
:::

```md
:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::
```

### Tip

必須ではないものの、作業を楽にしてくれる便利な近道やベストプラクティスです。

:::tip
`deployment.site` を設定すると、サイトマップと Open Graph 画像が絶対 URL を使うようになります。
:::

```md
:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::
```

### Success

良好な結果や、手順が期待どおりに完了したことを伝えます。

:::success
ドキュメントのビルドに成功し、デプロイの準備が整いました。
:::

```md
:::success
Your docs built successfully and are ready to deploy.
:::
```

### Warning

ミスや予想外の挙動を避けるために注意が必要な点を示します。

:::warning[ご注意]
`output: "server"` に切り替える場合、デプロイの前にアダプターが必要です。
:::

```md
:::warning[Heads up]
Switching to `output: "server"` requires an adapter before you can deploy.
:::
```

### Danger

簡単には元に戻せない、破壊的または破壊的変更を伴う操作を警告します。

:::danger
`blume eject` は一方通行の手順です — 生成された Astro プロジェクトはあなたのものになります。
:::

```md
:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::
```

### Info

情報提供のための補足です。中立的に読める、エイリアスにも使いやすいデフォルトです。

:::info
コアテーマにはクライアントフレームワークの JS は含まれません。
:::

```md
:::info
The core theme ships no client framework JS.
:::
```

`caution`、`error`、`important`、`warn` という名前は、それぞれ `warning`、`danger`、`note`、`warning` のエイリアスとして使えます。

## 数式

KaTeX で LaTeX を中央揃えのブロックとしてレンダリングします — 数式の多いドキュメントや科学系のドキュメントに便利です。数式を `$$…$$` で囲みます：

$$
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

```md
$$
a^2 + b^2 = c^2
$$
```

:::note
数式はブロック専用で、自動的に有効になります — `$$…$$` と書けばレンダリングされ、書かなければ KaTeX のスタイルシートは一切配信されません。インラインの `$…$` 数式はありません：単独の `$`（通貨、シェル変数、コード）は常にそのままの文字列として扱われるため、エスケープすべき区切り文字も、切り替える設定もありません。数式は MDX 専用の機能です。レンダリングされたマークアップ内のクラス名（`.katex-html`、`.katex-base` など）は KaTeX 自身の内部実装であり、Blume が保証するスタイリングの契約ではありません — KaTeX のアップグレードで変わる可能性があるため、カスタムスタイルは `.katex-display` のラッパーを対象にしてください。
:::

## スマート句読点

Blume は、書いているそばから直線的な引用符やダッシュを組版上の等価な記号に変換するため、特殊文字を使わなくても、組版されたかのように文章が読めます。

"Quotes" は曲線的な引用符になり、-- は en ダッシュ、--- は em ダッシュ、... は省略記号になります。

```md
"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
```

---

# バージョニング
Source: https://useblume.dev/ja/docs/content/versioning

Blume は、実際のリリース運用に沿った形でドキュメントをバージョン管理します。最新のドキュメントはコンテンツのルートに置かれ、プレフィックスのないきれいな URL を持ちます。そして過去の各バージョンは、それぞれのフォルダに凍結されたスナップショットとして保存されます。リリース時にスナップショットを作成すれば、切り替え UI、「古いバージョン」の通知、検索のスコープ設定、SEO、エージェントインターフェースは Blume が自動で構成します。これはオプトイン方式です。`versions` ブロックがなければ、何も変わりません。

## 有効にする

現在のドキュメントとアーカイブ済みスナップショットを指定する `versions` ブロックを追加します:

```ts blume.config.ts lineNumbers
versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}
```

`current` は、切り替え UI におけるプレフィックスなしのツリーのラベルを設定します（`badge` は任意です）。アーカイブされた各エントリの `id` は、スナップショットのディレクトリ名であると同時に URL セグメントでもあります。id は文字で始める必要があり（`1.0` ではなく `v1.0`）、これにより[数値の並び順プレフィックス](/docs/content/navigation#ordering)と衝突することがなくなります。アーカイブ済みバージョンは新しいものから順に並べてください。その順序がそのまま切り替え UI の順序になります。

## バージョンを作成する

リリース時には、次のコマンド 1 つで現在のドキュメントを凍結できます:

```bash
blume version v1.0
```

このコマンドは、コンテンツツリーを `docs/v1.0/` にコピーし（既存のスナップショットは除外されます）、コピー内のルート絶対リンクをスナップショット内に留まるように書き換え（`/guides/x` は `/v1.0/guides/x` になります。フェンス付きコードおよびインラインコードは変更されません）、`blume.config.ts` に id を登録します。設定ファイルが自動編集できない形になっている場合は、貼り付け用のエントリを出力します。コピー対象のツリーに含まれないページへのリンク（生成された API リファレンス、変更履歴などのリモートソース）は、スナップショットにそのコピーが存在しないため、ライブのページを指したままになります。id を付けずに `blume version` を実行すると、設定済みのバージョン一覧が表示されます。

新しいディレクトリは、他のコンテンツと同様に確認してコミットしてください。反映するには `blume dev` を再起動します。

```txt
docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart
```

**アーカイブ済みとは凍結を意味します。** 今後の編集はライブのツリーに対して行ってください。スナップショットは当時のままのドキュメントです。Blume はその前提に基づいて動作します。スナップショットは独自のフォルダメタデータと翻訳を保持し、[`blume translate`](/docs/reference/translate) がスナップショットを再翻訳することはありません。また、設定で明示したサイドバーは現在のドキュメントにのみ適用され、スナップショットのサイドバーは常にそれ自身のファイルから生成されます。

## 切り替え UI と通知

バージョンを設定すると、ヘッダーにバージョンのドロップダウンが自動的に追加されます。切り替え時には、対象バージョンに同じページが存在すればそのページに、存在しなければそのバージョンのルートに遷移します（常にルートに遷移させるには `switcher.redirect: "root"` を設定します）。[`navigation.selectors`](/docs/content/navigation#selectors) で独自の `kind: "version"` セレクターを宣言した場合は、そちらが自動生成のものを置き換えます。

アーカイブ済みのすべてのページには、そのページのライブ版へのリンクを含む「最新版へ移動」の通知もデフォルトで表示されます（読者が閉じることはできません）。バージョンごとにカスタマイズまたは無効化できます:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0", banner: "These docs cover the 1.x SDK." },
    { id: "v0.9", banner: false },
  ],
}
```

## SEO

古いドキュメントは検索エンジンにとって格好の落とし穴です。古いページが最新のページより上位に表示されたり、両者が競合したりします。Blume は、SEO ガイドが推奨しながらも他のどのドキュメントフレームワークも自動化していない解決策をデフォルトとしています。アーカイブ済みページはインデックス可能なまま維持されますが、**最新版の対応ページを正規 URL として宣言します**。これによりライブのページが権威あるページとなり、一方でそのバージョンにしか存在しないコンテンツ（最新ドキュメントにはすでに存在しないページ）は自己正規 URL によって引き続き見つけられます。

バージョンごとに異なる扱いを選択できます:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0" }, // canonical → latest (default)
    { id: "v0.9", canonical: "self" }, // every page authoritative
    { id: "v0.8", noindex: true }, // deindexed entirely
  ],
}
```

サイトマップもこれに従います。正規 URL がライブの対応ページを指しているアーカイブ済みページは除外され、`noindex` のバージョンは丸ごと除外され、そのバージョンにしかないページは掲載されたままになります。ページ自身の `seo.canonical` フロントマターは常に優先されます。

## 検索

検索ダイアログは、閲覧中のバージョンに結果のスコープを絞り込み、言語トグルの隣に「すべてのバージョン」トグル（読者ごとに記憶されます）を表示します。バージョンをまたぐヒットは、結果の行にバージョン名が表示されます。Orama（デフォルト）、FlexSearch、Algolia、Typesense はいずれもこのスコープ設定に対応しています。ホスト型のレコードは `version` ファセットを持ち、現在のドキュメントは `"current"` としてアップロードされます。一方 Pagefind はスコープ設定に対応しておらず、ロケールの挙動と同様の扱いになります。

## エージェント

エージェントインターフェースはバージョンを認識します。これは他のどのドキュメントフレームワークにもない機能です:

- MCP の `search_docs` および `list_pages` ツールは、デフォルトで現在のドキュメントを対象とし、`version` を受け付けます。値はアーカイブ済みの id（`"v1.0"`）または `"all"` です。`get_navigation` はリクエストに応じてアーカイブ済みスナップショットのツリーを返します。
- `llms.txt` は、現在のドキュメントの後ろにアーカイブ済みバージョンのセクションを配置し、`1.0 (archived)` のようにラベル付けします。これにより、インデックスを読むエージェントはどのドキュメントが凍結されているかを把握できます。
- `llms-full.txt` は現在のバージョンのみを対象とします。フラットなダンプに同じページの凍結コピーが混在することはありません。
- 生の Markdown ミラー（`.md` の URL）は、他のルートと同様に、すべてのバージョンのページに存在します。

## i18n との併用

バージョニングは[国際化](/docs/content/i18n)と組み合わせられます。ディスク上ではバージョンフォルダが最も外側になり、スナップショットはその中にロケールフォルダを自然に含みます。一方 URL では、サイトの他の部分と同様にロケールが最も外側になります:

```txt
docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
```

ロケールのフォールバックは各バージョン内で機能します。未翻訳のスナップショットページは、ローカライズされた URL でフォールバックロケールのコンテンツを表示し、`hreflang` の代替指定はバージョンごとにグループ化されます。バージョン id は設定済みのロケールコードと衝突してはなりません。Blume はそのような設定を明確に拒否します。

## バージョン管理されないもの

バージョニングの対象はドキュメントのコンテンツツリーです。ブログ、変更履歴、OpenAPI 仕様から生成される API リファレンス、カスタムページは常に最新版のみです。さらに知っておくべき挙動が 2 つあります。ヘッダーのタブは現在のドキュメントに対して定義されるため、アーカイブ済みツリー内ではサイドバーはタブによるスコープなしで表示されます。また、大規模サイトでは、各スナップショットが完全なコピーである点に注意が必要です。コンテンツ、検索インデックスのエントリ、ナビゲーションデータはすべてバージョンごとに増加します。

---

# デプロイ
Source: https://useblume.dev/ja/docs/deployment

## どこにでもデプロイ（静的）

`blume build` はドキュメントを素の HTML、CSS、そしてローカル検索インデックスとして `dist/` にコンパイルします。実行するサーバーはありません — 任意の静的ホストにそのフォルダを向けるだけです。

| 設定             | 値            |
| ---------------- | ------------- |
| ビルドコマンド   | `blume build` |
| 出力ディレクトリ | `dist`        |
| Node バージョン  | 22.12 以降    |

これらの設定は Vercel、Netlify、Cloudflare Pages、GitHub Pages、Amazon S3 + CloudFront、その他あらゆるバケットや CDN で動作します。ホストがビルドを実行できるよう、`blume` が依存関係に含まれていることを確認してください。

静的ビルドには次のものが含まれます:

- すべてのドキュメントページとカスタムページ（静的 HTML として）
- ローカル検索インデックス（デフォルトは Orama、Pagefind はオプトイン）
- `deployment.site` が設定されている場合の [`sitemap.xml`](/docs/configuration/seo#sitemap) と [`robots.txt`](/docs/configuration/seo#robots)
- AI ツール向けの `llms.txt` と `llms-full.txt`
- リダイレクトページ
- `seo.og.enabled` が有効な場合、事前レンダリングされた [Open Graph 画像](/docs/configuration/seo#open-graph-images)

### サイト URL を設定する

サイトマップ、canonical タグ、RSS、Open Graph 画像には絶対オリジンが必要です。**Vercel**、**Netlify**、**Cloudflare Pages** では、Blume がビルド時にプラットフォームの環境から自動検出します — 設定は不要です。

検出された値を上書きする場合、またはそれを公開していないホスト（GitHub Pages、S3、カスタム CDN）で指定する場合は `deployment.site` を設定します:

```ts blume.config.ts lineNumbers
deployment: {
  site: "https://docs.example.com",
}
```

自動検出の際、Blume はデプロイごとのプレビュー URL よりも安定した本番ドメインを優先するため、canonical オリジンはデプロイをまたいで変わりません。

`blume dev` の実行中、サイト URL が未設定の場合はローカル開発サーバー（例: `http://localhost:4321`）にフォールバックするため、サイト URL に依存する機能 — Open Graph 画像、canonical、サイトマップ — がそのまま動作します。ビルドではこのフォールバックは使われないため、本番の出力が localhost を指すことはありません。

## ローカルでプレビューする

公開する前に、静的ホストが配信するのとまったく同じ形で本番ビルドをプレビューしましょう:

```bash
blume build
blume preview
```

## サブパスへのデプロイ

`example.com/docs` のようなパス配下でドキュメントを配信しますか？ `deployment.base` を設定してください — GitHub Pages のプロジェクトサイトでよくあるケースです。ルートを含むサイト全体がそのベース配下に移動し、内部リンクとアセットもベースを含むように書き換えられます。

```ts blume.config.ts lineNumbers
deployment: {
  base: "/docs",
}
```

## ドキュメントをパス配下にマウントする

`basePath` は生成されるすべてのルートをあるセグメント配下（`/docs/getting-started`）にマウントしますが、サイドバーはそのままです — トップレベルはラッパーグループではなく、あなたのセクションのままです。ドキュメントは `/docs/*` に置きつつ、サイトのルートは自分のものとして残したい場合に使います（Docusaurus の `routeBasePath` や Fumadocs の `baseUrl` のようなものです）。

```ts blume.config.ts lineNumbers
basePath: "/docs",
```

リンクはルートにマウントされている前提（`/getting-started`）で書いてください。Blume がリンクを書き換え、リダイレクト、サイトマップ、canonical URL、Open Graph 画像、`llms.txt`、検索インデックスも合わせて処理します。公開アセット（画像や `public/` 配下のファイル）はサイトのルートに残ります。

これは上記 2 つのパスとは別の概念です:

- ソースごとの [`prefix`](/docs/content/sources#multiple-sources) は**単一**のソースに名前空間を与え、サイドバーグループを**追加します**。
- `deployment.base` は**アプリ全体**が配信されるホスト側のサブディレクトリです。両者は組み合わせられます — 両方を設定すると、ページは `{deployment.base}/{basePath}/page` に配置されます。

## サーバーレンダリング

静的出力でほとんどのドキュメントは事足ります。リクエスト時の機能 — 特に [Ask AI](/docs/configuration/ai) エンドポイント — が必要な場合はサーバー出力に切り替えます:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

`vercel` と `node` のアダプターは Blume に同梱されています — 選ぶだけで動きます。`netlify` と `cloudflare` のアダプターはプロジェクトへのインストールが必要です（例: `bun add -d @astrojs/netlify`）。パッケージが見つからない場合、CLI が警告します:

| アダプター | パッケージ | 用途 |
| --- | --- | --- |
| `vercel` | `@astrojs/vercel` | Vercel — 最も洗練された選択肢 |
| `netlify` | `@astrojs/netlify` | Netlify Functions |
| `node` | `@astrojs/node` | セルフホストの Node サーバー、コンテナ |
| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers と Pages |

**Vercel**、**Netlify**、**Cloudflare Pages** では、サーバー出力時に Blume が対応するアダプターを自動選択します — `output: "server"` を設定してデプロイするだけです（Netlify と Cloudflare ではアダプターのパッケージもインストールしてください）。検出された値を上書きする場合や、`node` でセルフホストする場合は `adapter` を明示的に設定します。

サーバービルドには静的ビルドのすべてに加えて、追加した Astro のエンドポイントやミドルウェアが含まれます。`node` アダプターは直接実行できるスタンドアロンのサーバーを生成します。

Vercel と Cloudflare では、サーバービルドによって [`Accept: text/markdown` のコンテンツネゴシエーション](/docs/configuration/ai#content-negotiation) も有効になり、そのヘッダー付きで任意のコンテンツページをリクエストしたエージェントは、同じ URL で生の Markdown 版を受け取れます。Vercel では、Blume がデプロイのルーティング設定にヘッダー条件付きのリライトを挿入します。Cloudflare では、Astro の Worker の手前に小さな Worker を生成し、`assets.run_worker_first` をコンテンツルートに限定します — そうしないと、プラットフォームはサーバーコードが実行される前に事前レンダリング済みページを配信してしまうためです。その他のアセットは Worker を介さない高速パスを維持します。

:::note
サーバー機能にはそれぞれ独自の設定があります — 例えば Ask AI にはモデルの API キーが必要です。セットアップについては [AI ガイド](/docs/configuration/ai) を参照してください。
:::

## リダイレクト

`blume.config.ts` で古い URL を新しい URL にマッピングします:

```ts blume.config.ts
redirects: [{ from: "/old", to: "/new", status: 301 }];
```

`status` は `301`、`302`、`307`、`308` を受け付けます（デフォルトは `301`）。サーバービルドではリダイレクトをリクエスト時に処理します。静的ビルドではリダイレクトページ**に加えて**プラットフォーム用のファイルも出力するため、ホストが本物の HTTP リダイレクトを返せます: `_redirects`（Netlify、Cloudflare Pages）、`vercel.json`（Vercel）、そして `blume-redirects.json` — その他の環境（nginx/Apache のルール、エッジワーカーなど）向けの構造化マニフェストです。`public/` に配置した `_redirects` や `vercel.json` はそのまま維持されます。

:::note
`from` は完全一致のパスとして照合されます — ワイルドカードやパターンマッチ（例: `/blog/:slug` や `/old/*`）はサポートされていません。パターンベースのルールが必要な場合は、`vercel.json`（ワイルドカードの `source` パターンをサポート）のようなインフラ側のファイルや、ホストのリダイレクト設定で対応してください。`public/` に配置した `vercel.json` はそのまま保持されます。
:::

:::note
`from` と `to` はどちらもルートにマウントされている前提で書いてください — [`deployment.base`](#subpath-deploys) でも [`basePath`](#mount-the-docs-under-a-path) でも、Blume が両側を書き換えるため、リダイレクト先はベース配下に収まります。`to` に手動でベースを書き込んでいる場合は、二重にならずそのまま維持されます。
:::

## コンテンツタイプ

静的ビルドでは `_headers` ファイルも出力され、生の AI 対応エンドポイント — `/<route>.md`、`/<route>.mdx`、および `.txt` ファイル（`llms.txt`、`llms-full.txt`）— に `charset=utf-8` を固定します。これらのレスポンスは妥当な UTF-8 ですが、多くの静的ホストは charset **なし**の `text/markdown` / `text/plain` として配信し、ブラウザは Windows-1252 にフォールバックします — その結果、非 ASCII のドキュメント（日本語、アクセント付きラテン文字など）は生の URL を直接開いたときに文字化けします。HTML ページは `<meta charset>` を持つため影響を受けません。Netlify と Cloudflare（Pages/Workers の静的アセット）は `_headers` を読み取ります。読み取らないホスト（Vercel、S3）はこのファイルを無害に無視します。`public/` に配置した `_headers` はそのまま維持されます。

## 環境変数

機能が実行時のシークレットを必要とする場合、それが欠けていると Blume は `blume dev`/`build` の時点で警告します — 最初のリクエスト時ではなく、早い段階で問題が表面化します:

| 機能 | 変数 |
| --- | --- |
| Ask AI（AI Gateway） | `AI_GATEWAY_API_KEY`（または Vercel OIDC） |
| Ask AI（その他のプロバイダー） | プロバイダーのデフォルトのキー環境変数（`OPENROUTER_API_KEY`、`LLMGATEWAY_API_KEY`、`INKEEP_API_KEY`）、または設定した `apiKeyEnv` |
| Mixedbread 検索 | `MIXEDBREAD_API_KEY` |

ローカル開発では `.env.local` に、本番ではホストの環境に設定してください。検索インデックスの同期（Algolia、Orama Cloud、Typesense）に必要なビルド時のシークレットについては、同期ステップで個別に警告されます。

## ビルドサマリー

ビルドのたびにサマリーが出力されます — 出力モード、アダプター、解決されたサイト URL、検索プロバイダー、リダイレクト数、サイトマップと `llms.txt` の状態、有効になっているサーバー機能 — デプロイ前に、何が反映されたのか（自動検出されたものも含めて）を確認できます。

---

# FAQ
Source: https://useblume.dev/ja/docs/faq

よく寄せられる質問への回答です。載っていないものがありますか？[Issue を作成](https://github.com/haydenbleasel/blume/issues)するか、ページ内アシスタントにお尋ねください。

## Blume は Mintlify や Fumadocs などとどう違いますか？

ほとんどのドキュメントツールは、2 つの両極端のどちらかに位置しています。Mintlify のような**マネージドプラットフォーム**は洗練された結果をすばやく得られますが、ビルドとホスティングは彼らのサービスです — 彼らのシステム内で執筆し、彼らのインフラにデプロイすることになります。Fumadocs、Nextra、Docusaurus のような**コンポーネントライブラリやスターター**はオープンソースで柔軟ですが、渡されるのはアプリケーション（Next.js や React のプロジェクト）であり、一文字書く前も後も、スキャフォールドし、配線し、メンテナンスし続ける必要があります。

Blume は第三の道を選びます: **フレームワークがテンプレートそのもの**です。Markdown のフォルダを指定すれば、サイト全体 — ナビゲーション、検索、テーマ設定、Open Graph 画像、SEO、AI エンドポイント — を生成して動かします。所有すべきアプリはありません。完全にオープンソースかつセルフホスト可能なので、マネージドサービスもベンダーロックインもなく、同時に維持すべきボイラープレートもありません。

|  | Blume | Mintlify | Fumadocs / Nextra / Docusaurus |
| --- | --- | --- | --- |
| **モデル** | ゼロコンフィグのフレームワーク。コンテンツのみ | ホスト型プラットフォーム | ライブラリ + 自分でスキャフォールドするアプリ |
| **ソース** | オープンソース（MIT） | クローズドなコア | オープンソース |
| **ホスティング** | どこでも — 静的またはサーバー関数 | 彼らのマネージドインフラ | どこでも。自分でビルドしデプロイ |
| **メンテナンス対象** | あなたの Markdown | あなたの Markdown + プラットフォーム設定 | あなたの Markdown + その周りのアプリ |
| **レンダリング** | Astro。コアテーマはクライアント JS ゼロで配信 | 彼らのランタイム | React/Next.js ランタイム |
| **AI 機能** | `llms.txt`、生の Markdown、Ask AI、MCP — 組み込み、ホスト型サービス不要 | 組み込み（ホスト型） | 自分で用意 |

特筆すべき帰結がいくつかあります:

- **出力はあなたのものです。** `blume build` は、Vercel、Netlify、Cloudflare、S3、あるいは自前のマシンでホストできるプレーンなサイトを生成します。外部への通信は一切ありません。
- **ロックインなし、出口は 2 つ。** コンテンツはポータブルな Markdown であり、`blume eject` はプロジェクトを、完全な制御が欲しくなったときに引き続き `blume` パッケージを使うスタンドアロンの Astro アプリへと変換します。
- **デフォルトで高速。** コアテーマは React を使わず静的 HTML をレンダリングするため、チューニングなしで Core Web Vitals のスコアが良好です。サーバー機能（Ask AI、MCP）は必要なときにだけオプトインします。
- **型安全な設定。** `blume.config.ts` とすべての `meta.ts` は、スキーマで検証される本物の TypeScript です — 型の緩い YAML ではありません。

:::note
これは「あらゆる点で優れている」という話ではありません — ホスト型の製品が欲しい場合や、アプリを最大限にコントロールしたい場合には、マネージドプラットフォームやフル機能のフレームワークが正しい選択です。Blume は、プラットフォームも配管も所有せずに本番品質のドキュメントサイトが欲しいチームのためのものです。
:::

より詳しい説明は [Blume が存在する理由](/docs) をご覧ください。

## Blume は無料でオープンソースですか？

はい — Blume は MIT ライセンスで無料です。`blume` パッケージをインストールし、コンテンツは自分のリポジトリに置き、ビルド結果は好きな場所でホストできます。有料プランも、シートごとの課金も、サインアップするアカウントもありません。ソースは [GitHub](https://github.com/haydenbleasel/blume) にあります。

## Astro、React、Tailwind を知っている必要はありますか？

いいえ。Markdown のフォルダがそのまま完全なサイトになります — ナビゲーション、検索、テーマ設定は推論されるか、ごくわずかなトークンで設定できます。基盤となるスタックに触れるのは、カスタマイズしたいときだけです: [インタラクティブなアイランド](/docs/content/islands)（React）、[コンポーネントのオーバーライド](/docs/configuration/customization)、[テーマトークン](/docs/configuration/theming)（Tailwind）。その場合でも、[`blume.config.ts`](/docs/configuration) は型付けされているので、エディタが導いてくれます。

## React コンポーネントや MDX は使えますか？

はい。どのページも `.md` でも `.mdx` でも構いません。MDX なら、インポートなしで[組み込みコンポーネント](/docs/content/components)を挿入できます。独自の `.tsx`/`.jsx` [アイランド](/docs/content/islands)を追加することもできます — Blume はそれらを使うページでのみ React を自動的に有効化するので、他のすべての場所でコアテーマは JavaScript フリーのままです。

## どこにデプロイできますか？

どこにでも。`blume build` はデフォルトで静的 HTML を出力するので、任意の静的ホストや CDN — Vercel、Netlify、Cloudflare Pages、GitHub Pages、S3、あるいは自前のサーバー — から配信できます。サーバー専用の機能（Ask AI、MCP サーバー、オンデマンドレンダリング）を使うと、Vercel、Node、Netlify、Cloudflare 向けのアダプタを通じて、ビルドがサーバー関数へと切り替わります。[デプロイ](/docs/deployment)をご覧ください。

## 検索にはホスト型サービスが必要ですか？

いいえ。[Orama](/docs/configuration/search) は開発環境でも本番環境でも動作するローカルインデックスを構築し、ホストするものも支払うものもありません。非常に大規模なサイトでは、[Pagefind](/docs/configuration/search) がフラグ 1 つで使えます。いずれの場合も、インデックスはサイトの一部として配信されます。

## 見た目はどうカスタマイズしますか？

まずは[テーマトークン](/docs/configuration/theming)から — アクセントカラー、フォント、角丸、そして Tailwind で表現できるその他すべてのための `theme.css` です。さらに進めるなら、[組み込みコンポーネントのオーバーライド](/docs/configuration/customization)や[カスタムページ](/docs/configuration/customization#custom-pages)の追加があります。Astro プロジェクトそのものが欲しくなったら、[`blume eject`](/docs/reference/cli) が、引き続き `blume` パッケージを使うスタンドアロンのアプリを渡してくれます。

## なぜ oxfmt / Ultracite がディレクティブを潰すのですか？

Markdown を [Ultracite](https://www.ultracite.ai)（oxlint + [oxfmt](https://oxc.rs) を実行します）でフォーマットしている場合 — Blume 自身もそうしています — フォーマット後にコンテナディレクティブが 1 行に平坦化されることに気づくかもしれません:

```md
:::note
Regenerate the project with blume dev.
:::
```

が次のようになります

```md
:::note Regenerate the project with blume dev. :::
```

開始の `:::note` フェンスが本文と結合されてしまうと、それはもうディレクティブではなくなるため、[コールアウト](/docs/content/syntax#callouts)ではなくそのままのテキストとしてレンダリングされます。

### なぜ起きるのか

これは oxfmt の Markdown フォーマッタのバグです（Prettier の Markdown プリンタから受け継いだもの — [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040) を参照）。本文を折り返す際に、`:::` のフェンス行を通常のテキストとして扱い、隣接する行と結合してしまうため、ディレクティブが壊れます。これはすべてのコンテナディレクティブの種類 — `:::note`、`:::tip`、`:::info`、`:::warning`、`:::danger`、`:::success` — に影響します。

私たちは [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096) で上流に報告しました。そちらで修正されるまでは、以下のパッチが回避策です。

### 修正方法

`:::` フェンスに直接隣接する改行を保持するように oxfmt にパッチを当てます。Blume は自身のリポジトリでも同じ修正を配布しており、どんなプロジェクトにも適用できます。

1. パッチを `patches/oxfmt@0.66.0.patch` として保存します:

   ```diff patches/oxfmt@0.66.0.patch
   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
   --- a/dist/markdown-BgZGxhM2.js
   +++ b/dist/markdown-BgZGxhM2.js
   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
    		case "sentence": return Oh(e, r);
    		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
    		case "whitespace": {
   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   +			let { next: a, 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(":::");
   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
   +			// linkReference between two sentence nodes at the paragraph level: the
   +			// fence word ends the sentence before the reference, and the body's
   +			// leading newline opens the sentence after it. So when this whitespace
   +			// starts its sentence, climb to the paragraph and check whether the two
   +			// preceding siblings are a (link) reference and a sentence ending in a
   +			// `:::` fence word.
   +			let oxfmtPrevIsTitledFence = !1;
   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
   +				if (oxfmtSentIdx >= 2) {
   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
   +				}
   +			}
   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
   +			// words, so the whole directive is one sentence. For a newline
   +			// whitespace, walk back to the start of its visual line within the
   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
   +				let oxfmtLineFirst = null;
   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
   +					let oxfmtSib = e.parent.children[oxfmtJ];
   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
   +					oxfmtLineFirst = oxfmtSib;
   +				}
   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
   +			}
   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
    			return ou(e, n.value, u, !1, t);
    		}
    		case "emphasis": {
   ```

2. パッケージマネージャの `patchedDependencies` に登録します。Bun や pnpm では、`package.json` に追加します:

   ```json package.json
   {
     "patchedDependencies": {
       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
     }
   }
   ```

3. パッチが適用されるよう再インストールします:

   ```package-install
   bun install
   ```

:::warning[バージョン固定]
このパッチは特定の oxfmt ビルドを対象としています — その差分は、リリースごとにハッシュ化された名前を持つファイル（`dist/markdown-*.js`）を参照しています。oxfmt を更新する際は、パッチを再生成する（例: `bun patch oxfmt`）か、上流の修正が取り込まれてパッチが不要になっていないか確認してください。
:::

---

# クイックスタート
Source: https://useblume.dev/ja/docs/quickstart

空のフォルダから、いくつかのコマンドだけで動作するドキュメントサイトまで到達できます。Blume に必要なのは **Node.js 22.12 以降**と、`.md` または `.mdx` ファイルを 1 つ以上含む `docs/` フォルダだけです。それ以外に用意するものはありません。

## インストールと実行

1. **Blume をインストールする**

    新規または既存のプロジェクトにパッケージを追加します。

    ```package-install
    npm i blume
    ```

2. **プロジェクトを作成する**

    `blume init` はいくつかの質問をします — プロジェクトを作成する場所、ドキュメントサイトの名前、使用するテンプレート、コンテンツの配置場所 — そのうえで最小限の構成、つまりコンテンツフォルダと設定ファイルを生成します。プロンプトをスキップしてデフォルト値を使うには `--yes` を渡してください。

    ```bash
    blume init
    ```

    ```txt
    docs/
      index.mdx
    blume.config.ts
    ```

3. **開発サーバーを起動する**

    Blume がランタイムを生成し、ホットリロード付きでドキュメントを配信します。

    ```bash
    blume dev
    ```

4. **本番向けにビルドする**

    静的 HTML が `dist/` に出力され、それを対象としたローカル検索インデックスが構築されます。

    ```bash
    blume build
    ```

:::tip
Blume はあらゆるパッケージマネージャーで動作し、Astro や Tailwind を自分でセットアップする必要は一切ありません。
:::

## 最初のページを書く

すべてのページは、少しのフロントマターを添えた Markdown または MDX です。`title` と `description` は自動的にページの見出しとイントロとして表示されます。次の内容を `docs/index.mdx` に貼り付けてみましょう。

```mdx docs/index.mdx lineNumbers
---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::
```

保存すれば、開発サーバーが即座にリロードします。ナビゲーション、検索、ページメタデータは、ファイルを追加するたびにそれらから推論されます。書き続けるだけで、サイトがついてきます。

## 次のステップ

**[設定](/docs/configuration)**

タイトル、テーマ、検索、デプロイを調整します。

**[コンポーネント](/docs/content/components)**

組み込みのコンポーネントライブラリを見てみましょう。

**[AI](/docs/configuration/ai)**

`llms.txt` と Ask AI アシスタントを提供します。

**[デプロイ](/docs/deployment)**

任意の静的ホスティングで公開しましょう。

---

# CLI
Source: https://useblume.dev/ja/docs/reference/cli

```bash
blume <command> [options]
```

## コマンド

| コマンド | 説明 |
| --- | --- |
| `blume init [dir]` | プロジェクトをスキャフォールドします（デフォルトは対話形式）。 |
| `blume dev` | ホットリロード付きの開発サーバーを起動します。 |
| `blume build` | 静的（またはサーバー）サイトをビルドします。 |
| `blume preview` | 直近のビルドをプレビューします。 |
| `blume add <item>` | レジストリからソースコンポーネントをインストールします。 |
| `blume sync` | リモートコンテンツソースを再取得して再生成します。 |
| `blume eject` | ランタイムを独立した Astro アプリへ昇格させます。 |
| `blume check` | `astro check` でサイトを型チェックします。 |
| `blume doctor` | 設定とコンテンツの問題を診断します。 |
| `blume validate` | コンテンツ全体のリンクを検証します。 |
| `blume audit` | ビルド済みサイトの SEO と健全性の問題を監査します。 |
| `blume eval` | ドキュメントをテストします。エージェントがドキュメントのみを使って質問に回答します。 |
| `blume translate` | ローカルのエージェント CLI を使って、設定済みのロケールにドキュメントを翻訳します。 |
| `blume version [id]` | 現在のドキュメントを[アーカイブ版](/docs/content/versioning)として固定します（id を省略すると、設定済みのバージョンを一覧表示します）。 |

## よく使うフラグ

- `blume init` — ターミナルでは、いくつかの質問（プロジェクトの作成先、サイト名、テンプレート、コンテンツソース）に沿って進みます。以下の各フラグは、対応する質問にあらかじめ回答します。
- `blume init --yes` — プロンプトをスキップし、デフォルト設定でスキャフォールドします（CI 環境や stdin がターミナルでない場合の挙動でもあります）。
- `blume init --content-dir <dir>` — コンテンツフォルダーを指定します（デフォルトは `docs`）。
- `blume init --template docs|api|sdk|changelog` — スターターからスキャフォールドします（プレーンなドキュメントのシードではなく、API リファレンス、SDK、changelog）。
- `blume init --package-manager npm|pnpm|yarn|bun` — 出力される次のステップの案内をパッケージマネージャーに合わせます。
- `blume init --eject` — スキャフォールド後、独立した Astro プロジェクトへ eject します（依存関係がまだインストールされていない場合は、`blume eject` の手順を案内する動作にフォールバックします）。
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — `blume.config.ts` を編集せずに別のコンテンツフォルダーをスキャンします。
- `blume dev --debug` — トラブルシューティング用に Astro/Vite の詳細ログを出力します。
- `blume dev --preview` / `blume build --preview` — 下書きと未公開の CMS コンテンツを含めます。
- `blume build --no-strict` — 診断エラーがあってもビルドします。デフォルトでは `blume build` はエラー診断があると失敗します（終了コード 1）。フロントマターの検証に失敗したページは出力から除外されるためです。`--no-strict` を付けるとビルドは成功し、欠落しているページ数を報告します。`blume dev --strict` は、開発時にも同じ fail-fast の挙動を有効にします。
- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — `blume.config.ts` のデプロイ出力、アダプター、ベースパスを上書きします。
- `blume build --analyze` — ビルド後にクライアント JavaScript のバンドルサイズを（大きい順に）出力します。
- `blume build --budget-js <kb> --budget-css <kb>` — クライアントの JavaScript/CSS の合計が予算を超えた場合にビルドを失敗させ、パフォーマンス目標を CI のゲートに変えます。
- `blume build --isolated` — `.blume/` ではなく使い捨ての `.blume-verify/` ランタイム（および独自の `dist/`）にビルドするため、実行中の `blume dev` サーバーと実際の `dist/` はそのまま保たれます。[開発サーバー実行中の検証](#verifying-while-the-dev-server-runs)を参照してください。
- `blume preview --host --port <n>` — プレビューサーバーをバインドします。
- `blume sync --force` — キャッシュされたスナップショットを先に破棄して、リモートソースを再取得します。
- `blume add <item> --force` — 既に存在するファイルを上書きします。
- `blume check --preview` — チェック時に下書きと未公開の CMS コンテンツを含めます。
- `blume check --strict` — 型エラーに加えてコンテンツ診断でも失敗させます。
- `blume check --isolated` — 使い捨ての `.blume-verify/` ランタイムで型チェックを行うため、実行中の `blume dev` サーバーはそのまま保たれます。[開発サーバー実行中の検証](#verifying-while-the-dev-server-runs)を参照してください。
- `blume eject --yes` — 確認プロンプトをスキップします。
- `blume validate --external` — 外部リンクもネットワーク経由でチェックします。
- `blume validate --strict` — 警告でも非ゼロで終了します。
- `blume validate --json` / `blume doctor --json` — CI やエディター連携向けに、診断結果を JSON として標準出力に出力します（`code`、`severity`、`file`、`line`/`column`、`docsUrl` を含む）。
- `blume audit --fail-on error|warning|info` — CI のゲート。デフォルトは `error` です。`--strict` は `--fail-on warning` のエイリアスです。
- `blume audit --url <origin>` — 実際のデプロイに対して、ステータスコード、レスポンスヘッダー、リダイレクトチェーンも調べます。
- `blume audit --external` — 外部リンクをネットワーク経由で調べます。
- `blume audit --only <check|category>` / `--skip <check|category>` — 対応を進める間、レポートを絞り込みます（カンマ区切り）。
- `blume audit --list-checks` — 監査が報告できるすべてのチェックを出力します。
- `blume audit --verbose` — 影響を受けるすべてのページを、どのリンク先が壊れているかなど各所見の詳細とともに一覧表示します。
- `blume audit --json` — レポートを JSON として標準出力に出力します。
- `blume audit --claude` / `--codex` — 所見を Claude Code または Codex に渡して対話的に修正します。
- `blume eval` — `evals.yaml` の質問を、あなたのドキュメントのみを読むエージェントに通して実行します。[Evals](/docs/reference/eval) を参照してください。
- `blume eval init` — エージェントにドキュメントから `evals.yaml` のたたき台を作成させます。
- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — 各フラグについては [Evals](/docs/reference/eval) を参照してください。
- `blume translate --claude` / `--codex` — 未翻訳・内容が古いページを、設定済みのロケールに翻訳します。[Translate](/docs/reference/translate) を参照してください。
- `blume translate --check` — エージェントを実行せずに、翻訳のずれを報告して非ゼロで終了します（CI のゲート）。
- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — 各フラグについては [Translate](/docs/reference/translate) を参照してください。

## 開発サーバー実行中の検証

`blume dev` は生成された `.blume/` ランタイムをルートとするライブの Astro サーバーを提供し、変更のたびにそれを再生成します。`blume build` と `blume check` は*同じ* `.blume/` を再生成するため、開発サーバーの実行中にどちらかを実行するとランタイムが壊れてしまいます。そのため、どちらもエラーで拒否し、非ゼロで終了します:

```
A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

`--isolated` フラグはその回避手段です。生成されるランタイム全体（`build` の場合はその出力 `dist/` も）を隣接する `.blume-verify/` ディレクトリへ移すため、検証は開発サーバー — あるいは実際の `dist/` — が依存するものに一切書き込みません:

```bash
# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist
```

`check --isolated` は素早い方法です（Astro の型とテンプレートの診断のみで、`dist/` は生成しません）。`build --isolated` はより重く、実行時のレンダリングエラーも検出します。分離ビルドはデプロイ後の処理（検索インデックス、ホスティングプロバイダーとの同期、`llms.txt`、サイトマップ/robots、リダイレクト）をスキップします。検証で必要なのは、サイトがコンパイルされてレンダリングされることの確認だけであり、公開することではないためです。`--analyze` と `--budget-js`/`--budget-css` のゲートは引き続き実行され、分離された出力に対して計測されます。Blume は `.blume-verify/` を自動的に `.gitignore` に追加します。

これは、開発サーバーを開いたままにしつつコーディングエージェントに変更を検証させたい場合に特に便利です。フラグなしの `blume build`/`blume check` を分離実行させたい場合 — 例えばエージェントのシェル内で — は、使用するランタイムディレクトリを `BLUME_RUNTIME_DIR` に設定します:

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## 型チェック

`blume check` はプロジェクトに対して [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) を実行します。`.blume` ランタイムを再生成し、Astro のコンテンツ型を同期したうえで、TypeScript のエラーを報告します — `blume.config.ts`、カスタムの `.astro` ページ、そしてそれらがインポートするコンポーネントについて。エラーがある場合は非ゼロで終了するため、CI の `typecheck` ステップとして機能します:

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

作成したページが `blume/*` のインポートや `blume:data` のような仮想モジュールを解決できるよう、Astro の設定を継承する `tsconfig.json` をプロジェクトルートに追加してください:

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}
```

プロジェクトに `tsconfig.json` がない場合、チェックされるのは生成されたランタイムのみです。

## リンクの検証

`blume validate` は、コンテンツ内で見つかったすべてのリンクをチェックします:

- **内部ページリンク**（`/guides/intro`、`./sibling`）は実在するページに解決される必要があります。壊れているものはエラーとして報告されます。
- **アンカーリンク**（`#section`、`/guides/intro#setup`）はリンク先ページのアンカー — 見出しの id（自動生成、または[固定されたもの](/docs/content/syntax#custom-anchors)）か、生の HTML 要素の `id` 属性 — と一致する必要があり、一致しないものは警告として報告されます。コードブロック、インラインコード、HTML コメント、`<Prompt>` ブロック内の id は対象外です。

- **アセットリンク**は、そのファイルが存在する場所に対してチェックされます。絶対パス（`/logo.png`）は `public/` ディレクトリに対して、相対パスの画像埋め込み（`![](./diagram.png)`）はそのページ自身のフォルダーに対してチェックされます。相対パスへの通常のリンクは、引き続きサイトのルートとして解決されます。画像パイプラインを通るのは画像埋め込みのみです。
- **外部リンク**は `--external` を指定した場合のみチェックされます（ネットワークが必要なためデフォルトは無効）。切れたリンク（404/410/到達不能）はエラー、レート制限や一時的なレスポンス（403/429/5xx/タイムアウト）は警告です。

## ビルド済みサイトの監査

`blume validate` は*コンテンツ*を読み取り、`blume audit` は*ビルド済みサイト*を読み取ります。ビルド後の `dist/` 内の HTML をクロールし、SEO とサイトの健全性に関する問題 — タイトル、メタディスクリプション、canonical、Open Graph と X カード、見出し、hreflang、画像、サイトマップ、`robots.txt`、構造化データ — を報告します。

Blume がサイトをビルドしているため、各所見はクローラーが見る URL だけでなく、ソースファイル**とそれを修正するフロントマターの行**を示します:

```
⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.
```

ビルド後に実行します:

```bash
blume build
blume audit
```

所見はページごとではなくチェックごとにまとめられるため、レポートは ToDo リストのように読めます。影響を受ける各ページを詳細とともに展開するには `--verbose` を、1 カテゴリーずつ対応するには `--only`/`--skip` を使ってください。`blume audit --list-checks` は全カタログを出力します。

### CI を失敗させる

終了コードが契約です。デフォルトでは `blume audit` はエラーでのみ失敗します — ビルドされなかったページへのリンク、リダイレクトループ、無効なサイトマップなど、明確に壊れているものです。参考情報としての所見（説明が短い、タイトルの重複）は警告であり、ビルドを失敗させません:

```bash
blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings
```

### 実際のデプロイをチェックする

実サーバーでしか分からないこともあります。`dist/` に存在するページが、誤ったリライトの背後で実際には 404 になっていないか、レスポンスが圧縮されているか、そして HTML は問題なく見えるページを `X-Robots-Tag` ヘッダーが密かにインデックスから外していないか。これらのチェックを追加するには、監査をデプロイ先に向けます:

```bash
blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links
```

外部リンクは一律に失敗扱いにするのではなく、段階的に評価されます。404 は修正できる壊れたリンクですが、403 や 5xx は通常レート制限か相手側の障害であり、警告として報告されます。

### エージェントで所見を修正する

[Claude Code](https://claude.com/claude-code) や [Codex](https://developers.openai.com/codex/cli) を使っている場合、監査は所見をそのままエージェントに渡せます:

```bash
blume audit --claude   # or --codex
```

これは完全な JSON レポート — ターミナルに表示される 3 ページ分のプレビューではなく、影響を受けるすべてのページ — をファイルに書き出し、所見を順に処理させるプロンプトとともにエージェントを対話的に起動します。各所見が示すソースファイルを編集し、提案された修正を適用し、その後レポートがクリーンになるまで `blume build` と `blume audit` を再実行する、という流れです。このセッションは意図的に対話的です。編集内容はエージェント自身の権限フローを通じて確認でき、またエージェントにはコンテンツを削除して所見を修正することは決してしないよう指示されています。

`--only` と `--skip` はレポートを絞り込むのと同じように引き渡しの内容も絞り込むため、1 カテゴリーずつ送ることができます。

### チェックする内容としない内容

チェックの対象は、汎用の SEO クローラーよりも意図的に狭くしています。そうしたクローラーが報告する内容の多くは Blume のサイトでは起こり得ず — `rel=nofollow` は決して出力されず、Vite のコンテンツハッシュ付きバンドルが欠落したりリダイレクトしたりすることもありません — それらを常にゼロとして報告しても、レポートを無視する習慣がつくだけだからです。

はっきり述べておくべき制限が 2 つあります:

- **構造化データ**は整形式であるか（有効な JSON、`@context` の存在、すべてのノードに `@type` があるか）が検証されます。Blume は schema.org の語彙全体や Google のリッチリザルトのルールに対する検証は行いません。
- **Core Web Vitals** はチェックされません。これらには実際のブラウザが必要であり、実質何も計測しないフラグは、それが無いことよりも悪いためです。そのため `blume audit` は、オフラインで*見える*範囲のレイアウトシフトの原因（`width`/`height` のない画像、サイズの大きすぎるアセット）を報告し、残りは今のところ対象外としています。

監査が実行しなかった項目は、黙って合格扱いにするのではなく、スキップとして報告されます:

```
⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)
```

---

# 評価（Evals）
Source: https://useblume.dev/ja/docs/reference/eval

`blume audit` は、クローラーがドキュメントを見つけられるかどうかを教えてくれます。`blume eval` は、実際にドキュメントを _使える_ かどうかを教えてくれます。AI エージェントが初めて訪れた人と同じようにドキュメントを読み、そこから実際のユーザーの質問に答えようとします。ドキュメントに答えが書かれていない場合、実行は失敗し、答えを書くべきページを指摘します。

```bash
blume eval
```

```
blume eval  3 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: the adapter is auto-detected
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
```

## 仕組み

各質問は 2 つのエージェントセッションを通して実行され、すでにインストール済みのエージェント CLI を使用します。デフォルトでは [Claude Code](https://claude.com/claude-code)、`--agent codex` を指定すれば [Codex](https://developers.openai.com/codex/cli) です。Blume は API キーを保持せず、モデルを自ら呼び出すこともありません。

1. **リーダー（reader）** は、_あなたのドキュメントだけ_ を使って質問に答えます。ファイル、シェル、ウェブの各ツールを無効化した空のディレクトリで実行され、ドキュメントを配信するプライベートな [MCP サーバー](/docs/configuration/ai) に接続します。これは、実際のエージェントが公開済みサイトに対して使うのと同じ `search_docs`/`get_page` ツールです。リポジトリを読むことはできないため、初めて訪れたユーザーとまったく同じようにドキュメントを体験します。つまり、書かれていないものは存在しません。
2. **ジャッジ（judge）** は、あなたが列挙した事実に照らして回答を採点します。ツールは一切使いません。言い換えは合格。事実の欠落や矛盾は不合格で、「ドキュメントには書かれていません」も同様に不合格です。

MCP スナップショットはコンテンツソースから直接構築されるため、事前に `blume build` を実行する必要はなく、どこにもデプロイやアップロードは行われません。

ドキュメントが裏付けられない回答は、たまたまエージェントの事前知識が正しかったとしても不合格になります。それこそが狙いです。実際に届けられる唯一の情報源は、あなたのドキュメントだからです。

## 評価を書く

質問はプロジェクトルートの `evals.yaml` に置きます。既存のドキュメントからエージェントに雛形ファイルを作成させるには次のようにします。

```bash
blume eval init
```

あるいは手書きでも構いません。

```yaml
questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - the output directory is dist
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - pagefind is the default
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped
```

- `expected` には、正しい回答が実質的に述べていなければならない事実を列挙します。ジャッジは言い換えを受け入れ、矛盾を却下します。
- `routes` は、その質問に答えるべきページを指定します。失敗した場合、レポート内でそのページのソースファイルに紐づけられます。どのページにも一致しなくなったヒントは、黙って破棄されるのではなく警告されます。
- `severity: warning` は、CI を失敗させることなく質問をレポートに残します。`skip: true` は質問を完全に除外します。

ユーザーが実際に尋ねる質問を書きましょう。サポートスレッド、GitHub の issue、オンボーディング通話から出てきたものです。最良の評価とは、ドキュメントが掲げる約束（「設定不要のデプロイ」など）を、その約束を壊す PR が出たときに壊れる質問としてエンコードしたものです。

## CI を失敗させる

終了コードが契約です。失敗した質問が 1 つでもあれば、終了コードは 0 以外になります。積み上がった課題を消化している途中であれば、`--threshold` でゲートを合格割合まで緩められます。

```bash
blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout
```

JSON レポートは、`blume validate --json` や `blume audit --json` と同じ `diagnostics` + `summary` の形式を持ち、質問ごとの結果（回答、スコア、欠落した事実、コスト）が併記されます。

各質問はモデルセッション 2 回分にあたるため、評価の実行には実際の費用と時間がかかります。質問ごとの支出は実行中に表示されます。適切な CI 構成では、すべてのプッシュではなくドキュメント変更時に `blume eval` を実行します。

## 検出結果を修正する

各失敗には、欠落している事実と、それを述べるべきページが示されます。レポート全体をエージェントに渡すには次のようにします。

```bash
blume eval --fix
```

これは完全な JSON レポートをファイルに書き出し、失敗した質問を 1 つずつ処理するプロンプトとともにエージェントを対話的に起動します。指定されたページを読み、そのページの語り口で欠落している事実を追加し、すべて合格するまで `blume eval` を再実行する、という流れです。このセッションは意図的に対話的であり、エージェント自身の権限フローを通じて編集内容をレビューできます。また、エージェントには、合格させるために質問を削除したり expected の事実を弱めたりしないよう指示されています。

## フラグ

- `--agent claude|codex` — リーダーとジャッジを実行するエージェント CLI。デフォルトは `claude`。
- `--file <path>` — 評価ファイル。デフォルトは `evals.yaml`。
- `--threshold <0..1>` — 終了コードが 0 以外になる前に必要な最低合格割合。デフォルトは `1`。
- `--timeout <seconds>` — 質問ごとのリーダーの制限時間。デフォルトは `180`。
- `--json` — レポートを JSON として stdout に出力します。
- `--fix` — 実行が失敗した後、レポートをエージェントに渡してドキュメントを対話的に修正させます。
- `--verbose` — 各失敗の下にリーダーの完全な回答を含めます。

---

# フロントマター
Source: https://useblume.dev/ja/docs/reference/frontmatter

各ページでは以下のフロントマターを使用できます。すべてのフィールドは任意です。

| Prop | Type | Default | Description |
| - | - | - | - |
| `title?` | `string` | - | ページのタイトル。 |
| `description?` | `string` | - | ページの概要。 |
| `type?` | `string` | `doc` | コンテンツの種類。blog / changelog はフィードを生成します。 |
| `date?` | `string` | - | blog / changelog フィード用の公開日（ISO 形式または YAML の日付）。 |
| `authors?` | `string \| string[] \| object[]` | - | blog / changelog コンテンツの投稿者。名前、または name と任意の avatar / url、その他の追加フィールドを持つオブジェクトを指定します。値はそのまま保持されます。 |
| `slug?` | `string` | - | 生成されるスラッグを上書きします。 |
| `draft?` | `boolean` | `false` | 本番ビルドから除外します。 |
| `lastModified?` | `string` | - | ページの「最終更新日」を固定します（ISO 形式または YAML の日付）。git から取得した日付を上書きします。 |

## サイドバー

```yaml lineNumbers
sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page
```

`display` はそのページが属するフォルダーグループの表示モードを設定し（[グループ単位の上書き](/docs/content/navigation#per-group-overrides)）、生成されるサイドバーにおけるフォルダーの `index` ページでのみ意味を持ちます。それ以外の場所（index 以外のページ、コンテンツルート自身の `index` ページ、明示的な `navigation.sidebar` 配下のページ）では設定対象となるグループが存在しないため、Blume は `BLUME_SIDEBAR_DISPLAY_IGNORED` の警告を出します。

## SEO

```yaml lineNumbers
seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
```

## 検索

```yaml lineNumbers
search:
  exclude: false
  tags: [api]
```

## 変更履歴

変更履歴のエントリー（`type: changelog`）では、フィードや表示のメタデータをより充実させるために、任意の `changelog` オブジェクトを指定できます。

```yaml lineNumbers
type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features
```

`date` はここに書いてもトップレベルに書いても構いません。どちらも[変更履歴の RSS フィード](/docs/content#feeds)に反映されます。生成されるタイムラインページとフィードについては、[変更履歴](/docs/advanced/changelog)を参照してください。

## カスタムキー

このリファレンスに記載されていないキーはビルドを失敗させるため、タイプミスを早期に検出できます。独自のメタデータを扱うプロジェクトでは、`blume.config.ts` の [`frontmatter.extend`](/docs/configuration#frontmatter) で追加のキーを許可できます。各キーはプロジェクト側が用意したスキーマで検証されます。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

```yaml page.mdx
---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---
```

スキーマは [Standard Schema](https://standardschema.dev) インターフェース経由で受け付けられるため、Zod（プロジェクトがインストールしているバージョンを問わず）、Valibot、ArkType のいずれも利用できます。宣言されたキーはすべてのページで検証されます。存在しない場合も含めて検証されるため、必須スキーマにするとサイト全体でそのキーが強制されます。存在するページでのみ検証したい場合は `.optional()` を付けてください。それ以外のキーは引き続き厳密に検証され、組み込みフィールドを再宣言することはできません。

### タイプ別のキー

RFC の `status` やインシデントレポートの `severity` のように、特定のコンテンツタイプでのみキーを必須にしたい場合は、代わりに [`content.types`](/docs/configuration#content) の下で、適用対象となるフロントマターの `type` をキーとして宣言します。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

```yaml rfcs/openapi-request-schemas.mdx
---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---
```

タイプ別のキーは `extend` と同じ検証ルールに従い、解決された `type` が一致するページに限定して適用されます。宣言が [`content.defaultType`](/docs/configuration#content) に対するものであれば、`type` を指定していないページも対象に含まれます。1 つのキーはサイト全体の宣言かタイプ別の宣言のどちらか一方にのみ属し、両方に属することはできません。また、別のタイプでのみ宣言されたキーはそれ以外の場所では未知のキーのままなので、通常のドキュメントページに紛れ込んだ `status` は依然としてビルドを失敗させます。

検証に失敗したページがあると `blume build` は失敗し、該当するファイルとキーを示す診断メッセージが表示されます。[`--no-strict`](/docs/reference/cli#common-flags) を指定した場合はビルドが成功し、失敗したページは出力から除外されます。除外された件数はビルドのサマリーに報告されます。

スキーマはエディターや移行ツール向けに `blume/schema` からエクスポートされています。

---

# 翻訳
Source: https://useblume.dev/ja/docs/reference/translate

[i18n](/docs/content/i18n) を有効にすると、ソースページを編集するたびにその翻訳が静かに古くなっていきます。`blume translate` はそのループを閉じます。各ロケールでどのページが不足または古くなっているかを正確に計算し、ローカルのエージェント CLI でヘッドレスに翻訳し、実施内容をコミット対象の台帳に記録するため、次回の実行 — そして CI — が最新状態を把握できます。

```bash
blume translate --claude
```

```
blume translate  3 item(s) · 2 locale(s) · Claude Code

  ✔ docs/guides/install.mdx → fr 24.2s $0.11
  ✔ docs/guides/install.mdx → de 22.8s $0.10
  ✔ meta titles (2) → de 4.1s $0.01

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
```

## 仕組み

パイプラインは Blume が管理し、エージェントはテキストを翻訳するだけです。作業が必要なファイルごとに、Blume は翻訳プロンプトを組み立て、ファイル・シェル・ウェブの各ツールを無効化した状態でエージェント CLI をヘッドレスに実行し、応答の構造を検証したうえで、ターゲットファイルを自ら書き込みます。`--claude` では [Claude Code](https://claude.com/claude-code)、`--codex` では [Codex](https://developers.openai.com/codex/cli) を使います。Blume は API キーを一切保持せず、自身でモデルを呼び出すこともありません。

検証に通った書き込みはすべて、プロジェクトルートの `blume.translations.json` に記録されます。ソースファイルとロケールの組ごとに、翻訳した時点でのソースのハッシュが保存されます。**このファイルはコミットしてください。** 再実行時に「すでに翻訳済み」と「翻訳済みだが、その後ソースが変更された」を区別できるのはこのファイルのおかげであり、CI ゲートを成立させているのもこれです。

台帳はファイルが 1 つ終わるたびにフラッシュされるため、長時間の実行を中断（Ctrl+C）しても、失われるのは実行中だった翻訳だけです。次回の実行は中断したところから再開されます。ファイルはデフォルトで 4 件ずつ並列に処理されます。マシンの性能とエージェントのレート制限が許すなら `--concurrency` で増やしてください。

再実行はインクリメンタルです。前回の翻訳以降に変更されていないソースはスキップされるため、1 ページを編集したあとに `blume translate` を実行すると、ロケールごとに 1 ページだけが翻訳されます。古くなったページを再翻訳する際は、エージェントに既存の翻訳が提示され、その語調・方言・用語に合わせるよう指示されます。ソースの 1 段落の編集が生むのは 1 段落分の翻訳差分であり、ゼロからの書き直しではありません。

初回の翻訳には合わせるべき前例がないため、[ロケールの `style`](/docs/content/i18n) で方針を最初に固定してください（`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`）。この指示はすべての翻訳プロンプトに同梱され、既存の翻訳と食い違う場合は `style` が優先されます。そのため、再翻訳は古いページも設定済みのスタイルへと近づけていきます。

## 翻訳される対象

- **ページ** — デフォルトロケールの `.md`/`.mdx` ファイル。エージェントは本文と、人間が目にするフロントマターの値（`title`、`description`、`sidebar.label`、`sidebar.badge`、`seo.title`、`seo.description`）のみを翻訳します。出力先はパーサーに従います。`dir` では `fr/guides/install.mdx`、`dot` では `guides/install.fr.mdx` です。
- **フォルダーのナビゲーションタイトル** — `dir` パーサーでは、各ロケールで必要な [`meta.ts`](/docs/content/meta) のタイトルが 1 回のバッチ呼び出しで翻訳され、生成されるロケールごとの `meta.ts` はその他のキー（`order`、`pages`、`icon`、`collapsed`）をそのままコピーするため、そのロケールのサイドバーは並び順を保ちます。

手作業で書いた翻訳は**採用され、上書きされることはありません**。翻訳が存在するのに台帳エントリがない場合は、最新としてスタンプされ、そのまま残されます。再翻訳するのは `--force` のときだけです。

## 検証

構造の面でエージェントが信頼されることはありません。書き込む前に、Blume は各応答をチェックし、ソースからファイルを再構築します。

- フロントマターはソースファイルのデータから再構築され、翻訳可能な 6 つの値だけが上書きされます。エージェントが勝手に作ったキーは破棄され、削除されたキーは復元され、`slug`、`icon`、`order`、および日付は構造上ソースそのままになります。
- コードフェンスの数がソースと一致していること、本文が空でないこと、フロントマターがパースできることが必要です。

検証に失敗した応答は何も書き込みません。その項目は失敗として報告され、実行は次へ進みます。成功したものはすべて台帳にスタンプされたまま残るため、再実行では失敗分だけが再試行されます。

## CI を失敗させる

`blume translate --check` は読み取り専用のゲートです。不足・古くなったペアをすべて報告し、ずれがあれば非ゼロで終了します。エージェントの実行も書き込みも行いません。

```bash
blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

JSON レポートは `blume validate --json`、`blume audit --json`、`blume eval --json` と同じ `diagnostics` + `summary` の形式で、ずれはロケールごとにグループ化されます。手作業で書かれた（追跡対象外の）翻訳がゲートを失敗させることはありません。

## 制限事項

- メタタイトルの翻訳は `dir` パーサー専用です。`dot` パーサーにはロケールごとの `meta.ts` の仕組みがありません。関数をデフォルトエクスポートしている `meta.ts` は警告付きでスキップされるため、そのロケール用のファイルは手作業で書いてください。
- リモートおよび CMS 由来のソースはスキップされます。翻訳を書き込むローカルファイルが存在しないためです。
- ヘッダーのタブラベルはコンテンツではなく `blume.config.ts` にあります。[ロケールごとのラベルマップ](/docs/content/navigation#tabs)でそちらをローカライズしてください。
- 翻訳の品質はエージェント次第です。他のコントリビューションと同じように出力をレビューしてください。台帳が保証するのは鮮度だけであり、流暢さではありません。

## フラグ

- `--claude` / `--codex` — どのエージェント CLI で翻訳するか。ちょうど 1 つの指定が必須です（`--check` の場合を除く）。
- `--check` — ずれを報告して非ゼロで終了します。何も書き込みません。
- `--concurrency <n>` — 並列に実行するエージェントセッション数。デフォルトは `4`、最大は `16` です。
- `--locale <codes>` — カンマ区切りのターゲットロケール（デフォルトはデフォルト以外のすべてのロケール）。
- `--force` — 最新のファイルや手作業で書かれたファイルも含め、すべてを再翻訳します。
- `--timeout <seconds>` — ファイルごとのエージェントの時間制限。デフォルトは `600` です。この上限はハングしたエージェントを検出するためのもので、大きなページでも完了する余裕があります。
- `--json` — どちらのモードでも、レポートを JSON として標準出力に出力します。

---

# Introdução
Source: https://useblume.dev/pt/docs

Coloque Markdown ou MDX em uma pasta, execute `blume dev` e obtenha um site de documentação de nível de produção — navegação, busca, temas, imagens Open Graph e uma rica biblioteca de componentes — sem nenhum boilerplate de aplicação para escrever ou manter.

**[Início rápido](/docs/quickstart)**

Instale o Blume e publique sua primeira página em minutos.

**[Configuração](/docs/configuration)**

Ajuste o título, o tema, a busca e a implantação.

## Por que o Blume existe

A documentação deve ser rápida, pronta para IA e zero-config — a ponto de não precisar de um template inicial. Algumas ferramentas de documentação entregam a você uma base de código inteira para manter antes mesmo de você escrever uma palavra. Outras constroem o template em torno do seu conteúdo, mas prendem você ao serviço gerenciado delas.

O Blume reúne o melhor dos dois mundos. O framework é o template, então a única coisa em que você mexe é o seu conteúdo. Quando quiser personalizar, você pode começar substituindo os componentes integrados, modificando o único arquivo de configuração ou até fazendo eject se quiser o site Astro diretamente. O [FAQ](/docs/faq) explica como isso se compara ao Mintlify, Fumadocs e aos demais.

## O que torna o Blume diferente

### Rápido por padrão

O Blume é construído sobre Astro e Vite e renderiza HTML estático por padrão — rápido, cacheável e barato de hospedar. O tema principal não envia nenhum JS de framework para o cliente, então as páginas pontuam bem nos Core Web Vitals imediatamente. A inicialização em dev e o hot reload têm a sensação nativa do Vite, e você adota recursos de servidor apenas quando precisa.

### Pronto para IA desde o início

Todo site Blume fala a língua das máquinas com fluência. Ele gera [`llms.txt` e `llms-full.txt`](/docs/configuration/ai), serve o Markdown bruto de qualquer página adicionando `.md` à sua URL, expõe uma [API JSON descrita por OpenAPI](/docs/configuration/ai#json-api) e oferece aos leitores as ações **Copiar como Markdown** e **Abrir no chat** em todas as páginas. Adicione um assistente **Ask AI** opcional na página, ou hospede um [**servidor MCP**](/docs/configuration/ai#mcp-server) para que agentes de programação como Claude Code e Cursor possam pesquisar e ler sua documentação diretamente — sem scraping, sem serviço hospedado. Seu Markdown é a fonte da verdade tanto para humanos quanto para modelos.

### Configuração zero — até o template

Uma pasta de documentos é um projeto completo. Não há starter para clonar, nem Astro ou Tailwind para configurar, nem template para manter. A navegação é inferida a partir dos seus arquivos, a [busca](/docs/configuration/search) funciona em dev e em produção sem um serviço hospedado, e o tema é um punhado de tokens. Tudo tem um padrão sensato; a configuração é algo a que você recorre, não algo por onde você começa.

### Type-safe até o núcleo

Seu [`blume.config.ts`](/docs/configuration) e cada [`meta.ts`](/docs/content/meta) são TypeScript de verdade — validados por um schema e escritos com `defineConfig` e `defineMeta`. Seu editor autocompleta todas as opções e detecta erros de digitação, valores inválidos e campos ausentes enquanto você digita, muito antes de um build. A configuração é código que você pode refatorar, computar e no qual pode confiar — não YAML com tipagem frouxa.

## Tudo incluído

- **Componentes** — callouts, cards, steps, tabs, accordions, badges, árvores de arquivos e tabelas de parâmetros, utilizáveis em MDX [sem imports](/docs/content/components).
- **Busca local** — o Orama funciona em dev e em produção; o Pagefind está a uma flag de distância para sites grandes. Sem índice hospedado.
- **IA** — [`llms.txt`, URLs de Markdown bruto, uma API JSON com descrição OpenAPI, Copiar como Markdown, Abrir no chat, um assistente Ask AI e um servidor MCP hospedado](/docs/configuration/ai).
- **Navegação** — inferida a partir dos arquivos, refinada com `meta.ts` ou configuração.
- **SEO** — metadados, imagens Open Graph, feeds RSS e JSON-LD, [já integrados](/docs/configuration/seo).
- **Personalização** — substituições de componentes, ilhas React, páginas personalizadas, tokens de tema e um registro de componentes-fonte via `blume add`.
- **Eject** — `blume eject` produz um projeto Astro independente que ainda usa o pacote `blume`.

## Como funciona

A CLI do Blume descobre seu conteúdo, constrói um grafo de conteúdo e gera um projeto Astro oculto em `.blume/` que ela conduz para dev e build. O runtime gerado é um detalhe de implementação — você escreve Markdown, o Blume cuida do resto — até você optar por fazer eject e assumi-lo.

## Próximos passos

**[Configuração](/docs/configuration)**

Ajuste o título, o tema, a busca e a implantação.

**[Componentes](/docs/content/components)**

Explore a biblioteca de componentes integrada.

**[IA](/docs/configuration/ai)**

Publique `llms.txt` e um assistente Ask AI.

**[CLI](/docs/reference/cli)**

Todos os comandos e flags do `blume`.

---

# OpenAPI / AsyncAPI
Source: https://useblume.dev/pt/docs/advanced/api-reference

Aponte o Blume para uma especificação OpenAPI e ele gera uma referência de API nativa: uma **página real por operação**, agrupada por tag em uma barra lateral delimitada por aba, com tabelas de esquema, exemplos de requisição/resposta, amostras de código geradas e um painel interativo [Try it](#try-it-playground). Como cada operação é uma página Blume genuína, ela ganha sua própria URL, aparece na **busca do site** e no `llms.txt`, e recebe uma imagem Open Graph — igual a qualquer documento escrito à mão. A configuração abaixo aponta o Blume para a especificação pública do Petstore como exemplo.

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}
```

Isso monta a referência em `/reference` (uma página de visão geral) com cada operação em `/reference/<tag>/<operation>`. O `spec` é uma URL `http(s)` ou um caminho para um arquivo local no seu projeto. O Blume o analisa com o [parser OpenAPI do Scalar](https://github.com/scalar/scalar) — especificações Swagger 2.0 e OpenAPI 3.0 são atualizadas para 3.1 automaticamente. Está documentando uma API GraphQL? Veja a [referência GraphQL](/docs/advanced/graphql).

A referência não adiciona uma aba de cabeçalho por conta própria. Para exibi-la, aponte uma [aba de navegação](/docs/content/navigation#tabs) para sua rota — isso também delimita a barra lateral de operações para o renderizador nativo:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
As operações são indexadas para busca pelo seu **resumo e tag**. As tabelas de esquema renderizadas e as amostras de código não são indexadas em texto completo; a busca corresponde ao título e à seção de uma operação e, em seguida, cria um link para sua própria página.
:::

## Uma especificação local

Um caminho relativo é resolvido a partir da raiz do seu projeto e lido em tempo de build. Tanto JSON quanto YAML funcionam:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}
```

## Rota

`route` controla onde a referência é montada — a página de visão geral e o prefixo para cada rota de operação (e a rota para a qual você aponta uma aba de navegação):

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}
```

## Amostras de código e esquemas

`codeSamples` escolhe quais linguagens são renderizadas por operação (nativas: `curl`, `js`, `python`); `expandSchemas` inicia as linhas de esquema aninhadas expandidas em vez de recolhidas:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}
```

## Playground Try it

Páginas de operação renderizadas nativamente vêm com um painel interativo **Try it** por padrão. O Blume gera o formulário a partir da própria operação: um campo por parâmetro de caminho, consulta e cabeçalho, um editor de corpo construído a partir do esquema do corpo da requisição, tudo pré-preenchido a partir dos exemplos da especificação. Um seletor de servidor lista os `servers` da especificação, com um campo de texto livre para qualquer outra URL base, e os campos de autenticação correspondem à [segurança resolvida](#authorization) da operação — token bearer, chave de API e credenciais basic, com OAuth2 como um campo para colar o token (traga um token de acesso; o Blume não executa o fluxo).

O painel e as amostras de código andam em sincronia: valores digitados no formulário atualizam as amostras geradas ao vivo, então um comando curl copiado sempre corresponde exatamente ao que o **Send** faria. E ele fica fora do caminho — o painel é renderizado no servidor já recolhido, e seu JavaScript é carregado apenas quando um leitor o abre pela primeira vez. Leitores que nunca o tocam não baixam nada disso.

`playground: false` é todo o interruptor de desligamento:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}
```

### Credenciais

As credenciais digitadas nos campos de autenticação ficam na memória e desaparecem ao recarregar. Marcar **Remember on this device** as persiste no `localStorage`, delimitado à origem da documentação — elas nunca são enviadas para lugar nenhum além da API que está sendo chamada. As amostras de código continuam exibindo espaços reservados (`YOUR_TOKEN` e companhia) independentemente do que for digitado, a menos que o leitor ative **Include my values in samples**.

### CORS e o proxy

Assim como no [renderizador Scalar](#o-renderizador-scalar), as requisições vão **diretamente do navegador** para a API de destino, então a API precisa permitir requisições de origem cruzada a partir do site de documentação (`Access-Control-Allow-Origin`). Para APIs que não podem, defina `playground.proxy`: uma URL roteia as requisições através de um proxy hospedado por você, e `true` habilita a rota interna `/_api-proxy` — que precisa de um build de servidor, então exige [`deployment.output: "server"`](/docs/deployment#server-rendering):

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}
```

O proxy interno só encaminha requisições para as origens que suas especificações declaram em `servers` — inclusive através de redirecionamentos — então uma implantação pública de documentação não pode ser apontada para outros hosts na sua rede. Uma **Custom base URL** digitada no painel não é um servidor documentado: com o proxy habilitado, requisições para ela são recusadas com um 403.

## Múltiplas especificações

Use `sources` para publicar mais de uma especificação. Cada fonte recebe sua própria rota de visão geral, páginas de operação e aba de cabeçalho. Dê a cada uma um `label` (usado para a aba e para derivar sua rota), ou defina uma `route` explícita:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}
```

`spec` é um atalho para um `sources` de entrada única, então você só recorre a `sources` quando tem mais de uma.

### Indexação por fonte

As páginas geradas participam da busca, do `llms.txt` e da indexação por rastreadores por padrão. Uma especificação secundária ou sobreposta pode optar por sair de qualquer superfície sem ocultar suas páginas ou removê-la da navegação:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}
```

- `includeInSearch: false` mantém a visão geral e as operações da fonte fora da busca do site.
- `includeInLlms: false` as mantém fora de ambos os arquivos `llms.txt`.
- `noindex: true` adiciona metadados noindex para rastreadores e remove as páginas do sitemap.

A meta descrição de cada página de operação é a própria `description` da operação (ou o `summary`), seguida de uma frase gerada que nomeia o endpoint — "Reference for the `GET /pets` endpoint in the Petstore API." — então uma especificação com resumos secos de uma linha ainda entrega uma descrição distinta e do tamanho de um snippet por página. Essa frase está em inglês. Em um site cuja prosa da especificação está escrita em outro idioma, defina `seoDescriptionSuffix: false` na fonte para descartá-la e descrever cada página apenas com a prosa autoral; uma operação sem `description` nem `summary` recorre ao seu título (`GET /pets`), então nenhuma página é entregue com uma descrição vazia:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}
```

Com o [renderizador Scalar](#o-renderizador-scalar), apenas `noindex` se aplica — uma referência renderizada pelo Scalar já fica fora da busca e do `llms.txt` do Blume, então as duas configurações `include*` não têm sobre o que atuar ali.

## Autorização

Operações que declaram [requisitos de segurança](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) renderizam uma seção **Authorization** acima de seus parâmetros, e as amostras de código geradas enviam uma credencial de espaço reservado (`Authorization: Bearer YOUR_TOKEN`, um cabeçalho de chave de API ou uma chave de consulta — o que o esquema exigir). Não há nada para configurar: o Blume lê `security` da especificação, então a referência sempre corresponde ao que a API realmente aplica.

A semântica do OpenAPI é mantida conforme escrita:

- O `security` próprio de uma operação sobrescreve o padrão da raiz do documento; `security: []` a marca como **pública** e não renderiza nenhuma seção de Autorização.
- Múltiplas entradas de requisito são alternativas — renderizadas como grupos "ou"; todos os esquemas dentro de uma entrada são exigidos em conjunto. A primeira alternativa alimenta as amostras de código.
- Uma entrada `{}` vazia significa que a autenticação é **opcional** para aquela operação, e a seção informa isso.
- Os escopos OAuth2 são listados por esquema; as `description`s de esquema de `components.securitySchemes` são renderizadas inline.

## O renderizador Scalar

O renderizador nativo é o padrão — as páginas de operação, a integração com a busca e o [playground Try it](#playground-try-it) acima são todos obra dele. Se você preferir incorporar a interface de referência de API autocontida do [Scalar](https://scalar.com) — com sua própria barra lateral, busca, tema e cliente de requisições em uma única rota — defina `renderer: "scalar"`:

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}
```

Uma referência renderizada pelo Scalar é uma incorporação autocontida em sua própria rota — ela não se integra à barra lateral, à busca ou ao `llms.txt` do Blume, e a configuração [`playground`](#playground-try-it) do Blume não se aplica a ela. O que ela segue é o alternador claro/escuro do Blume: a incorporação é fixada no tema da página quando é montada e muda junto com ele, então o alternador de tema do próprio Scalar fica oculto (defina `scalar.forceDarkModeState` ou `scalar.darkMode` para devolver o controle do modo de cor ao Scalar). O Scalar traz seu próprio cliente de requisições, que chama sua **API de destino diretamente do navegador** (a rota `playground.proxy` não está disponível aqui), então a API precisa permitir requisições de origem cruzada a partir do site de documentação (`Access-Control-Allow-Origin`). `theme` se aplica apenas ao renderizador Scalar.

### Passando opções do Scalar

`theme` é um atalho para a opção que a maioria das pessoas usa, mas o Scalar suporta muitas outras. Um objeto `scalar` encaminha qualquer [configuração do Scalar](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) diretamente para a referência incorporada — o Blume não restringe as chaves, então tudo o que o Scalar aceita passa adiante:

```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",
  },
}
```

O [`i18n`](/docs/content/i18n) do próprio Blume traduz a interface da documentação, mas o Scalar tem um sistema de localização separado — defina `scalar.localization.locale` para traduzir também a referência incorporada. As opções no objeto `scalar` prevalecem sobre a configuração derivada do Blume, então tudo que for definido aqui (incluindo `theme`, `customCss` ou o `content`/`url` da especificação) sobrescreve os padrões do Blume. O mesmo bloco `scalar` funciona na referência `asyncapi`.

## AsyncAPI

APIs orientadas a eventos usam um bloco irmão `asyncapi` com o mesmo formato — e o mesmo renderizador nativo. Cada operação `send`/`receive` se torna uma página real com tabelas de esquema do payload e dos cabeçalhos da mensagem, parâmetros de canal, bindings de protocolo, uma seção de Autorização derivada dos `securitySchemes` da especificação (em nível de servidor e de operação, com alternativas como grupos "ou") e um compositor de mensagens [Try it](#try-it-para-eventos). Apenas a rota padrão difere (`/events`):

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}
```

Especificações AsyncAPI **2.x são normalizadas para 3.x automaticamente** com o conversor oficial do AsyncAPI, então canais `publish`/`subscribe` são mapeados para páginas de operação `send`/`receive` com URLs estáveis — atualizar mais tarde o próprio arquivo de especificação através do conversor não move nada. As operações são agrupadas por tag; operações sem tag são agrupadas sob o endereço do seu canal.

As amostras de código são **sensíveis ao protocolo**, derivadas do binding da operação (ou do protocolo dos seus servidores): `wscat` e um snippet de `WebSocket` do navegador para WebSockets, `kcat` para Kafka, `mosquitto_pub`/`mosquitto_sub` para MQTT. `codeSamples` filtra esse conjunto, da mesma forma que escolhe linguagens no bloco `openapi`; um protocolo sem uma ferramenta suportada renderiza apenas o exemplo de payload da mensagem em vez de um cliente fabricado.

Tudo o que foi documentado acima se mantém, incluindo o [`playground`](#try-it-para-eventos): `route`, `sources` com `label`/`route`, `expandSchemas`, as flags de [indexação por fonte](#indexação-por-fonte) (`seoDescriptionSuffix` também — a frase gerada nomeia o canal e a ação em vez de um endpoint) e a indexação de busca por resumo e tag da operação.

Definir `renderer: "scalar"` volta a optar pelo SPA incorporado do Scalar, onde — como no OpenAPI — apenas `noindex` se aplica. O Scalar não tem um playground AsyncAPI próprio; sua incorporação detecta automaticamente o tipo de documento e renderiza canais, operações, mensagens e uma seção de Modelos, então essa troca abre mão do compositor.

### Try it para eventos

Páginas de operação renderizadas nativamente também vêm com um painel **Try it** aqui, nos mesmos termos do [painel OpenAPI](#playground-try-it): renderizado no servidor já recolhido, com seu JavaScript carregado apenas quando um leitor o abre pela primeira vez.

Seja qual for o protocolo, o painel abre com um editor de payload pré-preenchido a partir dos `examples` da mensagem — ou, quando a mensagem não declara nenhum, a partir de um valor amostrado do esquema do payload — validado contra o esquema de payload da mensagem conforme você digita. Abaixo dele ficam um campo por parâmetro de canal e um seletor de servidor alimentado pelos `servers` do canal, com um campo de texto livre para qualquer outra URL. As amostras de código sensíveis ao protocolo andam em sincronia com o formulário exatamente como curl, js e python fazem em uma operação HTTP: o template de endereço do canal é preenchido com os valores de parâmetro que você digita, então um snippet copiado de `wscat`, `WebSocket`, `kcat` ou `mosquitto_pub` corresponde ao que o formulário diz.

A conexão ao vivo é exclusiva para WebSocket. Em um binding `ws` ou `wss`, o painel se conecta à URL de canal resolvida, mostra o estado da conexão e registra cada frame com um timestamp. O AsyncAPI 3 declara uma ação do ponto de vista da API, e o painel segue isso: uma operação `receive` é uma que a API recebe de você, então ela ganha um botão **Send** que publica o payload composto; uma operação `send` apenas transmite mensagens para você, então ela se conecta e registra. Não há lógica de reconexão — uma vez que um socket fecha, ele permanece fechado até você conectar novamente. Kafka, MQTT, AMQP e todos os outros protocolos recebem o compositor e as amostras de CLI copiáveis, e o painel diz isso na própria página: o Blume não simula conectividade com broker a partir de uma aba do navegador.

`asyncapi.playground` espelha `openapi.playground` — ligado por padrão com o renderizador nativo, e `false` é todo o interruptor de desligamento:

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}
```

:::note
`playground.proxy` não se aplica a operações de evento. Ele encaminha requisições HTTP, e uma conexão WebSocket vai direto do navegador para o servidor nomeado na URL, então não há nada na frente de que um proxy possa ficar.
:::

O compositor de eventos não coleta credenciais de broker. A seção **Authorization** de cada página de operação documenta o que o broker espera, e uma conexão WebSocket carrega apenas o que já está na URL. Nada é persistido para operações de evento.

---

# Blog
Source: https://useblume.dev/pt/docs/advanced/blog

Um blog no Blume é apenas conteúdo com um tipo. Marque uma página com `type: blog` e o Blume lhe dá automaticamente um feed RSS e metadados de artigo mais ricos. Diferentemente do [changelog](/docs/advanced/changelog), não há página de índice gerada — você compõe a página inicial por conta própria, o que mantém o design inteiramente em suas mãos.

## Escreva um post

Um post é uma página `.md` ou `.mdx` comum com `type: blog` em seu frontmatter. Por convenção, os posts ficam em `blog/`, mas o que importa é o tipo — não a pasta:

```mdx blog/introducing-blume.mdx lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
```

Dê a cada post uma `date` para que os itens do feed sejam ordenados do mais recente para o mais antigo e carreguem uma `pubDate`, e uma `description` — ela é usada tanto no resumo do feed quanto no SEO.

## O feed RSS

O Blume cria um feed do blog em **`/blog/rss.xml`**, ordenado do mais recente para o mais antigo por `date`. Feeds precisam de uma URL absoluta do site, então defina [`deployment.site`](/docs/deployment); o Blume então injeta uma tag `<link rel="alternate">` em todas as páginas para que os leitores a descubram automaticamente.

O feed está ativado por padrão. Ajuste-o em [`seo.rss`](/docs/configuration/seo#rss-feeds):

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

Remova `"blog"` de `rss.types` para dispensar o feed.

## Dados estruturados

Quando os [dados estruturados](/docs/configuration/seo#structured-data) estão ativados, cada post é emitido como um **`BlogPosting`** do schema.org com sua descrição e data de publicação — o tipo de artigo mais rico que os mecanismos de busca esperam para conteúdo de blog.

## Criando um índice

O Blume não gera uma página inicial `/blog`, então você a constrói. A opção mais simples é uma página de conteúdo que liga a cada post manualmente:

```mdx blog/index.mdx lineNumbers
---
title: Blog
description: News and writing from the team.
---

<CardGroup cols={2}>
  <Card title="Introducing Blume" href="/blog/introducing-blume">
    Why we built a markdown-first docs framework.
  </Card>
</CardGroup>
```

Para listar os posts automaticamente, adicione uma [página personalizada](/docs/advanced/custom-pages) em `pages/blog/index.astro` que leia da coleção de conteúdo `docs` do Astro e associe cada entrada à sua rota vinda de `blume:data`:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    date: entry.data.date,
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }))
  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

Veja [Páginas Personalizadas](/docs/advanced/custom-pages#using-the-site-layout) para envolver isso no layout completo do site.

**[Páginas Personalizadas](/docs/advanced/custom-pages)**

Monte o índice do blog e leia de blume:data.

**[SEO](/docs/configuration/seo)**

Feeds, imagens Open Graph e dados estruturados.

---

# Changelog
Source: https://useblume.dev/pt/docs/advanced/changelog

O Blume traz um changelog pronto a usar. Escreva cada versão como um ficheiro de conteúdo normal, marque-o com `type: changelog`, e o Blume reúne todas as entradas numa página de cronologia gerada e num feed RSS — sem layout para construir, sem lista para manter. Ou dispense os ficheiros por completo e [alimente o seu changelog a partir do GitHub Releases](#from-github-releases).

## Escrever uma entrada

Uma entrada de changelog é uma página `.md` ou `.mdx` normal com `type: changelog` no seu frontmatter. Por convenção ficam em `changelog/`, mas o que importa é o tipo — não a pasta:

```mdx changelog/v1-2-0.mdx lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks
```

Atribua uma `date` a cada entrada para que a cronologia e o feed ordenem da mais recente para a mais antiga. Uma data YAML sem aspas serve — o Blume normaliza-a.

### O objeto `changelog`

O objeto opcional `changelog` acrescenta metadados mais ricos para a cronologia e o feed:

| Prop | Type | Default | Description |
| - | - | - | - |
| `changelog.version?` | `string` | - | Release version. Falls back to a v-prefixed label when there's no title. |
| `changelog.category?` | `string` | - | Shown as a tag beside the entry, e.g. Release, Features, Fixes. |
| `changelog.date?` | `string` | - | Publish date. May live here or at the top level — both feed the timeline and RSS feed. |

## A página de cronologia

Assim que tiver pelo menos uma entrada `type: changelog`, o Blume gera automaticamente uma página **`/changelog`**. É apresentada como uma cronologia focada e de largura total — sem barra lateral nem índice — com cada entrada da mais recente para a mais antiga, mostrando a sua data, etiqueta e a tag `category` numa coluna à esquerda, ao lado do conteúdo:

- O **título** da entrada torna-se a sua etiqueta — ou `v{version}` quando não há título. Liga à página da própria entrada, pelo que uma versão é ao mesmo tempo uma linha na cronologia e um permalink partilhável.
- A `category` é apresentada como uma tag junto à data.
- Os rascunhos e as entradas com `sidebar.hidden` são ignorados.

A página só aparece quando nada ocupa já a rota `/changelog`. Para a substituir pelo seu próprio design, adicione uma [página personalizada](/docs/advanced/custom-pages) em `pages/changelog.astro` — assume o controlo e o Blume deixa de gerar a cronologia predefinida.

Como esta página é gerada e não escrita, não faz parte da árvore de conteúdos — por isso um [separador](/docs/content/navigation#tabs) do cabeçalho que aponte para `/changelog` resolve antes para a entrada mais recente. Dê um `href` ao separador para chegar ao próprio índice:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

### Agrupado por versão principal

Quando as suas versões seguem o [semver](https://semver.org) e abrangem mais do que uma versão principal, o Blume pagina a cronologia por versão principal. Apenas a linha principal mais recente é apresentada, com um botão **Show N.x releases** no fundo que revela a versão principal imediatamente mais antiga, um clique de cada vez:

- A deteção é automática — sem configuração. Só entra em ação quando todas as versões listadas correspondem a `major.minor.patch` e existe mais do que uma versão principal; caso contrário, a cronologia mantém-se plana.
- Tolera as tags com âmbito que os monorepos publicam, pelo que `pkg@2.0.0` fica agrupado em `2.x` e `pkg@1.4.0` em `1.x`.
- É melhoria progressiva: todas as versões continuam presentes no HTML da página (e no seu feed RSS e índice de pesquisa), pelo que os leitores sem JavaScript — e os rastreadores — veem o histórico completo. O botão só recolhe as versões principais mais antigas depois de a página hidratar.

## A partir do GitHub Releases

Em vez de escrever as entradas à mão, aponte a [fonte `github-releases`](/docs/content/sources#github-releases) integrada para um repositório e cada versão passa a ser uma entrada `type: changelog` — a mesma cronologia e o mesmo feed, alimentados diretamente pelas versões que já publica. O próprio [changelog](/changelog) do Blume é construído assim:

```ts blume.config.ts
content: {
  sources: [
    { type: "filesystem", root: "content" },
    {
      type: "github-releases",
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    },
  ],
}
```

O nome da versão torna-se o título, a sua tag torna-se `changelog.version` e a respetiva data de publicação ordena a cronologia. Cada página de versão recebe ainda uma meta description única, resumida a partir das suas notas — sem markdown, sem títulos de secção nem prefixos de hash de commit dos changesets, cortada para o comprimento de excerto de pesquisa que o [`blume audit`](/docs/reference/cli#auditing-the-built-site) verifica — em vez de recorrer à descrição do site. Um repositório privado autentica-se com a variável de ambiente `GITHUB_TOKEN`. Consulte [Fontes de conteúdo](/docs/content/sources#github-releases) para todas as opções.

## O feed RSS

O Blume também constrói um feed do changelog em **`/changelog/rss.xml`**, ordenado por `date` da mais recente para a mais antiga. Os feeds precisam de um URL absoluto do site, por isso defina [`deployment.site`](/docs/deployment); o Blume injeta então uma tag `<link rel="alternate">` em todas as páginas para que os leitores o descubram automaticamente.

O feed está ativo por predefinição. Ajuste-o em [`seo.rss`](/docs/configuration/seo#rss-feeds):

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

Remova `"changelog"` de `rss.types` para dispensar o feed mantendo a cronologia.

## Dados estruturados

Quando os [dados estruturados](/docs/configuration/seo#structured-data) estão ativos, cada entrada do changelog é emitida como um **`TechArticle`** do schema.org com a sua descrição e data de publicação, para que os motores de busca possam indexar as versões como artigos datados.

**[Frontmatter](/docs/reference/frontmatter#changelog)**

O esquema completo do frontmatter do changelog.

**[Custom Pages](/docs/advanced/custom-pages)**

Substitua a cronologia gerada pelo seu próprio layout.

---

# Páginas Personalizadas
Source: https://useblume.dev/pt/docs/advanced/custom-pages

A maior parte de um site Blume é Markdown, mas às vezes você precisa de uma rota que _não seja_ um documento — uma landing page, uma página de preços, um índice de blog ou changelog construído à mão, ou um painel interativo. Coloque um arquivo `.astro` dentro da sua pasta **pages** e o Blume o monta como uma rota real, bem ao lado do seu conteúdo.

## Adicionar uma página

Crie uma pasta `pages/` na raiz do seu projeto e adicione um arquivo `.astro`:

```astro pages/pricing.astro lineNumbers
---
import data from "blume:data";
---

<h1>Pricing for {data.config.title}</h1>
```

O `blume dev` a detecta imediatamente e o `blume build` a pré-renderiza como HTML estático. O nome da pasta é configurável com [`content.pages`](/docs/configuration#content) (padrão `"pages"`).

As páginas personalizadas mantêm sua localização original em disco, então importações relativas, importações de componentes e [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) funcionam exatamente como funcionariam em um projeto Astro comum — o Blume monta cada arquivo onde ele está, em vez de copiá-lo.

## Arquivos e rotas

O caminho de cada arquivo dentro da pasta pages se torna a sua rota. `index` corresponde à pasta pai, e segmentos dinâmicos `[param]` são preservados:

| Arquivo                   | Rota          |
| ------------------------- | ------------- |
| `pages/pricing.astro`     | `/pricing`    |
| `pages/blog/index.astro`  | `/blog`       |
| `pages/blog/[slug].astro` | `/blog/:slug` |
| `pages/changelog.astro`   | `/changelog`  |

Uma página personalizada **prevalece** sobre uma rota gerada no mesmo caminho. Adicionar `pages/changelog.astro`, por exemplo, substitui a [linha do tempo de changelog gerada](/docs/advanced/changelog) pelo Blume pela sua própria.

## Lendo dados do site

Importe `blume:data` para ler a mesma configuração resolvida, navegação, rotas e feeds que o restante do site usa:

```astro pages/all-pages.astro lineNumbers
---
import data from "blume:data";
---

<h1>All pages</h1>
<ul>
  {
    data.routes
      .filter((route) => route.indexable)
      .map((route) => (
        <li>
          <a href={route.path}>{route.title}</a>
        </li>
      ))
  }
</ul>
```

Dentro de um projeto Blume, o módulo é tipado automaticamente. Você também pode trazer o formato explicitamente — para helpers tipados, props ou seu próprio tsconfig — com `import type { BlumeData } from "blume"`:

```ts
import type { BlumeData, BlumeRoute } from "blume";

const indexable = (data: BlumeData): BlumeRoute[] =>
  data.routes.filter((route) => route.indexable);
```

O módulo expõe:

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `BlumeDataConfig` | - | Configurações resolvidas do site: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host e a base da api REST — null quando não definido), search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap e imageZoom. |
| `navigation` | `Navigation` | - | A barra lateral, as abas e os seletores inferidos do seu conteúdo (idioma padrão). |
| `navigationByLocale` | `Record<string, Navigation>` | - | Árvores de navegação por idioma, indexadas pelo código do idioma. Vazio a menos que o i18n esteja configurado. |
| `routes` | `BlumeRoute[]` | - | Todas as páginas de conteúdo: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }. |
| `feeds` | `BlumeFeed[]` | - | Feeds RSS gerados: { href, title }. |
| `fontCssVars` | `string[]` | - | Nomes das variáveis CSS para as fontes configuradas (integração <Font> do Astro). |
| `ui` | `UIStrings` | - | Textos resolvidos da interface para o idioma padrão (rótulos de busca, barra lateral e rodapé). |
| `uiByLocale` | `Record<string, UIStrings>` | - | Textos da interface por idioma, indexados pelo código do idioma. Vazio a menos que o i18n esteja configurado. |

`routes` carrega metadados da página, mas não o frontmatter como `type` ou `date`. Para construir uma lista filtrada por tipo de conteúdo — um índice de blog ou changelog — combine-a com a coleção de conteúdo `docs` do Astro, que contém o frontmatter:

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";

// Each route's id matches its collection entry id.
const routeById = new Map(data.routes.map((route) => [route.id, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && !entry.data.draft)
  .map((entry) => ({
    description: entry.data.description,
    href: routeById.get(entry.id),
    title: entry.data.title,
  }));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

## Helpers de runtime

O `blume/runtime` agrupa os padrões de dados mais comuns para que você não precise mexer nos detalhes internos do `blume:data`.

**`getBlumeCollection(data, query?)`** seleciona rotas de conteúdo — filtradas por coleção, idioma ou prefixo de caminho, com rascunhos e páginas ocultas excluídos e o resultado ordenado por caminho — que é exatamente o que um índice personalizado precisa:

```astro pages/blog/index.astro lineNumbers
---
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const posts = getBlumeCollection(data, { prefix: "/blog" });
---

<ul>
  {posts.map((post) => (
    <li><a href={post.path}>{post.title}</a></li>
  ))}
</ul>
```

**`<BlumePage>`** renderiza o corpo de uma entrada de conteúdo dentro de uma página personalizada, com os componentes MDX integrados do Blume (callouts, cards, steps…) já conectados — para destacar um documento em uma landing page ou construir um índice sob medida que mostre conteúdo real:

```astro pages/index.astro lineNumbers
---
import BlumePage from "blume/components/BlumePage.astro";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const [intro] = getBlumeCollection(data, { prefix: "/docs" });
---

{intro && <BlumePage id={intro.entryId} />}
```

Passe `components` para adicionar suas próprias substituições ou ilhas (que ficam no runtime gerado e não são importadas por padrão), e `collection` para ler de uma coleção diferente de `"docs"`.

## Usando o layout do site

O `RootLayout` dá a uma página personalizada toda a estrutura da documentação — cabeçalho, barra lateral, busca, índice e tema — envolvendo-a na mesma grade de 3 colunas que as páginas geradas usam. Para uma landing page ou página de marketing, essa grade atrapalha, então recorra ao **`PageLayout`**: ele fornece a estrutura do documento, o cabeçalho, o tema e as fontes, e depois um único `<slot />` de largura total (sem barra lateral, sem prosa, sem índice). Um slot opcional `footer` é renderizado após o `<main>`:

```astro pages/index.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
import Footer from "./_home/Footer.astro";

const { config } = data;
---

<PageLayout
  site={{ title: config.title, description: config.description }}
  logo={config.logo}
  banner={config.banner}
  analytics={config.analytics}
  navigation={data.navigation}
  favicon={config.favicon}
  fontCssVars={data.fontCssVars}
  themeMode={config.theme.mode}
  searchEnabled={config.search.enabled}
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  page={{ title: "Acme — the fastest docs", description: config.description }}
>
  <section class="mx-auto max-w-5xl px-6 py-24">
    <h1>Build docs that fly</h1>
  </section>
  <Footer slot="footer" />
</PageLayout>
```

O cabeçalho que uma página personalizada recebe é o mesmo das páginas de documentação, então tudo o que vive nele vem junto: busca, alternador de tema, seletor de idioma e — quando o [Ask AI](/docs/configuration/ai) está configurado — o gatilho do Ask AI. Nada disso precisa ser conectado página por página. Passe `askEnabled={false}` para desativar o gatilho do Ask em uma página específica, mantendo-o em todas as outras.

Passar `siteUrl` (e `ogEnabled`) deriva automaticamente o `canonical` da página e uma `og:image` gerada: o Blume renderiza um card Open Graph para cada página personalizada estática — incluindo a home, a URL mais compartilhada — servido em `/og/<route>.png` (`/og/index.png` para `/`). O card da home usa o título do site com a descrição como sobretítulo; uma página mais profunda é intitulada a partir do último segmento do seu caminho. Defina `ogImage` ou `canonical` explicitamente para substituir qualquer um deles. `ogImage` aceita um caminho relativo à raiz — um arquivo em `public/`, resolvido em relação a [`deployment.site`](/docs/deployment) para a URL absoluta de que os rastreadores precisam — ou uma URL externa, que passa intacta:

```astro pages/index.astro lineNumbers
<PageLayout
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  ogImage="/opengraph-image.png"
  ogImageAlt="Acme — the fastest docs"
  ogImageSize={{ width: 1200, height: 630 }}
  page={{ title: config.title }}
>
  <!-- page content -->
</PageLayout>
```

Apenas esta página muda — todas as outras rotas mantêm seu card gerado — então é assim que você dá somente à página inicial uma imagem de compartilhamento sob medida. O card gerado declara seu tamanho e texto alternativo aos rastreadores por conta própria; para a sua própria `ogImage`, passe `ogImageAlt` e `ogImageSize` junto para que o card de compartilhamento receba o mesmo tratamento.

A página também emite JSON-LD do schema.org — o mesmo grafo `WebSite` que as páginas de documentação carregam, para que a página inicial (geralmente uma página personalizada) não seja a única URL sem dados estruturados. Passe `structuredDataEnabled={config.structuredData}` para mantê-lo em sincronia com a configuração [`structuredData`](/docs/configuration/seo), ou `structuredDataEnabled={false}` para desativá-lo em uma página específica.

`page.title` é usado literalmente como título do documento (sem o sufixo `- siteTitle`), já que páginas de marketing geralmente definem o seu próprio. Para dar a uma página personalizada toda a estrutura da documentação — barra lateral, índice e tudo mais — envolva-a no `RootLayout`, o layout que as páginas geradas usam. Puxe as props necessárias diretamente do `blume:data`:

```astro pages/pricing.astro lineNumbers
---
import RootLayout from "blume/components/layout/RootLayout.astro";
import data from "blume:data";
---

<RootLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  banner={data.config.banner}
  navigation={data.navigation}
  page={{ title: "Pricing", route: "/pricing" }}
  headings={[]}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  indexable={true}
>
  <h1>Pricing</h1>
</RootLayout>
```

:::note
O `RootLayout` faz parte do runtime gerado, então suas props podem mudar entre versões. Quando você quiser um layout totalmente seu, o [`blume eject`](/docs/configuration/customization#eject) transforma o `.blume/` em um projeto Astro padrão que é inteiramente seu.
:::

## Página 404

O Blume traz uma página **não encontrada** padrão de fábrica: uma mensagem "404" centralizada envolvida na estrutura do site (cabeçalho, busca, tema), servida para qualquer URL sem correspondência. O `blume build` a grava em `404.html`, que hospedagens estáticas servem automaticamente, e o `blume dev` a exibe para rotas desconhecidas. Abaixo da mensagem, uma lista **Onde procurar em seguida** aponta para cada seção de nível superior, além dos índices `sitemap.xml` e [`llms.txt`](/docs/configuration/ai#llmstxt) quando existirem, para que um leitor — ou um agente que seguiu uma URL desatualizada — tenha um caminho de volta.

A página também tem uma gêmea em Markdown em `/404.md` e uma gêmea em JSON em `/404.json` (detalhes de problema conforme a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) com os mesmos links de recuperação (URLs absolutas assim que [`deployment.site`](/docs/deployment) estiver definido), além da descrição [`openapi.json`](/docs/configuration/ai#json-api) quando a API JSON estiver ativa. Em um [build de servidor na Vercel](/docs/deployment#server-rendering), uma requisição para uma página inexistente que envie [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation), ou que peça uma URL `.md` sem página correspondente, recebe esse corpo em Markdown com o status `404` em vez da estrutura HTML; uma que envie `Accept: application/json`, ou que peça uma URL `.json` sem arquivo correspondente, recebe o documento de problema — assim um agente nunca precisa analisar uma página cheia de interface para descobrir para onde ir em seguida.

Para substituí-la pela sua própria, adicione um `pages/404.astro`. Ela assume a rota `/404` da mesma forma que `pages/changelog.astro` assume o changelog — sua página prevalece e a padrão é descartada. Construa-a como qualquer outra página personalizada, em `PageLayout` ou `RootLayout`:

```astro pages/404.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
---

<PageLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  navigation={data.navigation}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  page={{ title: "Page not found", route: "/404" }}
  noindex={true}
>
  <section class="mx-auto max-w-2xl px-6 py-24 text-center">
    <h1>This page took a wrong turn</h1>
    <a href="/">Back to home</a>
  </section>
</PageLayout>
```

Para manter o design padrão mas alterar o texto — inclusive para outros idiomas — sobrescreva os [textos da interface](/docs/content/i18n) de `notFound` (`title`, `description`, `home`) via `i18n.ui`.

## Páginas interativas

Páginas personalizadas são Astro comum, então você pode inserir [ilhas](/docs/configuration/customization#interactive-islands) React (ou de qualquer framework) com uma diretiva de hidratação. O React é ativado automaticamente assim que seu projeto contém um arquivo `.tsx` ou `.jsx`.

**[Personalização](/docs/configuration/customization)**

Substituições de componentes, ilhas React, o registro e o eject.

**[Blog](/docs/advanced/blog)**

Escreva posts e construa um índice de blog personalizado.

---

# GraphQL
Source: https://useblume.dev/pt/docs/advanced/graphql

Aponte o Blume para um schema GraphQL e ele gera uma referência de API nativa: uma **página real por campo raiz** — queries, mutations e subscriptions — mais uma **página por tipo nomeado** (objetos, objetos de entrada, enums, interfaces, unions e scalars customizados). Cada página mostra argumentos, valores padrão, descontinuações e backlinks de uso, junto com uma operação de exemplo gerada, exemplos de código e um painel interativo [Try it](#try-it-playground). Como cada página é uma página Blume de verdade, ela ganha sua própria URL, aparece na **busca do site** e no `llms.txt`, e recebe uma imagem Open Graph — igualzinho a qualquer doc escrito à mão.

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
}
```

Isso monta a referência em `/graphql` (uma página de visão geral), com campos raiz em `/graphql/queries/<field>`, `/graphql/mutations/<field>` e `/graphql/subscriptions/<field>`, e tipos agrupados por espécie em `/graphql/objects/<type>`, `/graphql/enums/<type>` e assim por diante.

O `spec` é ou um caminho para um arquivo local no seu projeto ou uma URL `http(s)`, e aceita dois formatos:

- **Texto SDL** — um arquivo `.graphql` com definições de tipos.
- **Um resultado de introspecção** — o JSON produzido ao rodar a query de introspecção padrão, seja no formato bruto `{ "__schema": … }` ou no envelope de resposta completo `{ "data": { "__schema": … } }`.

O `endpoint` é a URL da API GraphQL ao vivo. Um schema, diferente de um documento OpenAPI, não nomeia nenhum servidor — então o endpoint é o alvo do painel Try it e dos exemplos de código gerados. Se você não informar, os exemplos são renderizados com uma URL de placeholder que os leitores substituem.

A referência não adiciona uma aba de cabeçalho por conta própria. Para exibi-la, aponte uma [aba de navegação](/docs/content/navigation#tabs) para a rota dela — isso também define o escopo da sidebar da referência:

```ts blume.config.ts
navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}
```

## Exemplos gerados

Toda página de operação traz uma operação de exemplo completa e válida — uma variável por argumento, tipada a partir do schema, com um conjunto de seleção de profundidade limitada sobre o tipo de retorno — mais as variáveis de exemplo correspondentes e uma resposta de exemplo que espelha a mesma seleção. Os exemplos de código mostram a requisição HTTP exata (um `POST` JSON de `{ query, variables }`) em cada linguagem configurada:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  codeSamples: ["curl", "js"],   // built in: curl, js, python
}
```

## Páginas de tipos

Tipos nomeados ganham suas próprias páginas com deep link, agrupadas por espécie na sidebar: campos e campos de entrada com seus tipos linkados, valores de enum, membros de union, implementações de interface e uma seção **Usado por** listando as operações que retornam ou aceitam o tipo e os outros tipos que o referenciam. Scalars definidos pela especificação (`String`, `Int`, …) não ganham páginas; scalars customizados ganham, incluindo a URL `specifiedBy` deles.

## Múltiplos schemas

Cada entrada em `sources` renderiza um schema na sua própria rota. Um `endpoint` por fonte sobrescreve o do nível do bloco:

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  endpoint: "https://api.example.com/graphql",
  sources: [
    { label: "Public API", spec: "./schema.graphql" },
    {
      label: "Admin API",
      route: "/graphql-admin",
      spec: "./admin.graphql",
      endpoint: "https://admin.example.com/graphql",
    },
  ],
}
```

Cada fonte aceita os mesmos [controles por fonte](/docs/advanced/api-reference#per-source-indexing) do bloco OpenAPI: `includeInSearch`, `includeInLlms`, `noindex` e `seoDescriptionSuffix` (aqui a frase gerada nomeia a query, a mutation ou o tipo — "Reference for the `pets` query in the GraphQL API.").

## Playground Try it

Páginas de query e mutation renderizam um painel interativo: edite o corpo da requisição (a query e as variáveis), aponte para o seu endpoint ou uma URL customizada e envie — os exemplos de código atualizam ao vivo, então o que você copia é byte a byte o que foi enviado. Desative com `playground: false`. Páginas de subscription mostram a operação gerada e um evento de exemplo no lugar: subscriptions rodam sobre um transporte com estado (WebSocket ou SSE) que o único `POST` HTTP do playground não sabe falar.

Se a sua API GraphQL não permite requisições cross-origin vindas do site da documentação, roteie os envios por um proxy CORS — uma URL sua, ou `true` para o endpoint embutido `/_api-proxy` (que exige `deployment.output: "server"`). O proxy embutido só encaminha para origens declaradas pelas specs que você documenta — cada `endpoint` GraphQL configurado, mais qualquer `servers[].url` absoluto de uma [spec OpenAPI](/docs/advanced/api-reference) documentada — assim uma implantação pública da documentação não pode ser apontada para outros hosts. Isso torna o `endpoint` obrigatório para um proxy funcional: sem ele, o proxy não tem origem para permitir nesta referência e recusa todos os envios (o build avisa sobre isso).

```ts blume.config.ts lineNumbers
graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
  playground: { proxy: true },
}
```

---

# Skills
Source: https://useblume.dev/pt/docs/advanced/skills

O Blume oferece [agent skills](https://docs.claude.com/en/docs/claude-code/skills) — playbooks que ensinam um agente de programação (Claude Code, Codex, Cursor) a executar uma tarefa no formato Blume sem que você precise explicá-la. Elas ficam no GitHub, na pasta `skills/` do repositório, e vêm incluídas no pacote instalado em `skills/`, de modo que qualquer agente pode ser apontado diretamente para um `SKILL.md`.

## Blume

A skill principal. Ela ensina ao agente o que é o Blume e como estruturar, escrever e configurar um site — navegação derivada do sistema de arquivos, o schema de configuração, componentes de conteúdo — e o direciona para a documentação completa incluída no pacote instalado (o diretório `docs/` dentro de `blume`, resolvido a partir de onde quer que seu gerenciador de pacotes o instale — em um monorepo pnpm, isso é o `node_modules` do workspace dependente, não a raiz do repositório). Instale-a em qualquer projeto em que um agente ajude você a construir sua documentação:

```bash
npx skills add haydenbleasel/blume
```

## Documentação que se atualiza sozinha

A `blume-update-docs` mantém sua documentação em sincronia com o produto que ela documenta. A cada execução — normalmente a partir de um agendamento que você configura no seu executor de agentes — ela audita PRs mesclados recentemente, changelogs, schemas de configuração e a ajuda da CLI em relação ao conteúdo da documentação, atualiza apenas as páginas que estão factualmente desatualizadas (trabalhos por trás de feature flags são ignorados), verifica com `blume build` e abre ou atualiza um pull request `blume/*`. Se nada divergiu, ela reporta uma execução limpa sem alterações em vez de abrir um PR ruidoso.

```bash
npx skills add haydenbleasel/blume --skill blume-update-docs
```

O Blume não hospeda a automação — conecte a skill a uma tarefa agendada no Claude Code, a uma automação do Codex ou do Cursor, ou a um cron simples, com permissão para ler o histórico do repositório e abrir PRs. Um prompt semanal típico:

```text
Use the blume-update-docs skill. Review the PRs merged within the last 7 days and compare them to the docs content. Ignore work behind feature flags. If docs need updates, make them, verify the docs build, and open a blume/* PR. If not, report what you checked and do not open a PR.
```

---

# Arquivo de configuração
Source: https://useblume.dev/pt/docs/configuration

O Blume lê o `blume.config.ts` a partir da raiz do seu projeto. Envolva sua configuração em `defineConfig` para ter preenchimento automático e verificação de tipos — todos os campos são opcionais, com um valor padrão sensato.

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});
```

## Um exemplo completo

Um exemplo mais abrangente que aborda as opções mais comuns (consulte o guia de cada funcionalidade para as demais):

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [sitemap()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — see the Search guide
  search: {
    provider: "orama",
  },

  // Markdown features
  markdown: {
    imageZoom: true,
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
    },
    codeBlocks: {
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // AI — see the AI guide
  ai: {
    llmsTxt: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — see the Deployment guide
  deployment: {
    output: "static",
    site: "https://docs.example.com",
  },
});
```

## Site

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `title` | `"Documentation"` | Nome do site — exibido no cabeçalho, nos títulos das páginas e nos cards OG. |
| `description` | — | Meta descrição padrão, usada para SEO e OG. |
| `logo` | — | Marca gráfica e/ou logotipo textual exibido no cabeçalho. |
| `banner` | — | Barra de anúncios para todo o site, acima do cabeçalho. |

### Logotipo

Aponte o `logo` para um SVG e o Blume o incorpora inline, para que um logotipo com `currentColor` acompanhe automaticamente o tema claro e escuro:

```ts blume.config.ts
logo: "/logo.svg",
```

O SVG pode ficar na raiz do seu projeto ou em `public/`. A marca é composta por um símbolo (`image`) mais um logotipo textual (`text`); a forma de objeto permite defini-los de forma independente:

```ts blume.config.ts lineNumbers
logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},
```

`image` aceita o mesmo valor que a forma abreviada — um único caminho, ou `{ light, dark, alt }` para artes separadas para claro/escuro (as imagens raster precisam ficar em `public/`).

`text` controla o logotipo textual independentemente do símbolo:

- **Omita `text`** e a marca usa o `title` do seu site (o padrão).
- **Defina `text: ""`** para mostrar apenas o símbolo — útil quando a imagem do logotipo já inclui o logotipo textual.
- **Defina `text` sem `image`** para um logotipo apenas de texto.

### Favicon

Não existe uma opção de favicon — o Blume detecta um automaticamente pelo nome do arquivo, como o Next.js faz. Coloque um arquivo `icon` ou `favicon` (`.svg`, `.png` ou `.ico`) na raiz do seu projeto ou no diretório `public/` e ele vira o ícone da aba do navegador:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/
```

O SVG prevalece sobre o PNG, que prevalece sobre o ICO quando há vários, e um arquivo em `public/` é preferido a um na raiz. Se o Blume não encontrar nenhum ícone, ele recorre à sua própria marca.

Uma marca escura desaparece contra a interface escura do navegador, então você pode fornecer um segundo arquivo para o modo escuro. Adicione um arquivo irmão `-dark` ao seu arquivo de ícone — o mesmo nome e o mesmo diretório, com `-dark` antes da extensão (`icon.png` → `icon-dark.png`) — e o Blume emite os dois ícones atrás de uma media query `prefers-color-scheme`, além de uma tag clara simples para navegadores e crawlers que ignoram media queries em ícones:

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/
```

Só o irmão do ícone que o Blume escolheu é usado — um arquivo `-dark` com um nome diferente continua ignorado, então um arquivo sem relação não pode se emparelhar com a sua marca por acidente. O arquivo escuro é opcional; com apenas um ícone, o Blume emite uma única tag como antes. A marca de fallback do próprio Blume inclui as duas variantes.

### Ícone Apple touch

O ícone que o iOS usa quando alguém adiciona seu site à tela de início é detectado da mesma forma. Coloque um arquivo `apple-icon` (`.png`, `.jpg` ou `.jpeg`) — ou um `apple-touch-icon.png`, o nome que a maioria dos geradores de favicons produz — na raiz do seu projeto ou no diretório `public/` e o Blume cuida de configurar `<link rel="apple-touch-icon">` para você. Não há padrão; se nenhum arquivo for encontrado, nenhuma tag é emitida.

```
my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/
```

Coloque o arquivo em `public/` em vez da raiz do projeto: o iOS ignora o URI de dados incorporado que o Blume usa para um ícone no nível da raiz, então só um arquivo em `public/` (servido em `/apple-icon.png`) chega de forma confiável à tela de início. Diferentemente do favicon, aqui não existe um irmão `-dark` — o iOS ignora media queries nos ícones da tela de início, então uma variante escura nunca poderia ser servida.

### Faixa

Mostre uma barra de anúncios para todo o site acima do cabeçalho. Passe uma string, ou um objeto com um link e um botão para dispensar:

```ts blume.config.ts
banner: "Docs are in beta — expect changes.",
```

```ts blume.config.ts lineNumbers
banner: {
  content: "Blume v1 is here!",
  link: { text: "Read more", href: "/blog/v1" },
  dismissible: true,
  id: "v1",
},
```

Quando `dismissible` está ativo, a barra mostra um botão de fechar e permanece oculta para aquele visitante daí em diante. A chave de dispensa assume por padrão o texto do conteúdo, então editar a mensagem faz a faixa reaparecer; defina um `id` estável para mantê-la dispensada entre edições.

## Conteúdo

Onde seu conteúdo fica e como o Blume o descobre. Consulte [Páginas](/docs/content) para saber como os arquivos viram rotas.

```ts blume.config.ts lineNumbers
content: {
  root: "docs",
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `root` | `"docs"` | Pasta que o Blume analisa em busca de conteúdo. |
| `include` | `["**/*.{md,mdx}"]` | Globs que correspondem a arquivos de conteúdo. |
| `exclude` | `["**/_*", "**/.*"]` | Globs a ignorar (arquivos com underscore e com ponto). |
| `pages` | `"pages"` | Pasta para páginas `.astro` personalizadas. |
| `defaultType` | `"doc"` | `type` de página usado quando o frontmatter o omite. |
| `types` | `{}` | Definições de conteúdo por tipo — chaves de frontmatter personalizadas restritas às páginas de um `type`. Consulte [Frontmatter](#frontmatter). |

Os recursos estáticos ficam em `public/` — um arquivo em `public/logo.png` é servido em `/logo.png`, então uma referência como `![](/images/create.png)` é resolvida a partir de `public/images/create.png`. As imagens referenciadas por **caminho relativo** (`![](./diagram.png)`) ficam junto ao seu conteúdo e são [otimizadas no momento da build](/docs/content/syntax#links-and-images).

## Imagens

As imagens locais referenciadas por caminho relativo são otimizadas automaticamente no momento da build — comprimidas, convertidas para WebP e com atributos `width`/`height` intrínsecos, para que o layout não se desloque enquanto elas carregam. Não há nada a configurar; consulte [Links e imagens](/docs/content/syntax#links-and-images) para orientações de escrita.

As imagens remotas são servidas sem alterações por padrão. Para que o Blume também as baixe e otimize no momento da build, autorize seus hosts:

```ts blume.config.ts lineNumbers
image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `domains` | `[]` | Nomes de host cujas imagens remotas podem ser otimizadas. |
| `remotePatterns` | `[]` | Autorização baseada em padrões (`protocol`, `hostname`, `port`, `pathname`); os nomes de host aceitam os wildcards `*.` (um nível) e `**.` (qualquer profundidade). |

## Frontmatter

O frontmatter das páginas é validado de forma estrita — uma chave desconhecida faz a build falhar, então os erros de digitação são detectados cedo. Para levar metadados específicos do projeto (um responsável, uma data de revisão), declare as chaves adicionais em `frontmatter.extend`, cada uma mapeada para um schema que você fornece:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

Funciona com qualquer biblioteca [Standard Schema](https://standardschema.dev) — Zod (qualquer que seja a versão que seu projeto instale), Valibot, ArkType. As chaves fora da extensão continuam validadas de forma estrita, então a detecção de erros de digitação segue inalterada. Consulte [Chaves personalizadas](/docs/reference/frontmatter#custom-keys) para a semântica de validação.

As chaves em `extend` valem para todo o site. Para exigir chaves apenas em páginas de um tipo de conteúdo — o `status` de um RFC, o `service` de um runbook — declare-as por tipo em `content.types`:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

Uma chave pode ser declarada para todo o site ou por tipo, não os dois. Consulte [Chaves por tipo](/docs/reference/frontmatter#per-type-keys) para saber como o escopo é resolvido.

`facets` indica as chaves personalizadas cujos valores viram metadados filtráveis: elas acompanham os documentos de busca (`blume-search.json` e o índice MCP), e as [ferramentas MCP](/docs/configuration/ai#mcp-server) aceitam um input `filters` que faz correspondência com elas, para que um agente possa obter, por exemplo, apenas os RFCs com status `enforced` no domínio `architecture`. Cada faceta precisa ser uma chave personalizada declarada — por tipo ou para todo o site — e apenas os valores do tipo string (ou números/booleanos convertidos em string) funcionam como facetas.

## GitHub

Aponte o Blume para o seu repositório com `github`. É o que alimenta o [link para o repositório](/docs/content/navigation#repository-link) no cabeçalho e as [ações de página](/docs/content/navigation#page-actions) **Editar no GitHub** e **Enviar feedback**:

```ts blume.config.ts lineNumbers
github: {
  owner: "acme",
  repo: "docs",
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `owner` | — | Conta ou organização do GitHub dona do repositório. |
| `repo` | — | Nome do repositório. |
| `branch` | `"main"` | Branch para onde os links de edição apontam. |
| `dir` | — | Caminho da raiz do repositório até a raiz do projeto (para monorepos). |
| `host` | `"https://github.com"` | Origem da instância do GitHub, para instalações Enterprise. Precisa ser HTTP(S); normalizada para sua origem. |
| `api` | derivado de `host` | Base da API REST, para o `<GithubInfo>` em uma instância Enterprise. Precisa ser HTTP(S); normalizada para uma origem e um caminho. |

### GitHub Enterprise

Docs cujo repositório fica em uma instância do GitHub Enterprise definem `host`, e todo link derivado do repositório — a marca do cabeçalho, os links de edição, o manifesto do agente — aponta para essa instância em vez do site público:

```ts blume.config.ts lineNumbers
github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}
```

A base da API REST que o [`<GithubInfo>`](/docs/content/components) consulta é derivada de `host`: um tenant do Enterprise Cloud com residência de dados (`acme.ghe.com`) é servido a partir do seu subdomínio `api.`, e qualquer outro host é tratado como Enterprise Server (`/api/v3`). Defina `api` explicitamente quando sua instância estiver em outro lugar.

:::warning
Uma instância acessível apenas por HTTP simples ainda renderiza suas contagens, mas o `GITHUB_TOKEN` é omitido da requisição em vez de ser enviado em texto puro — então o card de um repositório privado volta sem elas.
:::

:::note
`host` cobre os links que o Blume deriva de `github`. Para apontar só a marca do cabeçalho para outro lugar — uma organização, digamos, quando o próprio repositório das docs é privado — use [`navigation.repo`](/docs/content/navigation#repository-link) com uma URL absoluta.
:::

## Última modificação

Mostre uma linha "Última atualização em …" no rodapé de cada página. Desativado por padrão; defina `lastModified` como `true` para derivar a data de cada página do respectivo histórico do git:

```ts blume.config.ts
lastModified: true,
```

| Valor | Descrição |
| --- | --- |
| `false` | Desativado (padrão). |
| `true` | Lê a data do histórico do git (datas dos commits). |
| `{ type: "git" }` | O mesmo que `true`, escrito explicitamente. |
| `{ type: "frontmatter" }` | Nunca executa o git — usa apenas o campo `lastModified` do frontmatter. |

A fonte git lê o commit mais recente que tocou em cada arquivo, então funciona em qualquer repositório git — incluindo monorepos — e precisa do histórico do repositório no momento da build. As plataformas de CI costumam fazer checkout de um clone raso, o que descarta silenciosamente a maioria das datas (a build avisa com `BLUME_SHALLOW_GIT_HISTORY` quando isso acontece): na Vercel, defina a variável de ambiente `VERCEL_DEEP_CLONE=true`; com o `actions/checkout`, defina `fetch-depth: 0`. O `lastModified` do frontmatter da própria página sempre prevalece, o que é útil para fixar uma data ou para arquivos que ainda não foram commitados:

```mdx page.mdx
---
title: My page
lastModified: 2026-06-20
---
```

Quando ativada, a data também é emitida como `dateModified` do schema.org nos dados estruturados da página.

## Formato de data

Tanto a marca de "Última atualização" quanto a linha do tempo do [changelog](/docs/advanced/changelog) exibem suas datas através do mesmo `dateFormat`, para que elas sejam lidas do mesmo jeito. As datas são sempre exibidas no locale do site; o `dateFormat` controla o _formato_. Por padrão ele usa a forma longa (`July 21, 2026`, `2026年7月21日`):

```ts blume.config.ts
dateFormat: { dateStyle: "long" },
```

`dateFormat` é repassado diretamente para as opções de [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). Use um preset `dateStyle` para escolher um comprimento:

```ts blume.config.ts
dateFormat: { dateStyle: "medium" },
```

Ou os campos de componentes individuais para um estilo numérico próprio como `2026/07/21`:

```ts blume.config.ts
dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
```

| Opção | Descrição |
| --- | --- |
| `dateStyle` | Comprimento predefinido: `"full"`, `"long"`, `"medium"` ou `"short"`. Não pode ser combinado com os campos de componentes. |
| `weekday`, `era`, `year`, `month`, `day` | Componentes individuais, p. ex. `year: "numeric"`, `month: "2-digit"`. |
| `timeZone` | Fuso horário IANA. Por padrão é `UTC`, para que uma data seja lida da mesma forma independentemente de onde o site é buildado. |
| `calendar`, `numberingSystem` | Sistema de calendário (p. ex. `"japanese"`) e sistema de numeração (p. ex. `"arab"`). |

## SEO

Imagens Open Graph, feeds RSS e dados estruturados JSON-LD, agrupados em `seo`. Consulte o [guia de SEO](/docs/configuration/seo) para metadados, substituições no frontmatter e a referência completa.

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `og.enabled` | automático | Imagens Open Graph por página — ativas quando uma URL do site está definida. |
| `rss.enabled` | `true` | Cria feeds para conteúdos de blog e de changelog. |
| `rss.types` | `["blog", "changelog"]` | Tipos de conteúdo que recebem cada um um feed. |
| `rss.limit` | `50` | Número máximo de itens por feed. |
| `sitemap` | `true` | Gera o sitemap.xml (precisa de deployment.site). |
| `robots` | `true` | Gera o robots.txt com um link para o Sitemap. |
| `structuredData` | `true` | Emite JSON-LD do schema.org no head de cada página. |

Eles funcionam melhor com um [`deployment.site`](/docs/deployment) absoluto, para URLs completas.

## Sumário da página

O esquema "nesta página" está ativo por padrão e lista os títulos `H2`–`H3`. Desative-o, ou altere o intervalo de títulos, com `toc`:

```ts blume.config.ts
export default defineConfig({
  toc: false, // hide it everywhere
});
```

Ou, em vez disso, restrinja o intervalo de títulos:

```ts blume.config.ts
export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});
```

## Opções de funcionalidades

Cada uma delas tem seu próprio guia. O campo de configuração é o ponto de entrada:

| Campo | O que configura | Guia |
| --- | --- | --- |
| `theme` | Cor de destaque, raio dos cantos, fontes, modo claro/escuro | [Temas](/docs/configuration/theming) |
| `navigation` | Barra lateral explícita e abas do cabeçalho | [Navegação](/docs/content/navigation) |
| `search` | Provedor (Orama, Pagefind, Algolia, entre outros) e indexação | [Busca](/docs/configuration/search) |
| `markdown` | Opções de renderização de Markdown — blocos de código, âncoras de títulos, zoom em imagens | [Sintaxe](/docs/content/syntax) |
| `ai` | `llms.txt`, Ask AI e o servidor MCP hospedado para agentes de programação | [IA](/docs/configuration/ai) |
| `analytics` | Vercel, PostHog e scripts personalizados | [Analytics](/docs/configuration/analytics) |
| `seo` | Metadados, imagens OG, feeds, dados estruturados | [SEO](/docs/configuration/seo) |
| `deployment` | Modo de saída, adaptador e URL do site | [Deploy](/docs/deployment) |
| `redirects` | Redirecionamentos permanentes e temporários | [Deploy](/docs/deployment#redirects) |
| `integrations` | Integrações do Astro adicionadas depois das integradas do Blume | [Personalização](/docs/configuration/customization#astro-integrations) |

## Precedência

As configurações são resolvidas da prioridade mais baixa para a mais alta, então você só precisa substituir o que quiser:

1. **Padrões do Blume**

    Um valor padrão sensato para cada campo.

2. **blume.config.ts**

    A configuração de todo o seu projeto.

3. **Meta da pasta**

    [`meta.ts`](/docs/content/meta) para o título e a ordenação de uma seção.

4. **Frontmatter da página**

    As substituições por página prevalecem.

---

# IA
Source: https://useblume.dev/pt/docs/configuration/ai

O Blume tem alguns recursos de IA: documentação legível por máquinas para ferramentas externas (`llms.txt` e uma [API JSON](#json-api) com uma descrição OpenAPI, ambos ativados por padrão), um assistente **Ask AI** na página e um **servidor MCP** hospedado para agentes de programação. O Ask AI e o MCP são opcionais, e a documentação estática continua totalmente estática até você ativar um recurso.

## llms.txt

O Blume emite versões legíveis por máquinas da sua documentação que agentes de programação e assistentes de chat podem consumir. Isso vem ativado por padrão; defina `llmsTxt: false` para desativar:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: false,
}
```

Enquanto estiver ativado, `blume build` escreve dois arquivos na raiz do seu site:

- **`/llms.txt`** — um índice compacto: o título e a descrição do seu site, depois uma lista com links de todas as páginas com seus resumos, organizada em seções que espelham a sua barra lateral — pastas e grupos viram cabeçalhos, para que um agente veja a estrutura da documentação, e não um bloco único e plano.
- **`/llms-full.txt`** — o corpus completo: o corpo Markdown inteiro de cada página, com sua URL de origem, em um único arquivo.

Páginas em rascunho são excluídas. Defina [`deployment.site`](/docs/deployment) para que os links e as URLs de origem resolvam para endereços absolutos.

`llmsTxt` também aceita uma forma de objeto com opções para o que os arquivos incluem. Se a sua [referência de API](/docs/advanced/api-reference) documenta uma especificação de exemplo ou provisória, defina `openapi: false` para manter as páginas geradas dela fora dos dois arquivos:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    enabled: true, // default
    openapi: false, // exclude generated API reference pages
  },
}
```

A forma de objeto também aceita `details`: Markdown colocado logo depois do título e do resumo no `llms.txt`, antes das seções de páginas — o bloco livre de "details" da [especificação do llms.txt](https://llmstxt.org). É o lugar para dizer aos agentes _quando_ recorrer ao seu produto e como chamá-lo, algo que scanners de prontidão procuram explicitamente; um comando de instalação e o nome do pacote também cabem aqui:

```ts blume.config.ts lineNumbers
ai: {
  llmsTxt: {
    details: [
      "## When to use Acme",
      "",
      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
    ].join("\n"),
  },
}
```

O `llms.txt` termina com duas seções geradas que não precisam de configuração. **Agent skills** lista cada skill publicada por meio de [`ai.skills`](#skills-discovery) com a descrição dela (onde uma skill diz quando deve ser usada). **Agent resources** traz links para todo artefato legível por máquinas que o build emite — `llms-full.txt`, o espelho de [Markdown bruto](#raw-markdown) por página, o [servidor MCP](#mcp-server) e seu documento de descoberta, o índice de skills, o [catálogo de API](#api-catalog), o [`agent-readability.json`](#agent-readability) e o [sitemap](/docs/configuration/seo#sitemap) — cada um só quando existe, para que um agente que não lê nada além do `llms.txt` ainda encontre a superfície inteira.

Para manter uma página individual fora dos dois arquivos, defina `ai.exclude` no frontmatter dela:

```mdx
---
title: Internal notes
ai:
  exclude: true
---
```

A página continua sendo renderizada, permanece na busca e mantém seu lugar no sitemap — só os arquivos `llms.txt` a pulam.

Para assumir o controle total de qualquer um dos arquivos, adicione seu próprio `llms.txt` ou `llms-full.txt` à sua pasta `public/`. Como um favicon personalizado, ele é detectado automaticamente e entra no lugar do arquivo gerado — substitua um e o Blume continua gerando o outro.

## Markdown bruto

Adicione `.md` ou `.mdx` à URL de qualquer página para buscar seu código-fonte Markdown bruto — perfeito para LLMs, agentes de programação e fluxos de trabalho de "copiar como Markdown". Está disponível para todas as páginas, em desenvolvimento e em produção, sem nenhuma configuração.

| URL               | Retorna                                               |
| ----------------- | ----------------------------------------------------- |
| `/quickstart`     | A página renderizada                                  |
| `/quickstart.md`  | Markdown simples, com os componentes convertidos      |
| `/quickstart.mdx` | O código-fonte MDX bruto, exatamente como foi escrito |

As rotas aninhadas funcionam do mesmo jeito (`/content/syntax.md`), e a página inicial é servida em `/index.md`.

A variante `.md` _reduz_ os componentes a Markdown simples para consumidores que não conseguem interpretar JSX: `<TypeTable>` vira uma tabela Markdown, `<Callout>` uma citação rotulada, `<Steps>` uma lista ordenada, `<Tabs>` seções com rótulos em negrito, `<Card>` seu título como um link acima do corpo (e `<CardGroup>` os cards que ele contém) e `<YouTube>` um link. As props são avaliadas com o `frontmatter` da página no escopo, então uma prop como `title={frontmatter.status}` resolve para o mesmo valor que a página renderizada mostra. Tudo que não puder ser convertido fielmente — um componente personalizado ou uma prop calculada a partir de um import — é deixado como está, e a marcação de componentes dentro de blocos de código cercados nunca é tocada. A mesma conversão se aplica ao `llms-full.txt` e à ferramenta `get_page` do servidor MCP, para que toda superfície voltada a agentes leia Markdown limpo. Quando quiser o código-fonte não transformado, use a variante `.mdx`.

### Negociação de conteúdo

Os agentes não precisam conhecer a convenção `.md`: pedir a própria URL de uma página com um cabeçalho [`Accept: text/markdown`](https://acceptmarkdown.com) serve a variante Markdown no mesmo endereço, com `Vary: Accept` para que os caches mantenham as duas separadas. O servidor de desenvolvimento respeita o cabeçalho de fábrica, e um [build de servidor na Vercel ou na Cloudflare](/docs/deployment#server-rendering) integra a mesma negociação ao deploy automaticamente — regras de roteamento na Vercel, um Worker gerado na Cloudflare — sem precisar de configuração. A página inicial sempre negocia, mesmo quando é uma landing page personalizada em vez de uma página de conteúdo: seu espelho Markdown recorre ao índice [`llms.txt`](#llmstxt), então um agente que pede Markdown à raiz do site recebe o mapa legível por máquinas do site. As respostas Markdown também carregam um cabeçalho `x-markdown-tokens` — uma contagem estimada de tokens (~4 caracteres por token), seguindo a convenção do [Markdown for Agents da Cloudflare](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — em toda superfície onde o Blume controla os cabeçalhos de resposta: o servidor de desenvolvimento, as respostas renderizadas no servidor e a página inicial negociada na Vercel e na Cloudflare. Outros destinos de deploy servem páginas pré-renderizadas a partir de uma camada estática sem nenhum hook em tempo de requisição, então os agentes ali buscam a URL `.md` diretamente; o [manifesto de legibilidade para agentes](#agent-readability) anuncia `contentNegotiation` só em deploys que respeitam o cabeçalho.

Páginas inexistentes também negociam. Todo build emite uma [página 404](/docs/advanced/custom-pages#404-page) em Markdown em `/404.md` — a mensagem de não encontrado seguida de links de recuperação para cada seção de nível superior, o sitemap e o `llms.txt` — e, na Vercel, uma requisição a uma URL inexistente que prefere Markdown, ou qualquer URL `.md` sem página por trás, recebe esse corpo com um status `404` de verdade, em vez do shell HTML.

### Serializadores de componentes personalizados

Dê aos seus próprios componentes uma forma Markdown com `ai.markdownComponents` — um mapa de nome JSX para serializador. Cada serializador recebe as `props` do componente (avaliadas estaticamente a partir dos atributos MDX, com o `frontmatter` da página no escopo), seus `children` (já reduzidos a Markdown) e os dados de `frontmatter` da página, e retorna a substituição — ou `null` para deixar o JSX como está:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import type { ComponentMarkdown } from "blume";

const chart: ComponentMarkdown = ({ props }) =>
  `![${props.title}](/charts/${props.slug}.png)`;

export default defineConfig({
  ai: {
    markdownComponents: {
      Chart: chart,
    },
  },
});
```

Para componentes de contêiner, `childComponents("Name")` extrai os filhos diretos por tag — do mesmo jeito que o serializador integrado de `<Steps>` coleta seus itens `<Step>` — e `childBlocks()` retorna todos os filhos diretos em ordem, componentes e prosa igualmente, cada um já reduzido a um bloco de Markdown (o serializador integrado de `<CardGroup>` é só esses blocos unidos por linhas em branco). Uma entrada com o mesmo nome substitui um serializador integrado, então você pode reformular como `<Callout>` é reduzido — ou retornar `null` para deixá-lo de fora por completo.

Os serializadores moram no `blume.config.ts`, não no `components.tsx`: o arquivo de configuração é executado em tempo de build, enquanto o arquivo de componentes é apenas analisado estaticamente (ele pode importar arquivos `.astro`, que não podem rodar fora do build do site). Seus componentes em si continuam registrados no `components.tsx` exatamente como antes — `markdownComponents` só adiciona a forma Markdown deles voltada a agentes.

## Copiar como Markdown

Toda página traz uma ação **Copiar como Markdown** — nas [ações da página](/docs/content/navigation#page-actions) abaixo do sumário — que copia o Markdown bruto da página para a área de transferência. É o mesmo código-fonte servido na [URL `.md`](#raw-markdown) acima, pronto para colar em um LLM, uma issue ou nas suas anotações. Está disponível em todas as páginas, em desenvolvimento e em produção, sem nenhuma configuração.

Onde a Clipboard API não está disponível ou o navegador a nega — navegadores dentro de apps, WebViews, origens inseguras — a ação recorre ao comando de cópia legado e, se nada chegar à área de transferência, o botão informa **Falha ao copiar** (localizado via `actions.copyFailed`) em vez de ficar em silêncio. O mesmo fallback sustenta todo botão de copiar que o Blume renderiza.

## Abrir no chat

A ação **Abrir no chat** abre a página atual em um assistente de IA — v0, ChatGPT, Claude, T3 Chat, Scira ou Cursor — pré-preenchida com um prompt que o aponta para o Markdown bruto da página, para que ele possa responder perguntas sobre o que você está lendo:

> Leia `https://your-site/this-page.md` para que eu possa te fazer perguntas sobre esta página.

Assim como Copiar como Markdown, não precisa de configuração. O assistente busca a página pela URL pública dela, então funciona assim que a página estiver publicada.

O prompt faz parte do [dicionário de interface](/docs/content/i18n#translated-ui) (`actions.openInChatPrompt`), então sites localizados o enviam no idioma deles, e `i18n.ui` pode sobrescrever o texto — mantenha o placeholder `{url}`, que é substituído pela URL do Markdown bruto da página.

Para ajustar a ação, defina `ai.openInChat`. `false` a esconde por completo, e um array de chaves de provedor — `"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"` — mostra apenas esses provedores, na ordem em que você os listar:

```ts blume.config.ts lineNumbers
ai: {
  openInChat: ["claude", "chatgpt", "cursor"],
}
```

Para incorporar um prompt pronto para copiar direto no seu conteúdo — em vez de uma ação de página inteira — use o [componente Prompt](/docs/content/components#prompt), que renderiza uma linha rotulada com um botão **Copiar prompt** e um link opcional para abrir no Cursor.

## Ask AI

Adicione um assistente que responde às perguntas dos leitores em um painel de chat na página, sustentado por um endpoint de servidor com streaming e pelo [AI SDK](https://ai-sdk.dev):

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "gateway", // default
    model: "openai/gpt-5.5",
  },
}
```

### Perguntas sugeridas

Preencha o estado vazio com alguns prompts iniciais. Cada um é renderizado como uma sugestão clicável — clique em uma para enviá-la — com um [ícone Lucide](/docs/content/components#icon) opcional ao lado do rótulo:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    suggestions: [
      { label: "What is Blume?", icon: "rocket" },
      { label: "How do I write a docs page?", icon: "file-text" },
      { label: "How do I configure the theme?", icon: "settings" },
    ],
  },
}
```

`label` é a pergunta que é feita; `icon` é opcional. Deixe `suggestions` sem definir (ou vazio) e o painel abre com um campo de entrada simples.

### Instruções personalizadas

Adicione seu próprio texto de prompt de sistema com `instructions` — identidade, idioma, tom ou qualquer outra coisa que o assistente deva ter em mente:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    instructions:
      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
  },
}
```

Seu texto é **acrescentado às** instruções integradas, em vez de substituí-las: a parte integrada carrega o contrato de [fundamentação](#grounding) — responder só a partir das páginas recuperadas, citá-las como links Markdown — do qual dependem as citações do painel de chat, então ela permanece intacta, não importa o que você adicione.

### Fundamentação

O Ask AI é **fundamentado na sua documentação**. Para cada pergunta, ele recupera as páginas mais relevantes — usando o mesmo índice lexical do [Orama](/docs/configuration/search) que alimenta a busca na página — e as injeta no prompt de sistema do modelo, para que as respostas venham do seu conteúdo, e não do conhecimento próprio do modelo. O assistente é instruído a responder só a partir das páginas recuperadas, a dizer quando algo não está coberto e a citar as páginas de onde tirou a informação.

A página em que o leitor está é adicionada primeiro ao contexto e usada para restringir a recuperação ao idioma dessa página, para que as respostas continuem relevantes para o ponto em que ele está na documentação. A recuperação roda em tempo de requisição a partir de um snapshot embutido no build, então funciona independentemente do seu provedor de [busca](/docs/configuration/search) — mesmo quando a busca está definida como `none` — e não precisa de configuração.

A fundamentação fica ativa em todos os backends, exceto o **[Inkeep](#backends)**, que executa a própria recuperação sobre o conteúdo que você indexou no painel dele.

### Tamanho da recuperação

Quanta documentação uma pergunta carrega é a maior alavanca sobre quanto tempo o leitor espera pela primeira palavra: o modelo lê cada caractere injetado antes de emitir um token. Em um modelo de fronteira hospedado isso é invisível, mas em um backend auto-hospedado é o fator dominante. `retrieval` dimensiona isso:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    retrieval: {
      maxResults: 3, // fewer pages retrieved per question
      excerptChars: 1200, // shorter excerpt from each one
      contextBudget: 3000, // smaller total injection
    },
  },
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `maxResults` | `6` | Documentos recuperados por pergunta. |
| `excerptChars` | `2000` | Caracteres mantidos de cada página recuperada. |
| `contextBudget` | `10000` | Total de caracteres injetados, somando os trechos. |

Os três não são intercambiáveis. `contextBudget` limita a injeção inteira, `excerptChars` decide quão fundo o trecho de uma única página longa chega — aumente quando uma página guarda a resposta inteira e o trecho a corta — e `maxResults` limita quantas páginas a recuperação adiciona. A página que o leitor está vendo é injetada além das recuperadas, então uma resposta pode citar até uma página a mais do que `maxResults`.

Os padrões servem bem a um modelo hospedado. Reduza-os quando você estiver servindo a partir do seu próprio hardware e o tempo até o primeiro token importar mais que a abrangência; as respostas continuam fundamentadas nos dois casos, e o assistente é instruído a dizer quando algo não está coberto, em vez de preencher a lacuna.

### Endpoint externo

Já tem um backend de API para IA? Aponte o painel para ele e mantenha o build da documentação estático:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}
```

O Blume envia o mesmo corpo `POST` que a rota integrada:

```json
{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}
```

Retorne uma resposta bem-sucedida cujo corpo seja um stream de texto UTF-8 simples. Se o endpoint estiver em outra origem, libere a origem da documentação com CORS: aceite `OPTIONS` e `POST`, permita o cabeçalho de requisição `content-type` e retorne os cabeçalhos CORS tanto no preflight quanto na resposta em streaming. Com `endpoint` definido, o Blume gera a interface de chat, mas nenhuma rota de servidor, snapshot de fundamentação, dependência de provedor ou aviso de segredo de provedor; o seu backend cuida de recuperação, autenticação, limitação de taxa, acesso ao modelo e citações.

### Saída de servidor obrigatória

O backend integrado do Ask AI no Blume é uma rota de servidor (`POST /api/ask`), então ele não pode rodar em um build estático. Mude para saída de servidor e escolha um adaptador:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

Um build estático com o Ask AI ativado e sem `endpoint` externo falha logo de cara, com uma mensagem dizendo para definir `deployment.output` como `server`. Veja [Deploy](/docs/deployment) para conhecer os adaptadores.

### Backends

Por padrão, o Ask AI é roteado pelo **Vercel AI Gateway**: `model` é uma string `provider/model`, então você troca de modelo alterando essa string (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, e assim por diante) sem nenhum SDK de provedor para instalar. O gateway lê `AI_GATEWAY_API_KEY` do seu ambiente e é configurado automaticamente quando você faz o deploy na Vercel.

Defina `provider` para apontar o Ask AI para outro lugar. Cada backend lê sua chave de API de uma variável de ambiente e faz o streaming por um SDK de provedor que você instala no seu projeto — só o que você usar:

| `provider` | `model` | Variável de ambiente da chave de API | SDK a instalar |
| --- | --- | --- | --- |
| `gateway` (padrão) | uma string `provider/model` via AI Gateway | `AI_GATEWAY_API_KEY` | nenhum — já vem com o Blume |
| `openrouter` | qualquer modelo do [OpenRouter](https://openrouter.ai) | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
| `llmgateway` | qualquer modelo do [LLMGateway](https://llmgateway.io) | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
| `inkeep` | um modelo QA do [Inkeep](https://inkeep.com) | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
| `openai-compatible` | o que quer que o seu endpoint sirva | definida com `apiKeyEnv` | `@ai-sdk/openai-compatible` |

Os SDKs são dependências de par opcionais, então adicione ao seu projeto aquele de que o seu backend precisa (por exemplo, `npm install @openrouter/ai-sdk-provider`). Se ele estiver faltando, o build avisa com o nome exato do pacote antes que o Vite falhasse ao resolver o import.

Por exemplo, para usar o OpenRouter:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openrouter",
    model: "anthropic/claude-sonnet-4-5",
  },
}
```

Qualquer endpoint compatível com OpenAI funciona via `openai-compatible` — informe o `baseUrl` e a variável de ambiente que guarda a chave:

```ts blume.config.ts lineNumbers
ai: {
  ask: {
    enabled: true,
    provider: "openai-compatible",
    baseUrl: "https://my-gateway.example.com/v1",
    apiKeyEnv: "MY_GATEWAY_API_KEY",
    model: "gpt-4o",
  },
}
```

Defina `apiKeyEnv` (e, para os provedores nomeados, `baseUrl`) em qualquer backend para apontar para outra variável de ambiente ou proxy.

:::note
O **Inkeep** responde a partir do conteúdo que você indexou no painel do Inkeep — ele executa a própria recuperação — então o Blume o deixa sem fundamentação. Todos os outros backends são [fundamentados](#grounding) nas páginas deste site.
:::

As chaves são lidas com `process.env`, o que cobre os adaptadores Node, Vercel e Netlify. Na Cloudflare, exponha a chave pelo [binding de runtime](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) da plataforma. Ativar o Ask AI também liga o React para a ilha na página — veja [Personalização](/docs/configuration/customization#interactive-islands).

### Limitação de taxa

O endpoint `POST /api/ask` é **não autenticado** — precisa ser, para que o assistente na página consiga chamá-lo. O Blume valida cada requisição — rejeitando corpos malformados, limitando a 1–40 mensagens e aceitando só os papéis `user`/`assistant`, para que quem chama não consiga injetar o próprio prompt de sistema e transformar a rota em um proxy genérico de LLM — para limitar quanto uma única chamada pode gastar do seu modelo, mas não consegue impedir alguém de chamar o endpoint repetidamente. Se abuso de custos for uma preocupação, coloque a rota atrás de um rate limiter — a limitação de taxa na edge do seu host (por exemplo, a da Vercel), um middleware ou os limites de gasto por chave do seu provedor de modelos.

## Servidor MCP

Hospede um servidor [Model Context Protocol](https://modelcontextprotocol.io) para que agentes de programação (Claude Code, Cursor, VS Code, conectores do claude.ai) possam buscar e ler sua documentação diretamente — sem scraping:

```ts blume.config.ts lineNumbers
ai: {
  mcp: {
    enabled: true,
    route: "/mcp", // where the server is mounted
  },
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `enabled` | `false` | Gerar e hospedar o servidor MCP. |
| `route` | `/mcp` | Caminho onde o endpoint Streamable-HTTP é montado. |
| `name` | título | Nome do servidor mostrado aos clientes (por padrão, o título). |
| `instructions` | — | Dica de sistema opcional passada aos agentes que se conectam. |

O servidor expõe ferramentas somente leitura — `search_docs`, `get_page`, `list_pages` e `get_navigation` — e cada página como um recurso MCP (`resources/list` enumera as páginas nas URLs em que são servidas com o tipo `text/markdown`; `resources/read` retorna o Markdown da página voltado a agentes, a mesma saída de `get_page`), para que clientes que anexam contexto por URI possam navegar pela documentação sem chamar uma ferramenta. Ele publica documentos de descoberta em `/.well-known/mcp.json` e `/.well-known/mcp/server-card.json`. O cartão do servidor segue o esquema da extensão Server Card [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) (`name` em DNS reverso, endpoints de transporte `remotes`), com campos de compatibilidade no formato do initialize (`serverInfo`, `capabilities`, `transports`) para scanners construídos com base na revisão anterior da proposta. O menu **Conectar ao MCP** de cada página oferece instalação de copiar e usar para Claude Code, Cursor, VS Code e Codex (mostrado assim que [`deployment.site`](/docs/deployment) estiver definido).

`search_docs` roda seu próprio índice de texto completo, então funciona independentemente do seu provedor de [busca](/docs/configuration/search) — e mesmo quando a busca está definida como `none`. O servidor MCP é um recurso separado da busca na página.

Tanto `search_docs` quanto `list_pages` aceitam um filtro opcional `contentTypes`, que restringe os resultados a páginas dos [`type`s](/docs/reference/frontmatter) de frontmatter indicados — `["rfc"]`, `["blog", "changelog"]` — para que um agente trabalhando com um site que mistura documentação com RFCs, runbooks ou políticas possa restringir a recuperação ao tipo de página de que precisa. Todo resultado informa seu tipo de conteúdo, e a saída do `list_pages` mostra os tipos em uso.

As duas ferramentas também aceitam um objeto `filters` que casa com as facetas que um site declara por tipo de conteúdo ([`content.types.<type>.facets`](/docs/configuration#frontmatter)) — chaves de frontmatter personalizadas cujos valores viram metadados filtráveis:

```json
{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}
```

Toda entrada de `filters` precisa casar (os resultados carregam seus valores de faceta, e o `list_pages` mostra os de cada página), então uma base de conhecimento pode conduzir fluxos de trabalho de agentes com divulgação progressiva — enumerar os padrões em vigor, buscar só dentro deles — sem nenhum servidor próprio.

### Saída de servidor obrigatória

O servidor MCP é um endpoint ativo (`/mcp`), então ele não pode rodar em um build estático. Mude para saída de servidor e escolha um adaptador:

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "node", // or "vercel" | "netlify" | "cloudflare"
  site: "https://docs.example.com",
}
```

Um build estático com `ai.mcp.enabled` falha logo de cara, com uma mensagem dizendo para definir `deployment.output` como `server`. Veja [Deploy](/docs/deployment) para conhecer os adaptadores. Depois do deploy, conecte a partir do Claude Code com:

```bash
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

## API JSON

Todo site Blume também serve sua documentação como uma pequena **API JSON** somente leitura — a irmã REST das ferramentas do [servidor MCP](#mcp-server), sobre o mesmo snapshot de páginas, para agentes e frameworks de function calling que falam HTTP simples em vez de MCP. Vem ativada por padrão e não precisa de configuração:

| Endpoint | Retorna |
| --- | --- |
| `/api/docs/pages.json` | Todas as páginas com sua rota, título, descrição, tipo de conteúdo, idioma, facetas e as URLs das suas formas renderizada, Markdown e JSON. |
| `/api/docs/pages/{route}.json` | Uma página: sua entrada de índice mais o Markdown voltado a agentes (o mesmo corpo que `get_page` retorna). `{route}` é a rota da página sem a barra inicial, `index` para a inicial. |
| `/api/docs/navigation.json` | A árvore de navegação — abas do cabeçalho e a hierarquia da barra lateral. |
| `/api/docs/search?q=` | Busca de texto completo, com a mesma restrição por `limit`, `contentTypes`, `locale`, `version` e `filters[key]` do `search_docs`. Só com saída de servidor. |
| `/openapi.json` | A descrição OpenAPI 3.1 de toda a superfície legível por máquinas. |

O índice de páginas, os documentos por página e a navegação são pré-renderizados, então um site estático os serve como arquivos a partir de qualquer host. A busca é um endpoint ativo e existe apenas com [saída de servidor](/docs/deployment#server-rendering), onde ela roda o mesmo índice que o `search_docs`. Os erros são problem details da [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (`application/problem+json`) com um `code` estável, um `detail` e uma dica de `resolution` dizendo ao agente para onde ir em seguida — uma página inexistente, uma consulta de busca vazia ou, com saída de servidor, qualquer URL `/api/…` que nenhum endpoint responda:

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

O **documento OpenAPI** em `/openapi.json` é gerado a cada build a partir da sua configuração, então descreve só o que o site publicado serve: cada endpoint JSON com um `operationId` único, parâmetros tipados e esquemas de resposta, mais as superfícies de texto ao lado — os [espelhos `.md`](#raw-markdown), o [`llms.txt`](#llmstxt) e o `llms-full.txt`, o [`agent-readability.json`](#agent-readability) — e o [endpoint MCP](#mcp-server) quando ele está ativado. Frameworks que constroem ferramentas a partir de uma descrição OpenAPI ganham o mesmo alcance que um cliente MCP tem. O documento é referenciado pelo [catálogo de API](#api-catalog), pelo [manifesto de legibilidade](#agent-readability), pelo cabeçalho `Link` da página inicial como `rel="service-desc"` e pelo `llms.txt`.

Nada disso mexe na sua própria [referência de API](/docs/advanced/api-reference): uma especificação documentada é renderizada em páginas, nunca servida em `/openapi.json`, e o catálogo lista as duas. Um `public/openapi.json` publicado por você assume essa rota (os endpoints JSON continuam). O catch-all de `/api/…` sai do caminho quando uma seção da documentação é servida a partir do namespace `/api` (`content/api/overview.md`) ou quando uma página personalizada é dona de uma rota rest sob `/api/`, então essas páginas continuam vencendo. Defina `ai.api` como `false` para não publicar nada disso:

```ts blume.config.ts lineNumbers
ai: {
  api: false,
}
```

## Legibilidade para agentes

O Blume escreve um manifesto **`/agent-readability.json`** na raiz do seu site que indexa a superfície voltada a agentes descrita nesta página — para que um agente possa descobri-la em uma única requisição, em vez de adivinhar convenções ou raspar o HTML. Assim como o `llms.txt`, vem ativado por padrão:

```ts blume.config.ts lineNumbers
seo: {
  agentReadability: true,
}
```

O manifesto lista só o que você ativou — o padrão de espelho de [Markdown bruto](#raw-markdown), a [API JSON](#json-api) e sua descrição OpenAPI, o [`llms.txt`](#llmstxt) e o `llms-full.txt`, o [servidor MCP](#mcp-server) e seu documento de descoberta, o endpoint do [Ask AI](#ask-ai), o [sitemap](/docs/configuration/seo#sitemap) e os [feeds RSS](/docs/configuration/seo#rss-feeds) — junto com o nome do seu site, a descrição, o repositório de origem e a política de uso de [content-signal](/docs/configuration/seo#content-signals). As URLs são absolutas quando [`deployment.site`](/docs/deployment) está definido e relativas à raiz caso contrário:

```json agent-readability.json
{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "https://docs.example.com/{route}.md"
    },
    "api": {
      "openapi": "https://docs.example.com/openapi.json",
      "pages": "https://docs.example.com/api/docs/pages.json",
      "search": "https://docs.example.com/api/docs/search"
    },
    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
    "llmsTxt": "https://docs.example.com/llms.txt",
    "mcp": {
      "discovery": "https://docs.example.com/.well-known/mcp.json",
      "url": "https://docs.example.com/mcp"
    }
  },
  "description": "Docs for the Acme API.",
  "generator": "blume@1.0.0",
  "name": "Acme Docs",
  "site": "https://docs.example.com",
  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
  "repository": "https://github.com/acme/docs"
}
```

O campo `contentNegotiation` aparece só quando o site em produção realmente respeita o cabeçalho `Accept: text/markdown` — veja [negociação de conteúdo](#content-negotiation); em todos os outros deploys, o manifesto anuncia apenas o padrão de espelho `.md`.

Defina `seo.agentReadability` como `false` para pulá-lo, ou publique seu próprio `public/agent-readability.json` para assumir o controle — o Blume nunca sobrescreve um arquivo que você coloca em `public/`.

### Cabeçalho Link de descoberta

Agentes que sondam um site não sabem que devem procurar o manifesto — por isso o Blume também o anuncia em um cabeçalho de resposta `Link` conforme a [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) na página inicial, usando tipos de relação registrados na IANA:

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
  </openapi.json>; rel="service-desc"; type="application/json",
  </agent-readability.json>; rel="describedby"; type="application/json",
  </llms.txt>; rel="describedby"; type="text/plain",
  </index.md>; rel="alternate"; type="text/markdown"
```

Cada entrada aparece só quando o respectivo recurso está ativo. O link `alternate` aponta para o espelho Markdown da página inicial — o [Markdown bruto](#raw-markdown) da própria página quando a rota inicial é uma página de conteúdo, ou o fallback do `llms.txt` sintetizado quando é uma landing page. O link `service-desc` ([RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)) aponta para a descrição OpenAPI da [API JSON](#json-api), e o `api-catalog` para o [catálogo de API gerado](#api-catalog). O cabeçalho vai em todas as superfícies que o Blume controla: o servidor de desenvolvimento (confira com `curl -I localhost:4321`), os builds estáticos via arquivo `_headers` emitido (Netlify e Cloudflare) e os builds de servidor na Vercel via regras de roteamento do deploy.

Mas nem todo agente entra pela raiz — um que segue um resultado de busca ou um link compartilhado cai em uma página profunda e nunca vê o cabeçalho da página inicial. Por isso toda página renderizada também carrega os mesmos links de descoberta no `<head>` do seu HTML, usando as mesmas relações registradas na IANA:

```html
<link
  rel="describedby"
  href="/agent-readability.json"
  type="application/json"
/>
<link rel="describedby" href="/llms.txt" type="text/plain" />
<link rel="alternate" href="/docs/example.md" type="text/markdown" />
```

Aqui o link `alternate` aponta para o [espelho Markdown bruto](#raw-markdown) _daquela própria página_, então um agente consegue pular direto do HTML em que caiu para a versão eficiente em tokens. Como os links no head viajam junto com o HTML pré-renderizado, eles também funcionam em hosts que ignoram `_headers` e não conseguem enviar cabeçalhos de resposta personalizados de jeito nenhum (GitHub Pages, S3) — não importa por qual página o agente entre.

### Catálogo de API

Quando o site publica APIs, o Blume gera um catálogo de API conforme a [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) em `/.well-known/api-catalog` — um [linkset](https://www.rfc-editor.org/rfc/rfc9264) que permite aos agentes enumerar suas APIs só a partir do domínio, servido com seu media type registrado `application/linkset+json` em todas as superfícies de build. Não há nada para configurar: o catálogo é derivado do que já está no `blume.config.ts`. Cada [referência OpenAPI ou AsyncAPI](/docs/advanced/api-reference) vira uma entrada ancorada na sua rota de documentação renderizada, com `service-doc` apontando para essa documentação e `service-desc` para a especificação quando ela mora em uma URL acessível; a própria [API JSON](#json-api) do site vira uma entrada descrita pelo seu `/openapi.json`; e o [servidor MCP](#mcp-server) vira uma entrada com seu documento de descoberta como descrição do serviço:

```json .well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://docs.example.com/reference",
      "service-doc": [
        { "href": "https://docs.example.com/reference", "type": "text/html" }
      ],
      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
    },
    {
      "anchor": "https://docs.example.com/api/docs",
      "service-desc": [
        {
          "href": "https://docs.example.com/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://docs.example.com/mcp",
      "service-desc": [
        {
          "href": "https://docs.example.com/.well-known/mcp.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    }
  ]
}
```

Um site sem referências de API, sem servidor MCP e com a [API JSON](#json-api) desativada não emite catálogo nenhum — não haveria nada nele. Como em todo lugar, um arquivo `public/.well-known/api-catalog` publicado por você vence o gerado.

### WebMCP

O [WebMCP](https://webmachinelearning.github.io/webmcp/) é uma API de navegador emergente que permite a uma página registrar ferramentas diretamente em um navegador agêntico — sem precisar de uma conexão com um servidor separado. Toda página do Blume registra a superfície somente leitura da documentação no model context da página: `search_docs` (busca do site), `get_page` (o [Markdown bruto](#raw-markdown) de uma página) e `list_pages` (o índice [`llms.txt`](#llmstxt)). O script é minúsculo, não carrega nenhuma maquinaria de busca até uma ferramenta ser de fato chamada e vira um no-op silencioso em todo navegador sem a API — o que hoje são todos, fora a [prévia inicial do Chrome](https://developer.chrome.com/blog/webmcp-epp). Ele se registra na superfície que a spec em evolução expuser (`navigator.modelContext` ou `document.modelContext`), via `provideContext` ou `registerTool` por ferramenta.

Vem ativado por padrão; defina `webmcp: false` para desativar:

```ts blume.config.ts lineNumbers
ai: {
  webmcp: false,
}
```

### Descoberta de skills

Se o seu projeto inclui [agent skills](https://agentskills.io) — o [próprio repositório do Blume inclui](#agent-skill) — aponte `ai.skills` para o diretório que as contém, e o build as publica para descoberta conforme a [RFC de Agent Skills Discovery](https://github.com/cloudflare/agent-skills-discovery-rfc):

```ts blume.config.ts lineNumbers
ai: {
  skills: "./skills",
}
```

O caminho é resolvido em relação à raiz do seu projeto, e cada subdiretório com um `SKILL.md` vira uma skill publicada. Uma skill que é só um `SKILL.md` sozinho é copiada como está para `/.well-known/agent-skills/<name>/SKILL.md` (`type: "skill-md"`); uma skill com recursos de apoio (`scripts/`, `references/`, `assets/`) é empacotada em um `.tar.gz` determinístico (`type: "archive"`) para que suas referências relativas resolvam depois da extração, com os bits de execução dos scripts preservados. O índice de descoberta em `/.well-known/agent-skills/index.json` carrega o `$schema` v0.2.0 e, por skill, o nome, o tipo, a descrição (do frontmatter do `SKILL.md`), a URL do artefato e o digest SHA-256 que os clientes usam para verificar os downloads.

Skills com `name`/`description` ausente ou inválido perante a spec são puladas com um aviso de build, em vez de publicadas quebradas, e um `public/.well-known/agent-skills/index.json` publicado por você assume o controle de toda a superfície.

### Descoberta baseada em DNS (DNS-AID)

O [DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) é um rascunho emergente do IETF que permite aos agentes descobrir a superfície de IA de um site antes de fazer uma única requisição HTTP, consultando registros [SVCB/HTTPS](https://www.rfc-editor.org/rfc/rfc9460) em ServiceMode em um ponto de entrada DNS bem conhecido. Os registros DNS moram na sua zona, não no build, então essa é a única superfície de descoberta que o Blume não pode publicar por você — em vez disso, adicione um registro no seu provedor de DNS:

```txt
_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
```

Use o tipo de registro `HTTPS` se o seu provedor oferecer (o Vercel DNS oferece; ele não suporta o tipo `SVCB` puro), ou, caso contrário, um registro `SVCB` em ServiceMode com os parâmetros `alpn` e `port`. O rascunho também recomenda assinar a zona com DNSSEC para que resolvedores validadores retornem respostas autenticadas — provedores como a Cloudflare ativam isso com um clique, enquanto alguns (incluindo o Vercel DNS) não suportam de jeito nenhum.

`blume audit --url <origin>` verifica isso por você: quando [`deployment.site`](/docs/deployment) está definido, a camada de rede consulta o ponto de entrada por DNS-over-HTTPS e informa o registro exato a publicar se não existir nenhum, além de dizer se as respostas são autenticadas por DNSSEC. Defina `BLUME_DOH_URL` para apontar a consulta para o seu próprio resolvedor se a sua rede bloquear os públicos (Google, Cloudflare).

### Web Bot Auth

O [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) funciona na direção contrária: não se trata de agentes lendo sua documentação, mas de **os agentes da sua organização se identificarem** quando fazem requisições em outros lugares. Seus agentes assinam as requisições com [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421), e os sites que as recebem as verificam contra um diretório de chaves públicas publicado no seu domínio. Se a sua organização roda agentes e o seu site Blume mora no domínio com que eles se identificam, publique as chaves públicas deles:

```ts blume.config.ts lineNumbers
ai: {
  webBotAuth: {
    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
  },
}
```

O Blume passa então a servir o JWKS em `/.well-known/http-message-signatures-directory` com seu media type registrado em todas as superfícies de build. O diretório é público por definição, então a configuração só admite chaves públicas — um JWK que contenha material privado (`d`, `p`, `q`, …) falha na validação com um erro, em vez de publicar uma credencial vazada. Gere um par Ed25519 com:

```bash
node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
```

O JWK público vai na configuração acima; o privado vai para onde quer que o seu agente de assinatura rode (um gerenciador de segredos, nunca o repositório). Se a sua organização não opera agentes, pule isso — um diretório vazio não anuncia nada que valha a pena verificar.

Como o `blume.config.ts` é executado em tempo de build, a chave não precisa estar no código — carregue-a de uma variável de ambiente em tempo de build para manter a configuração livre de blobs de chave e rotacioná-la sem commit:

```ts blume.config.ts lineNumbers
const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;

export default defineConfig({
  ai: {
    webBotAuth: {
      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
    },
  },
});
```

Ambientes sem a variável não publicam diretório nenhum, e uma chave carregada assim é validada exatamente como uma inline — incluindo a checagem de material privado. (A chave pública não é um segredo, então commitá-la inline é igualmente válido; a variável de ambiente é uma escolha ergonômica, não de segurança.)

## Agent skill

Está construindo um site Blume com a ajuda de um agente de programação? Instale a [agent skill](https://docs.claude.com/en/docs/claude-code/skills) do Blume para que ele saiba como o Blume funciona sem você precisar explicar:

```bash
npx skills add haydenbleasel/blume
```

A skill ensina ao agente o que é o Blume e como criar, escrever e configurar um site, e o aponta para a documentação completa incluída no pacote instalado (o diretório `docs/` dentro de `blume`, onde quer que o seu gerenciador de pacotes o instale).

É uma das [agent skills que o Blume traz](/docs/advanced/skills), junto com uma skill para manter a documentação em sincronia com o seu produto a partir de uma execução agendada de um agente.

---

# Analytics
Source: https://useblume.dev/pt/docs/configuration/analytics

O Blume injeta as análises por si a partir de um único bloco `analytics` no `blume.config.ts`. O Vercel Web Analytics e o PostHog são suportados de forma nativa, e uma válvula de escape `scripts` cobre todos os outros fornecedores — Plausible, Fathom, Google Analytics, Umami e os restantes.

As análises são carregadas **apenas em builds de produção**. Os scripts são emitidos pelo `blume build`, nunca pelo `blume dev`, por isso o tráfego local nunca chega aos seus painéis e não precisa de um projeto de "desenvolvimento" separado.

:::note
As análises são opcionais. Sem um bloco `analytics`, o Blume não injeta nada.
:::

## Vercel Web Analytics

Defina `vercel: true` para adicionar o [Vercel Web Analytics](https://vercel.com/docs/analytics). O Blume injeta o script nativo da Vercel, que é servido a partir do seu próprio domínio assim que o Web Analytics estiver ativado para o projeto no painel da Vercel.

```ts blume.config.ts lineNumbers
analytics: {
  vercel: true,
}
```

Não são necessárias chaves — o script reporta para o projeto sob o qual está implementado. Isto só recolhe dados em implementações na Vercel, onde existe o endpoint `/_vercel/insights`.

## PostHog

Forneça a sua **chave de API do projeto** para adicionar o [PostHog](https://posthog.com). O host assume por predefinição o PostHog Cloud US; defina `host` para o EU Cloud (`https://eu.i.posthog.com`) ou para uma instância auto-alojada.

```ts blume.config.ts lineNumbers
analytics: {
  posthog: {
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // optional, this is the default
  },
}
```

A chave de API do projeto pode ser enviada para o browser em segurança — é uma chave pública, apenas de escrita.

## Scripts personalizados

Use `scripts` para carregar qualquer outro fornecedor de análises. Cada entrada gera uma etiqueta `<script>` e tem de definir **exatamente um** de `src` (externo) ou `content` (inline).

```ts blume.config.ts lineNumbers
analytics: {
  scripts: [
    // Plausible
    {
      src: "https://plausible.io/js/script.js",
      strategy: "defer",
      attributes: { "data-domain": "example.com" },
    },
    // Fathom
    {
      src: "https://cdn.usefathom.com/script.js",
      strategy: "defer",
      attributes: { "data-site": "ABCDEFG" },
    },
    // An inline snippet
    {
      content: "console.log('analytics ready')",
    },
  ],
}
```

`attributes` é um mapa de atributos HTML adicionais (`data-*`, `id`, …) aplicados à etiqueta, e `strategy` adiciona `async` ou `defer` a scripts externos.

## Opções

| Opção | Predefinição | Descrição |
| --- | --- | --- |
| `vercel` | `false` | Adiciona o Vercel Web Analytics (apenas em implementações na Vercel). |
| `posthog.key` | — | Chave de API do projeto PostHog. Ativa o PostHog quando definida. |
| `posthog.host` | `https://us.i.posthog.com` | Host de ingestão do PostHog (EU Cloud ou auto-alojado). |
| `scripts[].src` | — | URL do script externo. Mutuamente exclusivo com `content`. |
| `scripts[].content` | — | Corpo do script inline. Mutuamente exclusivo com `src`. |
| `scripts[].strategy` | — | `async` ou `defer` para um script externo. |
| `scripts[].attributes` | — | Atributos HTML adicionais aplicados à etiqueta `<script>`. |

Os três podem ser combinados — ative a Vercel, o PostHog e scripts personalizados em conjunto. Para implementar o seu site já construído, consulte [Implementação](/docs/deployment).

---

# Personalização
Source: https://useblume.dev/pt/docs/configuration/customization

## Substituições de componentes

Adicione um `components.ts` (ou `components.tsx`) à raiz do seu projeto e exporte `defineComponents`. O mapa `mdx` **substitui** um componente integrado ou **adiciona** um novo — disponível em todas as páginas `.mdx` sem nenhum import.

```ts components.ts lineNumbers
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";
import Pricing from "./components/Pricing.astro";

export default defineComponents({
  mdx: {
    Callout, // replace the built-in Callout
    Pricing, // add a new <Pricing /> component
  },
});
```

As chaves são os nomes que você escreve no MDX (`<Callout>`, `<Pricing>`). Use o nome de arquivo `.tsx` quando importar componentes React.

### Forma de referência

Toda substituição — em `mdx`, `layout` ou `islands` — aceita três formas:

```ts components.ts
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";

export default defineComponents({
  mdx: {
    Callout, // 1. an imported component
    Note: "./components/Note.astro", // 2. a path string (resolved from the project root)
    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. a descriptor
  },
});
```

A forma de **descritor** adiciona um modo de hidratação para que um componente interativo React/Vue/Svelte envie seu JavaScript e ganhe vida no cliente. Sem um modo `client`, um componente de framework é renderizado como HTML estático — o Blume exibe um aviso de build quando detecta um desses, já que isso costuma ser um engano.

| `client` | Hidrata |
| --- | --- |
| `"load"` | Imediatamente ao carregar a página |
| `"idle"` | Quando a thread principal estiver ociosa |
| `"visible"` | Quando entrar na área visível ao rolar |
| `"media"` | Quando uma consulta `media` corresponder (adicione `media: "(min-width: 40rem)"`) |
| `"only"` | Apenas no cliente, nunca renderizado no servidor |

Para componentes interativos que você usa em muitas páginas, o [grupo `islands`](/docs/content/islands#registering-islands-in-componentsts) é um atalho para a forma de descritor com `client: "visible"`.

### Tipando uma substituição

Ao substituir um componente integrado, importe o tipo das suas props de `blume/components` para que seu componente respeite o contrato — os tipos derivam dos próprios componentes, então nunca ficam defasados:

```tsx components/Callout.tsx
import type { CalloutProps } from "blume/components";

export default function Callout(props: CalloutProps) {
  // …your own callout, same props as the built-in
}
```

Os tipos de props são exportados para os componentes de conteúdo (`CalloutProps`, `CardProps`, `TabsProps`, `StepsProps`, `BadgeProps` e outros).

## Slots de layout

O mapa `layout` substitui uma parte da estrutura visual do Blume pelo seu próprio componente. Cada substituição recebe as mesmas props do componente integrado que ela substitui, então você pode envolver o padrão ou começar do zero.

```ts components.ts
import { defineComponents } from "blume";
import Footer from "./components/Footer.astro";
import Logo from "./components/Logo.astro";

export default defineComponents({
  layout: {
    Logo, // brand mark + title in the header
    Footer, // site-wide footer (no built-in — renders only when set)
  },
});
```

Slots conectados:

| Slot | Substitui | Props |
| --- | --- | --- |
| `Layout` | Toda a estrutura da página (`RootLayout`) | Tudo o que o layout integrado recebe, mais o mapa `layout` |
| `Header` | A barra de navegação superior | `site`, `logo`, `navigation`, `route`, `searchEnabled`, … |
| `Logo` | O link da marca (símbolo + título) no cabeçalho | `site`, `logo` |
| `Search` | O gatilho de busca do cabeçalho + modal | `navigation`, `strings`, `locale`, `askEnabled` |
| `Sidebar` | A árvore de navegação principal | `items`, `currentRoute` |
| `MobileNav` | A navegação dentro da gaveta mobile (usa `Sidebar` por padrão) | `items`, `currentRoute` |
| `Breadcrumbs` | A trilha de navegação | `crumbs` |
| `TableOfContents` | O sumário desta página | `headings`, `title`, `variant` |
| `Pagination` | Os links de anterior/próximo no rodapé | `prev`, `next`, `strings` |
| `PageHeader` | Um ponto de injeção acima do artigo (sem componente integrado) | `page`, `headings`, `route` |
| `PageFooter` | Um ponto de injeção abaixo do artigo (sem componente integrado) | `page`, `headings`, `route` |
| `Footer` | Um rodapé para todo o site após a grade de conteúdo (sem componente integrado) | `site`, `navigation`, `ui` |

`PageHeader`, `PageFooter` e `Footer` não têm componente integrado — eles não renderizam nada até você defini-los, o que os torna pontos de injeção convenientes para um banner promocional, uma nota de "última atualização" ou um rodapé de marketing.

Os slots de layout aceitam as mesmas [três formas de referência](#reference-form) das substituições MDX, então um slot pode ser uma string de caminho ou um descritor hidratado (`{ component, client }`) quando você quiser um cabeçalho ou rodapé interativo.

## Ilhas interativas

Para UI interativa (React, Vue ou Svelte), coloque um componente em uma pasta `islands/` e use-o em qualquer página MDX — o Blume o hidrata para você, sem necessidade de wrapper ou registro:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}
```

```mdx page.mdx
Use it anywhere: <Counter />
```

Veja [Ilhas](/docs/content/islands) para estratégias de hidratação e configuração de frameworks.

## Páginas personalizadas

Adicione arquivos `.astro` dentro da sua pasta `pages/` para montar rotas totalmente personalizadas ao lado da sua documentação — uma landing page, uma página de preços ou um índice feito à mão. Elas mantêm sua localização, então imports relativos e `getStaticPaths` funcionam normalmente, e podem ler sua configuração, navegação e rotas a partir do módulo `blume:data`.

Veja [Páginas Personalizadas](/docs/advanced/custom-pages) para o guia completo.

## Registro

O `blume add` copia um componente mantido pelo Blume para o seu projeto como **código-fonte** — ele é seu e você pode editá-lo livremente. Execute-o sem argumentos para listar o que está disponível:

```bash
blume add
```

Instale um slot de layout (cabeçalho, barra lateral, trilha de navegação, sumário, paginação ou feedback) ou qualquer componente de conteúdo (callout, card, abas, passos, acordeão e outros):

```bash
blume add callout
blume add pagination
```

A cópia importa o restante do framework de `blume/*`, então ela renderiza exatamente como a versão integrada até você alterá-la. O `blume add` exibe o trecho de `defineComponents` para registrá-la — componentes de conteúdo em `mdx`, peças de layout em `layout`.

## Integrações do Astro

Adicione qualquer integração do Astro a partir do array `integrations` de nível superior em `blume.config.ts`. Instale a integração no seu site primeiro; o Blume não a adiciona às dependências do runtime gerado nem gerencia sua compatibilidade com o Astro.

```bash
npm install @astrojs/sitemap
```

```ts blume.config.ts lineNumbers
import sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

export default defineConfig({
  integrations: [
    sitemap({
      filter: (page) => !page.includes("/drafts/"),
    }),
  ],
});
```

O Blume mantém suas integrações internas na ordem existente e, em seguida, acrescenta as suas na ordem de declaração. Ele não as ordena nem remove duplicatas, então duas integrações com o mesmo `name` são ambas executadas. O Blume valida que `integrations` é um array, enquanto o Astro valida cada entrada e reporta integrações inválidas.

Como o Blume carrega suas integrações reimportando `blume.config.ts` a partir da configuração gerada do Astro, em vez de copiar as instâncias, o módulo de configuração é avaliado duas vezes por execução — uma quando o Blume lê sua configuração e outra quando o Astro a carrega. Mantenha as fábricas de integração livres de efeitos colaterais (retorne a integração; não escreva arquivos nem abra conexões na construção) para que a segunda avaliação seja inofensiva.

As mesmas integrações são executadas no `blume dev` e no `blume build`. Editar `blume.config.ts` durante o `blume dev` regenera a configuração oculta do Astro e dispara um reinício de configuração; se você não vir uma integração editada surtir efeito, reinicie o `blume dev`. O Blume não consegue determinar quais edições de configuração afetam integrações, então, quando `integrations` não estiver vazio, toda edição em `blume.config.ts` — mesmo em um campo não relacionado — reinicia o servidor de desenvolvimento em vez de aplicar a alteração a quente. O Blume só acompanha o conteúdo de `blume.config.ts`, então editar um arquivo separado que ele importa não dispara essa regeneração por si só — reinicie o `blume dev` após tais edições. Se você fizer eject, o `astro.config.mjs` sob sua responsabilidade mantém uma ponte relativa para o `blume.config.ts`, então as integrações configuradas continuam funcionando; mais tarde, você pode movê-las diretamente para a configuração do Astro como parte de assumir a propriedade total.

## Eject

Quando quiser controle total, faça o eject do runtime gerado para um projeto Astro independente:

```bash
blume eject --yes
```

O eject é um passo sem volta: o runtime oculto `.blume/` se torna um aplicativo Astro normal que é seu e que você pode modificar diretamente. O pacote `blume` continua importável, então você mantém seus componentes, tema e processadores de Markdown.

### O que o eject deixa para trás

Depois do eject, seu script `build` executa um `astro build` puro — o site em si é compilado da mesma forma, mas os artefatos que o `blume build` adicionava por cima não são mais produzidos. O comando de eject avisa sobre aqueles que sua configuração de fato utiliza. Para mantê-los:

- **Índice de busca do Pagefind** — com `search.provider: "pagefind"`, a interface de busca carrega o índice a partir do site compilado, então a busca deixa de funcionar em produção até que você mesmo gere o índice. Instale o `pagefind` como devDependency e indexe após cada build: `"build": "astro build && pagefind --site dist"`.
- **Sincronização de busca hospedada** — o índice de um provedor hospedado deixa de ser enviado no build; reenvie seus registros de busca após cada build com a API ou CLI do provedor.
- **sitemap.xml** — recrie-o com a integração padrão [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/).
- **robots.txt** — forneça o seu próprio como `public/robots.txt`.
- **llms.txt / llms-full.txt e agent-readability.json** — escreva-os à mão (ou gere-os em uma etapa de build própria) e sirva-os a partir de `public/`.
- **Arquivos de redirecionamento de plataforma** — `_redirects` e `vercel.json` não são mais emitidos para builds estáticos. Seus redirecionamentos continuam funcionando como páginas de meta-refresh geradas pelo Astro, ou você pode movê-los para a configuração do seu próprio provedor de hospedagem.

---

# Exportar
Source: https://useblume.dev/pt/docs/configuration/export

O Blume pode adicionar uma ação de **Exportar** às [ações de página](/docs/content/navigation#page-actions) abaixo do sumário, permitindo que os leitores salvem a página em que estão como **PDF** ou **EPUB**. Ela vem desativada por padrão e é totalmente do lado do cliente — sem servidor, e as builds [estáticas](/docs/deployment) continuam estáticas.

## Ativar

Ative os dois formatos com uma única opção:

```ts blume.config.ts
export: true,
```

Para oferecer apenas um formato, passe um objeto:

```ts blume.config.ts
export: {
  pdf: true,
  epub: false,
},
```

Qualquer formato que você omitir (ou definir como `false`) fica de fora do menu. Com ambos desativados — o padrão — a ação **Exportar** não aparece de forma alguma.

## PDF

**Exportar para PDF** abre a caixa de diálogo de impressão do navegador com uma folha de estilo de impressão que remove os elementos da interface do site — cabeçalho, barras laterais, navegação — deixando apenas o artigo. Escolha **Salvar como PDF** para concluir.

Como imprime a página ao vivo e totalmente estilizada, o resultado mantém o texto nítido e selecionável, fontes reais e código com realce de sintaxe. Não requer dependências e funciona da mesma forma em desenvolvimento, em produção e em hospedagens estáticas.

:::note
A exportação para PDF passa pela caixa de diálogo de impressão nativa do navegador, portanto o texto exato de "Salvar como PDF" e as opções dependem do navegador. Ative **Gráficos de plano de fundo** na caixa de diálogo para manter os fundos dos blocos de código e dos destaques.
:::

## EPUB

**Exportar para EPUB** gera um `.epub` autocontido da página atual no navegador e o baixa — pronto para o Apple Books, o Calibre ou qualquer leitor de e-books. O gerador só é carregado quando um leitor clica em Exportar, então ele nunca pesa no restante do seu site.

Para manter o arquivo legível em um dispositivo sem folha de estilo ou JavaScript próprios, o Blume reescreve a página em HTML limpo e independente: o código com realce de sintaxe vira monoespaçado simples, ícones decorativos e botões de copiar são removidos, e uma folha de estilo integrada para leitores de e-books cuida do espaçamento, dos blocos de código e das tabelas.

## O que é exportado

Ambos os formatos exportam a **única página** que o leitor está visualizando — não o site inteiro — o que condiz com o lugar onde a ação fica, abaixo do sumário daquela página.

:::note
Em um EPUB não há JavaScript para alternar abas, então o conteúdo em abas — como os blocos [package-install](/docs/content/syntax) e os grupos de código — é expandido para mostrar todos os painéis de uma vez. Embeds renderizados no cliente, como diagramas Mermaid, não são incluídos.
:::

---

# Busca
Source: https://useblume.dev/pt/docs/configuration/search

O Blume inclui busca local sem infraestrutura hospedada e sem chaves de API. Ela roda no navegador, funciona tanto em `blume dev` quanto em `blume build` e indexa apenas o seu conteúdo real — elementos de navegação e páginas excluídas são ignorados. Quando ela deixar de ser suficiente, você pode migrar para um backend hospedado ou semântico sem mudar a aparência ou o comportamento da busca — só muda o `search.provider` que você configura.

O Blume alcança paridade com o conjunto de provedores do Fumadocs: **Orama**, **FlexSearch**, **Algolia**, **Orama Cloud**, **Typesense** e **Mixedbread** (além do **Pagefind**). Somente o SDK do provedor configurado é instalado no seu projeto, então escolher um backend nunca traz os outros junto.

## Usando a busca

Abra a busca com <Badge variant="accent">⌘K</Badge> (ou `Ctrl K`), ou pressione `/` quando não estiver digitando em um campo. `Esc` a fecha, e `⌘J` (ou `Ctrl J`) alterna o painel de pré-visualização de resultados.

As consultas correspondem a **títulos**, **descrições** e **texto do corpo** das páginas, com as correspondências de título classificadas em primeiro lugar e as descrições acima do corpo.

## Páginas populares

Antes de o leitor digitar uma consulta, o diálogo de busca exibe uma lista **Popular**. Por padrão, são as seis primeiras páginas da barra lateral — o que, em sites com várias abas, muitas vezes destaca a seção errada. Em vez disso, fixe os links que você quiser:

```ts blume.config.ts lineNumbers
search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},
```

Cada entrada recebe um `href` (rota interna ou URL externa) e um `label`, além de um `icon` opcional — o nome de um [ícone integrado](/docs/content/components#icon), um caminho ou URL de imagem, ou um SVG inline (as mesmas _entradas_ dos ícones de navegação), com um glifo de arquivo como padrão. Omita `popular` ou deixe a lista vazia para manter o comportamento padrão baseado na barra lateral.

Escreva o `href` como se o site estivesse montado na raiz — um `basePath` é aplicado automaticamente, igual em `navigation.featured`. URLs externas passam sem alteração.

> **Warning**
>
> Uma lista curada é um único conjunto de links compartilhado por todos os
> idiomas. Em um site com `i18n` configurado, o comportamento padrão da barra
> lateral segue o idioma do leitor, mas as entradas de `popular` apontam para
> onde o `href` indicar — então fixe rotas com prefixo de idioma apenas se
> quiser que todos os leitores sejam levados àquele idioma.

## O que é indexado

Para Orama, FlexSearch, Algolia, Orama Cloud e Typesense — e para a ferramenta `search_docs` do servidor MCP —, o Blume indexa o título, a descrição e o corpo de cada página reduzido a texto simples: blocos de código, imagens e marcação são removidos, para que os resultados permaneçam relevantes. Esses índices são construídos a partir dos seus arquivos-fonte, então são idênticos em desenvolvimento e em produção. Já o Pagefind indexa o HTML compilado, e o Mixedbread sincroniza seu Markdown bruto, então ambos sempre buscam no código.

Se a sua documentação depende de exemplos de código para termos pesquisáveis como opções, métodos ou nomes de erros, ative os blocos de código cercados nos índices construídos a partir da fonte:

```ts blume.config.ts lineNumbers
search: {
  indexing: {
    includeCodeBlocks: true,
  },
},
```

O corpo e o título de cada bloco cercado (`blume.config.ts`, acima) se tornam pesquisáveis; a linguagem e os marcadores do bloco, não. Em páginas `.mdx`, o índice lê os componentes como o texto que eles exibem — o título de um Card, o rótulo de uma Tab, as descrições de uma TypeTable — usando os mesmos serializadores das [superfícies de agente](/docs/configuration/ai), então uma entrada em `ai.markdownComponents` cobre também os seus próprios componentes. A opção não tem efeito no Pagefind nem no Mixedbread. Espere que o índice cresça junto com o conteúdo cercado — o índice do cliente é enviado a todos os leitores, os provedores hospedados limitam o tamanho do registro (o Algolia rejeita o lote de sincronização quando o registro de uma página excede o limite do seu plano, mantendo o índice anterior no ar) e uma correspondência dentro de um bloco cercado exibe o código achatado no trecho do resultado.

Em um site com [versionamento](/docs/content/versioning), os resultados ficam restritos por padrão à versão que está sendo visualizada, com um botão "Todas as versões" no rodapé do diálogo (memorizado por leitor). As correspondências de outras versões indicam sua versão na linha. Orama, FlexSearch, Algolia e Typesense respeitam esse escopo — os registros hospedados carregam uma faceta `version`, com a documentação atual enviada como `"current"` — enquanto o Pagefind permanece sem escopo, seguindo o mesmo comportamento que tem com idiomas.

## Tags

Adicione `search.tags` ao frontmatter de uma página para agrupá-la sob um filtro no diálogo de busca — os leitores podem restringir os resultados a uma tag com um clique. As tags também se tornam uma faceta nos provedores hospedados.

```yaml
search:
  tags: [api, reference]
```

## Provedores

Os provedores do lado do cliente dispensam chaves e não precisam de configuração extra. Os hospedados recebem credenciais **públicas** em `blume.config.ts` (seguras para enviar ao navegador) e leem sua chave de administração **secreta** de uma variável de ambiente no momento do build — o segredo nunca chega à configuração nem ao bundle do cliente.

### Orama (padrão)

O mecanismo padrão do Blume. Ele constrói um índice JSON servido em `/blume-search.json` e o consulta no navegador — instantâneo, do lado do cliente e ativo em `blume dev` enquanto você edita. Sem chaves, sem serviço.

```ts blume.config.ts lineNumbers
search: {
  provider: "orama", // default
}
```

#### Escritas não latinas

O tokenizador padrão do Orama mantém apenas letras latinas básicas, dígitos e um punhado de vogais acentuadas, então textos em qualquer outra escrita — japonês, chinês, coreano e tailandês, mas igualmente russo, grego, hebraico e híndi — não produziriam nenhuma correspondência. O Blume cuida disso para você: quando [`i18n.defaultLocale`](/docs/content/i18n) corresponde a uma escrita não latina, o índice passa a usar um tokenizador que segmenta palavras (baseado no `Intl.Segmenter`, nativo do navegador e do Node). Basta declarar o idioma do seu site:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}
```

O mesmo tokenizador atende o diálogo de busca, a ferramenta `search_docs` do servidor MCP e o embasamento do Ask AI. Quem decide é a escrita, não o nome do idioma — `az-Cyrl` é segmentado, enquanto `sr-Latn` não é — e é o idioma padrão que decide por todo o índice: em um site com vários idiomas, todas as páginas compartilham o tokenizador do idioma padrão. Com um padrão não latino, isso é seguro, porque as palavras latinas sobrevivem intactas à segmentação, então páginas em inglês permanecem pesquisáveis ao lado do idioma padrão. O contrário não vale: traduções não latinas em um site com padrão latino não são pesquisáveis. Idiomas de escrita latina que dependem bastante de diacríticos (vietnamita, ou sérvio em escrita latina) também se saem pior no tokenizador padrão, que normaliza apenas algumas vogais acentuadas e divide as palavras no restante.

Japonês e chinês vão um passo além. A segmentação sozinha indexa um termo composto como suas partes — 資金決済法 como 資金, 決済 e 法 — o que permite que uma página que mencione cada parte em algum lugar seja melhor classificada do que a página que realmente trata do termo. Por isso, Han, Hiragana e Katakana são indexados como pares de caracteres sobrepostos, e as consultas sobre esses índices preferem páginas que contenham os pares de um termo juntos, afrouxando para a correspondência de qualquer par quando nenhuma página os contém todos, de modo que digitar uma frase inteira ainda retorna as páginas mais próximas. Coreano e tailandês mantêm suas palavras segmentadas.

### FlexSearch

Uma segunda opção do lado do cliente e sem chaves. Ela reutiliza o mesmo índice `/blume-search.json` que o Orama gera e constrói um índice de documentos do [FlexSearch](https://github.com/nextapps-de/flexsearch) no navegador. Funciona em `blume dev` e `blume build`.

O FlexSearch não tem um mecanismo equivalente de segmentação, então, para sites em escritas não latinas, prefira o Orama (o padrão) ou o [Pagefind](#pagefind), cujo binário `pagefind_extended` indexa um conjunto amplo de idiomas e segmenta chinês, japonês e coreano nativamente.

```ts blume.config.ts lineNumbers
search: {
  provider: "flexsearch",
}
```

### Pagefind

Para documentações muito grandes, opte pelo [Pagefind](https://pagefind.app). Ele indexa o HTML compilado e carrega o índice em fragmentos sob demanda, mantendo a carga inicial mínima por maior que o site fique.

```ts blume.config.ts lineNumbers
search: {
  provider: "pagefind",
}
```

O Pagefind só é executado durante o `blume build`, então a busca não fica disponível em `blume dev` com esse provedor.

### Algolia

O navegador consulta o [Algolia](https://www.algolia.com) diretamente com sua chave somente de busca. Cada `blume build` substitui o índice usando a chave de administração de `ALGOLIA_ADMIN_API_KEY` (o build emite um aviso e pula o envio se ela não estiver definida). Todo o índice é substituído a cada sincronização, então páginas que você excluir ou renomear não permanecem como resultados desatualizados.

```ts blume.config.ts lineNumbers
search: {
  provider: "algolia",
  algolia: {
    appId: "YOUR_APP_ID",
    indexName: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
  },
}
```

### Orama Cloud

Orama hospedado. O navegador consulta o endpoint do seu índice com a chave de API pública; o `blume build` envia registros para o índice usando `ORAMA_PRIVATE_API_KEY`. Defina `indexId` para habilitar a sincronização.

```ts blume.config.ts lineNumbers
search: {
  provider: "orama-cloud",
  oramaCloud: {
    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
    apiKey: "YOUR_PUBLIC_API_KEY",
    indexId: "your-index-id", // for the build-time sync
  },
}
```

### Typesense

[Typesense](https://typesense.org) auto-hospedado ou na nuvem. O navegador consulta a coleção com a chave somente de busca; o `blume build` recria a coleção e importa os documentos usando `TYPESENSE_ADMIN_API_KEY`. A coleção é descartada e reconstruída a cada sincronização, para que páginas excluídas ou renomeadas não permaneçam como resultados desatualizados — se você ajustar manualmente as configurações da coleção, reaplique-as após um build.

```ts blume.config.ts lineNumbers
search: {
  provider: "typesense",
  typesense: {
    host: "xyz.a1.typesense.net",
    collection: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
    // port + protocol default to 443 / https
  },
}
```

### Mixedbread

Busca semântica via [Mixedbread](https://www.mixedbread.com). As consultas passam por um endpoint `/api/search` gerado que guarda sua chave, então esse provedor **exige saída de servidor** (`deployment.output: "server"`). O endpoint lê `MIXEDBREAD_API_KEY`. Sincronize seu conteúdo com o store usando a CLI do Mixedbread no seu build, por exemplo, `mxbai vs sync <STORE_ID> ./content --ci`.

```ts blume.config.ts lineNumbers
search: {
  provider: "mixedbread",
  mixedbread: {
    storeId: "YOUR_STORE_ID",
  },
}
```

### Desativando a busca

```ts blume.config.ts lineNumbers
search: {
  provider: "none",
}
```

## Excluindo páginas

Apenas as páginas indexáveis são pesquisadas. Uma página fica de fora do índice quando define `search.exclude` no frontmatter:

```yaml
search:
  exclude: true
```

[Páginas ocultas](/docs/content/navigation#hidden-pages) também são excluídas por padrão. Para indexá-las mesmo assim, ative explicitamente:

```ts blume.config.ts lineNumbers
search: {
  indexing: { includeHiddenPages: true },
}
```

---

# SEO
Source: https://useblume.dev/pt/docs/configuration/seo

O Blume cuida da camada de descoberta por você: metadados de página, imagens de compartilhamento social, feeds e dados estruturados. Os recursos configuráveis ficam sob a chave `seo` em `blume.config.ts`; os metadados são gerados a partir do seu conteúdo.

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
  x: { handle: "@acme" },
}
```

A maior parte disso fica mais precisa com uma URL de site absoluta — defina [`deployment.site`](/docs/deployment) para que feeds, imagens OG, canônicos, o sitemap e o JSON-LD possam emitir URLs completas.

## Metadados

Cada página renderiza as tags `<head>` padrão a partir da sua configuração e do frontmatter:

- `<title>` — o título da página mais o `title` do seu site.
- `<meta name="description">` e `og:description` — a `description` da página, recorrendo à `description` do site.
- `og:title` e `og:site_name` — o título da página e o `title` do seu site.
- `<link rel="canonical">` e `og:url` — a URL absoluta da página (quando `deployment.site` está definido).
- `og:type` — `article` em posts de blog e entradas de changelog, `website` nos demais casos. Páginas de artigo também emitem `article:published_time` e `article:modified_time` a partir da `date` da página e do carimbo de última modificação.
- `og:image` — a [imagem OG](#open-graph-images) da página. Um card gerado também declara seus `og:image:width`, `og:image:height`, `og:image:type` e `og:image:alt`, para que um rastreador possa dispor o card sem precisar buscá-lo antes; uma `seo.image` fornecida por você não declara nenhum desses, já que seu tamanho e formato são desconhecidos.
- `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` — o card do X. Páginas com imagem recebem a variante ampla `summary_large_image`; páginas sem imagem ainda recebem o card compacto `summary` em vez de serem exibidas como um link simples.

### Atribuição no X

O X lê todo o restante do card a partir das tags `og:*`, então os únicos valores que ele não consegue inferir são as contas a creditar. Defina-as em `seo.x` e o Blume emite `twitter:site` (a conta do seu site) e `twitter:creator` (a da pessoa autora). O `@` é opcional — tanto `acme` quanto `@acme` funcionam.

```ts blume.config.ts lineNumbers
seo: {
  x: { handle: "@acme", creator: "@jane" },
}
```

Uma página pode reivindicar sua própria autoria, que é o que você quer para um post convidado:

```yaml lineNumbers
---
title: How we shipped it
seo:
  x:
    creator: "@guestauthor"
---
```

Sobrescreva qualquer uma das outras tags por página com o frontmatter `seo`:

```yaml lineNumbers
---
title: Pricing
description: Plans and pricing for every team size.
seo:
  title: Pricing — Acme
  canonical: https://acme.com/pricing
  noindex: false
---
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.title?` | `string` | - | Sobrescreve o <title> e o og:title desta página. |
| `seo.description?` | `string` | - | Sobrescreve a meta description e a og:description. |
| `seo.image?` | `string` | - | Imagem social personalizada (veja Open Graph). |
| `seo.canonical?` | `string` | - | Sobrescreve a URL canônica. |
| `seo.noindex?` | `boolean` | - | Emite robots noindex e ignora os dados estruturados. |
| `seo.x.creator?` | `string` | - | Credita esta página a uma conta do X (twitter:creator), sobrescrevendo o seo.x.creator da sua configuração. |

## Imagens Open Graph

O Blume pode renderizar um card social de 1200×630 para cada página no momento do build — sem navegador headless, graças ao [Takumi](https://takumi.kane.tw), então os builds continuam rápidos. Ativado por padrão assim que [`deployment.site`](/docs/deployment) é definido ou detectado automaticamente (a URL de `og:image` precisa ser absoluta para ser útil aos rastreadores), e desativado caso contrário. Defina `enabled` para sobrescrever esse comportamento em qualquer direção:

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}
```

### Aplique sua marca ao card gerado

Defina um SVG local e uma paleta de cores para alinhar o card gerado à sua marca. O logotipo pode ficar em `public/` ou na raiz do projeto. Omita qualquer valor da paleta para manter o padrão dele.

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

Por padrão, cada card é derivado do seu conteúdo e tema — o **título da página** como manchete, a **descrição da página** como subtítulo (o mesmo texto da sua `og:description`, então `seo.description` prevalece sobre `description`), o **título do site** como sobretítulo e o **accent** do seu tema para a marca. As imagens são servidas em `/og/<slug>.png`, espelhando cada rota, e são pré-renderizadas como arquivos estáticos mesmo em modo servidor:

| Rota da página      | URL da imagem              |
| ------------------- | -------------------------- |
| `/`                 | `/og/index.png`            |
| `/quickstart`       | `/og/quickstart.png`       |
| `/configuration/ai` | `/og/configuration/ai.png` |

Sobrescreva o card gerado de qualquer página com `seo.image` — um arquivo em `public/` ou uma URL externa. Ele tem precedência sobre o card gerado e funciona mesmo quando `og` está desativado, então você pode misturar imagens personalizadas com geradas:

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
Cada cor da paleta aceita qualquer cor CSS — hex, `oklch(…)`, `rgb(…)` e assim por diante. O accent também aceita uma predefinição nomeada (`blue`, `teal`, …), correspondendo a [`theme.accent`](/docs/configuration/theming#accent). Uma cor que o renderizador não consegue interpretar quebra o build em vez de entregar silenciosamente um card com a cor padrão.
:::

Emojis em um título de página ou de site são renderizados como glifos [Twemoji](https://github.com/jdecked/twemoji), buscados em uma CDN enquanto o card é renderizado — então um build cujos títulos contêm emojis precisa de acesso à rede. Cada glifo é buscado uma vez por build, independentemente de quantas páginas o usam.

### Exiba, oculte ou sobrescreva camadas do card

Além da manchete, o card carrega três camadas opcionais: a **marca** no canto superior esquerdo (seu logotipo, ou um bloco na cor accent com a inicial do título do site), o **subtítulo** abaixo da manchete (a `description` da página, ou a `description` do seu site nas páginas sem uma) e um **rodapé** com o slug do seu repositório (a partir de `github`) e a URL do site — o host do site de deployment mais [`deployment.base`](/docs/deployment#subpath-deploys), de modo que um site de projeto no GitHub Pages exibe `user.github.io/repo`. Sobrescreva qualquer uma delas com um texto seu, ou oculte uma com `false`:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}
```

### Fontes do card

Por padrão, o card é renderizado com a fonte integrada do Takumi, que cobre apenas glifos latinos — um título em outro sistema de escrita (japonês, chinês, coreano, árabe, …) apareceria como tofu, caixas vazias.

**Defina [`theme.fonts`](/docs/configuration/theming#fonts) e o card acompanha.** Quando sua configuração escolhe suas próprias fontes, os cards gerados automaticamente renderizam a manchete na sua fonte de display e a descrição e o rodapé na sua fonte de texto, para que os links compartilhados combinem com o site — incluindo cobertura não latina, sem nada a configurar aqui. (Famílias de provedores que não sejam o Google são ignoradas — o renderizador de cards só consegue buscar no Google Fonts — mas arquivos de fonte locais funcionam.)

Para usar fontes diferentes nos cards e no site, ou para adicionar cobertura de sistemas de escrita sem mexer no tema, defina `og.fonts` explicitamente — ele sempre prevalece sobre as fontes derivadas do tema:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

Cada entrada é o nome de uma família do Google Fonts, um objeto fixando seu `weight` (um número, uma lista ou um intervalo variável como `"100..900"`) e `style` (`"normal"`, `"italic"` ou ambos), ou um arquivo de fonte local — `src` é resolvido a partir da raiz do projeto, com `weight` e `style` opcionais para quando os metadados do próprio arquivo não devem decidir.

As famílias do Google são buscadas no build — então um build que as utiliza precisa de acesso à rede — e o renderizador baixa apenas os subconjuntos de glifos que cada título realmente usa. O fallback é por glifo, então adicionar uma família afeta apenas os glifos que as outras fontes não conseguem desenhar.

Um `og.fonts: []` explícito desativa tudo: os cards mantêm a fonte integrada mesmo quando `theme.fonts` está definido.

### Títulos de página personalizados

Uma [página `.astro`](/docs/advanced/custom-pages) personalizada não tem frontmatter a ler, então o card gerado é intitulado humanizando o último segmento de URL da sua rota — `/getting-started` vira "Getting Started", mas `/cli` vira "Cli". Nomeie esses cards explicitamente com `og.titles`, indexados por rota (`"/"` corresponde à página inicial, cujo card, de outro modo, carrega o título do site):

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

As entradas se aplicam apenas a páginas personalizadas — o card de uma página de conteúdo sempre tira sua manchete do título da página, então renomeie essas no frontmatter.

`seo.image` é frontmatter, então cobre apenas conteúdo em Markdown e MDX. Para dar a uma [página `.astro`](/docs/advanced/custom-pages) personalizada sua própria imagem social — uma home de marketing ou landing page, e a maneira de dar apenas à página inicial uma imagem de compartilhamento sob medida — passe a prop `ogImage` para o `PageLayout`.

## Feeds RSS

O Blume cria um feed RSS para cada tipo de conteúdo em `rss.types` — `blog` e `changelog` por padrão — que tenha páginas, servido em `/<type>/rss.xml`. Veja [Feeds](/docs/content#feeds) para escrever posts de blog e entradas de changelog com datas.

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

| Opção | Padrão | Descrição |
| --- | --- | --- |
| `enabled` | `true` | Gera os feeds. |
| `types` | `["blog", "changelog"]` | Tipos de conteúdo que recebem um feed cada. |
| `limit` | `50` | Máximo de itens por feed, dos mais novos aos mais antigos. |

O Blume injeta tags `<link rel="alternate">` para que navegadores e leitores de feed descubram os feeds automaticamente.

## Dados estruturados

O Blume emite JSON-LD do [schema.org](https://schema.org) no `<head>` de cada página para que os mecanismos de busca entendam seu conteúdo. Ativado por padrão:

```ts blume.config.ts lineNumbers
seo: {
  structuredData: true,
}
```

Cada página inclui:

- um nó **WebSite** para a identidade do site,
- a página como um **artigo** — `BlogPosting` para posts de blog, `TechArticle` para changelog e docs — com sua descrição e data de publicação,
- uma **BreadcrumbList** construída a partir da trilha de navegação.

As URLs são absolutas quando `deployment.site` está definido. Páginas marcadas com `seo.noindex` são ignoradas.

### Identidade do site

O nó WebSite diz que um site existe; ele não diz _o que_ ele é nem _quem_ o mantém — que é justamente o que os agentes de IA leem no JSON-LD antes de recomendar ou citar você. Dois blocos opcionais preenchem essa lacuna, ambos precisando de `deployment.site` (os nós carregam identificadores absolutos):

```ts blume.config.ts lineNumbers
seo: {
  organization: {
    name: "Acme", // defaults to the site title
    email: "hello@acme.com",
    telephone: "+1 555 0100",
    address: { addressLocality: "Sydney", addressCountry: "AU" },
    logo: "/logo.svg",
    sameAs: ["https://github.com/acme", "https://x.com/acme"],
  },
  software: {
    license: "MIT",
    operatingSystem: "Node.js 22+",
    price: 0, // emitted as an Offer; 0 marks it free
    sameAs: ["https://www.npmjs.com/package/acme"],
  },
}
```

`organization` adiciona um nó **Organization** a cada página — os nós WebSite e de artigo o citam como `publisher` — com o e-mail e o telefone como um `ContactPoint` (`contactType` assume `"customer support"` por padrão) e o endereço como um `PostalAddress`, os dois campos que as verificações de negócio procuram. `name` e `url` assumem os do site por padrão; um `logo` relativo à raiz é convertido em absoluto como qualquer URL de página.

`software` adiciona um nó **SoftwareApplication** à página inicial: o nome e a descrição do produto (assumindo os do site por padrão), `applicationCategory` (padrão `"DeveloperApplication"`), sistema operacional, licença, um `Offer` quando `price` está definido, e as URLs de registro ou repositório em `sameAs`. Passe `software: true` para aceitar todos os padrões. A organização, quando configurada, é citada como seu `publisher`.

## Sitemap

O Blume escreve um `sitemap.xml` com todas as páginas indexáveis no momento do build. Ele precisa de um [`deployment.site`](/docs/deployment) absoluto e lista todas as páginas, exceto rascunhos, ocultas e páginas com `noindex`. Em um site [versionado](/docs/content/versioning), as páginas arquivadas cujo canônico aponta para o equivalente em produção também ficam de fora — a página em produção é a que deve ser indexada. Ativado por padrão:

```ts blume.config.ts lineNumbers
seo: {
  sitemap: true,
}
```

Publique seu próprio `public/sitemap.xml` para assumir o controle — o Blume nunca sobrescreve um arquivo que você coloca em `public/`.

## Robots

O Blume escreve um `robots.txt` que permite todos os rastreadores, declara seus [sinais de conteúdo](#content-signals) e adiciona uma linha `Sitemap:` apontando para o sitemap quando há um disponível. Ativado por padrão:

```ts blume.config.ts lineNumbers
seo: {
  robots: true,
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://docs.example.com/sitemap.xml
```

### Sinais de conteúdo

A linha `Content-Signal` — a convenção emergente de uso de conteúdo — declara como os rastreadores de IA podem reutilizar sua documentação. O Blume a emite **ativada por padrão, com todos os sinais definidos como `yes`**, em linha com sua postura de que a documentação está aberta tanto a pessoas quanto a agentes:

- `search` — indexação de busca tradicional e por IA
- `aiInput` — grounding / RAG no momento da resposta
- `aiTrain` — treinamento de modelos

Restrinja qualquer sinal definindo-o como `false`; os que você deixar de fora permanecem como `yes`:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: {
    aiTrain: false, // opt out of training, keep search + grounding
  },
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /
```

Defina `contentSignals: false` para remover a declaração por completo:

```ts blume.config.ts lineNumbers
seo: {
  contentSignals: false,
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `seo.contentSignals?` | `boolean \| object` | - | Declaração Content-Signal. true ou omitido emite todos os sinais como yes; false remove a linha; um objeto define os sinais individualmente. |
| `contentSignals.search?` | `boolean` | - | Permite o uso para indexação de busca (search). Padrão: true. |
| `contentSignals.aiInput?` | `boolean` | - | Permite o uso para grounding / RAG de IA no momento da resposta (ai-input). Padrão: true. |
| `contentSignals.aiTrain?` | `boolean` | - | Permite o uso para treinamento de modelos de IA (ai-train). Padrão: true. |

Os sinais de conteúdo expressam uma preferência, não controle de acesso: eles informam aos rastreadores bem-comportados como você gostaria que seu conteúdo fosse usado, e cabe ao rastreador respeitá-los.

Publique seu próprio `public/robots.txt` para assumir o controle.

---

# Temas
Source: https://useblume.dev/pt/docs/configuration/theming

O tema do Blume é orientado a tokens e funciona nos modos claro e escuro por padrão. Use tão pouco ou tanto quanto precisar: alguns tokens de configuração para os casos comuns, um `theme.css` para sobrescrever qualquer token de design ou utilitários do Tailwind para componentes personalizados.

## Tokens de configuração

Os controles do dia a dia ficam em `theme` na sua configuração:

```ts blume.config.ts lineNumbers
theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}
```

### Cor de destaque

A cor de destaque tinge elementos interativos e realçados — marcadores de etapa, abas ativas, selos, hovers de cartões e mais. Use uma predefinição nomeada ou qualquer cor CSS:

```ts blume.config.ts lineNumbers
theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}
```

Predefinições nomeadas: `blue` (padrão), `green`, `orange`, `pink`, `purple`, `red` e `teal`.

Uma string se aplica a ambos os modos de cor; passe um objeto para [uma cor de destaque diferente por modo](#dark-mode-colors).

### Raio

`radius` define o arredondamento dos cantos compartilhado por cartões, blocos de código, avisos e campos de entrada — `none`, `sm`, `md` (padrão) ou `lg`.

### Modo de cor

`mode` define o esquema de cores inicial:

- **`system`** (padrão) — segue a preferência do sistema operacional do leitor
- **`light`** / **`dark`** — usa um esquema como padrão

Um alternador no cabeçalho sempre permite que os leitores mudem, e a escolha deles é lembrada entre as visitas. O modo escuro é aplicado com um atributo `data-theme="dark"` no elemento `<html>`.

### Fontes

`fonts` define os tipos de letra para três funções:

- **`display`** — títulos (`h1`–`h6`)
- **`body`** — texto do corpo, interface e prosa
- **`mono`** — blocos de código e código em linha

Os títulos recebem letter-spacing de display (`-0.05em`) do próprio tema, então o que você escolher para `display` — incluindo fontes de texto como o padrão Inter — fica correto nos tamanhos de título, sem depender do tracking embutido na fonte.

Cada uma tem como padrão uma Google Font selecionada, para que o Blume pareça intencional desde o início:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}
```

Defina apenas as funções que você quer alterar — as demais mantêm seus padrões:

```ts blume.config.ts lineNumbers
theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}
```

As fontes são **auto-hospedadas**: o Blume as baixa no momento da build e as serve a partir do seu próprio site, então não há requisição em tempo de execução ao Google nem deslocamento de layout (o Astro gera automaticamente faces com métricas de fallback).

Uma string simples é um slug do Google Fonts do conjunto selecionado abaixo:

| Categoria | Slugs |
| --- | --- |
| Sem serifa | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
| Com serifa | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4` |
| Monoespaçada | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono` |

#### Qualquer família de qualquer provedor

Precisa de uma família que não está no conjunto selecionado — digamos, uma que cubra um sistema de escrita não latino? Passe um objeto com o nome exato da família. Ela é auto-hospedada e otimizada da mesma forma:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}
```

- **`name`** — o nome da família exatamente como o provedor o lista.
- **`provider`** — de onde vem a família: `google` (padrão), `fontsource`, `bunny` ou `fontshare`.
- **`weights`** — os pesos a carregar, como números ou um intervalo variável como `"100..900"`. O padrão é `[400, 500, 600, 700]`.
- **`subsets`** — os subconjuntos de caracteres a carregar, pelos nomes do provedor (`latin`, `latin-ext`, `vietnamese`, `cyrillic`, `greek`, …). O padrão é `latin` mais o que os idiomas configurados precisarem — veja abaixo.
- **`fallback`** — a pilha de fontes do sistema exibida enquanto a fonte carrega e para glifos ausentes: `sans`, `serif` ou `mono`. O padrão é `mono` para a função mono e `sans` nos demais casos.

#### Subconjuntos e idiomas

Google, Bunny e Fontsource dividem cada família em subconjuntos por sistema de escrita, e apenas os subconjuntos que você carrega recebem um `@font-face`. O Blume deriva a lista a partir do seu [`i18n.locales`](/docs/content/i18n): um site com idiomas vietnamita, polonês, russo ou grego carrega `vietnamese`, `latin-ext`, `cyrillic` ou `greek` junto com `latin`, para que diacríticos e letras não latinas sejam renderizados na fonte escolhida em vez do fallback do sistema. Sites sem um bloco `i18n`, ou apenas com idiomas Latin-1, carregam somente `latin`. Os navegadores baixam um subconjunto apenas quando uma página usa seus caracteres, e os preloads seguem a mesma lista.

Defina `subsets` em uma família para sobrescrever a lista derivada — digamos, para um site de um único idioma cujo conteúdo ainda precisa de um sistema de escrita que o idioma não implica:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}
```

Slugs selecionados como `inter` seguem a lista derivada dos idiomas; use a forma de objeto para fixar subconjuntos nessas famílias também.

#### Arquivos de fonte locais

Para uma fonte que você possui (ou que nenhum provedor serve), aponte uma função para arquivos de fonte no seu projeto. Cada variante se torna um `@font-face`:

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}
```

Os caminhos são resolvidos a partir da raiz do projeto. `weight` e `style` (`normal`, `italic`, `oblique`) são opcionais — o Astro os lê do arquivo de fonte quando omitidos.

:::note
Quando você define `theme.fonts` explicitamente, suas fontes display e body também estilizam automaticamente os [cartões Open Graph](/docs/configuration/seo#card-fonts) gerados, para que os links compartilhados combinem com o site. Famílias de provedores que não sejam o Google são ignoradas ali (o renderizador de cartões só consegue buscar no Google Fonts); arquivos locais funcionam em todos os casos.
:::

Quer voltar para a pilha de fontes do sistema? Sobrescreva os tokens `--blume-font-*` diretamente em [`theme.css`](#themecss).

### Cores do modo escuro

`accent` e `background` seguem uma regra: uma string se aplica a ambos os modos de cor, e um objeto `{ light, dark }` define cada modo individualmente:

```ts blume.config.ts lineNumbers
theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}
```

Cada cor aceita uma predefinição nomeada ou qualquer cor CSS. Para `background` (e `backgroundImage`), qualquer uma das chaves pode ser omitida para sobrescrever apenas um modo — `background: { dark: "#0a0a0a" }` mantém o fundo claro padrão.

### Cor de ação

`action` é uma cor de destaque secundária para chamadas para ação principais e para os utilitários `action` do Tailwind (`bg-action`, `text-action`). Seu padrão é o seu `accent`:

```ts blume.config.ts
theme: {
  action: "#ff0066",
}
```

### Imagem de fundo

Defina uma imagem de fundo atrás do seu conteúdo com `backgroundImage` — uma URL ou um caminho dentro de `public/`. Assim como nas cores, uma string se aplica a ambos os modos e um objeto `{ light, dark }` define a imagem de cada modo:

```ts blume.config.ts lineNumbers
theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}
```

## theme.css

Coloque um `theme.css` na raiz do seu projeto para sobrescrever qualquer token de design. É a última camada da cascata, então ela prevalece sobre os padrões e sobre os tokens de configuração:

```css theme.css lineNumbers
:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}
```

Defina um token em `:root` para o modo claro e em `:root[data-theme="dark"]` para o modo escuro. Os tokens de cor têm valores escuros embutidos distintos, declarados na especificidade mais alta do seletor escuro, então uma sobrescrita apenas em `:root` de `--blume-accent`, `--blume-background` e companhia se aplica somente ao modo claro — declare também o bloco escuro quando ambos os modos devem mudar.

O `theme.css` é embutido no ponto de entrada do Tailwind do site, então diretivas do Tailwind também funcionam nele. A que vale conhecer para um monorepo é `@source`: o Blume analisa seu projeto em busca de classes utilitárias, e uma página que importa componentes de um pacote irmão do workspace precisa que esse pacote também seja analisado. Aponte para ele de forma relativa ao `theme.css` — a regra padrão do Tailwind — e o Blume leva o caminho para a folha de estilos gerada:

```css theme.css lineNumbers
@source "../../packages/ui/src";
```

### Tokens de design

| Token | Controla |
| --- | --- |
| `--blume-background` | Fundo da página |
| `--blume-foreground` | Texto do corpo |
| `--blume-muted` | Superfícies sutis — avisos, cabeçalhos de tabela |
| `--blume-muted-foreground` | Texto secundário |
| `--blume-border` | Bordas e divisores |
| `--blume-accent` | Cor de destaque |
| `--blume-accent-foreground` | Texto e ícones sobre um fundo de destaque |
| `--blume-action` | Destaque secundário (padrão: cor de destaque) |
| `--blume-code-background` | Superfície do bloco de código |
| `--blume-radius` | Raio dos cantos |
| `--blume-font-display` | Fonte dos títulos |
| `--blume-font-body` | Fonte do corpo / interface |
| `--blume-font-mono` | Fonte do código |

Defina um token `--blume-font-*` com qualquer pilha de fontes para usar uma fonte fora da lista selecionada, ou para recorrer à pilha do sistema:

```css theme.css lineNumbers
:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

## Utilitários do Tailwind

O tema do Blume é construído internamente com o Tailwind v4, e os arquivos `.astro`, `.tsx` e `.jsx` do seu projeto também são analisados — assim você pode estilizar componentes e páginas personalizados com classes utilitárias, sem precisar configurar o Tailwind. Cada token é exposto como um utilitário, então seus componentes acompanham o tema automaticamente:

| Token                       | Utilitários                |
| --------------------------- | -------------------------- |
| `--blume-background`        | `bg-background`            |
| `--blume-foreground`        | `text-foreground`          |
| `--blume-muted`             | `bg-muted`                 |
| `--blume-muted-foreground`  | `text-muted-foreground`    |
| `--blume-border`            | `border-border`            |
| `--blume-accent`            | `bg-accent`, `text-accent` |
| `--blume-accent-foreground` | `text-accent-foreground`   |
| `--blume-action`            | `bg-action`, `text-action` |
| `--blume-radius`            | `rounded-blume`            |
| `--blume-font-display`      | `font-display`             |
| `--blume-font-body`         | `font-sans`                |
| `--blume-font-mono`         | `font-mono`                |

## Ordem da cascata

Os estilos são resolvidos em três camadas, cada uma sobrescrevendo a anterior:

1. **Base**

    O reset, os tokens padrão e os estilos de componentes do Blume.

2. **Tokens de configuração**

    `--blume-accent`, `--blume-radius` e os tokens `--blume-font-*` vindos de
    `theme`.

3. **theme.css**

    Suas sobrescritas de tokens — a palavra final.

---

# Páginas
Source: https://useblume.dev/pt/docs/content

A sua documentação é apenas uma pasta de ficheiros Markdown e MDX. O Blume transforma cada ficheiro numa página — encaminhamento, navegação e metadados são inferidos a partir do sistema de ficheiros, pelo que não existe nenhum manifesto para manter sincronizado.

O conteúdo fica na sua **raiz de conteúdo** (`docs/` por predefinição; altere-a com `content.root` em [`blume.config.ts`](/docs/configuration)).

## Markdown e MDX

O Blume compõe dois tipos de ficheiro:

- **`.md`** — Markdown para prosa simples: GFM, frontmatter, pontuação inteligente e sobrescrito/subscrito.
- **`.mdx`** — tudo o que o `.md` tem, mais [componentes](/docs/content/components) e as [diretivas, instalações de pacotes e matemática](/docs/content/syntax) exclusivas do MDX.

Opte pelo `.md` quando uma página for apenas prosa, e pelo `.mdx` quando precisar de componentes ou diretivas. Mudar é tão simples como renomear o ficheiro.

## Ficheiros e rotas

Cada ficheiro corresponde a uma rota pelo seu caminho na raiz de conteúdo:

| Ficheiro                  | Rota              |
| ------------------------- | ----------------- |
| `docs/index.mdx`          | `/`               |
| `docs/quickstart.mdx`     | `/quickstart`     |
| `docs/guides/theming.mdx` | `/guides/theming` |
| `docs/guides/index.mdx`   | `/guides`         |

Pastas aninhadas tornam-se rotas aninhadas, e um `index.mdx` dentro de uma pasta torna-se a página dessa mesma pasta.

## Ordenação com prefixos numéricos

Prefixe um ficheiro ou pasta com um número para controlar a sua ordem na barra lateral. O prefixo é removido do URL, pelo que pode reordenar páginas sem quebrar ligações:

```txt
01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation
```

A ordenação tem várias camadas — consulte [Navegação](/docs/content/navigation) para as regras de precedência completas.

## Pastas de agrupamento

Envolva o nome de uma pasta em parênteses para agrupar as suas páginas na barra lateral **sem** adicionar um segmento ao URL:

```txt
docs/(internal)/security.mdx  ->  /security
```

As páginas partilham um grupo “Internal” na barra lateral, mas mantêm URLs planos e sem parênteses.

## Rascunhos

Marque uma página como rascunho para a manter fora das compilações de produção, podendo ainda pré-visualizá-la em `blume dev`:

```yaml lineNumbers
---
title: Work in progress
draft: true
---
```

O `blume build` ignora rascunhos; o `blume dev` compõe-nos para que possa trabalhar abertamente.

## Tipos de conteúdo

Cada página tem um **tipo**, definido com o campo de frontmatter `type` (predefinição `doc`). Os tipos permitem ao Blume tratar grupos de páginas de forma diferente — e, mais importante ainda, as páginas `blog` e `changelog` são reunidas em [feeds](#feeds).

```yaml lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---
```

O tipo é independente do local onde o ficheiro se encontra, mas, por convenção, as publicações de blogue ficam em `blog/` e as entradas do registo de alterações em `changelog/`. Ambos recebem automaticamente um feed RSS, e as entradas do registo de alterações são também reunidas numa [cronologia `/changelog`](/docs/advanced/changelog) gerada. Consulte [Blogue](/docs/advanced/blog) e [Registo de alterações](/docs/advanced/changelog) para escrever cada um deles.

## Feeds

O Blume gera automaticamente um feed RSS para cada tipo de conteúdo listado em [`rss.types`](/docs/configuration/seo#rss-feeds) — `blog` e `changelog` por predefinição — desde que tenha pelo menos uma página. Os feeds são servidos em `/<type>/rss.xml`:

| Tipo        | Feed                 |
| ----------- | -------------------- |
| `blog`      | `/blog/rss.xml`      |
| `changelog` | `/changelog/rss.xml` |

Atribua a cada entrada uma `date` para que os itens sejam ordenados do mais recente para o mais antigo e incluam uma `pubDate`. Uma data YAML sem aspas serve — o Blume normaliza-a:

```yaml lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---
```

Os feeds precisam de um URL absoluto do site, por isso defina [`deployment.site`](/docs/deployment). O Blume adiciona etiquetas `<link rel="alternate">` a todas as páginas para que navegadores e leitores de feeds as descubram automaticamente. Consulte [Blogue](/docs/advanced/blog) e [Registo de alterações](/docs/advanced/changelog) para escrever cada tipo de conteúdo.

## Nesta página

Cada página recebe um índice automático, construído a partir dos seus cabeçalhos. Em ecrãs largos, fica numa barra lateral fixa ao lado do seu conteúdo; em ecrãs mais estreitos, recolhe-se num painel **Nesta página** acima da página. À medida que desloca a página, a entrada da secção que está a ler é destacada, para que saiba sempre onde se encontra numa página longa.

O Blume converte cada cabeçalho num slug para criar uma âncora, pelo que cada entrada liga diretamente à sua secção — e pode criar ligações diretas para qualquer cabeçalho acrescentando o respetivo slug ao URL (`.../my-page#getting-started`).

O índice lista os seus cabeçalhos `##` e `###` (H2 e H3). Uma página sem cabeçalhos desse nível simplesmente não tem índice.

## Para onde ir a seguir

**[Frontmatter](/docs/reference/frontmatter)**

Metadados da página: título, descrição, barra lateral, SEO e pesquisa.

**[Sintaxe](/docs/content/syntax)**

Todas as funcionalidades de Markdown e MDX que pode escrever.

**[Componentes](/docs/content/components)**

Os componentes JSX disponíveis em qualquer página MDX.

**[Navegação](/docs/content/navigation)**

Molde a barra lateral, a ordenação e os separadores.

**[Meta de pasta](/docs/content/meta)**

Configure um grupo da barra lateral com um ficheiro `meta.ts`.

---

# Componentes
Source: https://useblume.dev/pt/docs/content/components

O Blume vem com um conjunto de componentes acessível e personalizável, disponível em qualquer página `.mdx` **sem imports**. Cada um é mostrado abaixo com uma prévia ao vivo e seu código-fonte. Os componentes são vanilla e não usam React; o React só entra em ação se você adicionar sua própria ilha.

## Card e CardGroup

Os cards apontam para um destino com um ícone, um título e um breve resumo. Agrupe-os com `CardGroup` para obter uma grade responsiva. Use-os em páginas iniciais, índices de seção e “próximos passos” — em qualquer lugar em que você esteja guiando o leitor adiante.

**[Início rápido](/docs/quickstart)**

Instale o Blume e publique sua primeira página.

**[Componentes](/docs/content/components)**

Explore a biblioteca de componentes.

```astro lineNumbers
<CardGroup cols={2}>
  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
    Install Blume and ship your first page.
  </Card>
  <Card title="Components" href="/docs/content/components" icon="folder">
    Browse the component library.
  </Card>
</CardGroup>
```

`Card` recebe `title`, um `href` opcional (omita-o para um card não clicável) e um `icon` do conjunto de ícones integrado do Blume. `CardGroup` recebe `cols` (padrão `2`).

## Steps

Uma sequência vertical numerada para instruções ordenadas — instalações, fluxos de configuração e tutoriais em que a ordem importa. Cada `Step` recebe um `title`.

1. **Instale o Blume**

    Adicione o pacote ao seu projeto.

2. **Escreva uma página**

    Coloque um arquivo `.mdx` na sua pasta de conteúdo.

3. **Publique**

    Execute `blume build` e faça o deploy de `dist/`.

```astro lineNumbers
<Steps>
  <Step title="Install Blume">Add the package to your project.</Step>
  <Step title="Write a page">
    Drop an `.mdx` file into your content folder.
  </Step>
  <Step title="Ship it">Run `blume build` and deploy `dist/`.</Step>
</Steps>
```

## Tabs

Alterne entre conteúdos equivalentes no mesmo lugar — variantes de linguagem, comandos específicos de sistema operacional ou abordagens alternativas — sem empilhar tudo na página. Cada `Tab` recebe um `title`.

**macOS**

Use o Homebrew para instalar o toolchain.

**Windows**

Use o winget para instalar o toolchain.

```astro lineNumbers
<Tabs>
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

Adicione `inline` para renderizar sem bordas — uma faixa de abas sobre uma linha de largura total, com o conteúdo fluindo abaixo como texto corrido — em vez da caixa com borda. Adicione `param` para sincronizar a aba ativa com um parâmetro de consulta na URL em vez do hash, o que torna a seleção compartilhável: um link terminando em `?install=windows` abre na aba Windows. Cada grupo sincroniza com seu próprio `param`, então você pode usar vários grupos independentes e endereçáveis por link em uma mesma página.

Grupos com abas de mesmo título alternam juntos — escolha “macOS” em um e todos os grupos com uma aba macOS acompanham. Adicione `syncKey` para delimitar essa sincronização: apenas os grupos que compartilham a mesma chave alternam juntos, então grupos não relacionados que por acaso tenham um título de aba em comum permanecem independentes.

**macOS**

Use o Homebrew para instalar o toolchain.

**Windows**

Use o winget para instalar o toolchain.

```astro lineNumbers
<Tabs inline param="install">
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

## Badge

Um pequeno rótulo em linha para status ou metadados — tags de versão, marcadores de “novo” ou “beta”, níveis de estabilidade. O `variant` ajusta a cor ao significado.

### Padrão

Metadados neutros, sem ênfase específica.

<Badge>Estável</Badge>

```astro
<Badge>Stable</Badge>
```

### Destaque

Chama a atenção usando a cor de destaque do seu tema — bom para marcadores de “novo” ou de destaque.

<Badge variant="accent">Novo</Badge>

```astro
<Badge variant="accent">New</Badge>
```

### Sucesso

Um estado positivo ou aprovado.

<Badge variant="success">Aprovado</Badge>

```astro
<Badge variant="success">Passing</Badge>
```

### Aviso

Algo a ser usado com cautela, como um recurso experimental.

<Badge variant="warning">Beta</Badge>

```astro
<Badge variant="warning">Beta</Badge>
```

### Perigo

Um estado negativo ou incompatível, como uma descontinuação.

<Badge variant="danger">Descontinuado</Badge>

```astro
<Badge variant="danger">Deprecated</Badge>
```

## Icon

Renderiza um ícone pelo nome — a mesma prop `icon` alimenta cards, steps, tabs e entradas da barra lateral. Os nomes vêm do [Lucide](https://lucide.dev/icons), em minúsculas e em kebab-case (`rocket`, `gauge`, `book-open`).

<Icon icon="rocket" size={20} />

```astro
<Icon icon="rocket" size={20} />
```

O Blume usa somente o Lucide — um nome simples é resolvido no Lucide, e você pode prefixar um nome com `lucide:` (`lucide:rocket`) por simetria com outras entradas de ícone. `size` define o tamanho em pixels (padrão `16`) e `color` o colore (qualquer cor CSS; o padrão é `currentColor`). Passe uma string `<svg>` bruta, uma URL de imagem ou um caminho de imagem local no lugar de um nome para renderizar sua própria arte, e adicione um `label` para expô-lo a tecnologias assistivas — sem ele, o ícone é decorativo.

Os ícones são resolvidos no momento do build e embutidos como SVG sem JS — nada é buscado em tempo de execução.

## Árvore de arquivos

Ilustre a estrutura de um projeto ou de uma pasta. Envolva uma lista normal em Markdown e o Blume a estiliza como uma árvore — útil para explicar a estrutura em guias de configuração e instalação.

<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>

```astro lineNumbers
<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>
```

## Accordion

Empilhe elementos recolhíveis relacionados em um único contêiner com borda e divisórias entre eles — perguntas frequentes, etapas opcionais ou exemplos longos. Cada filho é um `AccordionItem` (`title`, `icon` opcional, `description`, `defaultOpen`). Para uma única divulgação independente, use [Expandable](#expandable).

<Accordion>
  <AccordionItem title="Ele tem suporte a MDX?">
    Sim — toda página pode ser `.md` ou `.mdx`.
  </AccordionItem>
  <AccordionItem title="O tema é personalizável?">
    Sim, por meio dos tokens do Tailwind v4 e do seu próprio `theme.css`.
  </AccordionItem>
</Accordion>

```astro lineNumbers
<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>
```

## Expandable

Uma divulgação em linha e leve para detalhes aninhados — expandindo as subpropriedades de um campo ou uma nota opcional. `title` rotula o botão de alternância (o padrão é “Mostrar mais”); defina `defaultOpen` para começar expandido.

<Expandable title="Mostrar opções avançadas">
  Essas configurações são opcionais e raramente precisam ser alteradas.
</Expandable>

```astro
<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>
```

## Columns

Disponha cards ou blocos em uma grade responsiva de colunas iguais que se reorganiza no celular. `Columns` recebe `cols`; envolva cada célula em um `Column`.

<Columns cols={2}>
  <Column>
    **Rápido**

    Construído sobre Astro e Vite.
  </Column>
  <Column>
    **Personalizável**

    Tokens de design do Tailwind v4.
  </Column>
</Columns>

```astro lineNumbers
<Columns cols={2}>
  <Column>
    <Card title="Fast" icon="rocket">
      Built on Astro and Vite.
    </Card>
  </Column>
  <Column>
    <Card title="Themeable" icon="sun">
      Tailwind v4 design tokens.
    </Card>
  </Column>
</Columns>
```

## CodeGroup

Agrupe vários blocos de código em um único alternador com abas — uma aba por linguagem ou arquivo. O rótulo da aba é o título de cada bloco (o texto após a linguagem), e o botão de cópia do grupo fica na barra de abas e copia o bloco que está sendo exibido. Adicione `dropdown` para alternar com um menu em vez de uma barra de abas.

<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>

````astro
<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>
````

## Frame

Envolva uma imagem ou qualquer elemento visual em um quadro centralizado e com borda, com uma `caption` opcional (renderizada como Markdown) e um `hint`.

<Frame
  caption="Uma ilustração **emoldurada**."
  hint="Os frames centralizam e legendam elementos visuais."
>
  <svg
    width="160"
    height="72"
    viewBox="0 0 160 72"
    role="img"
    aria-label="Frame de exemplo"
  >
    <rect width="160" height="72" rx="8" fill="#3b82f6" />
  </svg>
</Frame>

```astro lineNumbers
<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <img src="/screenshot.png" alt="Product screenshot" />
</Frame>
```

## YouTube

Incorpore um vídeo do YouTube em um quadro 16:9 responsivo e respeitoso com a privacidade (`youtube-nocookie.com`) que não envia nenhum JavaScript ao cliente. Passe um `id` de vídeo ou uma `url` completa, além de um `title` opcional (para acessibilidade) e um tempo de `start` em segundos.

[Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

```astro lineNumbers
<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
<YouTube url="https://youtu.be/aqz-KE-bpKQ" start={30} />
```

## Color

Exiba amostras de cor com valores hexadecimais copiáveis — útil para documentar uma paleta ou as cores da marca. Use `variant="compact"` para uma lista de amostras, ou `variant="table"` com `Color.Row` para agrupá-las. Cada `Color.Item` recebe um `name` e um `value` (uma string hexadecimal, ou `{ light, dark }` para cores sensíveis ao tema).

<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>

```astro lineNumbers
<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>
```

## Tree

Renderize uma estrutura hierárquica de arquivos/pastas com pastas expansíveis. (Para uma versão rápida, baseada em listas, veja [Árvore de arquivos](#file-tree); `Tree` oferece controle por pasta.) Use `Tree.Folder` (`name`, `defaultOpen` opcional, `openable`) e `Tree.File` (`name`).

<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>

```astro lineNumbers
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>
```

## Panel

Um contêiner com título para conteúdo complementar, colocado à parte. `title` é opcional.

<Panel title="Bom saber">
  Os panels contêm detalhes de apoio sem interromper o fluxo principal.
</Panel>

```astro
<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>
```

## Tooltip

Revele uma definição ou dica ao passar o mouse sobre um termo em linha. `tip` é o texto exibido ao passar o mouse; adicione um `headline` opcional e um `cta` + `href` para um link de continuação.

Passe o mouse sobre o termo <Tooltip tip="Um conjunto de protocolos que os softwares usam para se comunicar." headline="API" cta="Leia o guia" href="/docs/quickstart">API</Tooltip> para saber mais.

```astro
Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term.
```

## Tile

Uma prévia clicável que começa com um elemento visual — um ícone ou imagem — acima de um título e uma descrição. Boa para galerias e vitrines. Recebe `title`, `description` e `href`; o filho é o elemento visual.

<Tile
  title="Início rápido"
  description="Publique sua primeira página em minutos."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>

```astro
<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>
```

## Prompt

Uma única linha com um rótulo e um botão de cópia. A `description` (Markdown) é o rótulo visível; o corpo é o próprio prompt — oculto, e copiado para a área de transferência quando o botão **Copiar prompt** é pressionado. `actions` controla os botões (por exemplo, `["copy", "cursor"]`).

<Prompt
  description="Peça ao modelo para **documentar** um endpoint."
  actions={["copy"]}
>
  Escreva a documentação de referência para o endpoint POST /v1/pets.
</Prompt>

```astro
<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>
```

## Visibility

Mostre ou oculte conteúdo de acordo com o público. `for="web"` renderiza somente no site; `for="agents"` tem como alvo o Markdown voltado a agentes que as IAs leem (`llms-full.txt` e o espelho `.md` de cada página).

```astro
<Visibility for="web">Shown on the site only.</Visibility>
<Visibility for="agents">Shown only in the generated Markdown.</Visibility>
```

## Tabelas de tipos

Tabelas para documentar as propriedades de um objeto — suas props, tipos e valores padrão. Escreva as linhas manualmente com `TypeTable`, ou gere-as diretamente a partir de uma interface ou alias de tipo do TypeScript com `AutoTypeTable`.

### Tabela de tipos

Uma grade **Prop / Tipo** em que cada linha se expande para revelar sua descrição e detalhes. Passe um mapa `type` indexado pelo nome da propriedade; cada entrada recebe um `type`, além de `description`, `default`, o sinalizador `required`, `typeDescription` e `typeDescriptionLink` opcionais. Props opcionais (`required` não definido) exibem um `?` após o nome.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `string` | - | O rótulo visível do botão. |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | Estilo visual. |
| `disabled?` | `boolean` | - | |

```astro lineNumbers
<TypeTable
  type={{
    label: {
      type: "string",
      required: true,
      description: "The button's visible label.",
    },
    variant: {
      type: '"primary" | "ghost"',
      default: '"primary"',
      description: "Visual style.",
    },
    disabled: { type: "boolean" },
  }}
/>
```

### Tabela de tipos automática

Gere uma tabela de tipos a partir de um tipo do TypeScript, para que a documentação permaneça em sincronia com o código-fonte. Aponte o `AutoTypeTable` para um arquivo com `path` (resolvido a partir da raiz do seu projeto) e um `name` de tipo. As descrições vêm de comentários JSDoc, os valores padrão de tags `@default`, e as propriedades opcionais (`?`) são marcadas conforme o caso.

```astro
<AutoTypeTable path="./src/button.ts" name="ButtonProps" />
```

Você também pode passar o tipo em linha com `type` em vez de um `path` — prático para exemplos pequenos:

<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>

```astro lineNumbers
<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>
```

## Informações do GitHub

Um card com link para um repositório do GitHub com suas contagens de estrelas e forks em tempo real. As contagens são buscadas no momento do build — sem JavaScript no cliente — e o card continua sendo renderizado se a API estiver inacessível. Passe `owner` e `repo`, ou omita-os para usar o repositório do seu `blume.config`. Defina uma variável de ambiente `GITHUB_TOKEN` para elevar o limite de requisições da API.

O card lê a instância a partir de [`github.host`](/docs/configuration#github-enterprise), então, em um site hospedado no Enterprise, `owner`/`repo` explícitos também apontam para essa instância. Passe `host` para direcionar um card para outro lugar — um projeto público a partir de um site Enterprise, por exemplo; a base REST é derivada dele da mesma forma que a partir de `github.host`.

<GithubInfo owner="haydenbleasel" repo="blume" />

```astro lineNumbers
<!-- Uses the repo from blume.config -->
<GithubInfo />

<!-- Or point it at any repository -->
<GithubInfo owner="haydenbleasel" repo="blume" />

<!-- Or at a repository on another instance -->
<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
```

## Component

O `Component` renderiza um arquivo de exemplo do diretório `examples/` do seu projeto como uma prévia ao vivo ao lado do seu código-fonte destacado, em abas. Aponte-o para um arquivo com `path` — sua localização dentro de `examples/`, sem a extensão (portanto `examples/counter.tsx` fica `path="counter"`). Exemplos em React, Vue, Svelte e Astro são todos suportados; exemplos de frameworks hidratam, os de Astro renderizam estaticamente. Ele mantém a prévia e o código em sincronia a partir de um único arquivo.

A prévia é renderizada em um frame isolado que os estilos da documentação nunca alcançam — nenhuma margem de texto, tipografia ou elemento visual do tema vaza para o seu componente. O frame recebe o Tailwind (preflight + utilitários varridos do seu projeto e do seu diretório de exemplos), os tokens de design do Blume, para que classes como `bg-background` sigam a paleta do site por padrão, e ele acompanha ao vivo a alternância claro/escuro do site. O painel se dimensiona conforme o exemplo renderizado — e continua acompanhando caso o exemplo cresça ou encolha após o carregamento — com as abas Prévia e Código compartilhando uma mesma altura, de modo que alterná-las nunca desloca a página.

Para estilizar as prévias com seu próprio design system — digamos, com variáveis do shadcn — aponte `examples.css` para uma folha de estilos. Ela é injetada em cada frame de prévia após os padrões do Blume, então seus tokens prevalecem. Não use `@import "tailwindcss"` nela; o frame já fornece o Tailwind. Tanto `.dark` quanto `[data-theme="dark"]` funcionam para sobrescritas de modo escuro:

```ts
// blume.config.ts
export default defineConfig({
  examples: { css: "examples/theme.css" },
});
```

```css
/* examples/theme.css */
:root {
  --primary: oklch(0.6 0.2 260);
}

.dark {
  --primary: oklch(0.75 0.15 260);
}

@theme inline {
  --color-primary: var(--primary);
}
```

O diretório também é configurável — defina `source` (ou use a forma abreviada em string, `examples: "..."`) quando seus exemplos estiverem em outro lugar (por exemplo, um layout de registro). O `path` é sempre relativo a ele:

```ts
// blume.config.ts
export default defineConfig({
  examples: "registry/files-sdk",
});
```

```astro
<!-- registry/files-sdk/file-list/basic.tsx -->
<Component path="file-list/basic" />
```

`examples` também pode ser um glob (qualquer coisa com `*`, `?`, `[]`, `{}` ou `!`). Somente os arquivos correspondentes são descobertos, e o `path` é relativo ao prefixo estático do glob (a parte anterior ao primeiro curinga). Isso serve para um registro que coloca o código-fonte de cada componente junto ao seu exemplo — aponte apenas para os exemplos, para que os códigos-fonte, que não têm export padrão para prévia, não sejam incluídos:

```ts
// blume.config.ts
export default defineConfig({
  // registry/files-sdk/file-list/file-list.tsx — source, left out
  // registry/files-sdk/file-list/examples/basic.tsx — discovered
  examples: "registry/files-sdk/**/examples/*",
});
```

```astro
<!-- keyed relative to registry/files-sdk -->
<Component path="file-list/examples/basic" />
```

Em um monorepo, os componentes que seus exemplos importam geralmente ficam em um pacote irmão do workspace. O `@source` do Tailwind varre arquivos, não imports: o Blume varre o seu projeto e o diretório `examples` (para onde quer que `source` aponte, mesmo fora do projeto), então uma classe usada apenas dentro daquele pacote irmão não é gerada até você adicionar o pacote à varredura. Faça isso com uma diretiva `@source` no `examples.css` (para os frames de prévia) ou no `theme.css` (para o site), escrita de forma relativa ao arquivo em que ela está — a regra padrão do Tailwind — e o Blume a leva para a folha de estilos gerada:

```css
/* examples/theme.css */
@source "../../../packages/ui/src";
```

```tsx
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <button
      className="rounded-blume border-border bg-background text-foreground hover:bg-muted border px-4 py-2 text-sm font-medium transition-colors"
      onClick={() => setCount((value) => value + 1)}
      type="button"
    >
      Clicked {count} {count === 1 ? "time" : "times"}
    </button>
  );
};

export default Counter;
```

```astro
<!-- examples/counter.tsx -->
<Component path="counter" />
```

Um exemplo em Astro renderiza ao vivo sem nenhum JavaScript no cliente:

```astro
---
interface Props {
  title?: string;
}

const { title = "Hello from Astro" } = Astro.props;
---

<div class="rounded-blume border border-border bg-muted/30 px-5 py-4">
  <p class="m-0 font-semibold text-foreground text-sm">{title}</p>
  <p class="m-0 mt-1 text-muted-foreground text-sm">
    A static, server-rendered example — no client JavaScript ships.
  </p>
</div>
```

## CodeBlock

O `CodeBlock` destaca uma string de código com o mesmo tema do Shiki e os mesmos transformadores do seu código em blocos de crase — incluindo a troca claro/escuro — para lugares aonde um bloco de crase não chega, como uma página inicial ou um componente personalizado. Passe `code` e uma `lang`:

<CodeBlock
  lang="ts"
  code={`export const greet = (name: string): string =>
  \`Hello, \${name}!\`;`}
/>

```astro
---
import CodeBlock from "blume/components/content/CodeBlock.astro";
---

<CodeBlock lang="ts" code={source} />
```

Para destacar você mesmo o código em uma string HTML (por exemplo, dentro do seu próprio componente), importe o helper subjacente de `blume/markdown`:

```ts
import { highlightCode } from "blume/markdown";

const html = await highlightCode(source, "ts");
```

## Diff

O `Diff` renderiza um diff no estilo do git, destacado com o mesmo tema do Shiki dos seus blocos de código e produzido inteiramente no momento do build — sem JavaScript no cliente. Passe a ele duas strings em linha (`old` / `new`), dois caminhos de arquivo (`before` / `after`) ou um patch unificado (uma string `patch` em linha ou um arquivo `src`).

<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>

```astro
<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>
```

Compare dois arquivos do seu projeto, relativos à sua raiz:

<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />

```astro
<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />
```

Ou renderize um patch unificado — seja de um arquivo com `src`, seja em linha com `patch`:

<Diff src="diffs/greet.patch" />

```astro
<Diff src="diffs/greet.patch" />
```

```astro
<Diff
  patch={`--- a/greet.ts
+++ b/greet.ts
@@ -1,3 +1,4 @@
-export function greet(name) {
-  return "Hi, " + name;
+export function greet(name: string): string {
+  const greeting = "Hi, " + name + "!";
+  return greeting;
 }`}
/>
```

---

# Internacionalização
Source: https://useblume.dev/pt/docs/content/i18n

O Blume serve um projeto em muitos idiomas. Coloque os arquivos traduzidos no lugar certo e o Blume cuida do roteamento, do seletor de idiomas, da navegação por locale e do SEO para você — não há uma camada de roteamento separada para manter. É opcional: sem um bloco `i18n`, seu site continua em um único idioma exatamente como antes. Também se combina com o [versionamento](/docs/content/versioning) — um snapshot congelado mantém suas traduções, e o fallback de locale funciona dentro de cada versão.

## Ative o recurso

Adicione um bloco `i18n` listando seus locales e qual deles é o padrão:

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}
```

Cada locale tem um `code` (usado nas URLs), um `label` (exibido no seletor de idiomas) e um `dir` opcional para escritas da direita para a esquerda (`"ltr"` por padrão). Um `style` opcional dá ao [`blume translate`](/docs/reference/translate) orientações livres para o locale — registro, dialeto, terminologia, por exemplo `"Brazilian Portuguese, informal você"` — de modo que a escolha fica fixada desde a primeira tradução, em vez de ser decidida pelo agente.

## Organize o conteúdo traduzido

O locale padrão fica na raiz do seu conteúdo. Todos os outros locales são pastas de nível superior nomeadas pelo respectivo `code`, espelhando a estrutura padrão:

```txt
docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar
```

| Arquivo                         | Rota                    |
| ------------------------------- | ----------------------- |
| `docs/index.mdx`                | `/`                     |
| `docs/guides/quickstart.mdx`    | `/guides/quickstart`    |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

Você traduz apenas os arquivos que quiser — todo o resto recorre automaticamente ao fallback (veja [Fallbacks](#fallbacks)).

### Sufixos de nome de arquivo

Prefere manter as traduções ao lado do original? Defina `parser: "dot"` e nomeie os arquivos com um sufixo de locale em vez de usar pastas:

```txt
docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)
```

Bom para traduções esparsas — coloque as poucas páginas que você traduziu junto às originais sem espelhar a árvore inteira.

### Arquivos compartilhados

Para conteúdo que é igual em todos os idiomas — um changelog, uma página de status — adicione um marcador `$` para que um único arquivo sirva a todos os locales sem duplicação:

```txt
docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

Um `meta.ts` específico de um locale ainda substitui o compartilhado para aquele idioma.

## URLs do locale padrão

Por padrão, o locale padrão não tem prefixo de URL (`/`, `/guides/quickstart`), enquanto os outros locales são prefixados (`/fr/…`). Isso mantém limpas as URLs do seu idioma principal. Para prefixar todos os locales, incluindo o padrão:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## Navegação por locale

Cada idioma ganha sua própria barra lateral, construída a partir dos arquivos daquele locale — então as traduções podem divergir em estrutura, ordenação ou rótulos. Os arquivos [`meta.ts`](/docs/content/meta) de pasta também são resolvidos por locale: com o parser `dir` padrão, coloque um `meta.ts` em `fr/guides/` para ordenar o grupo em francês de forma independente. Com o parser `dot`, as traduções ficam ao lado das originais, portanto o `meta.ts` de uma pasta se aplica a todos os locales. Todo o resto da [navegação](/docs/content/navigation) funciona da mesma forma, por idioma.

As abas do cabeçalho são configuradas, e não derivadas do conteúdo, então seus rótulos são localizados em `blume.config.ts`: o `label` de uma aba aceita um mapa por locale (`{ en: "Docs", fr: "Documentation" }`) além da forma de string simples, recorrendo à entrada do locale padrão para os locales que você não preencheu. Veja [Abas](/docs/content/navigation#tabs).

## Fallbacks

Quando uma página ainda não foi traduzida, o Blume renderiza o conteúdo do locale de fallback na URL localizada — assim o link funciona, a página é totalmente pré-renderizada e os motores de busca não são levados a um beco sem saída. O fallback usa por padrão o seu `defaultLocale`:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}
```

Páginas de fallback são excluídas do índice de busca e não são anunciadas como traduções reais no `hreflang`, de modo que conteúdo não traduzido não concorre por posicionamento. Elas ainda aparecem na barra lateral daquele locale, então a navegação permanece completa — um leitor consegue chegar a qualquer página em qualquer idioma.

:::tip
Comece traduzindo suas páginas mais importantes — a página inicial, o guia rápido e os principais guias — e deixe o resto usar o fallback. Você pode preencher as traduções ao longo do tempo sem quebrar nenhum link.
:::

## Traduzindo com um agente

Você não precisa preencher os locales manualmente. O [`blume translate`](/docs/reference/translate) encontra todas as páginas que estão faltando ou desatualizadas em cada locale e as traduz com uma CLI de agente local ([Claude Code](https://claude.com/claude-code) ou [Codex](https://developers.openai.com/codex/cli)):

```bash
blume translate --claude
```

O Blume valida a estrutura de cada resultado — frontmatter, blocos de código, links — e escreve os arquivos ele mesmo; o agente apenas traduz o texto. Um registro versionado (`blume.translations.json`) rastreia de qual revisão de origem cada tradução veio, então as reexecuções tocam apenas o que mudou, e as traduções que você escreveu à mão são adotadas como estão, nunca sobrescritas. Em CI, `blume translate --check` falha quando uma página de origem avançou além de suas traduções.

## O seletor de idiomas

Quando a i18n está ativada, um seletor de idiomas aparece automaticamente no cabeçalho, gerado a partir dos seus `locales`. Para cada página, ele aponta para a tradução correspondente em todos os idiomas; onde falta uma tradução, ele aponta para a página de fallback e a marca como não traduzida. Não há nada para configurar.

## Interface traduzida

O Blume inclui traduções nativas para os elementos da própria interface — “Nesta página”, “Buscar”, “Editar no GitHub” e o restante — de modo que um locale com um pacote nativo já vem com a interface traduzida. **Você traduz apenas o seu conteúdo.**

Há pacotes para mais de 30 idiomas — árabe, bengali, búlgaro, catalão, chinês (simplificado e tradicional), croata, tcheco, dinamarquês, holandês, finlandês, francês, alemão, grego, hebraico, híndi, húngaro, indonésio, italiano, japonês, coreano, norueguês, persa, polonês, português (e português brasileiro), romeno, russo, sérvio, eslovaco, espanhol, sueco, tailandês, turco, ucraniano e vietnamita. Eles são mantidos pela comunidade — abra um PR para adicionar um locale ou aprimorar uma tradução.

Strings ausentes ou não incluídas recorrem ao locale padrão e, depois, ao inglês. Para substituir uma string ou fornecer seu próprio idioma, defina `i18n.ui`, com chaves por locale:

```ts blume.config.ts lineNumbers
i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}
```

## SEO

O SEO localizado é cuidado para você — não há metadados por página para escrever:

- `<html lang>` e `dir` são definidos a partir do locale ativo.
- As alternativas `hreflang` apontam para todas as traduções reais de uma página, mais um `x-default` apontando para o locale padrão.
- As URLs canônicas são corretas por locale, e o JSON-LD carrega `inLanguage`.

Defina [`deployment.site`](/docs/deployment) para que isso possa ser emitido como URLs absolutas.

## Busca

A busca é limitada ao idioma ativo: em uma página `/fr/…`, o diálogo retorna resultados em francês, com uma opção **Todos os idiomas** para buscar em todos os locales de uma vez. Os índices padrão (Orama) e FlexSearch filtram no navegador; provedores hospedados carregam uma faceta `locale` em cada registro.

## Da direita para a esquerda

Defina `dir: "rtl"` em um locale e o Blume espelha toda a interface — a barra lateral, o cabeçalho, o índice da página, a paginação, a busca e os menus — e define `<html dir>` de acordo. Duas coisas permanecem deliberadamente da esquerda para a direita: **blocos de código** (código se lê da esquerda para a direita em qualquer idioma) e **conteúdo de fallback** — uma página não traduzida mantém a direção do idioma em que ela realmente está escrita, então o inglês exibido sob um locale RTL continua legível enquanto os elementos ao redor são espelhados.

## Para onde ir agora

**[Navegação](/docs/content/navigation)**

Molde a barra lateral, a ordenação e as abas de cada locale.

**[SEO](/docs/configuration/seo)**

Sitemaps, Open Graph e dados estruturados.

---

# Includes
Source: https://useblume.dev/pt/docs/content/includes

Escreva um trecho uma vez e insira ele em qualquer página. Uma instrução `<include>` em sua própria linha embute outro arquivo no momento do build, como se o conteúdo estivesse escrito ali mesmo — os títulos entram no sumário da página, o texto é indexado pela busca, e o conteúdo aparece no espelho `.md` da página e no llms-full.txt.

```mdx
<include>./_snippets/prerequisites.mdx</include>
```

O caminho é resolvido em relação ao arquivo que faz o include. Caminhos que começam com `/` são resolvidos a partir da raiz do seu conteúdo, então páginas em níveis profundos podem referenciar trechos compartilhados sem cadeias de `../../..`:

```mdx
<include>/_snippets/prerequisites.mdx</include>
```

A sintaxe é igual à do Fumadocs, então conteúdo migrado funciona sem alterações.

Veja funcionando na prática — este próximo destaque vem de um trecho compartilhado:

:::tip
Este aviso mora em `_snippets/include-demo.mdx` — ele aparece aqui porque a página o insere com uma instrução `<include>`.
:::

## Parciais

Qualquer arquivo cujo nome (ou pasta) comece com underscore fica excluído do roteamento, da navegação, da busca e dos sitemaps por padrão — essa convenção é o lar natural dos trechos compartilhados:

```text
docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx
```

Uma parcial é um arquivo Markdown ou MDX normal. O front matter dela é removido na inserção (o front matter da página que faz o include prevalece), e todo o resto — destaques, blocos de código, componentes, fórmulas matemáticas — é renderizado exatamente como seria inline. Parciais podem incluir outras parciais; um include circular é reportado como erro.

Referências relativas a imagens dentro de uma parcial continuam funcionando: elas são rebaseadas para a página que faz o include, então um `![diagrama](./diagram.png)` colocado ao lado da parcial é resolvido onde quer que a parcial seja inserida.

Editar uma parcial enquanto o `blume dev` está rodando recarrega todas as páginas que a incluem.

## Incluindo arquivos de código

Um alvo que não seja `.md`/`.mdx` é embutido como um bloco de código cercado, com a linguagem inferida da extensão. Use `lang` para sobrescrever a linguagem (ou para mostrar um arquivo Markdown como código-fonte em vez de inseri-lo), e `meta` para passar uma string de meta da cerca, como um título:

```mdx
<include>./examples/config.ts</include>

<include lang="ts" meta='title="blume.config.ts"'>
  ../blume.config.ts
</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>
```

## Regras e diagnósticos

Instruções de include precisam ocupar a própria linha — elas são de nível de bloco, não inline. Instruções dentro de blocos de código cercados são ignoradas, então você pode documentar a própria sintaxe (como esta página faz).

Os alvos precisam estar dentro da raiz do seu conteúdo: um arquivo fora dela ficaria silenciosamente ausente dos snapshots de versão e de projetos ejetados, então o `blume` reporta `BLUME_INCLUDE_OUTSIDE_ROOT` em vez de inseri-lo. Um alvo que não existe gera `BLUME_INCLUDE_NOT_FOUND`, e um laço de includes gera `BLUME_INCLUDE_CYCLE` — os três fazem o `blume build` falhar (passe `--no-strict` para buildar mesmo assim) e aparecem no `blume validate`.

Links quebrados dentro de uma parcial são reportados no arquivo da parcial, não nas páginas que a inserem, então você corrige onde eles realmente vivem.

:::note
Parciais são compartilhadas entre os idiomas e não são traduzidas pelo `blume translate` — mantenha as parciais neutras em relação ao idioma (código, tabelas, diagramas), ou crie parciais por idioma e inclua elas a partir das páginas de cada idioma.
:::

---

# Ilhas
Source: https://useblume.dev/pt/docs/content/islands

O Blume renderiza sua documentação como HTML estático com **zero JavaScript** por padrão. Quando você precisa de algo interativo — uma demonstração ao vivo, um gráfico, um playground — você adiciona uma **ilha**: um componente de framework que envia JS apenas para si mesmo, apenas nas páginas que o utilizam.

## A convenção `islands/`

Coloque um componente em uma pasta `islands/` na raiz do seu projeto. O nome do arquivo se torna um componente que você pode usar em **qualquer** página `.mdx`, sem importação:

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Clicked {count}</button>;
}
```

```mdx page.mdx
Here's a live counter: <Counter />
```

O nome do arquivo é o nome do componente, então ele **deve ser um identificador em PascalCase** — apenas letras, dígitos e sublinhados (`Counter.tsx` → `<Counter />`). Nomes de arquivo em minúsculas, nomes com traços/pontos/espaços (como `Time-Picker.tsx`) e duas ilhas que resolvem para o mesmo nome são ignorados com um aviso de compilação.

:::note
Ilhas são para UI **interativa**. Para um componente estático que você reutiliza entre páginas (um destaque estilizado, uma tabela de preços), use uma [substituição MDX](/docs/configuration/customization) em vez disso — ela não envia nenhum JavaScript.
:::

## Registrando ilhas em `components.ts`

Se você preferir manter as ilhas junto ao restante dos seus componentes — ou dar a elas um nome diferente do arquivo — registre-as com `defineComponents`. O grupo `islands` é exatamente como a pasta `islands/`: cada entrada está disponível em todas as páginas MDX e é hidratada (com padrão `client: "visible"`).

```ts components.ts
import { defineComponents } from "blume";
import Counter from "./widgets/Counter.tsx";

export default defineComponents({
  islands: {
    Counter, // <Counter /> in any MDX page, hydrated
  },
});
```

Referencie o componente por importação ou por uma string de caminho, e defina um modo de hidratação por ilha com a forma de descritor:

```ts components.ts
export default defineComponents({
  islands: {
    Chart: { component: "./widgets/Chart.tsx", client: "only" },
  },
});
```

## Hidratação

Por padrão, uma ilha usa `client:visible`: ela é hidratada quando o leitor a rola até o campo de visão, então uma página cheia de ilhas ainda carrega instantaneamente. Opte por uma estratégia diferente com um `export const client` no arquivo da ilha:

```tsx islands/Chart.tsx lineNumbers
// Skip server rendering entirely — for components that touch the DOM/window.
export const client = "only";

export default function Chart() {
  /* ... */
}
```

| Valor de `client` | Hidrata | Use para |
| --- | --- | --- |
| `"visible"` _(padrão)_ | Quando rolado até o campo de visão | A maioria das ilhas |
| `"load"` | Imediatamente ao carregar a página | UI acima da dobra, que deve ser instantânea |
| `"idle"` | Quando a thread principal está ociosa | Interatividade não urgente |
| `"only"` | Apenas no cliente, nunca renderizado no servidor | Bibliotecas que precisam de `window`/`document` (gráficos, editores) |

## Frameworks

**O React funciona de imediato** — o Blume o ativa automaticamente assim que seu projeto contém uma ilha `.tsx`/`.jsx`.

O [React Compiler](https://react.dev/learn/react-compiler) está ativado por padrão sempre que o React está habilitado, então suas ilhas são memoizadas automaticamente — sem necessidade de `useMemo`/`useCallback` escritos à mão. Ele vem com o Blume; não há nada para instalar. Desative em `blume.config.ts`:

```ts blume.config.ts
export default defineConfig({
  react: { compiler: false },
});
```

**Vue e Svelte** também são suportados; instale a integração Astro correspondente e o Blume configura o renderizador quando encontra uma ilha `.vue` ou `.svelte`:

```bash
# Vue
npm install @astrojs/vue vue

# Svelte
npm install @astrojs/svelte svelte
```

```vue islands/Toggle.vue lineNumbers
<script setup>
import { ref } from "vue";
const on = ref(false);
</script>

<template>
  <button @click="on = !on">{{ on ? "On" : "Off" }}</button>
</template>
```

As props que você passa no MDX (`<Counter start={5} />`) são encaminhadas ao componente, e os filhos (`<Counter>label</Counter>`) chegam como o slot padrão.

:::tip
As ilhas são hidratadas no cliente, então qualquer coisa que você passe como prop deve ser serializável — strings, números, objetos simples, não funções.
:::

## Hooks

As ilhas são hidratadas por conta própria, então não há contexto do React para conduzir os dados do projeto. Em vez disso, `blume/hooks` lê um pequeno snapshot que o layout serializa na página — sem props para repassar:

```tsx islands/PageInfo.tsx lineNumbers
import { useBlume, usePage } from "blume/hooks";

export default function PageInfo() {
  const blume = useBlume();
  const page = usePage();
  if (!(blume && page)) {
    return null;
  }
  return (
    <p>
      You're reading <strong>{page.title}</strong> on {blume.config.title}.
    </p>
  );
}
```

| Hook | Retorna |
| --- | --- |
| `useBlume()` | `{ config, navigation }` do site, ou `null` antes da montagem |
| `usePage()` | `{ route, title }` da página atual, ou `null` antes da montagem |
| `useSearch()` | `{ search, results, loading }` — consulta o provedor de busca configurado |
| `useAskAI()` | `{ ask, messages, loading, reset }` — transmite a partir do endpoint Ask AI |

`useBlume()` e `usePage()` retornam `null` até que a ilha seja montada (para que servidor e cliente renderizem o mesmo primeiro quadro) — proteja-se contra isso. O snapshot é emitido apenas em páginas que enviam React, então um site totalmente estático não paga nada.

Em [páginas personalizadas](/docs/advanced/custom-pages) construídas com `PageLayout`, passe `clientData` para que as ilhas ali possam lê-lo:

```astro
<PageLayout
  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
  {/* …other props… */}
/>
```

---

# Meta de pasta
Source: https://useblume.dev/pt/docs/content/meta

Toda pasta na sua árvore de conteúdo se torna um grupo da barra lateral. Coloque um `meta.ts` junto às suas páginas para controlar a aparência desse grupo e a ordenação de seus filhos. É totalmente opcional: sem ele, o rótulo do grupo é o nome da pasta humanizado e suas páginas são ordenadas por [índice, prefixo numérico e, então, alfabeticamente](/docs/content/navigation#ordering).

## Definindo o meta

Exporte um objeto `defineMeta` para obter uma configuração totalmente tipada. Coloque o arquivo na raiz da pasta que ele configura — `guides/meta.ts` configura o grupo **Guias**:

```ts meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});
```

Todos os campos são opcionais — defina apenas o que você quiser sobrescrever.

## Campos

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `title` | `string` | O rótulo do grupo. O padrão é o nome da pasta humanizado. |
| `icon` | `string` | Ícone exibido ao lado do rótulo. |
| `order` | `number` | Posição entre grupos e páginas irmãos. Números menores vêm primeiro. |
| `collapsed` | `boolean` | Sob o [modo de exibição `group`](/docs/content/navigation#display-modes), define se o grupo começa recolhido. |
| `display` | `"flat" \| "group" \| "page"` | Modo de renderização deste grupo; sobrescreve o [`navigation.sidebar.display`](/docs/content/navigation#display-modes) global. |
| `pages` | `string[]` | Ordem explícita dos filhos do grupo, por slug. |

O array `pages` lista os filhos por slug — o nome da pasta ou do arquivo com o prefixo numérico e quaisquer parênteses removidos (portanto `01-quickstart.mdx` é `"quickstart"`). Os filhos que você deixar de fora ainda aparecem, depois dos listados.

Como os grupos são renderizados — cabeçalhos planos, blocos recolhíveis ou painéis de navegação em profundidade — o padrão é o `navigation.sidebar.display` de toda a barra lateral; defina `display` aqui para sobrescrevê-lo apenas para este grupo. A página `index` de uma pasta também pode defini-lo pelo frontmatter, o que tem precedência sobre o `meta.ts` — veja [sobrescritas por grupo](/docs/content/navigation#per-group-overrides).

## Meta computado

Como `meta.ts` é um módulo de verdade, você pode computar o meta — passe uma função (síncrona ou `async`) em vez de um objeto para construí-lo no momento da varredura. Prático para ordenar páginas a partir de uma fonte externa:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));
```

## Ordenação dentro de um grupo

O array `pages` define a ordem dos filhos de um grupo. Tudo que ele omitir recorre ao `sidebar.order` do frontmatter de cada página e, em seguida, ao sistema de arquivos (uma página `index` primeiro, depois os prefixos numéricos e então a ordem alfabética). Para a precedência completa da barra lateral — incluindo uma barra lateral explícita na configuração — veja [Navegação › Ordenação](/docs/content/navigation#ordering).

Para agrupar páginas _sem_ adicionar um segmento de URL, você não precisa de um `meta.ts`: use um nome de pasta entre parênteses — veja [Páginas › Pastas de grupo](/docs/content#group-folders).

## Internacionalização

Sob o [i18n](/docs/content/i18n), o meta de pasta é resolvido por locale: coloque um `meta.ts` em `fr/guides/` para ordenar o grupo em francês de forma independente.

Para um meta de pasta idêntico em todos os idiomas, adicione um marcador `$` para que um único arquivo sirva a todos os locales sem duplicação:

```txt
docs/guides/meta.$.ts   (folder meta applied to every locale)
```

Um `meta.ts` específico de locale ainda sobrescreve o `meta.$.ts` compartilhado para aquele idioma.

## Para onde ir agora

**[Navegação](/docs/content/navigation)**

Como a barra lateral, as trilhas de navegação e as abas são construídas.

**[Frontmatter](/docs/reference/frontmatter)**

Metadados por página, incluindo as sobrescritas de `sidebar`.

---

# Navegação
Source: https://useblume.dev/pt/docs/content/navigation

O Blume monta sua barra lateral a partir do sistema de arquivos e depois permite refiná-la tanto — ou tão pouco — quanto você quiser: página por página, pasta por pasta ou com uma configuração explícita. Trilhas de navegação, links de anterior/próximo e o sumário da página derivam todos do mesmo modelo, sem nada para conectar manualmente.

## A barra lateral gerada

Por padrão, a barra lateral espelha a sua árvore de conteúdo:

- pastas viram **grupos**, arquivos viram **páginas**
- o rótulo de uma página é o `title` do seu frontmatter; o rótulo de um grupo é o nome humanizado da pasta
- os itens são ordenados por [prefixo numérico](/docs/content) e depois alfabeticamente, e a página `index` de uma pasta vem primeiro

Isso já basta para muitos sites — tudo abaixo é opcional.

## Rótulo, ícone e selo da página

Ajuste como uma única página aparece na barra lateral a partir do seu frontmatter, sob `sidebar`:

```yaml lineNumbers
sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group
```

Veja [Frontmatter](/docs/reference/frontmatter) para o esquema completo da página.

## Grupos de pastas

Cada pasta vira um grupo na barra lateral. Coloque um [`meta.ts`](/docs/content/meta) junto às suas páginas para definir o título, o ícone, a ordem do grupo e a ordem dos seus filhos:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

Veja [Meta de pasta](/docs/content/meta) para todos os campos e para computar meta no momento da varredura.

O `meta.title` de uma pasta e o `title` do frontmatter da sua própria página `index` são resolvidos de forma independente — traduzir um sob i18n e esquecer o outro renderiza uma barra lateral correta, mas com um `<title>`/título desatualizado na própria página de destino. O Blume emite um aviso `BLUME_NAV_INDEX_TITLE_MISMATCH` quando eles divergem. Páginas não traduzidas preenchidas a partir do idioma de fallback são isentas — o título delas pertence ao idioma de fallback, e a correção é traduzir a página, não editar o frontmatter dela.

Para agrupar páginas _sem_ adicionar um segmento de URL, use um nome de pasta entre parênteses — veja [Páginas](/docs/content#group-folders).

## Modos de exibição

`navigation.sidebar.display` define como cada grupo da barra lateral é renderizado:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`** (padrão) — um cabeçalho não recolhível com suas páginas listadas abaixo. Páginas que não pertencem a nenhum grupo sempre aparecem primeiro, acima das seções de grupo, para que não sejam confundidas com filhos de um grupo.
- **`group`** — um bloco recolhível `<details>` por grupo. Os grupos começam recolhidos por padrão; um grupo que contém a página atual sempre começa aberto, de modo que apenas a seção em que você está fica expandida. Defina `collapsed: false` no [meta de pasta](/docs/content/meta) para forçar um grupo a ficar aberto independentemente disso.
- **`page`** — cada grupo é uma única linha que, ao ser clicada, desliza a barra lateral para um subpainel mostrando apenas os itens daquele grupo, com uma seta de voltar no topo. O painel reconhece a rota, então cair diretamente em uma página dentro do grupo abre direto nela.

:::tip
O modo `page` mantém seções profundas organizadas — use-o quando os grupos tiverem muitos filhos e você preferir navegar dentro deles a rolar por eles.
:::

### Substituições por grupo

Qualquer grupo gerado pode abrir mão do modo global — sem precisar de uma barra lateral explícita. Defina `display` no [`meta.ts`](/docs/content/meta) da pasta ou — quando a pasta tem uma página `index` — sob `sidebar` no frontmatter dessa página, e apenas aquele grupo muda:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

O modo efetivo de um grupo gerado é resolvido da maior prioridade para a menor:

1. `sidebar.display` no frontmatter da própria página `index` do grupo
2. `display` no `meta.ts` da pasta
3. O `navigation.sidebar.display` global
4. O padrão do Blume (`flat`)

O `display` de um grupo se aplica somente àquele grupo — subgrupos aninhados resolvem seu próprio valor pela mesma cadeia. Um grupo em modo `page` com uma página de índice ainda navega para o seu subpainel: a página de índice aparece como o primeiro item do painel, e cair na URL dela abre o painel diretamente.

`sidebar.display` não significa nada em nenhum outro lugar — em uma página que não seja de índice, na própria página `index` da raiz do conteúdo (a raiz não é um grupo; use `navigation.sidebar.display`) ou em qualquer página quando uma [barra lateral explícita](#explicit-sidebar) estiver configurada (seus itens são donos do modo de cada grupo) — então o Blume emite um aviso `BLUME_SIDEBAR_DISPLAY_IGNORED` em vez de descartá-lo silenciosamente. `collapsed` continua específico do modo `group`; ele fica inerte quando um grupo resolve para `flat` ou `page`.

Um grupo em uma [barra lateral explícita](#explicit-sidebar) substitui o modo global com seu próprio `display`, exatamente como antes.

## Ordenação

Quando a barra lateral é gerada, a ordem é resolvida da maior prioridade para a menor:

1. **Barra lateral da configuração**

    Um `navigation.sidebar` explícito substitui inteiramente a árvore gerada.

2. **Meta de pasta**

    O array `pages` em `meta.ts` ordena um grupo.

3. **Frontmatter**

    `sidebar.order` em uma página.

4. **Sistema de arquivos**

    Uma página `index` primeiro, depois prefixos numéricos, depois em ordem
    alfabética por rótulo.

Dois irmãos que acabam com a mesma ordem explícita ou numérica recorrem à ordem alfabética entre si — o Blume emite um aviso `BLUME_DUPLICATE_SIDEBAR_ORDER` para que o empate não passe despercebido.

## Páginas ocultas

Oculte uma página da barra lateral — e da paginação de anterior/próximo — mantendo-a construída e acessível pela sua URL:

```yaml
sidebar:
  hidden: true
```

## Abas

Renderize seções de nível superior como abas no cabeçalho, útil para dividir um site grande em áreas distintas — digamos, adaptadores, uma API e guias de IA. Uma aba fica destacada quando a rota atual está sob o seu `path`:

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

Uma [referência OpenAPI ou AsyncAPI](/docs/advanced/api-reference) habilitada é montada na sua rota, mas não adiciona uma aba por conta própria — aponte uma aba para essa rota para exibi-la no cabeçalho (e, para o renderizador nativo, para delimitar a barra lateral de operações), com o rótulo que você quiser:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

O `path` de uma aba é o prefixo da sua seção, e ele também serve como destino do link. Uma seção cujo `path` não é uma página própria — uma pasta sem `index.mdx` — apontaria para um 404, então a aba recorre à primeira página da seção. Defina `href` quando quiser que ela leve a outro lugar:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

Isso importa para rotas que não fazem parte da árvore de conteúdo, já que o fallback não as enxerga: o índice de [changelog](/docs/advanced/changelog) gerado, ou uma [página personalizada](/docs/advanced/custom-pages) que você adicionou sob `pages/`. Sem `href`, uma aba `/changelog` cai na entrada mais recente em vez do índice. Abas que não definem `href` não são afetadas.

Em um site com [i18n](/docs/content/i18n), o `label` de uma aba (e o de um item de dropdown) pode ser um mapa por idioma em vez de uma string — a entrada do idioma ativo prevalece, depois a do idioma padrão:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}
```

As abas também **delimitam a barra lateral**: quando a rota atual está sob o `path` de uma aba, a barra lateral mostra apenas as páginas daquela seção — então `/adapters/*` lista os adaptadores e nada mais. A pasta no `path` de uma aba se torna a seção, então isso não requer nenhuma configuração além das próprias abas; estruture seu conteúdo em uma pasta por aba e aponte cada aba para ela.

Em uma rota que não está sob nenhuma aba (ou sob uma aba cujo `path` é `/`), a barra lateral mostra as páginas que _não_ pertencem a uma aba — a pasta de cada aba fica oculta dela, já que aquela seção já tem sua própria aba no cabeçalho. Assim, uma página inicial na raiz lista suas páginas soltas de nível superior enquanto o conteúdo seccionado permanece atrás da sua aba, espelhando as pastas raiz do Fumadocs. Se uma rota não tiver páginas próprias para mostrar dessa forma, a árvore completa é exibida em vez disso, de modo que a barra lateral nunca fica em branco.

## Seletores

Para alternar entre partições inteiras de um site — um produto, uma versão ou qualquer conjunto agrupado de destinos — adicione um `selector`. Cada um é renderizado como um dropdown no cabeçalho, mostrando a opção cujo `path` corresponde à rota atual:

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

Cada item recebe um `label`, um `path` e, opcionalmente, `icon`, `description` e `tag`. `kind` (`dropdown`, `product`, `version` ou `language`) é uma indicação de como o seletor é usado; todos renderizam o mesmo dropdown.

Com [versionamento](/docs/content/versioning) configurado, o Blume renderiza um seletor de versão automaticamente — declarar aqui o seu próprio seletor `kind: "version"` substitui o automático, então configurações feitas à mão continuam funcionando.

## Links em destaque

Fixe links no topo da barra lateral, acima de todas as seções — um blog, um changelog, uma página de contato ou suporte que deva estar sempre a um clique de distância. Diferentemente da árvore gerada, os links em destaque **não são delimitados por aba**: eles aparecem em todas as rotas, em todos os breakpoints.

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

Cada link recebe um `label`, um `href` e um `icon` opcional (um nome de [ícone integrado](/docs/content/components#icon), caminho/URL de imagem ou SVG inline — o mesmo que em qualquer outro lugar). Um `href` pode apontar para qualquer lugar: uma URL externa abre em uma nova aba, enquanto uma rota interna (`/contact`) é validada contra as suas páginas no momento da build, avisando você se nada corresponder.

## Barra lateral explícita

Para controle total, liste itens explícitos em `navigation.sidebar` — um array simples é um atalho para `sidebar.items`, e a forma de objeto os combina com um [`display`](#display-modes) global. Quando os itens são definidos, o Blume os usa literalmente e pula a geração pelo sistema de arquivos:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}
```

Cada item é uma rota de página (uma string), um grupo (`label` + `items`) ou um link (`label` + `href`). Grupos podem ser aninhados, substituir o [modo `display`](#display-modes) global e começar `collapsed`.

## Ações do cabeçalho

`navigation.actions` coloca links simples no cabeçalho, à esquerda dos botões de ícone, e `navigation.cta` é o único botão preenchido:

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

`cta` é singular de propósito — um cabeçalho de documentação tem espaço para exatamente uma coisa que se pede ao leitor que faça, e uma fileira de botões não pede nada. Links secundários pertencem a `actions`, ou a [`featured`](#featured-links) se devem ficar junto à barra lateral.

Um href `http(s)` ou relativo ao protocolo abre em uma nova aba; uma rota permanece na aba e é validada contra as suas páginas no momento da build, como um link `featured` — então uma página servida por outro app no mesmo host (`/signup` no produto, digamos) deve ser escrita como uma URL absoluta. As `actions` ficam ocultas abaixo do breakpoint `sm`, onde o cabeçalho tem espaço para o logo e o alternador de navegação e nada mais. O `cta` também se oculta ali, exceto em uma página sem alternador de navegação — uma landing page em `PageLayout` sem abas — onde ele permanece, já que nada mais pode exibi-lo em um celular.

## Link do repositório

Quando você define [`github`](/docs/configuration) na sua configuração, o Blume mostra um ícone do GitHub no cabeçalho — ao lado do alternador de tema — que leva ao seu repositório. Ele vem ativado por padrão; oculte-o com `navigation.repo`:

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // hide the header GitHub link (default: true)
}
```

O link só aparece quando `github` está configurado, então projetos sem repositório não são afetados de nenhuma forma.

`repo` também aceita uma URL absoluta, que aponta a marca do cabeçalho para qualquer lugar no GitHub:

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

Isso é para um projeto cujo repositório de documentação é privado. O `github` controla junto o link de edição de cada página, a marca do cabeçalho e o repositório do [manifesto de agente](/docs/configuration/ai), então um projeto assim precisa deixar `github` sem definir — e uma URL é o que permite que ele ainda exiba uma marca apontando para algo público. O ícone continua sendo a marca do GitHub, então um link para outro host pertence a [`actions`](#header-actions).

## Trilhas de navegação e paginação

Elas vêm de graça a partir da árvore da barra lateral — sem configuração:

- **Trilhas de navegação** mostram o grupo pai da página atual acima do título.
- **Links de anterior e próximo** no rodapé de cada página seguem a ordem da barra lateral, pulando páginas ocultas.

## Nesta página

Um sumário na coluna direita é gerado automaticamente a partir dos títulos `##` e `###` de cada página, para que páginas longas continuem fáceis de escanear. Em telas mais estreitas, onde a coluna direita fica oculta, ele se recolhe em um dropdown “Nesta página” acima do conteúdo.

## Ações da página

Abaixo do sumário, toda página exibe um conjunto de ações rápidas:

- **Editar no GitHub** — leva direto ao arquivo-fonte. Aparece assim que você define [`github`](/docs/configuration) na sua configuração.
- **Voltar ao topo** — retorna suavemente ao topo de páginas longas.
- **Enviar feedback** — abre uma issue do GitHub pré-preenchida com uma reação e uma nota opcionais (também requer `github`).

Outras entregam a página a ferramentas de IA — **Copiar como Markdown** e **Abrir no chat** — abordadas em [IA](/docs/configuration/ai#copy-as-markdown).

Com [`export`](/docs/configuration/export) ativado, uma ação de **Exportar** também permite que os leitores baixem a página como PDF ou EPUB.

---

# Fontes de conteúdo
Source: https://useblume.dev/pt/docs/content/sources

Por padrão, o Blume lê uma pasta de arquivos `.md`/`.mdx`. As **fontes de conteúdo** permitem trazer páginas de outro lugar — um repositório remoto, um CMS ou qualquer backend personalizado — e combinar várias fontes em um único site. As fontes são lidas em tempo de build; o Blume continua static-first.

## O padrão

Sem nenhuma configuração, o Blume varre a raiz do seu conteúdo (`docs`, por padrão) como uma única fonte de sistema de arquivos implícita. As opções de nível superior `content.root`/`include`/`exclude` continuam funcionando exatamente como antes — nada a mudar.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: { root: "docs" },
});
```

## Múltiplas fontes

Adicione um array `content.sources` para compor fontes. Cada entrada recebe um namespace por meio de um `prefix` opcional, de modo que suas rotas fiquem aninhadas sob `/<prefix>/…`. Quando `sources` está presente, ele substitui o padrão implícito, portanto inclua uma entrada `filesystem` para a sua documentação local.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      // Local docs at the site root
      { type: "filesystem", root: "docs" },

      // Remote MDX from a GitHub repo, mounted under /sdk
      {
        type: "mdx-remote",
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      },
    ],
  },
});
```

Se duas fontes resolverem para a mesma rota, o Blume reporta um erro de build `BLUME_DUPLICATE_ROUTE` — dê a cada fonte um `prefix` distinto.

## Obsidian

A fonte integrada `obsidian` lê um vault do [Obsidian](https://obsidian.md) no lugar onde ele está. Não há etapa de exportação nem nada gerado dentro do seu repositório: o vault continua sendo a fonte da verdade, e o Blume reduz o dialeto do Obsidian a Markdown conforme carrega.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "obsidian",
        prefix: "notes",
        vault: "vault",
        // Vault folder names to skip at any depth, on top of dot-folders
        exclude: ["Templates", "Daily"],
      },
    ],
  },
});
```

Os `[[Wikilinks]]` viram links de rota, endereçados pelo nome da nota em todo o vault em vez de pelo caminho, do jeito que o Obsidian endereça as notas. Texto de link personalizado (`[[Note|label]]`), âncoras de cabeçalho (`[[Note#Install]]`), caminhos completos (`[[folder/Note]]` e `[[folder/Note.md]]`), os caminhos parciais que a configuração padrão "shortest path when possible" do Obsidian escreve (`[[guides/Note]]`) e a forma `[[Note\|label]]` que o Obsidian escreve dentro de uma célula de tabela — tudo funciona; e uma nota que define `slug` no frontmatter é linkada na rota que esse slug publica. Quando duas notas compartilham um nome, vence a nota cujo caminho completo no vault é exatamente esse nome — o Obsidian resolve um link como caminho antes de resolver como nome — e depois a primeira na ordem do vault (pastas antes de notas, sem diferenciar maiúsculas de minúsculas, como o explorador de arquivos do Obsidian). O Blume avisa apenas quando um wikilink de fato é resolvido por meio de uma colisão dessas; escreva um caminho mais longo para desambiguar. Uma referência de bloco (`[[Note#^id]]`) leva à nota dela sem âncora: os blocos são renderizados sem id em que aterrissar. Uma âncora de cabeçalho é resolvida contra os cabeçalhos reais da nota de destino, correspondidos do jeito que o autocomplete do Obsidian os escreve (com `**bold**`, `` `code` `` e sintaxe de link removidos) e convertidos em slug pela mesma passagem `extractHeadings` que preenche o manifesto da página — de modo que um link para `#Install` cai no cabeçalho, e não em um id que nenhuma página emite. `[[#Install]]` endereça um cabeçalho na própria nota que você está escrevendo. Um link para um cabeçalho que não existe mantém o link da página, descarta a âncora e emite um aviso.

O frontmatter mantém o que o [esquema de página](/docs/reference/frontmatter) do Blume aceita, mais qualquer chave que você declare em [`frontmatter.extend`](/docs/reference/frontmatter#custom-keys) (ou, para notas daquele `type`, o `frontmatter` de um tipo de conteúdo); toda outra propriedade do Obsidian — campos do Dataview, datas do Templater, `publish` e os próprios `tags`, `aliases` e `cssclasses` do Obsidian — é descartada quando uma nota é reduzida, então um vault escrito com a UI de Properties compila sem erros de frontmatter. `aliases` é descartado em vez de resolvido — alvos de link por alias ainda não são suportados. Uma imagem Markdown relativa ao lado de uma nota (`![chart](./chart.png)`) é servida a partir do vault e, quando o vault fica dentro do seu repositório git, as páginas do vault ganham [datas de "Última atualização"](/docs/configuration#last-modified) derivadas do git, como qualquer outra página. Os links de "Editar esta página" são resolvidos por meio de `github.dir`, então um vault que fica ao lado do app de documentação em um monorepo ainda linka para o arquivo dele; um vault fora do repositório não recebe link.

Diretórios de idioma e snapshots de versão dentro do vault são lidos do mesmo jeito que a fonte de sistema de arquivos os lê: `fr/Note.md` publica sob `/fr/` com [i18n](/docs/content/i18n) configurado, `v1.0/Note.md` sob `/v1.0/` com [versões](/docs/content/versioning), e wikilinks para essas notas apontam para a rota que cada uma publica.

:::note
Um cabeçalho que contém um link recebe sua âncora de manifesto a partir do Markdown do cabeçalho e seu `id` renderizado a partir do conteúdo de texto. Os dois divergem nesse cabeçalho, então um wikilink para ele pode cair na página em vez de na seção.
:::

Um link para uma nota `index` cai na rota da pasta dela, em vez de em um `/index` fantasma. **Um wikilink não resolvido degrada para texto simples com um aviso de build, em vez de quebrar o build**, então um vault no meio de uma refatoração ainda publica. `%%comments%%` de uma única linha são removidos, um wikilink dentro de um comentário HTML (`<!-- [[Draft]] -->`) é deixado em paz, já que o Obsidian também o esconde, e uma nota sem `title` no frontmatter é intitulada pelo nome do arquivo — a mesma regra que o próprio Obsidian aplica. Uma nota `index` é a única exceção: ela nomeia uma rota, e não uma nota, então o título dela recai na derivação usual do Blume (primeiro cabeçalho, depois o segmento humanizado). Código em blocos cercados, indentado e inline passa literalmente, então uma nota que documenta a sintaxe sobrevive.

Pastas que começam com ponto são ignoradas, incluindo o próprio diretório de configuração `.obsidian` do Obsidian e a `.trash` — que o watcher de desenvolvimento também ignora, então mover um painel no app ou mandar uma nota para a lixeira não refaz o build do seu site. Editar uma nota, sim. Os diretórios que nenhuma varredura de conteúdo lê (`node_modules`, `dist`, `.git`, …) também são ignorados, então um vault com raiz no próprio projeto não publica os READMEs das dependências. Symlinks dentro do vault são seguidos, do mesmo jeito que a fonte de sistema de arquivos os segue, então uma pasta compartilhada linkada no vault é publicada junto. Um vault que fica dentro de `content.root` precisa ser excluído da fonte de sistema de arquivos (`exclude: ["vault/**"]`); o `blume version cut` então o deixa de fora do snapshot, já que o vault continua publicando as próprias notas como atuais.

Ainda não reduzidos: callouts (`> [!note]`) são renderizados como blockquotes simples, embeds (`![[image.png]]`) passam intocados, `%%comments%%` de várias linhas são deixados no lugar e não há grafo de backlinks.

## MDX remoto

A fonte integrada `mdx-remote` busca arquivos `.md`/`.mdx` brutos via HTTP. Enumere os arquivos a partir de uma subárvore de um repositório do GitHub (`github`) ou explicitamente contra uma URL base bruta (`url` + `files`):

```ts blume.config.ts
{
  type: "mdx-remote",
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
}
```

O token de um repositório privado é lido da variável de ambiente `GITHUB_TOKEN` — ele nunca é embutido na sua configuração ou na saída gerada, e é enviado somente para os próprios hosts do GitHub (`api.github.com`, `raw.githubusercontent.com`), nunca para uma base `url` personalizada.

As páginas remotas são renderizadas com fidelidade total de MDX-mais-componentes: seus corpos são materializados em um diretório de staging oculto e renderizados pelo Astro junto com a sua documentação local, de modo que callouts, abas e todos os demais componentes do Blume continuam funcionando.

### Cache e builds offline

Cada fonte remota mantém um snapshot em `.blume/cache/<source>/`. Se uma busca falhar — uma instabilidade de rede ou uma indisponibilidade do CMS — o Blume serve o último snapshot válido conhecido com um aviso, em vez de quebrar o build. O cache fica dentro de `.blume/` e é regenerado, nunca versionado.

Em desenvolvimento, o conteúdo remoto é buscado uma vez e congelado durante a sessão; reinicie o servidor de desenvolvimento para atualizá-lo. As fontes locais do sistema de arquivos recarregam a quente normalmente. Para, em vez disso, consultar periodicamente uma fonte remota em busca de alterações, defina `pollInterval` (em segundos) nela — o servidor de desenvolvimento refaz a busca nesse intervalo e recarrega apenas quando o conteúdo realmente muda. Deixe-o sem definir para evitar chamadas à API enquanto você trabalha.

## GitHub Releases

A fonte integrada `github-releases` transforma as releases de um repositório em um changelog: cada release vira uma entrada `type: changelog`, de modo que suas notas de versão _são_ o seu changelog — nada a escrever duas vezes. Combinado com a [linha do tempo de changelog](/docs/advanced/changelog) gerada, publicar uma release no GitHub entrega uma entrada de changelog.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // include prereleases (default off)
        // drafts: false,       // include drafts (needs a write token)
        // limit: 100,          // cap releases, newest-first
      },
    ],
  },
});
```

Cada release é mapeada automaticamente para os campos do changelog: seu nome (ou tag) vira o título, sua data de publicação define a ordem da linha do tempo, a tag vira `changelog.version`, e as prereleases são marcadas como `Prerelease` (as demais como `Release`). As notas são renderizadas como o corpo da entrada. Dê à fonte um `prefix` para que suas páginas de release fiquem aninhadas sob uma rota como `/changelog/v1-2-0`.

Um repositório privado se autentica com a variável de ambiente `GITHUB_TOKEN` — o mesmo token que os outros recursos do GitHub usam, nunca embutido na sua configuração. Como toda fonte remota, ela é armazenada em cache em `.blume/cache/<source>/` e servida offline se a API estiver inacessível. Como um changelog é complementar, uma falha de busca sem cache (digamos, um build de CI sem token) degrada para um changelog vazio com um aviso, em vez de quebrar o build — defina `GITHUB_TOKEN` nos seus ambientes de CI e de deploy para preenchê-lo.

## Sanity

A fonte integrada `sanity` executa uma consulta GROQ e mapeia os campos de cada documento para o frontmatter e seu corpo em Portable Text para Markdown. O pacote `@sanity/client` é uma dependência peer opcional — instale-o apenas se você usar esta fonte.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "sanity",
        prefix: "guides",
        projectId: "abc123",
        dataset: "production",
        query: `*[_type == "guide"]`,
        // Field paths default to title / slug.current / body / _updatedAt
        fields: { slug: "slug.current", body: "content" },
      },
    ],
  },
});
```

Um token de leitura para um dataset privado vem da variável de ambiente `SANITY_TOKEN`. Tipos de bloco personalizados de Portable Text são mapeados para componentes do Blume por meio da opção `serializers` do adaptador, disponível quando você constrói `sanitySource` diretamente via uma [fonte personalizada](#custom-sources).

## Notion

A fonte integrada `notion` transforma um banco de dados do Notion em uma coleção: cada linha vira uma página, suas propriedades viram frontmatter e sua árvore de blocos vira MDX. Callouts, toggles, colunas e blocos de código são mapeados para os componentes correspondentes do Blume. O `@notionhq/client` (v5 ou posterior) é uma dependência peer opcional; o Blume lê o banco de dados por meio da primeira fonte de dados dele.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "notion",
        prefix: "handbook",
        database: process.env.NOTION_DB_ID,
        // Property names default to the title-typed prop / Description / Slug / Order
        // Set publishedValue to treat Status as a publish gate (opt-in)
        publishedValue: "Published",
      },
    ],
  },
});
```

O token de integração vem da variável de ambiente `NOTION_TOKEN` (compartilhe o banco de dados com a sua integração). Por padrão, todas as páginas são importadas; defina `publishedValue` para fazer da propriedade `Status` um controle de publicação — qualquer outro valor passa então a ser mapeado para `draft: true`, que os builds de produção descartam. **As URLs de imagem do Notion são assinadas e expiram**, portanto o adaptador as baixa em tempo de build para os assets do site e reescreve as referências — uma imagem de CMS nunca apodrece um build estático. As chamadas à API são ritmadas por um pequeno pool de requisições (3 por vez, correspondendo ao limite de taxa por integração do Notion), de modo que bancos de dados com centenas de páginas são importados sem esbarrar em respostas `429`; defina `concurrency` na fonte para ajustar isso.

## Preview e sincronização

Duas flags controlam como o conteúdo remoto é buscado e o que é incluído:

- **`--preview`** em `blume dev` ou `blume build` renderiza rascunhos e traz conteúdo não publicado do CMS — o Sanity muda para sua perspectiva `previewDrafts`, e o Notion para de filtrar por `Status`. Builds de produção sem a flag excluem rascunhos normalmente, então um build de preview é uma forma segura de revisar trabalho não publicado antes de ele ir ao ar.
- **`blume sync`** refaz a busca de todas as fontes remotas e regenera o runtime. O ambiente de desenvolvimento é cache-first — uma fonte remota é buscada uma vez e servida a partir de `.blume/cache` ao reiniciar (rápido e tolerante a offline), portanto `blume sync` é como você traz o conteúdo mais recente do CMS sem reiniciar o servidor de desenvolvimento (um servidor em execução recarrega a quente). Adicione `--force` para descartar o cache antes, ou defina `pollInterval` em uma fonte para atualizar automaticamente.

```sh
blume dev --preview      # author workflow: see drafts live
blume build --preview    # render a full preview build
blume sync               # refresh remote content now
blume sync --force       # ...ignoring any cached snapshot
```

## Fontes personalizadas

Qualquer objeto que implemente a interface `ContentSource` pode ser passado diretamente, e é assim que um adaptador com serializers personalizados — ou qualquer backend não integrado — se conecta sem que seu SDK toque a instalação principal:

```ts blume.config.ts
import { defineConfig } from "blume";
import { sanitySource } from "blume/sources/sanity.ts";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      {
        type: "custom",
        source: sanitySource({
          name: "guides",
          prefix: "guides",
          projectId: "abc123",
          dataset: "production",
          query: `*[_type == "guide"]`,
          // Map custom Portable Text blocks to Blume components
          serializers: {
            callout: (block) => `<Callout>${block.text}</Callout>`,
          },
        }),
      },
    ],
  },
});
```

Uma fonte normaliza seu formato nativo (Portable Text, blocos do Notion, HTML remoto) para texto Markdown/MDX, de modo que os mesmos componentes e recursos de markdown se aplicam, não importa de onde uma página venha.

Uma fonte personalizada que lê arquivos locais deve definir `sourcePath` em cada entrada e `contentRoot` na própria fonte. O `sourcePath` nomeia o arquivo nos diagnósticos e resolve as imagens relativas ao lado dele; o `contentRoot` delimita o `log` do git que data as páginas, então sem ele as páginas da fonte não recebem [data de "Última atualização"](/docs/configuration#last-modified) derivada do git.

---

# Sintaxe
Source: https://useblume.dev/pt/docs/content/syntax

O Blume renderiza Markdown e MDX padrão com um conjunto de recursos curado, no estilo GitHub — sem imports, sem configuração. Escreva conteúdo do jeito que você já escreve; esta página mostra tudo o que é suportado, com uma pré-visualização ao vivo e o código-fonte de cada recurso.

## Títulos

Estruture uma página com títulos. O Blume renderiza o `title` do frontmatter como o título da página, então comece seu conteúdo em `##` — `##` e `###` viram entradas no índice. Todo título de `##` a `######` também é envolvido em um link para sua própria âncora, para que os leitores possam clicar em um título para copiar, salvar nos favoritos ou compartilhar um link permanente direto para aquela seção (passe o cursor para revelar o `#`). Desative isso com `markdown: { headingAnchors: false }` no `blume.config.ts`.

```md
## Section

### Subsection

#### Detail
```

### Âncoras personalizadas

Os ids das âncoras são gerados a partir do texto do título, então um título reescrito ganha uma âncora nova. Acrescente `[#custom-id]` para fixar a âncora — o marcador nunca é renderizado, e os links continuam funcionando independentemente de como o título estiver escrito. Âncoras fixadas também permanecem idênticas entre [locales traduzidos](/docs/content/i18n), onde ids gerados automaticamente seriam diferentes em cada idioma.

```md
## Getting started [#setup]
```

Crie um link para ela como `/page#setup`. A sintaxe é igual à do Fumadocs, então conteúdo migrado funciona sem alterações.

A forma `{#custom-id}`, usada pelo Pandoc, pelo kramdown e por toolchains de especificação baseadas em Markdown, é aceita como equivalente em arquivos `.md`. No `.mdx`, um `{…}` solto é uma expressão JSX e a página não compila — o `blume check` reporta o marcador como `BLUME_MDX_CURLY_ANCHOR` — então escreva `[#custom-id]` ali, ou escape as chaves. A forma escapada fixa a mesma âncora nos dois formatos, o que a torna a grafia certa para um partial que páginas `.mdx` [incluem](/docs/content/includes):

```md
## Getting started \{#setup\}
```

Links de fragmento também podem apontar para um elemento HTML puro com um `id` (`<a id="setup"></a>`); o `blume validate` aceita esses casos junto com as âncoras de título.

### Marcadores do índice

Outros dois marcadores finais controlam como um título aparece no índice. `[!toc]` mantém o título na página, mas fora do índice; `[toc]` faz o contrário — o título aparece apenas no índice, como um alvo de âncora invisível, o que é útil para rotular seções construídas com componentes em vez de prosa. Os marcadores podem ser encadeados em qualquer ordem. Uma exceção, herdada do CommonMark: um colchete final cujo rótulo tenha uma definição de referência de link em qualquer lugar da página (`[toc]: /url`) é um link de referência abreviado, não um marcador, e permanece no texto do título.

```md
## Appears on the page only [!toc]

## Appears in the TOC only [toc]

## Both markers together [toc] [#custom-id]
```

Os marcadores são sempre interpretados — um título que termine literalmente com um texto no formato de marcador seria tratado como marcado. Escapar com barra invertida não ajuda (o Markdown resolve `\[` para `[` antes de a análise do marcador rodar); para exibir o texto literal de um marcador no fim de um título, coloque-o em código inline: `` ## Using `[toc]` ``.

## Ênfase

Formatação inline para enfatizar palavras, marcar exclusões e mostrar código ou teclas no meio da frase.

**Negrito**, _itálico_, ~~tachado~~ e `código inline`.

```md
**Bold**, _italic_, ~~strikethrough~~, and `inline code`.
```

## Sobrescrito e subscrito

Para marcadores de nota de rodapé, ordinais e notação científica ou química inline.

E = mc^2^ e H~2~O.

{/* prettier-ignore */}
```md
E = mc^2^ and H~2~O.
```

## Citações

Destaque uma citação, um aparte de atenção ou uma nota editorial do texto ao redor.

> Documentação rápida, pronta para IA e sem configuração — até o template.

```md
> Documentation that's fast, AI-ready, and zero-config — down to the template.
```

## Listas

Use listas não ordenadas para conjuntos sem ordem, listas ordenadas para sequências e listas de tarefas para checklists e roadmaps.

- Autoria orientada a Markdown
- Estático por padrão
  - Adote recursos de servidor quando quiser
- Seja dono da sua saída

1. Instale o Blume
2. Escreva uma página
3. Publique

- [x] Estruturar o projeto
- [ ] Escrever o primeiro guia

```md
- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide
```

## Tabelas

Tabule dados estruturados — opções de configuração, matrizes de comparação, listas de parâmetros. Use dois-pontos na linha divisória para alinhar colunas.

| Comando       | Descrição                |  Saída  |
| ------------- | ------------------------ | :-----: |
| `blume dev`   | Inicia o servidor de dev |    —    |
| `blume build` | Compila o site estático  | `dist/` |

```md
| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |
```

Para uma tabela sem linha de cabeçalho — pares chave–valor, por exemplo — deixe as células do cabeçalho vazias. O Markdown exige as linhas de cabeçalho e divisória sintaticamente, mas o Blume remove o cabeçalho vazio da tabela renderizada.

```md
|                |          |
| -------------- | -------- |
| Current status | E-3 visa |
```

## Links e imagens

Crie links para outras páginas ou sites externos. As imagens aceitam um caminho relativo para um arquivo ao lado do seu conteúdo, qualquer caminho dentro de `public/` (servido na raiz do site) ou uma URL remota.

Leia o [guia rápido](/docs/quickstart) para começar.

```md
Read the [quickstart](/docs/quickstart) to get started.

![Alt text](./screenshot.png)
```

**Prefira caminhos relativos para imagens locais** — elas são otimizadas em tempo de build: comprimidas, convertidas para WebP e marcadas com `width`/`height` intrínsecos para que a página não salte durante o carregamento. Mantenha a imagem ao lado da página que a usa (ou em uma pasta compartilhada dentro do seu diretório de conteúdo) e a referencie de forma relativa:

```md
![Build output](./images/build-output.png)
```

Caminhos absolutos dentro de `public/` (`![Alt text](/screenshot.png)`) são servidos literalmente, sem otimização — use-os para arquivos que precisam manter exatamente seus bytes e URL, como um logotipo referenciado de fora da sua documentação. Imagens remotas também são repassadas intocadas, a menos que seu host esteja autorizado na [configuração de `image`](/docs/configuration#images).

As imagens de conteúdo têm zoom por clique por padrão — os leitores podem clicar em qualquer imagem para abri-la em um lightbox. Desative isso com `markdown: { imageZoom: false }` no `blume.config.ts`, ou exclua uma única imagem com `data-no-zoom`.

## Linha horizontal

Separe grandes mudanças de assunto dentro de uma página longa.

---

```md
---
```

## Blocos de código

Blocos de código delimitados por cercas recebem realce de sintaxe com um cabeçalho mostrando a linguagem — com um ícone da marca para linguagens reconhecidas — e um botão de copiar. Adicione um **título** depois da linguagem — normalmente um nome de arquivo — e ele substitui o rótulo da linguagem no cabeçalho.

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```

````md
```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```
````

O código inline também pode receber realce: adicione um marcador `{:lang}` dentro de um trecho entre crases e ele é colorido como um pequeno bloco de código — `useState(){:js}` ou `T extends object{:ts}`. Isso só entra em ação quando você adiciona o marcador, então o código inline comum permanece intocado — nada para ativar.

O realce usa os temas `github-light`/`github-dark` por padrão. Troque por qualquer [tema Shiki incluído](https://shiki.style/themes) por modo de cor com `markdown.codeBlocks.theme` — ele colore todas as superfícies de código de uma vez (cercas, trechos inline, `<CodeBlock>` e `<Diff>`):

```ts blume.config.ts
export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: "vesper" },
    },
  },
});
```

Você também pode fornecer uma [definição de tema Shiki](https://shiki.style/guide/load-theme) personalizada diretamente. Importe um arquivo JSON de tema compatível com o VS Code (usando um atributo de import quando seu runtime exigir) e atribua-o a qualquer modo de cor; nomes incluídos e definições personalizadas podem ser combinados:

```ts blume.config.ts
import darkTheme from "./themes/acme-dark.json" with { type: "json" };

export default defineConfig({
  markdown: {
    codeBlocks: {
      theme: { light: "github-light", dark: darkTheme },
    },
  },
});
```

### Números de linha

Acrescente `lineNumbers` para renderizar uma coluna com números de linha — sozinho ou junto de um título:

```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```

````md
```ts server.ts lineNumbers
import { serve } from "blume";

serve({ port: 3000 });
```
````

### Realce

Anote o código com comentários no estilo GitHub para chamar atenção para linhas, palavras e alterações. Os comentários são removidos da saída renderizada, então o código continua limpo para copiar e colar. Todos os quatro estão ativos por padrão — sem configuração.

Marque uma linha com `// [!code highlight]` para dar a ela um fundo realçado:

```ts
const config = defineConfig({
  title: "My docs", // [!code highlight]
});
```

Mostre alterações com `// [!code ++]` para adições e `// [!code --]` para remoções, renderizadas como um diff verde/vermelho:

```ts
export default defineConfig({
  title: "My docs", // [!code --]
  title: "Blume docs", // [!code ++]
});
```

Realce todas as ocorrências de um termo em uma linha com `// [!code word:serve]`:

```ts
import { serve } from "blume"; // [!code word:serve]

serve({ port: 3000 });
```

Escureça tudo, exceto as linhas que você marcar com `// [!code focus]` (o restante fica nítido ao passar o cursor):

```ts
export default defineConfig({
  title: "My docs", // [!code focus]
  description: "Built with Blume",
});
```

Ou realce linhas por **número** em vez de comentários — útil quando você não pode editar o código. Coloque um intervalo entre chaves depois da linguagem; linhas isoladas, listas separadas por vírgula e intervalos `início-fim` funcionam:

```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```

````md
```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```
````

### Tipos exibidos

Marque um bloco TypeScript com `twoslash` para exibir tipos reais direto do compilador — com tecnologia do [Twoslash](https://shiki.style/packages/twoslash). Passe o cursor sobre qualquer token para ver seu tipo inferido e adicione uma consulta inline `^?` para fixar um tipo abaixo da linha.

```ts twoslash
const config = {
  title: "My docs",
  version: 1,
};

config.title;
//     ^?
```

````md
```ts twoslash
const config = { title: "My docs", version: 1 };

config.title;
//     ^?
```
````

### Abas de TypeScript e JavaScript

Marque um bloco `ts` ou `tsx` com `ts2js` para renderizá-lo como um par de abas: seu TypeScript ao lado de uma variante JavaScript gerada automaticamente, para que você mantenha um único trecho e os leitores escolham seu dialeto. A conversão remove a sintaxe de tipos e os imports somente de tipos, mantendo sua formatação, seus comentários e o JSX exatamente como você escreveu — e as abas são sincronizadas, então escolher JavaScript uma vez troca todos os pares da página. Como os diagramas e a matemática, este é um recurso exclusivo do MDX — em um arquivo `.md` o bloco é renderizado como uma cerca de código TypeScript comum.

```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```

````md
```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```
````

Outros metadados da cerca se combinam: um `title="..."` aparece nas duas abas, enquanto intervalos de linha `{1,4-5}` se aplicam apenas à aba TypeScript (os números das linhas mudam quando os tipos somem). A única exceção é `twoslash` — os tipos exibidos ao passar o cursor não podem ser transferidos para o código gerado, então uma cerca marcada com os dois continua sendo um bloco Twoslash comum.

:::note
Oculte os ícones de linguagem ou quebre linhas longas em vez de rolar com `markdown: { code: { icons: false, wrap: true } }` no `blume.config.ts`.
:::

## Instalação de pacotes

Um bloco `package-install` transforma um único comando de instalação em um trecho com abas para npm, pnpm, yarn e bun — assim os leitores copiam o que corresponde à sua configuração. Como os diagramas e a matemática, este é um recurso exclusivo do MDX — em um arquivo `.md` o bloco é renderizado como uma cerca de código comum.

```package-install
npm i blume
```

````md
```package-install
npm i blume
```
````

## Diagramas

Um bloco `mermaid` renderiza um diagrama do [Mermaid](https://mermaid.js.org) direto do texto. O conteúdo da cerca é passado ao Mermaid literalmente, então todo tipo de diagrama suportado pelo Mermaid funciona aqui. Os diagramas seguem o tema de cores ativo e são renderizados novamente quando ele muda. Crie um delimitando o código-fonte com `mermaid`:

````md
```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```
````

Os diagramas são renderizados no cliente, então este é um recurso exclusivo do MDX, e a biblioteca Mermaid é carregada apenas em páginas que incluem um. O restante desta seção é uma galeria de tipos comuns — veja a [documentação do Mermaid](https://mermaid.js.org/intro/) para a lista completa.

### Fluxograma

```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```

### Diagrama de sequência

```mermaid
sequenceDiagram
  participant R as Reader
  participant B as Blume
  R->>B: Request /docs
  B-->>R: Prerendered HTML
```

### Diagrama de classes

```mermaid
classDiagram
  class Page {
    +string title
    +string route
    +render()
  }
  Page <|-- Doc
  Page <|-- Changelog
```

### Diagrama de estados

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: build
  Published --> [*]
```

### Entidade-relacionamento

```mermaid
erDiagram
  PAGE ||--o{ HEADING : contains
  PAGE {
    string title
    string route
  }
```

### Jornada do usuário

```mermaid
journey
  title Publishing a page
  section Write
    Draft MDX: 5: Author
  section Ship
    blume build: 4: Author
    Deploy: 3: Author
```

### Gantt

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Docs
    Draft   :a1, 2026-01-01, 7d
    Review  :after a1, 3d
```

### Grafo do Git

```mermaid
gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit
```

### Gráfico de pizza

```mermaid
pie title Content types
  "Docs" : 70
  "Blog" : 20
  "Changelog" : 10
```

### Mapa mental

```mermaid
mindmap
  root((Blume))
    Content
      MDX
      Markdown
    Build
      Static HTML
      llms.txt
```

### Linha do tempo

```mermaid
timeline
  title Blume milestones
  2025 : Prototype
  2026 : 1.0 release
```

## Avisos

Os avisos chamam a atenção do leitor para contexto, conselhos ou riscos. Escreva-os como diretivas `:::type`; adicione um título entre colchetes, como `:::warning[Atenção]`. As diretivas são um recurso exclusivo do MDX — em um arquivo `.md` uma linha `:::note` permanece como texto literal.

### Nota

Contexto neutro e complementar que o leitor deve ter em mente.

:::note
O Blume regenera `.blume/` a cada execução — nunca o edite manualmente.
:::

```md
:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::
```

### Dica

Um atalho útil ou uma boa prática que não é obrigatória, mas facilita a vida.

:::tip
Defina `deployment.site` para que os sitemaps e as imagens do Open Graph usem URLs absolutas.
:::

```md
:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::
```

### Sucesso

Confirme um resultado positivo ou que uma etapa foi concluída como esperado.

:::success
Sua documentação foi compilada com sucesso e está pronta para publicação.
:::

```md
:::success
Your docs built successfully and are ready to deploy.
:::
```

### Aviso

Sinalize algo que exige cuidado para evitar um erro ou comportamento inesperado.

:::warning[Atenção]
Mudar para `output: "server"` exige um adaptador antes que você possa publicar.
:::

```md
:::warning[Heads up]
Switching to `output: "server"` requires an adapter before you can deploy.
:::
```

### Perigo

Destaque uma ação destrutiva ou disruptiva que não pode ser desfeita com facilidade.

:::danger
`blume eject` é um passo sem volta — o projeto Astro gerado passa a ser seu.
:::

```md
:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::
```

### Info

Um aparte informativo; um padrão flexível quanto a aliases que soa neutro.

:::info
O tema principal não envia nenhum JS de framework do lado do cliente.
:::

```md
:::info
The core theme ships no client framework JS.
:::
```

Os nomes `caution`, `error`, `important` e `warn` são aceitos como aliases de `warning`, `danger`, `note` e `warning`, respectivamente.

## Matemática

Renderize LaTeX com o KaTeX como blocos centralizados — útil para documentação científica ou com muita matemática. Envolva uma fórmula em `$$…$$`:

$$
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

```md
$$
a^2 + b^2 = c^2
$$
```

:::note
A matemática funciona apenas em bloco e está ativa automaticamente — escreva `$$…$$` e ela é renderizada; não escreva nenhuma e a folha de estilo do KaTeX nunca é enviada. Não existe matemática inline com `$…$`: um `$` isolado (moeda, variáveis de shell, código) é sempre mantido como texto literal, então não há delimitador para escapar nem configuração para alternar. A matemática é um recurso exclusivo do MDX. Os nomes de classe dentro da marcação renderizada (`.katex-html`, `.katex-base`, …) são internos do próprio KaTeX, não um contrato de estilização que o Blume mantém — eles podem mudar quando o KaTeX for atualizado, então mire no wrapper `.katex-display` para estilos personalizados.
:::

## Pontuação inteligente

O Blume converte aspas retas e traços em equivalentes tipográficos enquanto você escreve, para que o texto pareça diagramado — sem exigir caracteres especiais.

"Aspas" ficam curvas, -- vira um travessão curto, --- um travessão longo e ... uma reticência.

```md
"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
```

---

# Versionamento
Source: https://useblume.dev/pt/docs/content/versioning

O Blume versiona seus docs do jeito que os releases funcionam de verdade: a documentação mais recente fica na raiz do seu conteúdo, com URLs limpas e sem prefixo, e cada versão passada é um snapshot congelado na própria pasta. Crie um snapshot quando você lançar, e o Blume monta o seletor, o aviso de "versão antiga", o escopo da busca, o SEO e a superfície de agentes pra você. É opcional: sem um bloco `versions`, nada muda.

## Habilite

Adicione um bloco `versions` nomeando os docs atuais e quaisquer snapshots arquivados:

```ts blume.config.ts lineNumbers
versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}
```

`current` rotula a árvore sem prefixo no seletor (com um `badge` opcional). O `id` de cada entrada arquivada é ao mesmo tempo o nome do diretório do snapshot e o segmento da URL — os ids precisam começar com uma letra (`v1.0`, não `1.0`) para que nunca colidam com [prefixos numéricos de ordenação](/docs/content/navigation#ordering). Liste as versões arquivadas da mais nova para a mais antiga; essa é a ordem do seletor.

## Crie uma versão

Quando você lançar, congele os docs atuais com um comando:

```bash
blume version v1.0
```

Isso copia sua árvore de conteúdo para `docs/v1.0/` (snapshots existentes são excluídos), reescreve os links absolutos a partir da raiz dentro da cópia para que continuem dentro do snapshot (`/guides/x` vira `/v1.0/guides/x`, com código em blocos e inline intocados) e registra o id em `blume.config.ts` — ou imprime a entrada para você colar, quando seu config estiver estruturado de um jeito que ele não vai mexer. Links para páginas que não fazem parte da árvore copiada — referências de API geradas, fontes remotas como um changelog — continuam apontando para as páginas vivas, já que o snapshot não tem cópia delas. Rode `blume version` sem id para listar as versões configuradas.

Revise e commite o novo diretório como qualquer outro conteúdo. Reinicie o `blume dev` para que ele seja reconhecido.

```txt
docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart
```

**Arquivado significa congelado.** As edições futuras pertencem à árvore viva; um snapshot são os docs como eles eram. O Blume se apoia nisso: snapshots mantêm os próprios metadados de pasta e traduções, o [`blume translate`](/docs/reference/translate) nunca os retraduz, e uma sidebar explícita configurada se aplica só aos docs atuais — a sidebar de um snapshot sempre vem dos arquivos dele.

## O seletor e o aviso

Com as versões configuradas, o cabeçalho ganha um dropdown de versão automaticamente. Ao trocar, você cai na mesma página da versão de destino quando ela existe, e na raiz daquela versão quando não existe (defina `switcher.redirect: "root"` para sempre cair na raiz). Se você declarar seu próprio seletor `kind: "version"` em [`navigation.selectors`](/docs/content/navigation#selectors), ele substitui o automático.

Toda página arquivada também mostra um aviso não dispensável com um link "Ir para a mais recente" apontando para o equivalente vivo da página. Personalize ou desative por versão:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0", banner: "These docs cover the 1.x SDK." },
    { id: "v0.9", banner: false },
  ],
}
```

## SEO

Docs antigos são a armadilha favorita dos mecanismos de busca: a página desatualizada supera a viva no ranking, ou as duas competem. O Blume usa como padrão a resposta que os guias de SEO recomendam e que nenhum outro framework de docs automatiza — páginas arquivadas continuam indexáveis, mas declaram o **equivalente mais recente como seu canônico**, então a página viva é a autoritativa enquanto o conteúdo exclusivo daquela versão (uma página que não existe mais nos docs mais recentes) continua localizável com um canônico apontando para si mesma.

Por versão, você pode escolher um tratamento diferente:

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0" }, // canonical → latest (default)
    { id: "v0.9", canonical: "self" }, // every page authoritative
    { id: "v0.8", noindex: true }, // deindexed entirely
  ],
}
```

O sitemap segue a mesma lógica: páginas arquivadas cujo canônico aponta para um equivalente vivo ficam de fora, versões com `noindex` ficam de fora por completo, e páginas exclusivas de uma versão continuam listadas. O frontmatter `seo.canonical` da própria página sempre vence.

## Busca

O diálogo de busca limita os resultados à versão que está sendo vista, com um alternador "Todas as versões" (lembrado por leitor) ao lado do de idioma. Resultados de outras versões mostram a versão deles na linha do resultado. Orama (o padrão), FlexSearch, Algolia e Typesense todos respeitam esse escopo — os registros hospedados carregam uma faceta `version`, com os docs atuais enviados como `"current"` — enquanto o Pagefind fica sem escopo, coerente com o comportamento dele para locales.

## Agentes

A superfície de agentes entende versões — algo que nenhum outro framework de docs faz:

- As ferramentas MCP `search_docs` e `list_pages` usam os docs atuais por padrão e aceitam `version`: um id arquivado (`"v1.0"`) ou `"all"`. O `get_navigation` retorna a árvore de um snapshot arquivado quando solicitado.
- O `llms.txt` coloca as versões arquivadas depois dos docs atuais, rotuladas como `1.0 (archived)`, para que um agente lendo o índice saiba quais docs estão congelados.
- O `llms-full.txt` continua somente com a versão atual — o dump plano nunca intercala cópias congeladas da mesma página.
- Espelhos em Markdown puro (URLs `.md`) existem para as páginas de todas as versões, como para qualquer rota.

## Com i18n

O versionamento se combina com a [internacionalização](/docs/content/i18n). No disco, a pasta da versão é a mais externa — um snapshot naturalmente contém as pastas de locale dele — enquanto nas URLs o locale continua sendo o mais externo, igual ao resto do site:

```txt
docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
```

O fallback de locale funciona dentro de cada versão: uma página de snapshot não traduzida renderiza o conteúdo do locale de fallback na URL localizada, e as alternativas `hreflang` se agrupam por versão. Um id de versão não pode colidir com um código de locale configurado — o Blume rejeita essa configuração de cara.

## O que fica sem versionamento

O versionamento cobre a árvore de conteúdo dos docs. O blog, o changelog, as referências de API geradas a partir de specs OpenAPI e as páginas customizadas são sempre a versão atual. Mais dois comportamentos que vale conhecer: as abas do cabeçalho são definidas em relação aos docs atuais, então dentro de uma árvore arquivada a sidebar é renderizada sem escopo por abas; e sites grandes devem notar que cada snapshot é uma cópia completa — conteúdo, entradas do índice de busca e dados de navegação crescem a cada versão.

---

# Implantação
Source: https://useblume.dev/pt/docs/deployment

## Implante em qualquer lugar (estático)

`blume build` compila sua documentação para HTML, CSS e um índice de busca local em `dist/`. Não há servidor para executar — basta apontar qualquer host estático para a pasta.

| Configuração       | Valor             |
| ------------------ | ----------------- |
| Comando de build   | `blume build`     |
| Diretório de saída | `dist`            |
| Versão do Node     | 22.12 ou superior |

Essas configurações funcionam na Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, ou em qualquer bucket ou CDN. Certifique-se de que `blume` seja uma dependência para que o host possa executar o build.

Um build estático inclui:

- cada página de documentação e página personalizada como HTML estático
- um índice de busca local (Orama por padrão, Pagefind opcional)
- um [`sitemap.xml`](/docs/configuration/seo#sitemap) e um [`robots.txt`](/docs/configuration/seo#robots) quando `deployment.site` está definido
- `llms.txt` e `llms-full.txt` para ferramentas de IA
- páginas de redirecionamento
- [imagens Open Graph](/docs/configuration/seo#open-graph-images) pré-renderizadas quando `seo.og.enabled` está ativado

### Defina a URL do seu site

Sitemaps, tags canônicas, RSS e imagens Open Graph precisam de uma origem absoluta. Na **Vercel**, na **Netlify** e no **Cloudflare Pages**, o Blume a detecta a partir do ambiente da plataforma em tempo de build — nenhuma configuração é necessária.

Defina `deployment.site` para sobrescrever o valor detectado, ou para fornecer um em hosts que não o expõem (GitHub Pages, S3, uma CDN personalizada):

```ts blume.config.ts lineNumbers
deployment: {
  site: "https://docs.example.com",
}
```

Ao detectar automaticamente, o Blume prefere seu domínio de produção estável em vez das URLs de pré-visualização de cada deploy, de modo que a origem canônica permanece a mesma entre implantações.

Durante o `blume dev`, a URL do site recorre ao seu servidor de desenvolvimento local (por exemplo, `http://localhost:4321`) quando nenhuma é definida, para que os recursos que dependem do site — imagens Open Graph, canônicas, o sitemap — funcionem imediatamente. Os builds nunca usam esse fallback, então a saída de produção nunca aponta para o localhost.

## Pré-visualize localmente

Antes de publicar, pré-visualize o build de produção exatamente como um host estático o serviria:

```bash
blume build
blume preview
```

## Implantações em subcaminho

Está servindo a documentação sob um caminho como `example.com/docs`? Defina `deployment.base` — comum em sites de projeto do GitHub Pages. O site inteiro, incluindo a raiz, passa a ficar sob a base, e os links internos e os recursos são reescritos para incluí-la.

```ts blume.config.ts lineNumbers
deployment: {
  base: "/docs",
}
```

## Monte a documentação sob um caminho

`basePath` monta todas as rotas geradas sob um segmento (`/docs/getting-started`) sem alterar a barra lateral — o nível superior são suas seções, não um grupo envoltório. Use-o quando a documentação fica em `/docs/*` mas a raiz do site continua sendo sua (como o `routeBasePath` do Docusaurus ou o `baseUrl` do Fumadocs).

```ts blume.config.ts lineNumbers
basePath: "/docs",
```

Escreva os links como se estivessem montados na raiz (`/getting-started`); o Blume os reescreve, junto com os redirecionamentos, o sitemap, as URLs canônicas, as imagens Open Graph, o `llms.txt` e o índice de busca. Os recursos públicos (imagens, arquivos em `public/`) permanecem na raiz do site.

Este é um conceito distinto dos dois caminhos acima:

- Um [`prefix`](/docs/content/sources#multiple-sources) por fonte dá um namespace a **uma** fonte e **adiciona** um grupo na barra lateral.
- `deployment.base` é o subdiretório do host a partir do qual **toda** a aplicação é servida. Os dois se combinam — com ambos definidos, uma página fica em `{deployment.base}/{basePath}/page`.

## Renderização no servidor

A saída estática atende à maioria das documentações. Mude para a saída de servidor quando precisar de recursos em tempo de requisição — sobretudo o endpoint [Ask AI](/docs/configuration/ai):

```ts blume.config.ts lineNumbers
deployment: {
  output: "server",
  adapter: "vercel",
}
```

Os adaptadores `vercel` e `node` já vêm com o Blume — basta escolher um e funciona. Os adaptadores `netlify` e `cloudflare` precisam ser instalados no seu projeto (por exemplo, `bun add -d @astrojs/netlify`); a CLI avisa se o pacote estiver faltando:

| Adaptador | Pacote | Usar para |
| --- | --- | --- |
| `vercel` | `@astrojs/vercel` | Vercel — o caminho mais refinado |
| `netlify` | `@astrojs/netlify` | Netlify Functions |
| `node` | `@astrojs/node` | Servidores Node auto-hospedados, contêineres |
| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers e Pages |

Na **Vercel**, na **Netlify** e no **Cloudflare Pages**, o Blume escolhe automaticamente o adaptador correspondente para a saída de servidor — defina `output: "server"` e implante (na Netlify e na Cloudflare, instale também o pacote do adaptador). Defina `adapter` explicitamente para sobrescrever o valor detectado, ou ao auto-hospedar com `node`.

Um build de servidor inclui tudo o que um build estático inclui, além de quaisquer endpoints ou middlewares do Astro que você adicionar. O adaptador `node` produz um servidor autônomo que você pode executar diretamente.

Na Vercel e na Cloudflare, um build de servidor também ativa a [negociação de conteúdo com `Accept: text/markdown`](/docs/configuration/ai#content-negotiation), de modo que um agente que solicite qualquer página de conteúdo com esse cabeçalho recebe seu espelho em Markdown puro na mesma URL. Na Vercel, o Blume insere reescritas condicionadas ao cabeçalho na configuração de roteamento da implantação; na Cloudflare, ele gera um pequeno Worker na frente do Worker do Astro e restringe `assets.run_worker_first` às rotas de conteúdo, já que, de outra forma, a plataforma serviria as páginas pré-renderizadas antes de qualquer código de servidor ser executado — os demais recursos mantêm seu caminho rápido sem Worker.

:::note
Os recursos de servidor têm sua própria configuração — por exemplo, o Ask AI precisa de uma chave de API de modelo. Consulte o [guia de IA](/docs/configuration/ai) para a configuração.
:::

## Redirecionamentos

Mapeie URLs antigas para novas em `blume.config.ts`:

```ts blume.config.ts
redirects: [{ from: "/old", to: "/new", status: 301 }];
```

`status` aceita `301`, `302`, `307` ou `308` (padrão `301`). Os builds de servidor tratam os redirecionamentos em tempo de requisição. Os builds estáticos geram páginas de redirecionamento **e** arquivos específicos da plataforma para que seu host emita um redirecionamento HTTP real: `_redirects` (Netlify, Cloudflare Pages), `vercel.json` (Vercel) e `blume-redirects.json` — um manifesto estruturado para qualquer outro caso (regras de nginx/Apache, um edge worker). Um `_redirects` ou `vercel.json` que você inclua em `public/` permanece intocado.

:::note
`from` é comparado como um caminho exato — curingas e correspondência por padrão (por exemplo, `/blog/:slug` ou `/old/*`) não são suportados. Se você precisar de regras baseadas em padrões, trate-as em um arquivo de infraestrutura como o `vercel.json` (que suporta padrões com curinga em `source`) ou na configuração de redirecionamento do seu host. Um `vercel.json` que você inclua em `public/` é preservado como está.
:::

:::note
Escreva tanto `from` quanto `to` como se estivessem montados na raiz — tanto sob [`deployment.base`](#subpath-deploys) quanto sob [`basePath`](#mount-the-docs-under-a-path), o Blume reescreve os dois lados para você, de modo que o redirecionamento fica dentro da base. Uma base que você já tenha escrito manualmente em `to` é preservada, e não duplicada.
:::

## Tipos de conteúdo

Um build estático também gera um arquivo `_headers` que fixa `charset=utf-8` nos endpoints brutos prontos para IA — `/<route>.md`, `/<route>.mdx` e os arquivos `.txt` (`llms.txt`, `llms-full.txt`). Essas respostas são UTF-8 válido, mas muitos hosts estáticos as servem como `text/markdown` / `text/plain` **sem** charset, e então os navegadores recorrem ao Windows-1252 — de modo que documentações não-ASCII (japonês, latim acentuado, …) aparecem como mojibake quando a URL bruta é aberta diretamente. As páginas HTML não são afetadas porque carregam `<meta charset>`. A Netlify e a Cloudflare (recursos estáticos de Pages/Workers) leem o `_headers`; os hosts que não leem (Vercel, S3) ignoram o arquivo sem prejuízo. Um `_headers` que você inclua em `public/` permanece intocado.

## Variáveis de ambiente

Quando um recurso precisa de um segredo em tempo de execução, o Blume avisa no `blume dev`/`build` caso ele esteja faltando — assim o problema aparece cedo, em vez de na primeira requisição:

| Recurso | Variável |
| --- | --- |
| Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (ou OIDC da Vercel) |
| Ask AI (outros provedores) | a variável de ambiente padrão da chave do provedor (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), ou o seu `apiKeyEnv` configurado |
| Busca Mixedbread | `MIXEDBREAD_API_KEY` |

Defina-as no `.env.local` para o desenvolvimento local e no ambiente do seu host para produção. Os segredos em tempo de build para a sincronização do índice de busca (Algolia, Orama Cloud, Typesense) são avisados separadamente durante a etapa de sincronização.

## Resumo do build

Todo build imprime um resumo — modo de saída, adaptador, URL do site resolvida, provedor de busca, contagem de redirecionamentos, status do sitemap e do `llms.txt`, e quaisquer recursos de servidor habilitados — para que você possa confirmar o que foi publicado (incluindo tudo o que foi detectado automaticamente) antes de implantar.

---

# FAQ
Source: https://useblume.dev/pt/docs/faq

Respostas para perguntas que aparecem com frequência. Falta alguma? [Abra uma issue](https://github.com/haydenbleasel/blume/issues) ou pergunte ao assistente na própria página.

## Em que o Blume é diferente do Mintlify, do Fumadocs e de outros?

A maioria das ferramentas de documentação fica em um de dois extremos. **Plataformas gerenciadas** como o Mintlify entregam um resultado polido rápido, mas o build e a hospedagem são o serviço deles — você escreve dentro do sistema deles e publica na infraestrutura deles. **Bibliotecas de componentes e starters** como o Fumadocs, o Nextra ou o Docusaurus são open-source e flexíveis, mas entregam para você um aplicativo (um projeto Next.js ou React) que você precisa montar, conectar e manter antes e depois de escrever uma única palavra.

O Blume segue um terceiro caminho: **o framework é o template.** Você aponta ele para uma pasta de Markdown e ele gera e conduz o site inteiro — navegação, busca, temas, imagens Open Graph, SEO e endpoints de IA — sem nenhum app para cuidar. É totalmente open-source e você mesmo pode hospedar, então não existe serviço gerenciado nem dependência de fornecedor, mas também não existe boilerplate para manter.

|  | Blume | Mintlify | Fumadocs / Nextra / Docusaurus |
| --- | --- | --- | --- |
| **Modelo** | Framework de configuração zero; só conteúdo | Plataforma hospedada | Biblioteca + app que você monta |
| **Código-fonte** | Open-source (MIT) | Núcleo fechado | Open-source |
| **Hospedagem** | Em qualquer lugar — estático ou uma função de servidor | A infraestrutura gerenciada deles | Em qualquer lugar; você faz o build e publica |
| **Você mantém** | O seu Markdown | O seu Markdown + configuração da plataforma | O seu Markdown + o app em volta dele |
| **Renderização** | Astro; o tema principal não envia nenhum JS de cliente | O runtime deles | Runtime React/Next.js |
| **Recursos de IA** | `llms.txt`, Markdown bruto, Ask AI, MCP — integrados, sem serviço hospedado | Integrados (hospedados) | Traga os seus |

Vale destacar algumas consequências:

- **O resultado é seu.** O `blume build` gera um site simples que você hospeda na Vercel, Netlify, Cloudflare, S3 ou na sua própria máquina. Nada manda dados para casa.
- **Sem dependência de fornecedor, com duas saídas.** O seu conteúdo é Markdown portátil, e o `blume eject` transforma o projeto em um app Astro autônomo que continua usando o pacote `blume` quando você quiser controle total.
- **Rápido por padrão.** O tema principal não usa React e renderiza HTML estático, então as páginas vão bem nos Core Web Vitals sem ajuste nenhum. Você adota os recursos de servidor (Ask AI, MCP) só quando precisa deles.
- **Configuração com segurança de tipos.** O `blume.config.ts` e cada `meta.ts` são TypeScript real validado por um schema — e não YAML de tipagem frouxa.

:::note
Isso não é "melhor que tudo" — plataformas gerenciadas e frameworks completos são a escolha certa quando você quer um produto hospedado ou controle máximo sobre o app. O Blume é para times que querem um site de documentação de nível de produção sem ter que cuidar nem da plataforma nem da encanação.
:::

Veja [Por que o Blume existe](/docs) para a versão mais longa.

## O Blume é gratuito e open-source?

Sim — o Blume tem licença MIT e é gratuito. Você instala o pacote `blume`, mantém o seu conteúdo no seu próprio repositório e hospeda o build onde quiser. Não tem plano pago, nem preço por usuário, nem conta para criar. O código-fonte está no [GitHub](https://github.com/haydenbleasel/blume).

## Preciso saber Astro, React ou Tailwind?

Não. Uma pasta de Markdown é um site completo — navegação, busca e temas são inferidos ou definidos com um punhado de tokens. Você só recorre à stack por baixo quando quiser personalizar: [ilhas interativas](/docs/content/islands) (React), [substituições de componentes](/docs/configuration/customization) ou [tokens de tema](/docs/configuration/theming) (Tailwind). E, mesmo assim, o [`blume.config.ts`](/docs/configuration) é tipado, então o seu editor te guia.

## Posso usar componentes React e MDX?

Sim. Qualquer página pode ser `.md` ou `.mdx`, e o MDX permite inserir os [componentes integrados](/docs/content/components) sem imports. Você também pode adicionar as suas próprias [ilhas](/docs/content/islands) `.tsx`/`.jsx` — o Blume ativa o React automaticamente só nas páginas que as usam, então o tema principal continua livre de JavaScript em todo o resto.

## Onde posso publicar?

Em qualquer lugar. O `blume build` gera HTML estático por padrão, que você pode servir de qualquer hospedagem estática ou CDN — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3 ou o seu próprio servidor. Os recursos exclusivos de servidor (Ask AI, o servidor MCP, renderização sob demanda) mudam o build para uma função de servidor por meio de um adaptador para Vercel, Node, Netlify ou Cloudflare. Veja [Publicação](/docs/deployment).

## A busca precisa de um serviço hospedado?

Não. O [Orama](/docs/configuration/search) monta um índice local que funciona tanto em desenvolvimento quanto em produção, sem nada para hospedar ou pagar. Para sites muito grandes, o [Pagefind](/docs/configuration/search) está a uma flag de distância. De qualquer forma, o índice vai junto como parte do seu site.

## Como personalizo a aparência?

Comece pelos [tokens de tema](/docs/configuration/theming) — cor de destaque, fontes, raio e um `theme.css` para tudo o mais que o Tailwind conseguir expressar. Vá além [substituindo componentes integrados](/docs/configuration/customization) ou adicionando [páginas personalizadas](/docs/configuration/customization#custom-pages). Quando você quiser o projeto Astro em si, o [`blume eject`](/docs/reference/cli) entrega um app autônomo que continua usando o pacote `blume`.

## Por que o oxfmt / Ultracite está colapsando as minhas diretivas?

Se você formata o seu Markdown com o [Ultracite](https://www.ultracite.ai) (que roda oxlint + [oxfmt](https://oxc.rs)) — como o próprio Blume faz — talvez note que as diretivas de contêiner ficam achatadas em uma única linha depois de uma passagem de formatação:

```md
:::note
Regenerate the project with blume dev.
:::
```

vira

```md
:::note Regenerate the project with blume dev. :::
```

Uma vez que a linha de abertura `:::note` é unida à prosa, ela deixa de ser uma diretiva, então é renderizada como texto literal em vez de um [callout](/docs/content/syntax#callouts).

### Por que isso acontece

Isso é um bug no formatador de Markdown do oxfmt (herdado do printer de Markdown do Prettier — veja [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). Quando ele quebra a prosa, trata as linhas de fence `:::` como texto comum e junta com a linha vizinha, quebrando a diretiva. Isso afeta todos os tipos de diretiva de contêiner — `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::success`.

Reportamos o problema upstream em [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096); até ser corrigido lá, o patch abaixo é a solução alternativa.

### A correção

Aplique um patch no oxfmt para que ele preserve a quebra de linha que fica encostada em um fence `:::`. O Blume inclui a mesma correção no próprio repositório, e você pode aplicá-la em qualquer projeto.

1. Salve o patch como `patches/oxfmt@0.66.0.patch`:

   ```diff patches/oxfmt@0.66.0.patch
   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
   --- a/dist/markdown-BgZGxhM2.js
   +++ b/dist/markdown-BgZGxhM2.js
   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
    		case "sentence": return Oh(e, r);
    		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
    		case "whitespace": {
   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   +			let { next: a, 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(":::");
   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
   +			// linkReference between two sentence nodes at the paragraph level: the
   +			// fence word ends the sentence before the reference, and the body's
   +			// leading newline opens the sentence after it. So when this whitespace
   +			// starts its sentence, climb to the paragraph and check whether the two
   +			// preceding siblings are a (link) reference and a sentence ending in a
   +			// `:::` fence word.
   +			let oxfmtPrevIsTitledFence = !1;
   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
   +				if (oxfmtSentIdx >= 2) {
   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
   +				}
   +			}
   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
   +			// words, so the whole directive is one sentence. For a newline
   +			// whitespace, walk back to the start of its visual line within the
   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
   +				let oxfmtLineFirst = null;
   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
   +					let oxfmtSib = e.parent.children[oxfmtJ];
   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
   +					oxfmtLineFirst = oxfmtSib;
   +				}
   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
   +			}
   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
    			return ou(e, n.value, u, !1, t);
    		}
    		case "emphasis": {
   ```

2. Registre ele no `patchedDependencies` do seu gerenciador de pacotes. Com o Bun ou o pnpm, adicione ao `package.json`:

   ```json package.json
   {
     "patchedDependencies": {
       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
     }
   }
   ```

3. Reinstale para que o patch seja aplicado:

   ```package-install
   bun install
   ```

:::warning[Fixado em uma versão]
O patch tem como alvo um build específico do oxfmt — o diff dele referencia um arquivo cujo nome tem um hash por release (`dist/markdown-*.js`). Quando você atualizar o oxfmt, regere o patch (por exemplo, `bun patch oxfmt`) ou verifique se a correção upstream já chegou e o patch não é mais necessário.
:::

---

# Início rápido
Source: https://useblume.dev/pt/docs/quickstart

Passe de uma pasta vazia a um site de documentação em funcionamento com apenas alguns comandos. O Blume precisa de **Node.js 22.12 ou superior** e de uma pasta `docs/` com pelo menos um ficheiro `.md` ou `.mdx` — não há mais nada para configurar.

## Instalar e executar

1. **Install Blume**

    Adicione o pacote a um projeto novo ou já existente.

    ```package-install
    npm i blume
    ```

2. **Scaffold a project**

    O `blume init` faz algumas perguntas — onde criar o projeto, qual o nome do
    seu site de documentação, que modelo usar e onde reside o seu conteúdo — e
    depois gera a estrutura mínima: uma pasta de conteúdo e um ficheiro de
    configuração. Passe `--yes` para saltar as perguntas e aceitar as predefinições.

    ```bash
    blume init
    ```

    ```txt
    docs/
      index.mdx
    blume.config.ts
    ```

3. **Start the dev server**

    O Blume gera o runtime e serve a sua documentação com recarregamento automático.

    ```bash
    blume dev
    ```

4. **Build for production**

    O HTML estático é escrito em `dist/`, com um índice de pesquisa local construído sobre ele.

    ```bash
    blume build
    ```

:::tip
O Blume funciona com qualquer gestor de pacotes e nunca exige que configure o Astro ou o Tailwind por si próprio.
:::

## Escrever a sua primeira página

Cada página é Markdown ou MDX com um pouco de frontmatter — o `title` e a `description` são apresentados automaticamente como o cabeçalho e a introdução da página. Coloque isto em `docs/index.mdx`:

```mdx docs/index.mdx lineNumbers
---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::
```

Guarde o ficheiro e o servidor de desenvolvimento recarrega de imediato. A navegação, a pesquisa e os metadados das páginas são inferidos a partir dos seus ficheiros à medida que os adiciona — continue a escrever, que o site acompanha.

## Próximos passos

**[Configuration](/docs/configuration)**

Ajuste o título, o tema, a pesquisa e a implementação.

**[Components](/docs/content/components)**

Explore a biblioteca de componentes integrada.

**[AI](/docs/configuration/ai)**

Publique um `llms.txt` e um assistente Ask AI.

**[Deployment](/docs/deployment)**

Entre em produção em qualquer alojamento estático.

---

# CLI
Source: https://useblume.dev/pt/docs/reference/cli

```bash
blume <command> [options]
```

## Comandos

| Comando | Descrição |
| --- | --- |
| `blume init [dir]` | Cria a estrutura de um projeto (interativo por padrão). |
| `blume dev` | Inicia o servidor de desenvolvimento com hot reload. |
| `blume build` | Compila o site estático (ou de servidor). |
| `blume preview` | Pré-visualiza a última compilação. |
| `blume add <item>` | Instala um componente de origem a partir do registro. |
| `blume sync` | Busca novamente as fontes de conteúdo remotas e regenera. |
| `blume eject` | Promove o runtime para um app Astro independente. |
| `blume check` | Verifica os tipos do site com `astro check`. |
| `blume doctor` | Diagnostica problemas de configuração e conteúdo. |
| `blume validate` | Valida os links em todo o seu conteúdo. |
| `blume audit` | Audita o site compilado em busca de problemas de SEO e de saúde. |
| `blume eval` | Testa a documentação: um agente responde às suas perguntas usando apenas a documentação. |
| `blume translate` | Traduz a documentação para os idiomas configurados com uma CLI de agente local. |
| `blume version [id]` | Congela a documentação atual como uma [versão arquivada](/docs/content/versioning) (sem id, lista as versões configuradas). |

## Flags comuns

- `blume init` — em um terminal, guia você por algumas perguntas (onde criar o projeto, nome do site, template, fontes de conteúdo); cada flag abaixo responde antecipadamente à sua pergunta.
- `blume init --yes` — pula as perguntas e cria a estrutura com os padrões (também é o comportamento em CI ou quando o stdin não é um terminal).
- `blume init --content-dir <dir>` — define a pasta de conteúdo (padrão `docs`).
- `blume init --template docs|api|sdk|changelog` — cria a estrutura a partir de um modelo inicial (referência de API, SDK ou changelog em vez da semente de documentação simples).
- `blume init --package-manager npm|pnpm|yarn|bun` — adapta os próximos passos exibidos ao seu gerenciador de pacotes.
- `blume init --eject` — cria a estrutura e depois faz eject para um projeto Astro independente (volta a guiar você por `blume eject` quando as dependências ainda não estão instaladas).
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — escaneia uma pasta de conteúdo diferente sem editar o `blume.config.ts`.
- `blume dev --debug` — log detalhado do Astro/Vite para resolução de problemas.
- `blume dev --preview` / `blume build --preview` — inclui rascunhos e conteúdo de CMS não publicado.
- `blume build --no-strict` — compila apesar de erros de diagnóstico. Por padrão, o `blume build` falha (código de saída 1) diante de qualquer diagnóstico de erro, porque as páginas que falham na validação do frontmatter são removidas do resultado; com `--no-strict` a compilação é bem-sucedida e informa quantas páginas estão faltando. O `blume dev --strict` faz o desenvolvimento adotar o mesmo comportamento de falha imediata.
- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — sobrescreve o resultado de deploy, o adaptador e o caminho base definidos no `blume.config.ts`.
- `blume build --analyze` — exibe os tamanhos dos bundles de JavaScript do cliente (do maior para o menor) após a compilação.
- `blume build --budget-js <kb> --budget-css <kb>` — faz a compilação falhar quando o total de JavaScript/CSS do cliente excede o orçamento, transformando uma meta de desempenho em uma barreira de CI.
- `blume build --isolated` — compila para um runtime descartável `.blume-verify/` (e o seu próprio `dist/`) em vez de `.blume/`, para que um servidor `blume dev` em execução e o seu `dist/` real fiquem intactos. Veja [Verificar enquanto o servidor de desenvolvimento roda](#verifying-while-the-dev-server-runs).
- `blume preview --host --port <n>` — vincula o servidor de pré-visualização.
- `blume sync --force` — busca novamente as fontes remotas, descartando primeiro o snapshot em cache.
- `blume add <item> --force` — sobrescreve os arquivos que já existem.
- `blume check --preview` — inclui rascunhos e conteúdo de CMS não publicado na verificação.
- `blume check --strict` — falha também diante de diagnósticos de conteúdo, além dos erros de tipos.
- `blume check --isolated` — verifica os tipos em um runtime descartável `.blume-verify/` para que um servidor `blume dev` em execução fique intacto. Veja [Verificar enquanto o servidor de desenvolvimento roda](#verifying-while-the-dev-server-runs).
- `blume eject --yes` — pula o pedido de confirmação.
- `blume validate --external` — verifica também os links externos pela rede.
- `blume validate --strict` — sai com código diferente de zero também diante de avisos.
- `blume validate --json` / `blume doctor --json` — emite os diagnósticos em JSON no stdout (com `code`, `severity`, `file`, `line`/`column` e `docsUrl`) para integrações de CI e de editores.
- `blume audit --fail-on error|warning|info` — a barreira de CI; o padrão é `error`. `--strict` é um alias para `--fail-on warning`.
- `blume audit --url <origin>` — sonda também um deploy ativo em busca de códigos de status, cabeçalhos de resposta e cadeias de redirecionamento.
- `blume audit --external` — sonda os links de saída pela rede.
- `blume audit --only <check|category>` / `--skip <check|category>` — restringe o relatório enquanto você o resolve (separados por vírgulas).
- `blume audit --list-checks` — exibe todas as verificações que a auditoria pode reportar.
- `blume audit --verbose` — lista todas as páginas afetadas com o detalhe completo de cada constatação, como qual destino de link está quebrado.
- `blume audit --json` — emite o relatório em JSON no stdout.
- `blume audit --claude` / `--codex` — entrega as constatações ao Claude Code ou ao Codex para correção interativa.
- `blume eval` — executa as perguntas de `evals.yaml` através de um agente que lê apenas a sua documentação; veja [Evals](/docs/reference/eval).
- `blume eval init` — faz o agente redigir um `evals.yaml` inicial a partir da sua documentação.
- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — veja [Evals](/docs/reference/eval) para cada flag.
- `blume translate --claude` / `--codex` — traduz páginas faltantes e desatualizadas para os idiomas configurados; veja [Translate](/docs/reference/translate).
- `blume translate --check` — reporta o desvio de tradução e sai com código diferente de zero (a barreira de CI), sem executar um agente.
- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — veja [Translate](/docs/reference/translate) para cada flag.

## Verificar enquanto o servidor de desenvolvimento roda

O `blume dev` serve um servidor Astro ativo com raiz no runtime `.blume/` gerado e o regenera a cada alteração. O `blume build` e o `blume check` regeneram o _mesmo_ `.blume/`, então executar qualquer um deles com o servidor de desenvolvimento ativo iria corrompê-lo — ambos recusam com um erro e saem com código diferente de zero:

```
A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

A flag `--isolated` é a válvula de escape. Ela realoca todo o runtime gerado (e, no caso do `build`, o seu `dist/` de saída) para um diretório irmão `.blume-verify/`, de modo que a verificação nunca escreva nada de que o servidor de desenvolvimento — ou o seu `dist/` real — dependa:

```bash
# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist
```

O `check --isolated` é o caminho rápido (diagnósticos de tipos e de templates do Astro, sem `dist/`); o `build --isolated` é o mais pesado, que também detecta erros de renderização em tempo de execução. As compilações isoladas pulam os passos posteriores de deploy (índice de busca, sincronização com provedor hospedado, `llms.txt`, sitemap/robots, redirecionamentos) — uma verificação só precisa confirmar que o site compila e renderiza, não publicá-lo. O `--analyze` e as barreiras `--budget-js`/`--budget-css` continuam sendo executados, medidos em relação ao resultado isolado. O Blume adiciona automaticamente `.blume-verify/` ao seu `.gitignore`.

Isso é especialmente útil quando um agente de programação precisa verificar alterações enquanto você mantém o servidor de desenvolvimento aberto. Para que o `blume build`/`blume check` simples isolem sem a flag — por exemplo, no shell de um agente — defina `BLUME_RUNTIME_DIR` com o diretório de runtime a usar:

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## Verificação de tipos

O `blume check` executa o [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) sobre o seu projeto. Ele regenera o runtime `.blume`, sincroniza os tipos de conteúdo do Astro e depois reporta quaisquer erros de TypeScript — no seu `blume.config.ts`, em páginas `.astro` personalizadas e nos componentes que elas importam. Ele sai com código diferente de zero quando existem erros, então funciona como um passo `typecheck` em CI:

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

Adicione à raiz do projeto um `tsconfig.json` que estenda a configuração do Astro, para que as páginas criadas resolvam as importações `blume/*` e módulos virtuais como `blume:data`:

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}
```

Sem um `tsconfig.json` no projeto, apenas o runtime gerado é verificado.

## Validar links

O `blume validate` verifica todos os links descobertos no seu conteúdo:

- **Links internos de páginas** (`/guides/intro`, `./sibling`) precisam resolver para uma página real — os que estiverem quebrados são reportados como erros.
- **Links de âncora** (`#section`, `/guides/intro#setup`) precisam corresponder a uma âncora na página de destino — o id de um cabeçalho (gerado ou [fixado](/docs/content/syntax#custom-anchors)) ou o atributo `id` de um elemento HTML puro — e as falhas são reportadas como avisos. Ids dentro de blocos de código, código inline, comentários HTML e blocos `<Prompt>` não contam.

- **Links de assets** são verificados onde o arquivo fica: um caminho absoluto (`/logo.png`) em relação ao diretório `public/`, uma imagem incorporada com caminho relativo (`![](./diagram.png)`) em relação à pasta da própria página. Um link simples para um caminho relativo continua resolvendo como uma rota do site — apenas imagens incorporadas passam pelo pipeline de imagens.
- **Links externos** só são verificados com `--external` (desativado por padrão, já que requer rede); links mortos (404/410/inacessíveis) são erros, enquanto respostas com limite de taxa ou transitórias (403/429/5xx/timeout) são avisos.

## Auditar o site compilado

O `blume validate` lê o seu _conteúdo_; o `blume audit` lê o _site compilado_. Ele rastreia o HTML em `dist/` após uma compilação e reporta problemas de SEO e de saúde do site — títulos, meta descrições, canônicos, cards Open Graph e X, cabeçalhos, hreflang, imagens, o sitemap, o `robots.txt` e dados estruturados.

Como foi o Blume que compilou o site, cada constatação indica o arquivo de origem **e a linha do front matter** que a corrige, e não apenas a URL que um rastreador veria:

```
⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.
```

Execute-o após uma compilação:

```bash
blume build
blume audit
```

As constatações são agrupadas por verificação em vez de listadas por página, para que o relatório se leia como uma lista de tarefas. Use `--verbose` para expandir todas as páginas afetadas com o seu detalhe completo, e `--only`/`--skip` para tratar de uma categoria por vez. O `blume audit --list-checks` exibe o catálogo completo.

### Fazer a CI falhar

O código de saída é o contrato. Por padrão, o `blume audit` só falha diante de erros — coisas que estão definitivamente quebradas, como um link para uma página que nunca foi compilada, um loop de redirecionamento ou um sitemap inválido. Constatações consultivas (uma descrição curta, um título duplicado) são avisos e não fazem a compilação falhar:

```bash
blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings
```

### Verificar um deploy ativo

Há coisas que só o servidor real pode te dizer: se uma página que existe em `dist/` realmente retorna 404 por trás de um rewrite incorreto, se as respostas estão comprimidas e se um cabeçalho `X-Robots-Tag` está discretamente desindexando uma página cujo HTML parece perfeitamente correto. Aponte a auditoria para um deploy para acrescentar essas verificações:

```bash
blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links
```

Os links de saída são classificados em vez de simplesmente reprovados: um 404 é um link quebrado que você pode corrigir, enquanto um 403 ou 5xx normalmente é limitação de taxa ou uma indisponibilidade de terceiros e é reportado como aviso.

### Corrigir as constatações com um agente

Se você usa o [Claude Code](https://claude.com/claude-code) ou o [Codex](https://developers.openai.com/codex/cli), a auditoria pode entregar as suas constatações diretamente a ele:

```bash
blume audit --claude   # or --codex
```

Isso escreve o relatório JSON completo — todas as páginas afetadas, e não a prévia de três páginas do terminal — em um arquivo e abre o agente de forma interativa com um prompt que o orienta pelas constatações: editar o arquivo de origem que cada constatação indica, aplicar a correção sugerida e depois executar novamente `blume build` e `blume audit` até o relatório estar limpo. A sessão é interativa por design: você revisa as edições através do próprio fluxo de permissões do agente, e o agente é instruído a nunca corrigir uma constatação apagando conteúdo.

O `--only` e o `--skip` restringem a entrega da mesma forma que restringem o relatório, então você pode enviar uma categoria por vez.

### O que ele verifica e o que não verifica

O conjunto de verificações é deliberadamente mais restrito do que o de um rastreador de SEO de uso geral. Muito do que esse rastreador reporta não pode acontecer a um site Blume — ele nunca emite `rel=nofollow`, e os bundles com hash de conteúdo do Vite nunca estão faltando nem redirecionando — e reportar isso como zeros permanentes só ensinaria você a ignorar o relatório.

Dois limites que vale a pena declarar com clareza:

- **Dados estruturados** são validados quanto à boa formação (JSON válido, um `@context`, um `@type` em cada nó). O Blume não valida em relação ao vocabulário completo do schema.org nem às regras de resultados enriquecidos do Google.
- **Core Web Vitals** não são verificados. Eles precisam de um navegador real, e uma flag que discretamente não medisse nada seria pior do que não tê-la — por isso o `blume audit` reporta as causas de deslocamento de layout que _consegue_ ver offline (imagens sem `width`/`height`, assets superdimensionados) e deixa o resto de lado por enquanto.

Tudo o que a auditoria não executou é reportado como ignorado, em vez de passar silenciosamente:

```
⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)
```

---

# Avaliações
Source: https://useblume.dev/pt/docs/reference/eval

O `blume audit` diz se os rastreadores conseguem encontrar sua documentação. O `blume eval` diz se alguém consegue de fato _usá-la_: um agente de IA lê sua documentação como um estranho leria e tenta responder a perguntas reais de usuários a partir dela. Quando a documentação não apresenta a resposta, a execução falha e aponta a página que deveria apresentá-la.

```bash
blume eval
```

```
blume eval  3 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: the adapter is auto-detected
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
```

## Como funciona

Cada pergunta passa por duas sessões de agente, usando uma CLI de agente que você já tem instalada — [Claude Code](https://claude.com/claude-code) por padrão, ou [Codex](https://developers.openai.com/codex/cli) com `--agent codex`. O Blume não guarda nenhuma chave de API e não chama nenhum modelo por conta própria.

1. **O leitor** responde à pergunta usando _apenas_ sua documentação. Ele roda em um diretório vazio, com as ferramentas de arquivo, shell e web desativadas, conectado a um [servidor MCP](/docs/configuration/ai) privado que serve sua documentação — as mesmas ferramentas `search_docs`/`get_page` que um agente real usa contra o seu site publicado. Ele não consegue ler seu repositório, então vivencia a documentação exatamente como um usuário novo: o que não está escrito não existe.
2. **O juiz** avalia a resposta em relação aos fatos que você listou, sem nenhuma ferramenta. Paráfrase passa; um fato ausente ou contradito falha — e "a documentação não diz" também falha.

O snapshot do MCP é construído diretamente a partir das suas fontes de conteúdo, então não é necessário rodar o `blume build` antes, e nada é publicado ou enviado para lugar nenhum.

Uma resposta que a documentação _não_ consegue sustentar falha mesmo quando o conhecimento prévio do agente por acaso está correto — esse é justamente o ponto. Sua documentação é a única fonte que vai para produção.

## Escrevendo avaliações

As perguntas ficam em `evals.yaml` na raiz do projeto. Para que um agente rascunhe um arquivo inicial a partir da sua documentação existente:

```bash
blume eval init
```

Ou escreva à mão:

```yaml
questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - the output directory is dist
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - pagefind is the default
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped
```

- `expected` lista os fatos que uma resposta correta deve declarar, em substância — o juiz aceita paráfrase e rejeita contradição.
- `routes` indica a(s) página(s) que deveriam responder à pergunta. Uma falha é então ancorada ao arquivo-fonte dessa página no relatório; uma dica que não corresponde mais a uma página gera um aviso em vez de ser descartada silenciosamente.
- `severity: warning` mantém uma pergunta no relatório sem fazer a CI falhar; `skip: true` deixa uma pergunta de fora por completo.

Escreva as perguntas que seus usuários realmente fazem — as que vêm de tópicos de suporte, issues no GitHub e chamadas de onboarding. As melhores avaliações codificam uma promessa que sua documentação faz ("deploys sem configuração") como uma pergunta que quebra quando um PR quebra a promessa.

## Fazendo a CI falhar

O código de saída é o contrato: qualquer pergunta que falhe sai com código diferente de zero. O `--threshold` afrouxa a barreira para uma fração de aprovação quando você está saindo de um acúmulo de pendências:

```bash
blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout
```

O relatório JSON tem o mesmo formato de `diagnostics` + `summary` que `blume validate --json` e `blume audit --json`, com os resultados por pergunta (resposta, pontuação, fatos ausentes, custo) ao lado.

Como cada pergunta são duas sessões de modelo, uma execução de avaliação custa dinheiro e minutos reais — o gasto por pergunta é exibido conforme a execução acontece. Uma configuração sensata de CI roda o `blume eval` em mudanças na documentação, e não a cada push.

## Corrigindo os achados

Cada falha indica os fatos ausentes e a página que deveria declará-los. Para entregar o relatório inteiro ao agente em vez disso:

```bash
blume eval --fix
```

Isso grava o relatório JSON completo em um arquivo e abre o agente de forma interativa com um prompt que o conduz por cada pergunta que falhou: ler a página indicada, adicionar os fatos ausentes na voz da página e rodar o `blume eval` novamente até tudo passar. A sessão é interativa por design — você revisa as edições através do próprio fluxo de permissões do agente — e o agente é instruído a nunca excluir perguntas ou enfraquecer os fatos esperados para chegar ao verde.

## Flags

- `--agent claude|codex` — qual CLI de agente executa o leitor e o juiz. Padrão: `claude`.
- `--file <path>` — o arquivo de avaliações. Padrão: `evals.yaml`.
- `--threshold <0..1>` — fração mínima de aprovação antes de a execução sair com código diferente de zero. Padrão: `1`.
- `--timeout <seconds>` — limite de tempo do leitor por pergunta. Padrão: `180`.
- `--json` — emite o relatório como JSON no stdout.
- `--fix` — após uma execução com falhas, entrega o relatório ao agente para corrigir a documentação interativamente.
- `--verbose` — inclui a resposta completa do leitor abaixo de cada falha.

---

# Frontmatter
Source: https://useblume.dev/pt/docs/reference/frontmatter

Todas as páginas aceitam o frontmatter a seguir. Todos os campos são opcionais.

| Prop | Type | Default | Description |
| - | - | - | - |
| `title?` | `string` | - | Título da página. |
| `description?` | `string` | - | Resumo da página. |
| `type?` | `string` | `doc` | Tipo de conteúdo. blog/changelog alimentam os feeds. |
| `date?` | `string` | - | Data de publicação para os feeds de blog/changelog (ISO ou data YAML). |
| `authors?` | `string \| string[] \| object[]` | - | Autor(es) do post para conteúdo de blog/changelog — um nome, ou objetos com um nome mais avatar/url opcionais e quaisquer campos extras. Preservado como está. |
| `slug?` | `string` | - | Substitui o slug gerado. |
| `draft?` | `boolean` | `false` | Exclui das builds de produção. |
| `lastModified?` | `string` | - | Fixa a data de "última atualização" da página (ISO ou data YAML); substitui a data derivada do git. |

## Barra lateral

```yaml lineNumbers
sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page
```

`display` define o modo de renderização do grupo de pasta da página ([sobrescritas por grupo](/docs/content/navigation#per-group-overrides)) e só faz sentido na página `index` de uma pasta sob a barra lateral gerada — em qualquer outro lugar (uma página que não seja index, a própria página `index` da raiz de conteúdo ou qualquer página sob uma `navigation.sidebar` explícita) não há grupo para configurar, e o Blume avisa com `BLUME_SIDEBAR_DISPLAY_IGNORED`.

## SEO

```yaml lineNumbers
seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
```

## Pesquisa

```yaml lineNumbers
search:
  exclude: false
  tags: [api]
```

## Changelog

As entradas de changelog (`type: changelog`) aceitam um objeto `changelog` opcional para metadados mais ricos de feed e exibição:

```yaml lineNumbers
type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features
```

`date` pode ficar aqui ou no nível superior — ambos alimentam o [feed RSS do changelog](/docs/content#feeds). Consulte [Changelog](/docs/advanced/changelog) para a página de linha do tempo gerada e o feed.

## Chaves personalizadas

Qualquer chave fora desta referência faz a build falhar, então erros de digitação são detectados cedo. Projetos que carregam seus próprios metadados podem incluir chaves extras via [`frontmatter.extend`](/docs/configuration#frontmatter) em `blume.config.ts`, cada uma validada por um schema fornecido pelo projeto:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

```yaml page.mdx
---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---
```

Os schemas são aceitos pela interface [Standard Schema](https://standardschema.dev), então Zod (qualquer que seja a versão instalada pelo seu projeto), Valibot e ArkType funcionam. Toda chave declarada é validada em cada página — inclusive as ausentes — de modo que um schema obrigatório impõe a chave em todo o site; marque-a como `.optional()` para validar apenas onde estiver presente. Todas as demais chaves permanecem estritamente validadas, e os campos integrados não podem ser redeclarados.

### Chaves por tipo

Para exigir chaves apenas em um tipo de conteúdo — o `status` de uma RFC, a `severity` de um relatório de incidente — declare-as em [`content.types`](/docs/configuration#content), organizadas pelo `type` do frontmatter ao qual se aplicam:

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

```yaml rfcs/openapi-request-schemas.mdx
---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---
```

As chaves por tipo seguem as mesmas regras de validação de `extend`, restritas às páginas cujo `type` resolvido corresponda — incluindo páginas que não definem nenhum `type`, quando a declaração é para [`content.defaultType`](/docs/configuration#content). Uma chave pertence a uma única declaração, no site inteiro ou por tipo, nunca às duas. E uma chave declarada apenas para outro tipo continua desconhecida nos demais, então um `status` perdido numa página de doc comum ainda faz a build falhar.

Uma página que falha na validação faz `blume build` falhar com um diagnóstico nomeando o arquivo e a chave. Com [`--no-strict`](/docs/reference/cli#common-flags), a build é bem-sucedida mesmo assim e as páginas com falha são removidas da saída — o resumo da build informa quantas.

Os schemas são exportados de `blume/schema` para ferramentas de edição e migração.

---

# Traduzir
Source: https://useblume.dev/pt/docs/reference/translate

Depois de ativar o [i18n](/docs/content/i18n), cada edição em uma página de origem desatualiza silenciosamente suas traduções. O `blume translate` fecha esse ciclo: ele calcula exatamente quais páginas estão faltando ou desatualizadas em cada locale, as traduz em modo headless com uma CLI de agente local e registra o que fez em um livro de registro versionado, para que a próxima execução — e o CI — saibam o que está atualizado.

```bash
blume translate --claude
```

```
blume translate  3 item(s) · 2 locale(s) · Claude Code

  ✔ docs/guides/install.mdx → fr 24.2s $0.11
  ✔ docs/guides/install.mdx → de 22.8s $0.10
  ✔ meta titles (2) → de 4.1s $0.01

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
```

## Como funciona

O Blume é o dono do pipeline; o agente só traduz texto. Para cada arquivo que precisa de trabalho, o Blume monta um prompt de tradução, executa a CLI do agente em modo headless com as ferramentas de arquivo, shell e web desativadas, valida a estrutura da resposta e escreve ele mesmo o arquivo de destino — [Claude Code](https://claude.com/claude-code) com `--claude`, ou [Codex](https://developers.openai.com/codex/cli) com `--codex`. O Blume não guarda chaves de API e não chama nenhum modelo por conta própria.

Cada escrita validada é registrada em `blume.translations.json` na raiz do projeto: para cada arquivo de origem e locale, um hash da origem no momento em que foi traduzida. **Faça commit desse arquivo.** É assim que uma nova execução distingue entre "já traduzido" e "traduzido, mas a origem mudou desde então" — e é o que torna o portão de CI possível.

O livro de registro é gravado após cada arquivo concluído, então interromper uma execução longa (Ctrl+C) perde, no máximo, as traduções que estavam em andamento — a execução seguinte retoma de onde você parou. Por padrão, os arquivos são processados 4 por vez; aumente esse valor com `--concurrency` se a sua máquina e os limites de taxa do agente permitirem.

As novas execuções são incrementais: uma origem que não mudou desde a última tradução é ignorada, então rodar `blume translate` depois de editar uma página traduz uma página por locale. Quando uma página desatualizada é retraduzida, o agente vê a tradução existente e é instruído a manter seu registro, dialeto e terminologia — uma edição de um parágrafo na origem produz um diff de tradução de um parágrafo, não uma reescrita do zero.

Uma primeira tradução não tem precedente para seguir, então fixe a escolha desde o início com [`style` no locale](/docs/content/i18n) (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`). Essa orientação acompanha todo prompt de tradução e, quando uma tradução existente discorda dela, o `style` vence — assim, uma retradução também empurra as páginas mais antigas na direção do estilo configurado.

## O que é traduzido

- **Páginas** — arquivos `.md`/`.mdx` no locale padrão. O agente traduz a prosa e apenas os valores de frontmatter visíveis para humanos (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`). Os destinos seguem o seu parser: `fr/guides/install.mdx` com `dir`, `guides/install.fr.mdx` com `dot`.
- **Títulos de navegação de pastas** — com o parser `dir`, os títulos [`meta.ts`](/docs/content/meta) necessários de cada locale são traduzidos em uma única chamada em lote, e o `meta.ts` gerado por locale copia todas as outras chaves (`order`, `pages`, `icon`, `collapsed`) sem alteração, para que a barra lateral do locale mantenha sua ordenação.

As traduções que você escreveu à mão são **adotadas, nunca sobrescritas**: uma tradução que existe mas não tem entrada no livro de registro é marcada como atual e deixada intacta. Só o `--force` a retraduz.

## Validação

A estrutura nunca é confiada ao agente. Antes de escrever, o Blume verifica cada resposta e reconstrói o arquivo a partir da origem:

- O frontmatter é reconstruído a partir dos dados do arquivo de origem, com apenas os seis valores traduzíveis sobrepostos — as chaves que o agente inventou são descartadas, as chaves que ele apagou são restauradas, e `slug`, `icon`, `order` e as datas são, por construção, idênticas às da origem.
- O número de blocos de código precisa corresponder ao da origem, o corpo não pode estar vazio e o frontmatter precisa ser analisável.

Uma resposta que falha na validação não escreve nada — o item é reportado como falho e a execução segue em frente. Tudo o que teve sucesso permanece registrado no livro de registro, então uma nova execução repete apenas as falhas.

## Falhar o CI

O `blume translate --check` é o portão somente leitura: ele reporta todos os pares faltando e desatualizados e sai com código diferente de zero quando há dessincronização, sem executar um agente nem escrever nada.

```bash
blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

O relatório JSON tem o mesmo formato `diagnostics` + `summary` que o `blume validate --json`, o `blume audit --json` e o `blume eval --json`, com a dessincronização agrupada por locale. As traduções escritas à mão (não registradas) nunca fazem o portão falhar.

## Limitações

- A tradução de títulos de meta existe apenas no parser `dir` — o parser `dot` não tem mecanismo de `meta.ts` por locale. Um `meta.ts` que exporta uma função como default é ignorado com um aviso; escreva a cópia desse locale à mão.
- As origens remotas e vindas de CMS são ignoradas: não existe um arquivo local onde escrever a tradução.
- Os rótulos das abas do cabeçalho vivem em `blume.config.ts`, não no conteúdo — localize-os lá com [mapas de rótulos por locale](/docs/content/navigation#tabs).
- A qualidade da tradução é do agente. Revise o resultado como qualquer outra contribuição — o livro de registro só garante atualidade, não fluência.

## Flags

- `--claude` / `--codex` — qual CLI de agente traduz. Exatamente uma é obrigatória (exceto com `--check`).
- `--check` — reportar a dessincronização e sair com código diferente de zero, sem escrever nada.
- `--concurrency <n>` — sessões de agente em paralelo. O padrão é `4`; máximo `16`.
- `--locale <codes>` — locales de destino separados por vírgula (por padrão, todos os locales não padrão).
- `--force` — retraduzir tudo, incluindo arquivos atualizados e escritos à mão.
- `--timeout <seconds>` — limite de tempo do agente por arquivo. O padrão é `600`; o teto existe para pegar agentes travados, então páginas grandes têm espaço para terminar.
- `--json` — emitir o relatório em JSON no stdout, nos dois modos.