@tenphi/cookbook 0.15.0 → 0.17.0

package/docs/index.md

@@ -0,0 +1,74 @@
+---
+title: Cookbook
+description: Build a polished static documentation site from the Markdown your project already owns.
+template: splash
+hero:
+  title: Documentation that stays with the code.
+  tagline: Turn repository Markdown or a locked npm package into a polished, searchable Astro site—without creating a second source of truth.
+  image:
+    html: '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="240" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
+  actions:
+    - text: Get started
+      link: /getting-started/
+      variant: primary
+    - text: See how it compares
+      link: /starlight-comparison/
+      variant: secondary
+sidebar:
+  order: 1
+---
+## Keep documentation close to its source
+
+Cookbook combines [Astro](https://astro.build) and
+[Starlight](https://starlight.astro.build) with repository-aware content,
+strict validation, local Pagefind search, and a theme powered by
+[Tasty](./upstream/tasty/README.md) and [Glaze](./upstream/glaze/README.md).
+
+### Repository-native
+
+Keep `README.md`, `docs/`, and local assets where they already live. Cookbook
+transforms sources in memory and never rewrites them.
+
+### Package-first
+
+Build a reproducible site from the files actually published to npm—without
+cloning the package repository or running its lifecycle scripts.
+
+### Strict and static
+
+Broken links, missing assets, duplicate routes, invalid navigation, and unsafe
+paths fail with source locations. The result is prerendered HTML and CSS ready
+for GitHub Pages or any static host.
+
+## Choose a path
+
+Create a documentation project from a published npm package:
+
+```sh
+npm create @tenphi/cookbook@latest my-package-docs -- --package your-package
+```
+
+Or add the complete integration to an Astro project:
+
+```sh
+npx astro add @tenphi/cookbook
+```
+
+Continue with [Getting started](./getting-started.md), then learn how
+[content sources](./content-sources.md) become routes.
+
+## See the product, not a mock-up
+
+The pages you are reading live in this repository's root `docs/` directory.
+The small Astro app under `apps/reference` points the integration at the
+repository root, validates this content through the same graph-backed route
+pipeline used by consumer sites, builds the site, and publishes the result to
+GitHub Pages. There is no copied documentation tree.
+
+This homepage also uses Cookbook's public `template: splash` and `hero`
+frontmatter. The heading permalinks, code-copy controls, edit links, and Git
+timestamps throughout the guide are the same capabilities available to every
+Cookbook site.
+
+See [Architecture](./architecture.md) for the package boundaries behind the
+site.

package/docs/migration.md

@@ -0,0 +1,36 @@
+---
+title: Prerelease migration
+description: Upgrade to the shared configuration, source identity, and typed customization APIs.
+sidebar:
+  order: 9
+---
+
+This prerelease intentionally tightens several contracts.
+
+- Move generated inline documentation configuration to `docs.config.ts` and use
+  `cookbook()` in Astro. Existing explicit `cookbook({ config })` remains valid,
+  but CLI commands read the shared configuration file.
+- For nested Astro apps, put `root: "../.."` in `docs.config.ts`; paths resolve
+  relative to that file. Individual sources may now specify `root` and `id`.
+- Run `cookbook update` after changing a requested npm specifier. A lock for
+  another range or tag is no longer accepted by package name alone.
+- `rawHtml: "sanitize"` preserves safe HTML and removes executable markup and
+  presentational attributes. Use `"strip"` for the former removal behavior;
+  removal now emits a diagnostic. `"reject"` still fails validation.
+- Unrecognized page frontmatter is kept in graph entry `metadata`. Use
+  `content.frontmatter: "reject"` for the former strict behavior. Cookbook's
+  recognized fields retain their validation.
+- `slug` is now relative to the source mount, including when it starts with `/`.
+  Use a separate source mount for an unrelated public route.
+- Repeated files in separate source declarations create separate entries.
+  Give mounts stable IDs and use `source:<id>/<source-path>` for explicit links.
+  `entryBySource(path)` returns `undefined` for an ambiguous path; pass a source
+  ID as its second argument. Graph entry IDs include the source ID.
+- Unknown names in `theme.styles` are errors. Register user-authored component
+  styles in `theme.customStyles`. Built-in component names and sub-elements
+  provide strict editor checking; style objects still contain only overrides.
+- `Tabs` now expects `Tab` children with accessible labels. It provides keyboard
+  navigation and panels; use an ordinary custom component for a grouping layout.
+
+See [authoring](./authoring.mdx) for the new components and [working
+examples](./examples.md) for complete configuration patterns.

package/docs/starlight-comparison.md

@@ -0,0 +1,124 @@
+---
+title: Cookbook and Starlight
+description: Understand which Starlight authoring conventions Cookbook preserves and where its repository and theme model differs.
+sidebar:
+  order: 5
+---
+Cookbook uses [Astro Starlight](https://starlight.astro.build/) as its
+documentation shell. It keeps familiar page-authoring conventions while adding
+repository and npm content sources, stricter validation, and a Tasty/Glaze
+theme model.
+
+## Cookbook or Starlight?
+
+Start with the place where the documentation must live. Starlight is a strong
+choice when an Astro site owns its content. Cookbook is designed for projects
+where the repository Markdown—or the documentation actually published in an
+npm package—must remain the source of truth.
+
+| Concern                 | Starlight                                                                          | Cookbook                                                                                                                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Starting point          | Add Starlight to an Astro project and author its documentation content collection. | Add one integration to an Astro project, or generate a complete site directly from a published npm package.                                                                           |
+| Content ownership       | The documentation site conventionally owns its Markdown under `src/content/docs/`. | Reads `README.md`, repository `docs/` trees, files outside the Astro app, and selected files from npm artifacts without copying or rewriting them.                                    |
+| Reproducible releases   | Follows the dependencies and content committed with the site.                      | Can lock an npm package to its exact resolved version and integrity, then rebuild from the files users actually receive.                                                              |
+| Build guarantees        | Provides Starlight's content schema and Astro build pipeline.                      | Adds strict checks for duplicate routes, broken links, missing assets, unsafe paths, and invalid navigation with source-aware diagnostics.                                            |
+| Design system           | Supports CSS variables, custom CSS, and component overrides.                       | Exposes the full [Tasty styling DSL](./upstream/tasty/docs/dsl.md) through configuration, with Glaze-generated semantic colors and named style trees for Cookbook and shell surfaces. |
+| Familiar authoring      | Defines the Starlight page, navigation, i18n, and frontmatter conventions.         | Preserves those conventions—including splash pages, locales, edit links, and last-updated metadata—while resolving them against each original source.                                 |
+| Structural escape hatch | Replaces Starlight components when markup or behavior must change.                 | Supports Astro component overrides for structural changes; visual changes normally stay in typed `theme` configuration.                                                               |
+
+Choose Starlight when the documentation site is the natural home for the
+content and its CSS-oriented customization model fits the project. Choose
+Cookbook when documentation must stay beside the code, match a published
+package, fail strictly when references drift, or expose a reusable design
+system entirely through configuration.
+
+## Customize with Tasty's DSL
+
+Cookbook customization is not limited to replacing token values. Every entry
+under `theme.styles` is a partial Tasty style object that Cookbook merges into
+the component's base style tree. That gives configuration access to the same
+responsive values, state maps, calculations, semantic tokens, typography
+presets, and named sub-elements used by Cookbook itself:
+
+```ts
+export default defineDocsConfig({
+  theme: {
+    states: {
+      "@touch": "@media(pointer: coarse)",
+    },
+    styles: {
+      MarkdownCodeBlock: {
+        Pre: {
+          padding: {
+            "": "2x 4x",
+            "@mobile": "1.5x 3x",
+          },
+          radius: "$card-radius",
+        },
+        CopyButton: {
+          inlineSize: {
+            "": "2rem",
+            "@touch": "2.5rem",
+          },
+          scale: {
+            "": "1",
+            ":active": "0.94",
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+The user supplies only overrides; the merge happens inside Cookbook. See
+[Theme and components](./theme-and-components.md#style-customization) for the
+complete component and sub-element inventory, and the
+[Tasty documentation](./upstream/tasty/docs/README.md) for the DSL's properties and
+conditional syntax. Structural Astro overrides remain available when a change
+requires different markup or behavior rather than styling.
+
+## Configure the shared capabilities
+
+```ts
+export default defineDocsConfig({
+  editLink: {
+    baseUrl: "https://github.com/example/project/edit/main/",
+  },
+  lastUpdated: true,
+  locales: {
+    root: { label: "English", lang: "en" },
+    fr: { label: "Français", lang: "fr" },
+  },
+  defaultLocale: "root",
+});
+```
+
+The keys deliberately match Starlight so an existing Starlight author does not
+need to relearn page metadata or i18n. Cookbook resolves edit and Git metadata
+before handing each page to Starlight because its source may live in a root
+`docs/` directory, outside the Astro app, or inside a locked npm artifact.
+
+## Create a splash page
+
+```yaml
+---
+title: Example
+template: splash
+hero:
+  title: Build something clear.
+  tagline: A short explanation of the value your project provides.
+  actions:
+    - text: Get started
+      link: /getting-started/
+      variant: primary
+    - text: View API
+      link: /reference/
+      variant: secondary
+---
+```
+
+Use `template: doc` (the default) for conventional reference pages. See
+Starlight's [page guide](https://starlight.astro.build/guides/pages/) for the
+authoring model Cookbook builds on, then use [Theme and
+components](./theme-and-components.md) for Cookbook-specific styling.