blume 0.0.0 → 0.1.0

package/docs/content/navigation.mdx

@@ -0,0 +1,168 @@
+---
+title: Navigation
+description: Build the sidebar from your files, then refine it with frontmatter, folder meta, or config.
+---
+
+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, [display
+mode](/docs/content/meta#display-modes), 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, the three display modes,
+and computing meta at scan time.
+
+To group pages _without_ adding a URL segment, use a parenthesized folder name —
+see [Pages](/docs/content#group-folders).
+
+## Ordering
+
+When the sidebar is generated, order is resolved highest priority first:
+
+<Steps>
+  <Step title="Config sidebar">
+    An explicit `navigation.sidebar` replaces the generated tree entirely.
+  </Step>
+  <Step title="Folder meta">
+    The `pages` array in `meta.ts` orders a group.
+  </Step>
+  <Step title="Frontmatter">`sidebar.order` on a page.</Step>
+  <Step title="File system">
+    An `index` page first, then numeric prefixes, then alphabetical by label.
+  </Step>
+</Steps>
+
+## 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 separating, say, docs
+from an API reference. A tab is highlighted when the current route falls under
+its `path`:
+
+```ts blume.config.ts lineNumbers
+navigation: {
+  tabs: [
+    { label: "Docs", path: "/", icon: "book-open" },
+    { label: "API", path: "/api", icon: "rocket" },
+  ],
+}
+```
+
+## Explicit sidebar
+
+For full control, define `navigation.sidebar` in config. When it's set, Blume
+uses it 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, take a [`display`
+mode](/docs/content/meta#display-modes), and start `collapsed`.
+
+## 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.
+
+## 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 this page 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`).
+
+Three more hand the page to AI tools — **Copy as Markdown**, **Open in chat**, and
+**Ask AI about this page** — 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.

package/docs/content/sources.mdx

@@ -0,0 +1,216 @@
+---
+title: Content sources
+description: Pull docs from local files, a remote repo, or any custom backend — and mix several sources into one site.
+---
+
+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`.
+
+## 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.
+
+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.
+
+## 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` is an optional peer dependency.
+
+```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.
+
+## 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.