@tenphi/cookbook 0.15.0 → 0.17.0

package/README.md

@@ -1,5 +1,13 @@
 # @tenphi/cookbook
 
+Before changing a site's appearance, read the
+[customization rules](./docs/customization-rules.md)
+([online](https://cookbook.tenphi.me/customization-rules/)). The package ships
+the complete [Cookbook documentation](./docs/index.md) and local Tasty and Glaze
+references under `docs/upstream/`, including Tasty's
+[style rules for AI agents](./docs/upstream/tasty/docs/ai-agents.md).
+The guide includes a project instruction snippet and the lint setup.
+
 Install the complete integration with `npx astro add @tenphi/cookbook`:
 
 ```ts
@@ -17,6 +25,23 @@ import { defineDocsConfig } from "@tenphi/cookbook/config";
 export default defineDocsConfig({ site: { title: "My project" } });
 ```
 
+Set fonts, typography, and built-in element styles in the same file:
+
+```ts
+export default defineDocsConfig({
+  theme: {
+    fonts: { body: "Inter", heading: "Newsreader" },
+    presets: { h1: { fontSize: "3rem" } },
+    styles: { Sidebar: { LinkLabel: { whiteSpace: "normal" } } },
+  },
+});
+```
+
+For local fonts, place files in `public/fonts/` and use
+`fonts: { body: { family: "My Font", files: [{ src: "/fonts/my-font.woff2" }] } }`.
+See [Theme and components](./docs/theme-and-components.md) for all named
+sub-elements and the custom component flow.
+
 Without configuration, a root `README.md` becomes `/` and
 `docs/**/*.{md,mdx}` supplies the remaining pages. Cookbook includes Starlight,
 generates only static output, and derives its URL base from Astro. Adding other

package/dist/config.d.ts

@@ -1,3 +1,3 @@
 
-import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStylesConfig, DocsConfig, DocsSource, ThemeConfig, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs/config";
-export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStylesConfig, type DocsConfig, type DocsSource, type ThemeConfig, defineDocsConfig, mergeDocsConfig };
+import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStylesConfig, DocsConfig, DocsSource, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs/config";
+export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStylesConfig, type DocsConfig, type DocsSource, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, defineDocsConfig, mergeDocsConfig };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 
 import starlight_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/starlight";
-import { BrandConfig, BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStyleConfig, ComponentStyles, ComponentStylesConfig, ComponentsConfig, ContentConfig, CookbookComponentName, CookbookComponentStyles, CookbookComponentSubElementName, DocsAsset, DocsConfig, DocsDiagnostic, DocsEntry, DocsFrontmatter, DocsGraph, DocsRoute, DocsSource, EditLinkConfig, HeadConfig, LocaleConfig, MarkdownConfig, NavigationConfig, NavigationItem, NavigationPlacement, NavigationTab, SearchConfig, SiteConfig, SiteIconConfig, ThemeConfig, ThemePaletteConfig, ThemeTokenValue, ThemeTokens, TypographyPreset, TypographyPresets, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
-export { type BrandConfig, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type CookbookComponentStyles, type CookbookComponentSubElementName, type CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, type DocsAsset, type DocsConfig, type DocsDiagnostic, type DocsEntry, type DocsFrontmatter, type DocsGraph, type DocsRoute, type DocsSource, type EditLinkConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type SearchConfig, type SiteConfig, type SiteIconConfig, type ThemeConfig, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, starlight_default as default, defineDocsConfig, mergeDocsConfig };
+import { BrandConfig, BrandDeclaration, BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStyleConfig, ComponentStyles, ComponentStylesConfig, ComponentsConfig, ContentConfig, CookbookComponentName, CookbookComponentStyles, CookbookComponentSubElementName, DocsAsset, DocsConfig, DocsDiagnostic, DocsEntry, DocsFrontmatter, DocsGraph, DocsRoute, DocsSource, EditLinkConfig, HeadConfig, LocaleConfig, MarkdownConfig, NavigationConfig, NavigationItem, NavigationPlacement, NavigationTab, SearchConfig, SiteConfig, SiteIconConfig, SiteVersion, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, ThemePaletteColor, ThemePaletteConfig, ThemeTokenValue, ThemeTokens, TypographyPreset, TypographyPresets, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
+export { type BrandConfig, type BrandDeclaration, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type CookbookComponentStyles, type CookbookComponentSubElementName, type CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, type DocsAsset, type DocsConfig, type DocsDiagnostic, type DocsEntry, type DocsFrontmatter, type DocsGraph, type DocsRoute, type DocsSource, type EditLinkConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type SearchConfig, type SiteConfig, type SiteIconConfig, type SiteVersion, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, type ThemePaletteColor, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, starlight_default as default, defineDocsConfig, mergeDocsConfig };

package/docs/ai-agents.md

@@ -0,0 +1,61 @@
+---
+title: AI agents
+description: Create a Cookbook site with a coding agent and make the published docs easy for agents to find and read.
+sidebar:
+  order: 3
+---
+
+Cookbook's project creator writes an `AGENTS.md` beside `docs.config.ts` and an
+`.agents/skills/upgrade-cookbook/SKILL.md` for dependency upgrades. They tell
+coding agents where content lives, where to find Cookbook's installed reference
+docs, how to upgrade Cookbook, and how to validate changes. Give an agent a
+concrete task, for example:
+
+> Create a Cookbook site for this repository in `docs-site/`. Use the existing
+> README and `docs/` pages as sources. Set the public site URL to
+> `https://docs.example.com`, add a getting started page if one is missing,
+> and run the doctor and production build.
+
+From the repository root, the agent can run:
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --site https://docs.example.com --yes
+cd docs-site
+npm run doctor
+npm run build
+```
+
+For a new project without existing documentation, omit `--source .`. To document
+an npm artifact, use `--package name@version` instead. The [getting started
+guide](./getting-started.md) covers all three paths. Agents should edit
+`docs.config.ts` for site metadata, navigation, and theme, and follow the
+[customization rules](./customization-rules.md) for styling.
+Replace the example URL with the site's actual public origin.
+
+## Make the published site readable
+
+Set `site.url` in `docs.config.ts` to the public HTTPS origin. If the site is
+hosted under a path, set Astro's `base` in `astro.config.ts`. A production build
+then gives every page a canonical URL and creates a sitemap. Cookbook also writes:
+
+- `llms.txt`, a short index of published pages with titles, descriptions, and
+  links to their readable HTML pages. Drafts are omitted. This is an optional
+  discovery aid for agents that choose to read it.
+- `robots.txt` at origin-root deployments with a pointer to the sitemap. A
+  `robots.txt` below a path such as `/project/` would not control the origin's
+  crawlers, so Cookbook does not generate one there.
+
+You can supply your own `public/llms.txt` or `public/robots.txt`; Cookbook keeps
+those files. For sites under a path, configure an origin-root `robots.txt` at
+the hosting layer if you need one.
+
+The HTML pages remain the primary source of information. Their text, headings,
+links, and page metadata are present in the static response, so an agent can
+read them without running client JavaScript. Write descriptive headings and
+link text, keep instructions current, and verify the production output with
+`npm run build` and `npm run preview`.
+
+Google's [AI Search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
+prioritizes ordinary crawlability and useful content. It says `llms.txt` is
+not used by Google Search; Cookbook provides it for other agents that use the
+[llms.txt proposal](https://llmstxt.org/).

package/docs/architecture.md

@@ -0,0 +1,91 @@
+---
+title: Architecture
+description: Understand the four packages and the static content pipeline behind Cookbook.
+sidebar:
+  order: 8
+---
+
+Cookbook keeps content concerns separate from rendering so another renderer
+can consume the same validated graph in the future.
+
+## Packages
+
+| Package                   | Responsibility                                                                                              |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `@tenphi/create-cookbook` | Inspect an npm artifact and scaffold a reproducible documentation project                                   |
+| `@tenphi/cookbook`        | Provide the memorable Astro integration, public config exports, and CLI                                     |
+| `@tenphi/docs`            | Discover sources, resolve packages, build the content graph, transform Markdown, and report diagnostics     |
+| `@tenphi/starlight`       | Adapt the graph to Astro/Starlight and provide the Tasty/Glaze theme, components, search, and static assets |
+
+The `@tenphi/cookbook` default export represents the complete product. Consumers do
+not compose Starlight or renderer internals themselves.
+
+## Build pipeline
+
+1. Validate and normalize the configuration.
+2. Collect local and locked package sources.
+3. Assign canonical routes to every document.
+4. Parse Markdown and collect headings, links, and assets.
+5. Rewrite internal references through the completed route graph.
+6. Reject unsafe paths and report strict diagnostics.
+7. Render static pages through Astro and Starlight.
+8. Copy content-hashed assets and build the local Pagefind index.
+
+Source documents are read-only throughout this process. The transformed body
+exists in the in-memory graph and the renderer's virtual module; a build never
+rewrites the repository Markdown.
+
+## Theme pipeline
+
+Theme resolution has three deliberately separate layers:
+
+1. Glaze resolves semantic palette inputs into light, dark, and high-contrast
+   colors.
+2. The Glaze values, design tokens, typography presets, states, and units are
+   registered directly with Tasty.
+3. Cookbook components use `tasty()` and the Tasty selector bridge styles DOM
+   owned by Astro, Starlight, Expressive Code, Pagefind, and rendered Markdown.
+
+The palette owns color relationships. Components never choose raw light/dark
+colors, and shape tokens never contain palette logic. This keeps a palette
+change, a density change, and a typography change independent. Astro runs
+Tasty in extract mode, so these runtime style calls become a shared static CSS
+asset during the build; no Tasty styling runtime ships to the browser.
+
+## Public graph API
+
+Renderer and tooling authors can work directly with `@tenphi/docs`:
+
+```ts
+import {
+  assertValidDocs,
+  createDocsGraph,
+  defineDocsConfig,
+} from "@tenphi/docs";
+
+const config = defineDocsConfig({
+  content: {
+    sources: [{ glob: "docs/**/*.md", base: "docs" }],
+  },
+});
+
+const graph = await createDocsGraph({ root: process.cwd(), config });
+assertValidDocs(graph);
+
+for (const route of graph.routes) {
+  console.log(route.route, route.sourcePath);
+}
+```
+
+The graph exposes normalized entries, routes, assets, and structured
+diagnostics without importing Starlight.
+
+## Reference app
+
+The monorepo's `apps/reference` project is both the deployed documentation site
+and an end-to-end fixture. Its integration discovers `docs.config.ts`, whose
+`root: "../.."` loads this `docs/` tree through the same route pipeline used by
+convention-mode sites. CI builds the same app before GitHub Pages publishes it.
+
+Return to [Cookbook](./index.md) or inspect the
+[repository](https://github.com/tenphi/cookbook).

package/docs/authoring.mdx

@@ -0,0 +1,86 @@
+---
+title: Authoring components
+description: Use accessible tabs, callouts, code groups, cards, steps, and isolated previews.
+sidebar:
+  order: 4
+---
+
+import { Callout, CodeGroup, Tab, Tabs } from "@tenphi/cookbook/components";
+
+Write ordinary Markdown for most pages. Use MDX when a page needs components,
+and import them from `@tenphi/cookbook/components`. Local MDX is supported by
+default; npm MDX requires an explicit `trust: "mdx"` source declaration.
+
+## Tabs
+
+Every panel requires a `label`. Arrow keys, Home, and End move between tabs;
+right-to-left layouts reverse the horizontal arrow direction. Without
+JavaScript, all panels remain readable under their headings.
+
+```mdx
+import { Tab, Tabs } from "@tenphi/cookbook/components";
+
+<Tabs label="Installation">
+  <Tab label="npm">Run `npm install your-package`.</Tab>
+  <Tab label="pnpm">Run `pnpm add your-package`.</Tab>
+</Tabs>
+```
+
+<Tabs label="Installation">
+  <Tab label="npm">Run `npm install your-package`.</Tab>
+  <Tab label="pnpm">Run `pnpm add your-package`.</Tab>
+</Tabs>
+
+## Callouts
+
+Use `kind="note"`, `"tip"`, `"caution"`, or `"danger"`; `title` overrides the
+visible label. The default kind is `note`. Status colors come from
+`theme.palette.info`, `success`, `warning`, and `danger` and adapt to all schemes
+and contrast modes.
+
+```mdx
+<Callout kind="tip" title="Keep content close to code">
+  Relative Markdown links continue to work after Cookbook assigns public routes.
+</Callout>
+```
+
+<Callout kind="tip" title="Keep content close to code">
+  Relative Markdown links continue to work after Cookbook assigns public routes.
+</Callout>
+
+## Code groups
+
+Pass labeled source strings to create an accessible tabbed code group. `language`
+is an optional visible label; these programmatic snippets render as escaped plain
+text. Ordinary fenced Markdown provides syntax highlighting.
+
+```mdx
+<CodeGroup
+  label="Install Cookbook"
+  items={[
+    { label: "npm", language: "shell", code: "npm install @tenphi/cookbook" },
+    { label: "pnpm", language: "shell", code: "pnpm add @tenphi/cookbook" },
+  ]}
+/>
+```
+
+<CodeGroup
+  label="Install Cookbook"
+  items={[
+    { label: "npm", language: "shell", code: "npm install @tenphi/cookbook" },
+    { label: "pnpm", language: "shell", code: "pnpm add @tenphi/cookbook" },
+  ]}
+/>
+
+## Other components
+
+| Component | Props and behavior                                                                                                |
+| --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `Card`    | Optional `title` and `href`; renders an article or link with slot content                                         |
+| `Steps`   | Ordered list container; supply `li` elements                                                                      |
+| `Logo`    | Optional `label`, `decorative`, and `class`; renders the Cookbook mark                                            |
+| `Preview` | Required `title`; optional `html`, `css`, and `javascript`; isolates examples in Shadow DOM or a sandboxed iframe |
+
+The public package exports each component's props type, such as `TabProps`,
+`CalloutProps`, and `CodeGroupProps`. Styles and all named sub-elements are
+listed in [Theme and components](./theme-and-components.md#style-customization).

package/docs/cli.md

@@ -0,0 +1,88 @@
+---
+title: CLI commands
+description: Validate documentation and reconcile package locks using the same configuration as Astro.
+sidebar:
+  order: 6
+---
+
+The integration and CLI discover `docs.config.ts`, `.mts`, `.js`, or `.mjs` in the
+project directory. Its `root` sets the content and lock directory. Use `--root`
+to select another project, or `--config` for an explicit config path relative to
+that project.
+
+## Validate with doctor
+
+```sh
+npx @tenphi/cookbook doctor
+npx @tenphi/cookbook doctor --root ./apps/docs
+npx @tenphi/cookbook doctor --config ./config/manual.ts --json
+```
+
+Doctor checks the content graph, configuration, semantic theme, links, assets,
+navigation, and redirects without starting Astro. It exits non-zero for errors.
+It does not compile MDX or replace a full Astro build.
+
+JSON results use a stable envelope, including configuration failures:
+
+```json
+{
+  "ok": true,
+  "pages": 8,
+  "assets": 3,
+  "diagnostics": []
+}
+```
+
+## Update package content
+
+```sh
+npx @tenphi/cookbook update
+npx @tenphi/cookbook update @scope/package --dry-run
+npx @tenphi/cookbook update --json
+```
+
+`update` reads package sources from configuration, creates the first lock,
+resolves changed tags or ranges, and removes entries that are no longer declared.
+A package name or exact requested specifier selects individual updates. An
+unselected source must already have a matching lock; otherwise run a full update.
+
+`--dry-run` resolves versions and shows the proposed changes without writing
+files. JSON output adds `dryRun`, `changes`, `removed`, and `lock` to the envelope.
+Review and commit the resulting lock diff before deploying. Builds require an
+exact requested-specifier match and never silently substitute a lock for another
+range or tag.
+
+Vendored sources remain vendored. New artifacts are stored in separate integrity
+folders before the lock is replaced, so a failed download leaves the old lock
+and its content available. Old vendor folders can be removed after reviewing
+which paths the new lock references.
+
+## Creator flags
+
+Start with local content, an existing repository, or an npm artifact:
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --yes
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+npm create @tenphi/cookbook@latest docs-site -- --package @scope/package --yes
+```
+
+| Flag                                                             | Purpose                                           |
+| ---------------------------------------------------------------- | ------------------------------------------------- |
+| `--source <directory>`                                           | Document an existing local repository             |
+| `--package <specifier>`                                          | Document a locked npm artifact                    |
+| `--yes`, `-y`                                                    | Use non-interactive defaults                      |
+| `--brand <color>`                                                | Set the Glaze brand seed                          |
+| `--site <url>`                                                   | Set the canonical site URL                        |
+| `--base <path>`                                                  | Set Astro's hosting subpath                       |
+| `--deploy github-pages\|netlify\|cloudflare-pages\|vercel\|none` | Add deployment setup or a host guide              |
+| `--package-manager npm\|pnpm\|yarn`                              | Select the project manager                        |
+| `--no-install`                                                   | Generate files without installing dependencies    |
+| `--vendor`                                                       | Vendor the npm artifact for offline builds        |
+| `--trust-package`                                                | Permit MDX execution from the locked npm artifact |
+| `--open`                                                         | Start and open the development server             |
+
+`--source` and `--package` are mutually exclusive. With neither, the creator
+writes a local starter. `--vendor` and `--trust-package` require `--package`.
+`--open` requires installation. A non-empty destination requires interactive
+confirmation before generated files can be overwritten.