@tenphi/cookbook 0.20.4 → 0.21.0

package/docs/configuration.md

@@ -24,6 +24,13 @@ Start with a complete [configuration recipe](./recipes.md) for common tasks.
 This page documents the available options; [working examples](./examples.md)
 covers repository layouts and shared presets.
 
+For a focused explanation, use [content sources](./content-sources.md),
+[theme basics](./theme-and-components.md),
+[fonts and typography](./fonts-and-typography.md),
+[component styles](./component-styles.md), or
+[publishing metadata](./publishing.md). The sections below are the complete
+configuration reference.
+
 ## Project resolution and presets
 
 `cookbook()` and CLI commands discover the same `docs.config.ts`. Set `root`
@@ -105,7 +112,7 @@ single-version site can continue using `site.version` for a simple label.
 with `src` (one image) or `light` and `dark` (appearance variants). Optional
 `alt`, `decorative`, `href`, `width`, and `height` control accessible text,
 destination, and intrinsic sizing. It applies to the header and mobile drawer.
-See the [shared logo guide](./theme-and-components.md#a-shared-site-logo).
+See the [shared logo guide](./custom-components.md#a-shared-site-logo).
 The logo and favicon are independent.
 
 ## Site icons
@@ -217,6 +224,10 @@ renderer frontmatter. Use `content.frontmatter: "reject"` to reject unrelated
 fields. Other supported fields include `aliases`, `template`, `hero`, `editUrl`,
 `lastUpdated`, `prev`, `next`, `head`, `draft`, and `slug`.
 
+Set `pagefind: false` to omit an individual published page from search while
+keeping its normal route and navigation. A draft is excluded from search
+regardless of `pagefind`.
+
 ### Draft pages
 
 Set `draft: true` to publish a page for review at its normal URL. Drafts remain
@@ -388,7 +399,7 @@ theme: {
       saturation: 0,
       contrast: { wcag: [7, 10] }
     },
-    textSoft: {
+    "text-soft": {
       base: "surface",
       tone: [25, 10],
       saturation: 0.05,
@@ -421,43 +432,47 @@ theme: {
   },
   styles: {
     ThemeSelect: {
-      Select: { border: "#border-strong" },
-      Picker: { shadow: "0 1rem 3rem #shadow" }
+      Trigger: { border: "#border-strong" },
+      Panel: { shadow: "0 1rem 3rem #shadow" }
     }
   },
   contrastLevel: "auto"
 }
 ```
 
-The default brand is `okhsl(266 68% 48%)`, a blue with 68% saturation; controls
-use an `8px` radius and cards use `16px`. Onest is the default body and heading family, while JetBrains Mono is
-used for code. `theme.fonts` loads Google families by name or local files from
-`public/`, and applies them to the body, heading, and code presets. See
-[Change font families](./theme-and-components.md#change-font-families) for both
-flows. The default layout is capped at `87.5rem` (1400px), matching the
-Tasty site, with a `58rem` reading column and a `17.5rem` sidebar. `brand.from`
-supplies the color seed. `palette` supplies semantic Glaze declarations that
-inherit its hue and saturation unless a role supplies its own `from`. `tone` and
-a saturation factor set the surface. Reading text uses absolute tones: body
-text starts at 0, and headings at 4. Glaze applies normal-mode tone boundaries
-and adapts the values for dark mode; `base` and `contrast` provide minimum
-contrast safeguards. `palette.heading` follows an explicit `palette.text`
-declaration unless customized separately. Glaze resolves light, dark, and both
-high-contrast modes independently. Literal color shorthand and structured
-brand hue/saturation/tone remain supported. A requested APCA floor below 45 requires the explicit
-`unsafeContrast: true` escape hatch. Learn more in
-[Theme and components](./theme-and-components.md).
+The default brand is `okhsl(266 68% 48%)`, a blue with 68% saturation.
+Controls use an `8px` radius and cards use `16px`. Onest is the default body
+and heading family; JetBrains Mono is used for code. `theme.fonts` loads Google
+families by name or local files from `public/`. See
+[Fonts and typography](./fonts-and-typography.md) for both flows.
+
+The default layout is capped at `87.5rem` (1400px), with a `58rem` reading
+column and a `17.5rem` sidebar. `brand.from` supplies the color seed.
+`theme.palette` supplies semantic Glaze declarations that inherit its hue and
+saturation unless a role has its own `from`. Reading text uses absolute tones:
+body text starts at 0 and headings at 4. Glaze applies normal-mode tone
+boundaries and adapts the values for dark mode; `base` and `contrast` supply
+minimum contrast safeguards. `palette.heading` follows an explicit
+`palette.text` declaration unless configured separately.
+
+Glaze resolves light, dark, and both high-contrast modes independently.
+Literal brand color shorthand and structured hue/saturation/tone declarations
+remain supported. An APCA floor below 45 requires `unsafeContrast: true`.
+See [Theme and components](./theme-and-components.md) for the color model and
+examples.
 
 `theme.styles` is keyed by Cookbook UI surface name. A plain Tasty style object
 contains only the properties to override; Cookbook deep-merges it into that
 surface's complete base object internally. Unknown built-in names and sub-elements are rejected. Register custom
 component names and their overrides in `theme.customStyles`. Structural Astro overrides under
 `components.overrides` remain available when styling alone is insufficient.
-`theme.states` registers additional Tasty state shorthands, and `contrastLevel`
-is forwarded to Glaze's palette resolution.
+`theme.states` registers additional Tasty state shorthands or replaces a
+built-in alias; see the [responsive state reference](./component-styles.md#responsive-states)
+for all nine defaults. `contrastLevel` is forwarded to Glaze's palette
+resolution.
 The built-in documentation navigation surfaces are available as `Sidebar`,
 `TableOfContents`, `MobileMenuToggle`, and `MobileNavigationTabs`; see
-[Theme and components](./theme-and-components.md#style-customization) for their
+[Component styles](./component-styles.md#style-customization) for their
 complete sub-element lists.
 
 ## Markdown
@@ -521,7 +536,11 @@ search: {
 ```
 
 Search is generated locally with Pagefind during a static build. Disable it
-for hosts or fixtures that do not need an index.
+for hosts or fixtures that do not need an index. Readers can open the search
+dialog with Ctrl+K (⌘+K on macOS), type a query, and close it with Escape.
+Search loads its index when opened, so a development server shows a notice
+instead of results. Build and preview the site to test actual results. See
+[Search and navigation](./site-navigation.md) for the reader experience.
 
 ## Components
 
@@ -537,6 +556,20 @@ components: {
 Component replacement is the advanced escape hatch. Prefer theme tokens and
 named styles for visual changes that do not need new structure.
 
+Cookbook uses these Astro component slots. A relative override path resolves
+from the project root; a package specifier resolves from the app's dependencies:
+
+| Area                    | Override names                                                                                                                                             |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Page shell              | `Head`, `PageFrame`, `Header`, `Footer`, `Sidebar`, `Hero`, `SiteTitle`                                                                                    |
+| Navigation and controls | `Search`, `LanguageSelect`, `ThemeSelect`, `SocialIcons`, `MobileMenuToggle`, `MobileMenuFooter`, `MobileTableOfContents`, `TableOfContents`, `Pagination` |
+| Content and metadata    | `MarkdownContent`, `DraftContentNotice`, `EditLink`, `LastUpdated`                                                                                         |
+
+An override owns its markup and interaction behavior. Page overrides can read
+the validated route and navigation data from `Astro.locals.cookbookRoute`;
+see [Extending Cookbook](./plugins.md#read-the-content-graph). Use
+[Custom components](./custom-components.md) for a complete site title example.
+
 Cookbook uses its built-in footer by default, including the “Generated with
 Cookbook” credit. Replace the complete footer with the `Footer` component path
 shown above, or remove it with:

package/docs/custom-components.md

@@ -0,0 +1,367 @@
+---
+title: Custom components
+description: Style your Astro and MDX components with Tasty and validate their tokens and parts.
+---
+
+Use this guide after [theme configuration](./theme-and-components.md) when you
+need markup beyond Cookbook's built-in surfaces. For ordinary visual changes,
+consult the [component styles](./component-styles.md) reference first.
+
+## Authoring custom components
+
+Import styling tools from `@tenphi/cookbook/styling`. They use the same Tasty
+runtime as Cookbook, with its semantic colors, typography presets, units, and
+responsive states. The renderer package also exposes them from
+`@tenphi/renderer/styling`.
+
+| Export                   | Purpose                                                                            |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| `defineComponent`        | Create a named Tasty component with its `theme.customStyles[name]` overrides.      |
+| `tasty`                  | Use Tasty directly without binding a component to `theme.customStyles`.            |
+| `useGlobalStyles`        | Collect a global Tasty style tree while rendering a page.                          |
+| `resolveComponentStyles` | Merge `theme.customStyles[name]` into a complete base style tree for global rules. |
+| `mergeStyles`            | Compose your own base styles with Tasty's deep-merge semantics.                    |
+| `Styles`                 | TypeScript type for a Tasty style object.                                          |
+
+Cookbook supplies the React renderer and extracts these styles into its static
+CSS. No additional Tasty dependency, Astro integration, or `client:*` directive
+is needed for static components. Set shared tokens, presets, and states in
+`docs.config.ts` before rendering. Import the styling entry point in component
+modules; configuration files should import `defineDocsConfig()` from
+`@tenphi/cookbook/config`.
+
+### A small named component
+
+For a component used by your pages, give its root a name and define its parts
+inside the same style object:
+
+```ts
+// src/components/StatusBadge.ts
+import { defineComponent } from "@tenphi/cookbook/styling";
+
+export const StatusBadge = defineComponent("StatusBadge", {
+  as: "span",
+  styles: {
+    display: "inline-flex",
+    padding: "0.5x 1x",
+    radius: "$radius",
+    fill: "#surface-2",
+    color: "#text",
+    preset: "small",
+    Label: { $: "> strong", preset: "strong" },
+  },
+});
+```
+
+Use `<StatusBadge><strong>Stable</strong></StatusBadge>` in a local MDX page.
+A site can change just one part in `docs.config.ts`:
+
+```ts
+theme: {
+  customStyles: {
+    StatusBadge: { Label: { color: "#accent-text" } },
+  },
+}
+```
+
+`theme.customStyles` supplies a partial style object. `defineComponent()`
+merges it with the base styles while rendering on the server. Document the
+root name and every named part when sharing a custom component.
+
+### A shared site logo
+
+Set `site.logo` once to use your artwork in the header and mobile drawer:
+
+```ts
+site: {
+  title: "Acme",
+  logo: "./assets/acme.svg"
+}
+```
+
+Paths are local files relative to the resolved project root, just like
+`site.favicon`. Cookbook reads the intrinsic dimensions and copies the image to
+a content-hashed URL under the deployment base. SVG, PNG, JPEG, WebP, AVIF, and
+GIF are supported. Missing or invalid files fail during setup.
+
+```ts
+site: {
+  title: "Acme",
+  logo: {
+    light: "./assets/acme-light.svg",
+    dark: "./assets/acme-dark.svg",
+    alt: "Acme documentation",
+    href: "/",
+    decorative: true
+  },
+  favicon: "./assets/acme-icon.svg"
+}
+```
+
+Use `src` for one image, or both `light` and `dark`. Variants follow the
+appearance control and the system preference in Auto mode. They must share an
+aspect ratio to prevent layout shifts. Optional `width` and `height` describe
+intrinsic dimensions; Tasty controls display size. Customize
+`theme.styles.SiteLogo` and its complete anatomy: `Image`, `Light`, and `Dark`.
+Wide wordmarks retain their proportions within the header.
+
+The logo is decorative by default because the neighboring title labels the
+site. Set `decorative: false` and `alt` when the image itself carries meaningful
+text. The header logo link still has a name when the image is decorative.
+`href` defaults to the localized documentation home; it accepts a root-relative
+documentation route or HTTP(S) destination. The header title and drawer use the
+same destination. `site.logo: false` removes the mark from both locations.
+
+A logo does not change the favicon or touch icons. Configure `site.favicon`
+separately for square artwork; the default Cookbook icon set remains in place
+until changed. `Logo` remains available as the standalone Cookbook book mark.
+
+The built-in mark uses `theme.palette["logo-surface"]` and `theme.palette["logo-mark"]`.
+The default homepage hero artwork also uses `logo-surface` for its brand fill.
+Both default to Glaze `mode: "fixed"`: the brand background and light book keep
+their polarity in dark mode while respecting Glaze's tone boundaries and
+high-contrast settings. The mark-to-background contrast floor is 3:1 normally
+and 4.5:1 in high contrast. These colors are separate from interactive accents.
+For example, to customize the logo background while retaining brand hue:
+
+```ts
+theme: {
+  brand: { from: "#315efb" },
+  palette: {
+    "logo-surface": {
+      base: "logo-mark",
+      tone: 40,
+      saturation: 0.8,
+      mode: "fixed",
+      contrast: { wcag: [3, 4.5] },
+    },
+    "logo-mark": { tone: 100, saturation: 0, mode: "fixed" },
+  },
+}
+```
+
+Custom image assets keep their authored colors; use `light`/`dark` files when
+you want distinct artwork. Header and drawer home links center logos with the
+site title regardless of their aspect ratio. Use `theme.styles.SiteLogo` for
+image size and `theme.styles.Header.SiteTitle` / `Sidebar.HomeLink`
+for typography; they do not need baseline offsets for a different preset.
+
+### Advanced site title markup
+
+To put your own logo and title in one home link, create
+`docs/components/site-title.ts`:
+
+```ts
+import { defineComponent } from "@tenphi/cookbook/styling";
+
+export const SiteTitleRoot = defineComponent("ProjectSiteTitle", {
+  as: "a",
+  styles: {
+    display: "flex",
+    alignItems: "center",
+    gap: "1x",
+    inlineSize: "min 0",
+    color: "#text",
+    preset: { "": "h4 / strong", "@mobile": "h5 / strong" },
+    textDecoration: "none",
+    Logo: {
+      $: "> svg",
+      display: "block",
+      flexShrink: "0",
+      inlineSize: { "": "2rem", "@mobile": "1.75rem" },
+      blockSize: { "": "2rem", "@mobile": "1.75rem" },
+      color: "#accent-text",
+    },
+    Label: {
+      $: "> span",
+      inlineSize: "min 0",
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+      whiteSpace: "nowrap",
+    },
+  },
+});
+```
+
+Then create `docs/components/SiteTitle.astro`, using an SVG whose paths use
+`currentColor` to follow the semantic accent color:
+
+```astro
+---
+import ProjectLogo from "../../public/logo.svg";
+import { SiteTitleRoot } from "./site-title.js";
+
+const { siteTitle, siteTitleHref } = Astro.locals.cookbookRoute;
+---
+
+<SiteTitleRoot href={siteTitleHref}>
+  <ProjectLogo aria-hidden="true" focusable="false" />
+  <span translate="no">{siteTitle}</span>
+</SiteTitleRoot>
+```
+
+Register the replacement in `docs.config.ts` and disable the shared mark.
+A `SiteTitle` override affects the header; use `site.logo` above for ordinary
+branding shared with the drawer. For custom drawer markup, override `Sidebar`.
+The custom component supports root styles plus its complete list of named
+sub-elements: `Logo` and `Label`.
+
+```ts
+site: { logo: false },
+components: {
+  overrides: {
+    SiteTitle: "./docs/components/SiteTitle.astro"
+  }
+},
+theme: {
+  customStyles: {
+    ProjectSiteTitle: { Logo: { color: "#text" } }
+  }
+}
+```
+
+`defineComponent(name, options)` accepts Tasty factory options and a name for
+`theme.customStyles[name]`. It merges the configured partial style object before
+creating the component, retaining the other base properties and responsive
+states. Tasty options such as `elements`, `variants`, `styleProps`, `modProps`,
+and `tokenProps` keep their behavior and inferred types, including generated
+subcomponents such as `Component.Label`.
+Configured styles become the component's defaults; variants and styles passed
+at render time follow Tasty's usual precedence.
+
+Use `defineComponent` when authoring a component that should support
+`theme.customStyles`. Use `tasty` directly for ordinary Tasty creation or composition
+that does not need a configuration name. To define a named component around
+an existing React component that forwards `className`, pass it as `as` in the options. Use `className`
+when passing a class to a Tasty component from Astro.
+
+### Global style trees
+
+For markup you do not render through a Tasty component, call
+`useGlobalStyles()` during rendering. For example, this Astro component
+supports root styles and a `Label` sub-element through `theme.customStyles.ProjectNote`:
+
+```astro
+---
+import {
+  resolveComponentStyles,
+  useGlobalStyles,
+} from "@tenphi/cookbook/styling";
+
+useGlobalStyles(
+  ".project-note",
+  resolveComponentStyles("ProjectNote", {
+    padding: "2x",
+    fill: "#surface-2",
+    Label: { $: "> strong", color: "#text", preset: "strong" },
+  }),
+);
+---
+
+<aside class="project-note"><strong>Note</strong><slot /></aside>
+```
+
+`defineComponent` and `resolveComponentStyles` read the same `theme.customStyles`
+configuration; user configuration contains only the properties to change. Each custom style name must match a call to one of these helpers.
+
+## Linting custom styles
+
+`@tenphi/cookbook/eslint-plugin` re-exports the Tasty ESLint plugin together with
+Cookbook's `validationConfig`. The renderer offers the same exports from
+`@tenphi/renderer/eslint-plugin`. Keep style definitions in `.ts` or `.tsx`
+modules, as in the site title example above, to lint them with either ESLint or
+oxlint.
+
+Create `tasty.config.ts` at your project root:
+
+```ts
+export default {
+  extends: "@tenphi/cookbook",
+};
+```
+
+Renderer-only consumers can use `extends: "@tenphi/renderer"` instead.
+The preset registers both Cookbook styling import paths, its built-in tokens,
+units, responsive states, and typography presets. It also describes
+`defineComponent`, `resolveComponentStyles`, and `mergeStyles`, so their inline
+style objects, variants, and named sub-elements receive the same checks as
+`tasty()` calls. Partial overrides passed to `mergeStyles` may omit default state
+values and retain the plugin's safeguards against fixes that replace base styles.
+
+### ESLint
+
+Install ESLint and a TypeScript parser:
+
+```sh
+pnpm add -D eslint @typescript-eslint/parser
+```
+
+Add the plugin to `eslint.config.mjs`:
+
+```js
+import parser from "@typescript-eslint/parser";
+import tasty from "@tenphi/cookbook/eslint-plugin";
+
+export default [
+  {
+    ...tasty.configs.recommended,
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: { parser },
+  },
+];
+```
+
+Run `pnpm exec eslint docs/components --max-warnings 0`. Use
+`tasty.configs.strict` for additional checks, including custom property names and
+runtime style values. The named `recommended` and `strict` exports contain rule
+maps for configurations that register the plugin themselves.
+
+### oxlint
+
+Install oxlint:
+
+```sh
+pnpm add -D oxlint
+```
+
+Create `oxlint.config.mjs` using its JavaScript plugin support:
+
+```js
+import { recommended } from "@tenphi/cookbook/eslint-plugin";
+
+export default {
+  jsPlugins: [{ name: "tasty", specifier: "@tenphi/cookbook/eslint-plugin" }],
+  rules: recommended,
+};
+```
+
+Run `pnpm exec oxlint --config oxlint.config.mjs docs/components --deny-warnings`.
+The `tasty` alias keeps rule names such as `tasty/known-property` consistent with
+ESLint. Import `strict` instead of `recommended` to enable the stricter rule map.
+Both presets are tested with oxlint 1.83.0; JavaScript plugin support is experimental.
+
+### Custom theme names
+
+Add names introduced by your `docs.config.ts` theme to the validation config.
+For example, after defining `theme.tokens["$project-gap"]`, `theme.states["@project-wide"]`,
+and `theme.presets["project-title"]`:
+
+```ts
+import type { TastyValidationConfig } from "@tenphi/cookbook/eslint-plugin";
+
+export default {
+  extends: "@tenphi/cookbook",
+  tokens: ["$project-gap"],
+  states: ["@project-wide"],
+  presets: ["project-title"],
+} satisfies TastyValidationConfig;
+```
+
+`extends` merges and deduplicates these arrays with the inherited configuration,
+so list only your additions. It also inherits the styling helper signatures;
+entries you add to `styleFunctions` override inherited signatures by function name.
+The exported `validationConfig` object remains available for programmatic use.
+The entry point also exports the upstream `StyleFunctionConfig` and
+`ResolvedConfig` types for shared lint configurations. Additional imported
+helpers can be registered in `styleFunctions`; use `partial: true` for helpers
+that merge overrides into existing styles.

package/docs/customization-rules.md

@@ -14,7 +14,7 @@ registries or internal helpers.
 Inspect `docs.config.ts`, `tasty.config.ts`, and the components you are changing.
 Reuse the site's existing semantic colors, tokens, presets, responsive states,
 and named sub-elements. Do not invent configuration names. Consult the complete
-[component anatomy reference](./theme-and-components.md#style-customization)
+[component anatomy reference](./component-styles.md#style-customization)
 before overriding a built-in component.
 
 ## Choose the customization surface
@@ -76,8 +76,9 @@ belong in `docs.config.ts`.
   of spreading component anatomy across unrelated global rules.
 * Use semantic color tokens such as `#text`, `#surface`, and `#accent-text`
   in component styles. Configure Glaze color declarations through `theme.brand`
-  and the supported `theme.palette` roles so Glaze can resolve every scheme and
-  contrast mode. Do not hard-code component colors or invent palette keys.
+  and `theme.palette` so Glaze can resolve every scheme and contrast mode.
+  Declare any new semantic color role in `theme.palette` before using its
+  `#name` token. Do not hard-code component colors.
 * Apply semantic typography with `preset`, for example `"small"` or
   `"h2 / strong"`. Do not reconstruct presets from individual font tokens or
   wire modifier internals such as `$bold-font-weight` yourself.
@@ -88,7 +89,7 @@ belong in `docs.config.ts`.
 * When replacing a component, own its markup and behavior. Keep keyboard
   access, focus, semantics, responsive behavior, and appearance modes intact.
 
-The [custom component examples](./theme-and-components.md#authoring-custom-components)
+The [custom component examples](./custom-components.md#authoring-custom-components)
 show both a component root and a global style tree using these APIs.
 
 ## Read the underlying references
@@ -151,7 +152,7 @@ cookbook doctor, and build commands after changes.
 
 ## Check the result
 
-Adopt the [Cookbook Tasty lint configuration](./theme-and-components.md#linting-custom-styles)
+Adopt the [Cookbook Tasty lint configuration](./custom-components.md#linting-custom-styles)
 and extend its built-in vocabulary in `tasty.config.ts`:
 
 ```ts

package/docs/es/getting-started.md

@@ -0,0 +1,109 @@
+---
+title: Primeros pasos
+description: Crea un sitio de documentación, documenta un repositorio existente o usa un paquete npm publicado.
+sidebar:
+  order: 2
+---
+
+Cookbook requiere Node.js 22.19 o una versión posterior.
+
+## Crea tu primer sitio
+
+```sh
+npm create @tenphi/cookbook@latest my-docs -- --yes
+cd my-docs
+npm run dev
+```
+
+El creador genera un README, la configuración de Astro y `docs.config.ts`, e instala las dependencias. También escribe `AGENTS.md` con instrucciones para agentes de programación. Edita `README.md` para cambiar la página de inicio. Añade `docs/guide.md` para crear `/guide`. Las páginas nuevas o modificadas aparecen en el servidor de desarrollo sin reiniciarlo.
+
+## Documenta un repositorio existente
+
+Ejecuta estos comandos desde la raíz del repositorio:
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+El archivo `docs.config.ts` generado apunta a tu repositorio. El README de la raíz se convierte en la página de inicio y `docs/**/*.{md,mdx}` aporta las demás páginas. Cookbook lee esos archivos sin copiarlos ni modificarlos.
+
+Usa `--no-install` para generar los archivos sin instalar las dependencias. En modo no interactivo, el creador se niega a sobrescribir un directorio de destino que no esté vacío.
+
+## Documenta un paquete npm publicado
+
+```sh
+npm create @tenphi/cookbook@latest my-package-docs -- \
+  --package @scope/package@latest --yes
+cd my-package-docs
+npm run dev
+```
+
+El creador descubre la documentación dentro del paquete publicado y guarda su versión exacta y su valor de integridad en `cookbook.lock.json`. Incluye este archivo en Git. El paquete documentado no se instala ni se ejecutan sus scripts. Ejecuta `npm run update` cuando quieras resolver de nuevo la etiqueta o el rango de versiones solicitado.
+
+## Añádelo a un proyecto Astro existente
+
+Cookbook requiere `output: "static"` en Astro. Si tu proyecto usa `output: "server"`, crea un proyecto Astro independiente para la documentación estática.
+
+```sh
+npx astro add @tenphi/cookbook
+```
+
+La configuración de Astro necesita una sola integración:
+
+```ts
+import { defineConfig } from "astro/config";
+import cookbook from "@tenphi/cookbook";
+
+export default defineConfig({ integrations: [cookbook()] });
+```
+
+Cookbook incluye su renderizador Astro y detecta `docs.config.ts` automáticamente. Sin configuración de documentación, usa las convenciones de README y `docs/`.
+
+## Configura el sitio
+
+Empieza con las [recetas completas de marca, logotipo y fuentes](../recipes.md). Para cambios de estilo más detallados o componentes nuevos, consulta las [reglas de personalización](../customization-rules.md). Estas reglas y las referencias originales también se incluyen en el paquete instalado de Cookbook.
+
+Crea `docs.config.ts` junto a `astro.config.ts`:
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Example Project",
+    description: "Documentation for Example Project",
+    repository: "https://github.com/example/project",
+  },
+  theme: {
+    brand: { from: "#2f5bff" },
+    fonts: { body: "Inter", heading: "Newsreader" },
+  },
+});
+```
+
+Cambia `theme.fonts` para usar [Google Fonts por nombre o tus propios archivos de fuentes](../fonts-and-typography.md). Usa `theme.presets` para los detalles tipográficos, `theme.styles` para los elementos integrados y `defineComponent()` con `theme.customStyles` para añadir elementos. La [guía del tema](../theme-and-components.md) es un punto de partida; la [referencia de estilos de componentes](../component-styles.md) enumera todas las partes personalizables.
+
+La integración y la CLI cargan la misma configuración. Se admiten `docs.config.ts`, `.mts`, `.js` y `.mjs`, en ese orden. Un objeto `config` explícito en la integración tiene prioridad; `configFile: false` desactiva la detección. Usa `cookbook({ configFile: "./config/manual.ts" })` y `cookbook doctor --config ./config/manual.ts` para una ubicación no estándar.
+
+## Raíces de monorepositorios
+
+Una aplicación en `apps/docs/` puede usar el contenido del repositorio con:
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({ root: "../.." });
+```
+
+`root` es relativo al archivo de configuración de la documentación. Determina dónde se encuentran el contenido, los recursos locales y `cookbook.lock.json`. Ejecuta `npm run doctor` desde el directorio de la aplicación: resolverá la misma raíz que la integración. Cada fuente también puede declarar su propia raíz para sitios con varios paquetes.
+
+## Valida y publica
+
+```sh
+npm run validate
+npm run preview
+```
+
+El resto de las guías se encuentra actualmente en inglés: [ejemplos](../examples.md), [componentes para redactar](../authoring.mdx), [flujo para agentes de IA](../ai-agents.md), [despliegue](../deployment.md) y [actualización entre versiones](../migration.md). Puedes partir de las [recetas](../recipes.md) para adaptar una configuración completa. Si falla la validación, consulta [solución de problemas](../troubleshooting.md).