blume 0.3.0 → 0.5.0

package/docs/content/components.mdx

@@ -3,16 +3,11 @@ title: Components
 description: The built-in JSX components — cards, columns, steps, tabs, accordions, badges, code groups, frames, trees, tooltips, type tables, live component previews, diffs, and a GitHub card — usable in any MDX page.
 ---
 
-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.
+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.
+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.
 
 <CardGroup cols={2}>
   <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
@@ -34,13 +29,11 @@ indexes, and “next steps” — anywhere you’re guiding the reader onward.
 </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`).
+`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`.
+A numbered vertical sequence for ordered instructions — installs, setup flows, and tutorials where the order matters. Each `Step` takes a `title`.
 
 <Steps>
   <Step title="Install Blume">Add the package to your project.</Step>
@@ -62,9 +55,7 @@ and tutorials where the order matters. Each `Step` takes a `title`.
 
 ## 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`.
+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`.
 
 <Tabs>
   <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
@@ -80,8 +71,7 @@ Each `Tab` takes a `title`.
 
 ## 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.
+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
 
@@ -135,9 +125,7 @@ A negative or breaking state, such as a deprecation.
 
 ## Icon
 
-Render an icon from Blume's built-in set by name — the same set the `icon` props
-on cards, tiles, tabs, and sidebar entries draw from. Names are lowercase and
-kebab-cased (`rocket`, `book-open`, `chevron-right`).
+Render an icon by name — the same `icon` props power cards, steps, tiles, tabs, and sidebar entries. Names come from three bundled libraries: [Lucide](https://lucide.dev) (the default), [Font Awesome](https://fontawesome.com/icons) (its free set), and [Tabler](https://tabler.io/icons). Names are lowercase and kebab-cased (`rocket`, `gauge-high`, `book-open`).
 
 <Icon icon="rocket" size={20} />
 
@@ -145,16 +133,30 @@ kebab-cased (`rocket`, `book-open`, `chevron-right`).
 <Icon icon="rocket" size={20} />
 ```
 
-`icon` is the icon name; `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.
+A bare name resolves against your project's [`icons.library`](#default-library) (Lucide unless you change it). Two ways to reach another library for a single icon:
+
+- **`iconType`** selects a Font Awesome style — `solid` (default), `regular`, or `brands`: `<Icon icon="github" iconType="brands" />`. Font Awesome Pro styles (`light`, `thin`, `duotone`, `sharp-solid`) aren't in the bundled free data and fall back to solid.
+- **A `library:name` prefix** overrides the default per icon: `fa6-solid:gauge-high`, `fa6-brands:github`, `lucide:rocket`, `tabler:heart`.
+
+`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.
+
+### Default library
+
+Set which library bare icon names resolve against:
+
+```ts title="blume.config.ts"
+export default defineConfig({
+  icons: { library: "fontawesome" }, // "lucide" (default) | "fontawesome" | "tabler"
+});
+```
+
+A `library:name` prefix always wins over this, so you can mix libraries on any default. Migrating from Mintlify sets this to `fontawesome` for you (Mintlify's default), so your existing icon names keep working.
 
 ## 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.
+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>
 
@@ -180,10 +182,7 @@ styles it as a tree — handy for explaining structure in setup and config guide
 
 ## 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).
+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?">
@@ -207,9 +206,7 @@ disclosure, use [Expandable](#expandable).
 
 ## 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.
+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.
@@ -223,8 +220,7 @@ sub-properties or an optional aside. `title` labels the toggle (defaults to
 
 ## 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`.
+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>
@@ -256,9 +252,7 @@ mobile. `Columns` takes `cols`; wrap each cell in a `Column`.
 
 ## 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). Add `dropdown`
-to switch with a menu instead of a tab bar.
+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). Add `dropdown` to switch with a menu instead of a tab bar.
 
 <CodeGroup>
 
@@ -302,8 +296,7 @@ fn greet(name: &str) -> String {
 
 ## Frame
 
-Wrap an image or any visual in a centered, bordered frame with an optional
-`caption` (rendered as Markdown) and `hint`.
+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."
@@ -329,12 +322,20 @@ Wrap an image or any visual in a centered, bordered frame with an optional
 </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.
+
+<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
+
+```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).
+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" />
@@ -352,10 +353,7 @@ with `Color.Row` to group them. Each `Color.Item` takes a `name` and a `value`
 
 ## 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`).
+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>
@@ -395,8 +393,7 @@ A titled container for supplementary, set-aside content. `title` is optional.
 
 ## 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.
+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.
 
@@ -406,9 +403,7 @@ Hover the <Tooltip tip="A set of protocols software uses to communicate." headli
 
 ## 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.
+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"
@@ -430,10 +425,7 @@ and `href`; the child is the visual.
 
 ## 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"]`).
+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."
@@ -453,8 +445,7 @@ buttons (e.g. `["copy", "cursor"]`).
 
 ## Visibility
 
-Show or hide content by audience. `for="web"` renders only on the site;
-`for="agents"` targets the generated Markdown (`llms.txt`) that AI agents read.
+Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the generated Markdown (`llms.txt`) that AI agents read.
 
 <Visibility for="web">
   This note appears on the website but is omitted from the agent-facing
@@ -466,19 +457,47 @@ Show or hide content by audience. `for="web"` renders only on the site;
 <Visibility for="agents">Shown only in the generated Markdown.</Visibility>
 ```
 
+## API fields
+
+Document a single request/response field — a CLI flag, an SDK argument, an endpoint parameter — with its name, type, and description. `ParamField`, `ResponseField`, and `RequestField` are Mintlify-compatible, so a migrated site's field markup renders unchanged. Each takes a `type`, plus `required`, `deprecated`, and `default`; the description is the element's body and may hold rich MDX, including a nested [Expandable](#expandable) for sub-properties.
+
+`ParamField` names the field through the attribute that marks its location — `path`, `query`, `header`, or `body` (or a plain `name`); the location shows as a small label.
+
+<ParamField path="userId" type="string" required>
+  The unique identifier of the user.
+</ParamField>
+
+<ParamField query="limit" type="integer" default="20">
+  Maximum number of results to return per page.
+</ParamField>
+
+<ResponseField name="createdAt" type="string">
+  ISO 8601 timestamp for when the record was created.
+</ResponseField>
+
+```mdx
+<ParamField path="userId" type="string" required>
+  The unique identifier of the user.
+</ParamField>
+
+<ParamField query="limit" type="integer" default="20">
+  Maximum number of results to return per page.
+</ParamField>
+
+<ResponseField name="createdAt" type="string">
+  ISO 8601 timestamp for when the record was created.
+</ResponseField>
+```
+
+For a full spec-driven API reference — one page per operation with generated schemas — use the [OpenAPI reference](/docs/advanced/api-reference) instead.
+
 ## 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`.
+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.
+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.
 
 <TypeTable
   type={{
@@ -516,17 +535,13 @@ name.
 
 ### 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.
+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:
+You can also pass the type inline with `type` instead of a `path` — handy for small examples:
 
 <AutoTypeTable
   name="ButtonProps"
@@ -566,11 +581,7 @@ export interface ButtonProps {
 
 ## 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.
+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.
 
 <GithubInfo owner="withastro" repo="astro" />
 
@@ -584,16 +595,9 @@ variable to lift the API rate limit.
 
 ## 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.
+`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 directory is configurable — set `examples` in `blume.config.ts` when your
-examples live elsewhere (e.g. a registry layout). `path` is always relative to
-it:
+The directory is configurable — set `examples` in `blume.config.ts` when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it:
 
 ```ts
 // blume.config.ts
@@ -607,11 +611,7 @@ export default defineConfig({
 <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:
+`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
@@ -640,9 +640,7 @@ An Astro example renders live with no client JavaScript:
 
 ## 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` 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"
@@ -658,8 +656,7 @@ 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`:
+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";
@@ -669,10 +666,7 @@ 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` 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"

package/docs/content/i18n.mdx

@@ -3,10 +3,7 @@ title: Internationalization
 description: Serve your docs in multiple languages with locale-aware routing, per-language navigation, translated UI, and SEO — all convention-first.
 ---
 
-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.
+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.
 
 ## Enable it
 
@@ -23,20 +20,13 @@ i18n: {
 }
 ```
 
-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).
+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).
 
-:::tip
-Migrating from Mintlify? `blume migrate mintlify` reads
-`navigation.languages[]` and writes the `i18n` block for you — the `default: true`
-language becomes `defaultLocale`, and translated folders already match Blume's
-layout.
-:::
+:::tip Migrating from Mintlify? [`blume migrate mintlify`](/docs/advanced/migrate) reads `navigation.languages[]` and writes the `i18n` block for you — the `default: true` language becomes `defaultLocale`, and translated folders already match Blume's layout. :::
 
 ## 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:
+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/
@@ -55,13 +45,11 @@ docs/
 | `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)).
+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:
+Prefer to keep translations next to the original? Set `parser: "dot"` and name files with a locale suffix instead of using folders:
 
 ```txt
 docs/
@@ -69,13 +57,11 @@ docs/
   guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)
 ```
 
-Good for sparse translations — colocate the few pages you've translated without
-mirroring the whole tree.
+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:
+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)
@@ -86,9 +72,7 @@ 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:
+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: {
@@ -99,17 +83,11 @@ i18n: {
 
 ## 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: put a `meta.ts`
-under `fr/guides/` to order the French group independently. Everything else about
-[navigation](/docs/content/navigation) works the same, per language.
+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: put a `meta.ts` under `fr/guides/` to order the French group independently. Everything else about [navigation](/docs/content/navigation) works the same, per language.
 
 ## 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`:
+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: {
@@ -118,40 +96,21 @@ i18n: {
 }
 ```
 
-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.
+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.
-:::
+:::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. :::
 
 ## 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.
+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.**
+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 36 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.
+Packs ship for 36 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:
+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: {
@@ -170,28 +129,18 @@ i18n: {
 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.
+- `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.
+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.
+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.
+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