blume 0.0.0 → 0.1.0

package/docs/content/i18n.mdx

@@ -0,0 +1,205 @@
+---
+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.
+
+## 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).
+
+:::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.
+:::
+
+## 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: 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`:
+
+```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.
+:::
+
+## 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 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:
+
+```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
+
+<CardGroup cols={2}>
+  <Card title="Navigation" href="/docs/content/navigation" icon="menu">
+    Shape each locale's sidebar, ordering, and tabs.
+  </Card>
+  <Card title="SEO" href="/docs/configuration/seo" icon="rocket">
+    Sitemaps, Open Graph, and structured data.
+  </Card>
+</CardGroup>

package/docs/content/index.mdx

@@ -0,0 +1,161 @@
+---
+title: Pages
+description: How files in your content folder become pages, and how to organize them.
+---
+
+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
+
+<CardGroup cols={2}>
+  <Card title="Frontmatter" href="/docs/reference/frontmatter" icon="file">
+    Page metadata: title, description, sidebar, SEO, and search.
+  </Card>
+  <Card title="Syntax" href="/docs/content/syntax" icon="book-open">
+    Every Markdown and MDX feature you can write.
+  </Card>
+  <Card title="Components" href="/docs/content/components" icon="folder">
+    The JSX components available in any MDX page.
+  </Card>
+  <Card title="Navigation" href="/docs/content/navigation" icon="menu">
+    Shape the sidebar, ordering, and tabs.
+  </Card>
+  <Card title="Folder meta" href="/docs/content/meta" icon="panel-left">
+    Configure a sidebar group with a `meta.ts` file.
+  </Card>
+</CardGroup>

package/docs/content/islands.mdx

@@ -0,0 +1,94 @@
+---
+title: Islands
+description: Drop an interactive component into islands/ and use it in any MDX page — hydrated automatically, no per-page import.
+---
+
+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 PascalCase**
+(`Counter.tsx` → `<Counter />`). Lowercase filenames 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.
+:::
+
+## 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.
+
+**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.
+:::

package/docs/content/meta.mdx

@@ -0,0 +1,119 @@
+---
+title: Folder meta
+description: Configure a sidebar group — its title, icon, order, display mode, and page order — with a meta.ts file.
+---
+
+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,
+  display: "flat",
+  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.                     |
+| `display`   | `"flat" \| "group" \| "page"` | How the group renders in the sidebar. Defaults to `flat`. See [below](#display-modes). |
+| `collapsed` | `boolean`                     | For `display: "group"`, whether the group starts collapsed.                            |
+| `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.
+
+## Display modes
+
+`display` controls how a group and its items appear in the sidebar:
+
+- **`flat`** (default) — a non-collapsible header with its pages listed beneath.
+- **`group`** — a collapsible `<details>` disclosure. Pair it with `collapsed`
+  to set the initial state; a group containing the current page always starts
+  open.
+- **`page`** — 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 a group has many
+children and you'd rather drill into it than scroll past it.
+:::
+
+`display` works the same on a group in an [explicit
+sidebar](/docs/content/navigation#explicit-sidebar) config.
+
+## 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
+
+<CardGroup cols={2}>
+  <Card title="Navigation" href="/docs/content/navigation" icon="menu">
+    How the sidebar, breadcrumbs, and tabs are built.
+  </Card>
+  <Card title="Frontmatter" href="/docs/reference/frontmatter" icon="file">
+    Per-page metadata, including the `sidebar` overrides.
+  </Card>
+</CardGroup>

package/docs/content/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  order: 3,
+  pages: [
+    "navigation",
+    "meta",
+    "syntax",
+    "components",
+    "islands",
+    "sources",
+    "i18n",
+  ],
+  title: "Content",
+});