blume 0.0.0 → 0.1.0

package/docs/content/syntax.mdx

@@ -0,0 +1,445 @@
+---
+title: Syntax
+description: Every Markdown and MDX feature Blume renders — formatting, lists, tables, callouts, code blocks, package installs, and math.
+---
+
+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 `##` — `##` through `####` 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
+```
+
+## 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.
+
+```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/` |
+```
+
+## Links and images
+
+Link to other pages or external sites. Images accept any path under `public/` 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)
+```
+
+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}`. Turn it on with `markdown: { code: { inline: true } }`.
+
+### 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;
+//     ^?
+```
+````
+
+:::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.
+
+```package-install
+npm i blume
+```
+
+````md
+```package-install
+npm i blume
+```
+````
+
+## Diagrams
+
+A `mermaid` block renders a [Mermaid](https://mermaid.js.org) diagram — flowcharts,
+sequence diagrams, and more — straight from text. Diagrams follow the active color
+theme and re-render when it changes.
+
+```mermaid
+flowchart LR
+  A[Markdown] --> B{blume build}
+  B --> C[Static HTML]
+  B --> D[llms.txt]
+```
+
+````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.
+
+## 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]`.
+
+### 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 zero client JavaScript.
+:::
+
+```md
+:::info
+The core theme ships zero client JavaScript.
+:::
+```
+
+The names `caution`, `error`, `important`, and `warn` are accepted as aliases for
+`warning`, `danger`, `note`, and `warning` respectively.
+
+## Math
+
+Render LaTeX with KaTeX for formulas in prose or as centered blocks — useful for
+math-heavy or scientific docs. Inline math goes in `$…$`; block math in `$$…$$`.
+
+The Pythagorean theorem is $a^2 + b^2 = c^2$.
+
+$$
+\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
+$$
+
+```md
+The Pythagorean theorem is $a^2 + b^2 = c^2$.
+
+$$
+\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
+$$
+```
+
+:::note
+Math is opt-in because `$` is common in prose and code. Enable it with
+`markdown: { math: true }` in `blume.config.ts`.
+:::
+
+## 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.
+```

package/docs/index.mdx

@@ -0,0 +1,112 @@
+---
+title: Introduction
+description: Blume is an open-source, markdown-first documentation framework on Astro and Vite — fast, AI-ready, and zero-config down to the template.
+sidebar:
+  label: Introduction
+  order: 0
+---
+
+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.
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
+    Install Blume and ship your first page in minutes.
+  </Card>
+  <Card title="Configuration" href="/docs/configuration" icon="file">
+    Tune the title, theme, search, and deployment.
+  </Card>
+</CardGroup>
+
+## Why Blume exists
+
+Blume is the answer to a problem I kept trying to solve at Vercel: documentation
+should be _fast_, _AI-ready_, and require _zero configuration_ — down to not
+needing a starter template at all.
+
+Most docs tools hand you a project to own before you've written a word: an app to
+scaffold, a framework to learn, a template to keep in sync with upstream. Blume
+flips that around. The framework _is_ the template, so the only thing you ever
+touch is your content. When you outgrow the defaults, you add configuration one
+file at a time — and you can `blume eject` to a plain Astro project the day you
+want full control.
+
+— Hayden Bleasel
+
+## 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 is React-free and ships **zero
+client JavaScript**, 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, 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, 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`.
+- **Migration** — `blume migrate mintlify | starlight | fumadocs`.
+- **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
+
+<CardGroup cols={2}>
+  <Card title="Configuration" href="/docs/configuration" icon="file">
+    Tune the title, theme, search, and deployment.
+  </Card>
+  <Card title="Components" href="/docs/content/components" icon="folder">
+    Explore the built-in component library.
+  </Card>
+  <Card title="AI" href="/docs/configuration/ai" icon="lightbulb">
+    Ship `llms.txt` and an Ask AI assistant.
+  </Card>
+  <Card title="CLI" href="/docs/reference/cli" icon="rocket">
+    Every `blume` command and flag.
+  </Card>
+</CardGroup>

package/docs/reference/cli.mdx

@@ -0,0 +1,43 @@
+---
+title: CLI
+description: The Blume command-line interface.
+---
+
+```bash
+blume <command> [options]
+```
+
+## Commands
+
+| Command                | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| `blume init`           | Scaffold a minimal project.                            |
+| `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 migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
+| `blume eject`          | Promote the runtime into a standalone Astro app.       |
+| `blume doctor`         | Diagnose config and content problems.                  |
+| `blume validate`       | Validate links across your content.                    |
+
+## Common flags
+
+- `blume dev --host --port <n> --open`
+- `blume build --strict` — fail on diagnostics.
+- `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.
+
+## 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 a heading on
+  the target page — misses are warnings.
+- **Asset links** (`/logo.png`) are checked against the `public/` directory.
+- **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.

package/docs/reference/frontmatter.mdx

@@ -0,0 +1,74 @@
+---
+title: Frontmatter
+description: The page metadata schema.
+---
+
+Every page accepts the following frontmatter. All fields are optional.
+
+<TypeTable
+  type={{
+    title: { type: "string", description: "Page title." },
+    description: { type: "string", description: "Page summary." },
+    type: {
+      type: "string",
+      default: "doc",
+      description: "Content type. blog/changelog drive feeds.",
+    },
+    date: {
+      type: "string",
+      description: "Publish date for blog/changelog feeds (ISO or YAML date).",
+    },
+    slug: { type: "string", description: "Override the generated slug." },
+    draft: {
+      type: "boolean",
+      default: "false",
+      description: "Exclude from production builds.",
+    },
+  }}
+/>
+
+## Sidebar
+
+```yaml lineNumbers
+sidebar:
+  label: Install
+  order: 2
+  icon: Download
+  hidden: false
+```
+
+## SEO
+
+```yaml lineNumbers
+seo:
+  title: Install Blume
+  image: /og/install.png
+  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.
+
+Schemas are exported from `blume/schema` for editor and migration tooling.

package/docs/reference/meta.ts

@@ -0,0 +1,7 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  order: 6,
+  pages: ["frontmatter", "cli"],
+  title: "Reference",
+});