blume 0.1.0 → 0.1.2

package/dist/types/theme/fonts.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Curated Google Fonts exposed through `theme.fonts`.
+ *
+ * Each slug maps to the official Google family name (Astro's font provider needs
+ * the exact name), a docs-appropriate set of weights, and a fallback category.
+ * Fonts are self-hosted and optimized by Astro's built-in Fonts API; this module
+ * only resolves config slugs into the data that drives it.
+ */
+export type FontCategory = "sans" | "serif" | "mono";
+/** The three configurable roles in `theme.fonts`. */
+export type FontSlot = "display" | "body" | "mono";
+/** Resolved theme fonts (a validated slug per role, all optional). */
+export type FontsConfig = Partial<Record<FontSlot, string>> | undefined;
+/** A single Astro `fonts:` entry (sans the literal `fontProviders.google()`). */
+export interface FontEntry {
+    cssVariable: string;
+    fallbacks: string[];
+    name: string;
+    weights: number[];
+}
+/** Slug -> Google family + weights + fallback category. Keep keys alphabetical. */
+export declare const GOOGLE_FONTS: {
+    "dm-sans": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    figtree: {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "fira-code": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    geist: {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "geist-mono": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    "ibm-plex-mono": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    "ibm-plex-sans": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "ibm-plex-serif": {
+        category: "serif";
+        family: string;
+        weights: number[];
+    };
+    inter: {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "inter-tight": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "jetbrains-mono": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    lora: {
+        category: "serif";
+        family: string;
+        weights: number[];
+    };
+    manrope: {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    merriweather: {
+        category: "serif";
+        family: string;
+        weights: number[];
+    };
+    "open-sans": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "playfair-display": {
+        category: "serif";
+        family: string;
+        weights: number[];
+    };
+    "plus-jakarta-sans": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    roboto: {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "roboto-mono": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    "source-code-pro": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    "source-sans-3": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "source-serif-4": {
+        category: "serif";
+        family: string;
+        weights: number[];
+    };
+    "space-grotesk": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+    "space-mono": {
+        category: "mono";
+        family: string;
+        weights: number[];
+    };
+    "work-sans": {
+        category: "sans";
+        family: string;
+        weights: number[];
+    };
+};
+export type FontSlug = keyof typeof GOOGLE_FONTS;
+/** All supported slugs, for schema validation and error messages. */
+export declare const FONT_SLUGS: string[];
+/** Type guard: is `value` a supported font slug? */
+export declare const isFontSlug: (value: string) => value is FontSlug;
+/** The unique Astro `fonts:` entries for the configured roles (deduped). */
+export declare const buildFontEntries: (fonts: FontsConfig) => FontEntry[];
+/**
+ * The config-token CSS that points each role's `--blume-font-<role>-src` at the
+ * Astro-populated family variable. Concatenated into the generated entry's
+ * config tokens; empty when no fonts are set so defaults stay the system stacks.
+ */
+export declare const buildFontsCss: (fonts: FontsConfig) => string;
+/** The CSS variables to feed Astro's `<Font>` component in the document head. */
+export declare const configuredCssVars: (fonts: FontsConfig) => string[];

package/docs/advanced/custom-pages.mdx

@@ -69,32 +69,68 @@ import data from "blume:data";
 </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:
 
 <TypeTable
   type={{
     config: {
-      type: "object",
+      type: "BlumeDataConfig",
       required: true,
       description:
-        "Resolved site config — title, description, logo, banner, theme, site URL, repoUrl, and search settings.",
+        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, search, i18n, mcp, og, analytics, feedback, structuredData, codeWrap, and imageZoom.",
     },
     navigation: {
-      type: "object",
+      type: "Navigation",
+      required: true,
+      description:
+        "The sidebar, tabs, and selectors inferred from your content (default locale).",
+    },
+    navigationByLocale: {
+      type: "Record<string, Navigation>",
       required: true,
-      description: "The sidebar and tab tree inferred from your content.",
+      description:
+        "Per-locale navigation trees, keyed by locale code. Empty unless i18n is configured.",
     },
     routes: {
-      type: "Route[]",
+      type: "BlumeRoute[]",
       required: true,
       description:
-        "Every content page: { id, path, title, indexable, hidden, draft, editUrl }.",
+        "Every content page: { id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }.",
     },
     feeds: {
-      type: "Feed[]",
+      type: "BlumeFeed[]",
       required: true,
       description: "Generated RSS feeds: { href, title }.",
     },
+    fontCssVars: {
+      type: "string[]",
+      required: true,
+      description:
+        "CSS variable names for the configured fonts (Astro <Font> integration).",
+    },
+    ui: {
+      type: "UIStrings",
+      required: true,
+      description:
+        "Resolved UI chrome strings for the default locale (search, sidebar, and footer labels).",
+    },
+    uiByLocale: {
+      type: "Record<string, UIStrings>",
+      required: true,
+      description:
+        "Per-locale UI strings, keyed by locale code. Empty unless i18n is configured.",
+    },
   }}
 />
 
@@ -133,9 +169,54 @@ const posts = (await getCollection("docs"))
 
 ## Using the site layout
 
-To give a custom page the full Blume chrome — header, sidebar, search, and theme
-— wrap it in `RootLayout`, the same layout the generated pages use. Pull the
-required props straight from `blume:data`:
+`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>
+```
+
+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.
+
+`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
 ---

package/docs/configuration/index.mdx

@@ -137,6 +137,25 @@ 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.
 
+### 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.
+
 ### Banner
 
 Show a site-wide announcement bar above the header. Pass a string, or an object

package/docs/content/components.mdx

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: The built-in JSX components — cards, columns, steps, tabs, accordions, badges, code groups, frames, trees, tooltips, type tables, and a GitHub card — usable in any MDX page.
+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
@@ -563,3 +563,105 @@ variable to lift the API rate limit.
 <!-- Or point it at any repository -->
 <GithubInfo owner="withastro" repo="astro" />
 ```
+
+## 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 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
+export default defineConfig({
+  examples: "registry/files-sdk",
+});
+```
+
+```astro
+<!-- registry/files-sdk/file-list/basic.tsx -->
+<Component path="file-list/basic" />
+```
+
+<Component path="counter" />
+
+```astro
+<!-- examples/counter.tsx -->
+<Component path="counter" />
+```
+
+An Astro example renders live with no client JavaScript:
+
+<Component path="card" />
+
+## 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" />
+
+Or render a unified patch from a file:
+
+<Diff src="diffs/greet.patch" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -31,10 +31,17 @@
     "docs"
   ],
   "type": "module",
+  "types": "./dist/types/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.ts"
+    },
     "./ai/*": "./src/ai/*",
-    "./schema": "./src/core/schema.ts",
+    "./schema": {
+      "types": "./dist/types/core/schema.d.ts",
+      "default": "./src/core/schema.ts"
+    },
     "./runtime": "./src/runtime/index.ts",
     "./astro": "./src/astro/index.ts",
     "./og": "./src/og/index.ts",
@@ -62,6 +69,7 @@
     "@astrojs/vercel": "^11.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@orama/orama": "^3.1.18",
+    "@pierre/diffs": "^1.2.11",
     "@scalar/astro": "^0.4.5",
     "@shikijs/transformers": "^4.2.0",
     "@shikijs/twoslash": "^4.2.0",
@@ -79,6 +87,7 @@
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "jiti": "^2.4.0",
+    "js-yaml": "^4.1.0",
     "katex": "^0.17.0",
     "mermaid": "^11.15.0",
     "pagefind": "^1.3.0",
@@ -93,6 +102,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/src/ai/llms.ts

@@ -1,5 +1,4 @@
-import matter from "gray-matter";
-
+import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { PageRecord } from "../core/types.ts";

package/src/astro/examples.ts

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+
+import { join, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import type { IslandClientMode } from "./islands.ts";
+import { readClientMode } from "./islands.ts";
+
+/** Framework an example is authored in, inferred from its extension. */
+export type ExampleFramework = "astro" | "react" | "svelte" | "vue";
+
+/** A discovered `examples/` file, ready to wrap (live) and show (source). */
+export interface ExampleSpec {
+  /** Hydration directive for a framework example; `undefined` for `.astro`. */
+  client?: IslandClientMode;
+  /** Absolute path to the example source file. */
+  file: string;
+  /** Framework, or `astro` for a server-rendered (static) example. */
+  framework: ExampleFramework;
+  /** Shiki language for the source pane — the file extension. */
+  lang: string;
+  /** MDX-facing key: the path under `examples/`, sans extension, `/`-joined. */
+  path: string;
+  /** Raw source text shown in the code tab. */
+  source: string;
+}
+
+export interface ExampleDiscovery {
+  examples: ExampleSpec[];
+  warnings: string[];
+}
+
+/** Example extensions mapped to the framework that renders them. */
+const FRAMEWORK_BY_EXT: Record<string, ExampleFramework> = {
+  astro: "astro",
+  jsx: "react",
+  svelte: "svelte",
+  tsx: "react",
+  vue: "vue",
+};
+
+// Captures the extension so we can strip it from the path key and pick the
+// framework. Kept in sync with the glob below.
+const EXAMPLE_FILE = /\.(?<ext>astro|jsx|svelte|tsx|vue)$/u;
+
+/**
+ * Discover preview examples under `<root>/<subdir>` (the `examples` config,
+ * default `examples`). Every `.astro`/`.tsx`/`.jsx`/`.vue`/`.svelte` file
+ * becomes addressable by `<Component path="...">`, where the path is the file's
+ * location under that directory without its extension (e.g. `forms/login.tsx` →
+ * `forms/login`). Discovery is path-based (a glob), so no example code is
+ * executed. Framework examples carry a hydration mode (default `client:visible`,
+ * overridable via `export const client`); `.astro` examples render statically
+ * with no client directive.
+ */
+export const discoverExamples = async (
+  root: string,
+  subdir = "examples"
+): Promise<ExampleDiscovery> => {
+  const dir = join(root, subdir);
+  const matches = await glob(["**/*.{astro,jsx,svelte,tsx,vue}"], {
+    absolute: true,
+    cwd: dir,
+    onlyFiles: true,
+  });
+  const files = matches.toSorted();
+  const sources = await Promise.all(
+    files.map((file) => readFile(file, "utf-8"))
+  );
+
+  const examples: ExampleSpec[] = [];
+  const warnings: string[] = [];
+  const seen = new Map<string, string>();
+
+  for (const [index, file] of files.entries()) {
+    const ext = file.match(EXAMPLE_FILE)?.groups?.ext;
+    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    if (!(ext && framework)) {
+      continue;
+    }
+    // Strip the trailing `.<ext>` to form the `<Component path>` key.
+    const path = relative(dir, file).slice(0, -(ext.length + 1));
+    const existing = seen.get(path);
+    if (existing) {
+      warnings.push(
+        `Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`
+      );
+      continue;
+    }
+    seen.set(path, file);
+    const source = sources[index] ?? "";
+    examples.push({
+      client:
+        framework === "astro"
+          ? undefined
+          : readClientMode(source, file, warnings),
+      file,
+      framework,
+      lang: ext,
+      path,
+      source,
+    });
+  }
+
+  return { examples, warnings };
+};