@tenphi/cookbook 0.19.2 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/docs/configuration.md +3 -0
  2. package/docs/index.md +50 -67
  3. package/docs/publishing.md +13 -4
  4. package/package.json +3 -3
package/docs/configuration.md CHANGED
@@ -206,6 +206,9 @@ sidebar:
206
206
  group: Guides
207
207
  ```
208
208
 
209
+ `template: splash` uses a wider layout without sidebars by default. Set
210
+ `tableOfContents` in that page's frontmatter to show its contents list.
211
+
209
212
  Set `sidebar: false` to omit a page from generated sidebars. `label`, `order`,
210
213
  and `group` affect both the default sidebar and autogenerated navigation
211
214
  directories. Relative hero images are validated, content-hashed, and copied
package/docs/index.md CHANGED
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  title: Cookbook
3
- description: Build a customizable static documentation site from the Markdown your project already owns.
3
+ description: Build a static Astro documentation site from your repository or a published npm package, with a theme that fits your product.
4
4
  template: splash
5
+ seo:
6
+ title: Cookbook — docs that stay with the code and fit your product
5
7
  hero:
6
8
  title: Documentation that stays with the code.
7
- tagline: Turn repository Markdown or a locked npm package into an Astro docs site that fits your design system—without creating a second source of truth.
9
+ tagline: Build a static Astro docs site from repository Markdown or a locked npm package, then shape its colors, typography, and components to fit your product.
8
10
  image:
9
- 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>'
11
+ html: '<svg xmlns="http://www.w3.org/2000/svg" width="176" height="176" 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>'
10
12
  actions:
11
13
  - text: Get started
12
14
  link: /getting-started/
@@ -17,82 +19,63 @@ hero:
17
19
  sidebar:
18
20
  order: 1
19
21
  ---
20
- ## Keep documentation close to its source
22
+ ## Start with your repository
21
23
 
22
- Cookbook combines [Astro](https://astro.build) and
23
- an Astro renderer with repository-aware content,
24
- strict validation, local Pagefind search, and a theme powered by
25
- [Tasty](./upstream/tasty/README.md) and [Glaze](./upstream/glaze/README.md).
24
+ Run this from a project that already has a `README.md` or `docs/` directory:
26
25
 
27
- ### Repository-native
28
-
29
- Keep `README.md`, `docs/`, and local assets where they already live. Cookbook
30
- transforms sources in memory and never rewrites them.
31
-
32
- ### Package-first
33
-
34
- Build a reproducible site from the files actually published to npm—without
35
- cloning the package repository or running its lifecycle scripts.
36
-
37
- ### Strict and static
26
+ ```sh
27
+ npm create @tenphi/cookbook@latest docs-site -- --source . --yes
28
+ cd docs-site
29
+ npm run dev
30
+ ```
38
31
 
39
- Broken links, missing assets, duplicate routes, invalid navigation, and unsafe
40
- paths fail with source locations. The result is prerendered HTML and CSS ready
41
- for GitHub Pages or any static host.
32
+ Cookbook reads those files where they live. You can also
33
+ [start a new site](./getting-started.md#create-your-first-site),
34
+ [document the exact files published to npm](./getting-started.md#document-a-published-npm-package),
35
+ or [add Cookbook to an Astro project](./getting-started.md#add-to-an-existing-astro-project).
42
36
 
43
- ### Styling that fits your product
37
+ ## This site is the example
44
38
 
45
- [Glaze](./upstream/glaze/README.md) turns a brand and semantic palette into light, dark, and high-contrast
46
- colors with contrast targets. [Tasty](./upstream/tasty/README.md) applies those color roles alongside shared
47
- tokens and typography presets, so the docs can follow your design system.
48
- State maps keep hover, focus, and responsive values beside the styles they
49
- change. Partial `theme.styles` overrides merge before CSS extraction, letting
50
- you adjust supported components without selector chains or `!important`.
51
- The browser receives static CSS, with no Tasty or Glaze styling runtime.
52
- See the [theme reference](./theme-and-components.md) for the palette, presets,
53
- states, and named component styles.
39
+ The page you're reading comes from this repository's
40
+ [docs/index.md](https://github.com/tenphi/cookbook/blob/main/docs/index.md).
41
+ A small [Astro app](https://github.com/tenphi/cookbook/tree/main/apps/reference)
42
+ builds directly from the root `docs/` directory. Its navigation, search, code
43
+ controls, edit links, and Git timestamps are available to every Cookbook site.
54
44
 
55
- ## Choose a path
45
+ ## Content and design on your terms
56
46
 
57
- | I want to… | Start here | Then read |
58
- | ------------------------------------ | --------------------------------------- | --------------------------------------------------------------------- |
59
- | Start a site | [Getting started](./getting-started.md) | [Validate and deploy](./deployment.md) |
60
- | Choose a documentation tool | [Compare tools](./comparison.md) | [Getting started](./getting-started.md) |
61
- | Have an agent set it up | [AI agent workflow](./ai-agents.md) | [Customization rules](./customization-rules.md) |
62
- | Bring existing Markdown or an API | [Content sources](./content-sources.md) | [Working examples](./examples.md) |
63
- | Write pages and interactive examples | [Authoring](./authoring.mdx) | [Mobile contents and hero images](./authoring.mdx#on-page-navigation) |
64
- | Change brand, fonts, or logo | [Configuration recipes](./recipes.md) | [Theme reference](./theme-and-components.md) |
65
- | Add a Markdown extension | [Extend Cookbook](./plugins.md) | [Architecture](./architecture.md) |
66
- | Publish for people and agents | [Deployment](./deployment.md) | [Publishing metadata](./publishing.md) |
67
- | Update or fix an existing site | [Upgrade Cookbook](./migration.md) | [Troubleshooting](./troubleshooting.md) |
47
+ ### Keep the source where it belongs
68
48
 
69
- The **Guide** follows these tasks. **Reference** contains the complete
70
- [configuration](./configuration.md), [theme and component anatomy](./theme-and-components.md),
71
- [publishing controls](./publishing.md), and [CLI](./cli.md).
49
+ Use a repository's Markdown and local assets without copying them into an Astro
50
+ content tree. Cookbook can also read OpenAPI specs or the documentation inside an
51
+ npm artifact pinned to its exact version and integrity.
52
+ [Explore content sources](./content-sources.md).
72
53
 
73
- To start immediately:
54
+ ### Shape the site through configuration
74
55
 
75
- ```sh
76
- npm create @tenphi/cookbook@latest my-docs -- --yes
77
- cd my-docs
78
- npm run dev
79
- ```
56
+ Start with a brand color, then configure semantic palettes, fonts, typography,
57
+ and named component parts through [Tasty](./upstream/tasty/README.md) and
58
+ [Glaze](./upstream/glaze/README.md). Partial `theme.styles` overrides merge with
59
+ Cookbook's defaults before CSS extraction, so the browser receives static CSS.
60
+ [Explore the theme](./theme-and-components.md).
80
61
 
81
- Existing Astro projects can use `npx astro add @tenphi/cookbook`. See
82
- [Getting started](./getting-started.md) for repository and npm package sources.
62
+ ### Catch drift before publishing
83
63
 
84
- ## See the product, not a mock-up
64
+ Broken links, missing assets, duplicate routes, and invalid navigation fail with
65
+ source-aware errors. The result is prerendered HTML with local search, ready for
66
+ any static host. [See the validation workflow](./quality-checks.md).
85
67
 
86
- The pages you are reading live in this repository's root `docs/` directory.
87
- The small Astro app under `apps/reference` points the integration at the
88
- repository root, validates this content through the same graph-backed route
89
- pipeline used by consumer sites, builds the site, and publishes the result to
90
- GitHub Pages. There is no copied documentation tree.
68
+ ## Explore the guide
91
69
 
92
- This homepage also uses Cookbook's public `template: splash` and `hero`
93
- frontmatter. The heading permalinks, code-copy controls, edit links, and Git
94
- timestamps throughout the guide are the same capabilities available to every
95
- Cookbook site.
70
+ * [Getting started](./getting-started.md) covers repositories, npm packages, and
71
+ existing Astro projects.
72
+ * [Compare documentation tools](./comparison.md) explains Cookbook's content and
73
+ customization model alongside other options.
74
+ * [Working examples](./examples.md) show repository, monorepo, package, and
75
+ shared-theme configurations.
76
+ * [Authoring](./authoring.mdx) covers pages, components, and interactive examples.
77
+ * [Deployment](./deployment.md) covers validation and static hosting.
96
78
 
97
- See [Architecture](./architecture.md) for the package boundaries behind the
98
- site.
79
+ For agent-assisted setup, see the [AI agent workflow](./ai-agents.md). The
80
+ [configuration reference](./configuration.md), [publishing controls](./publishing.md),
81
+ and [CLI reference](./cli.md) cover the full set of options.
package/docs/publishing.md CHANGED
@@ -34,10 +34,19 @@ Without a template, Cookbook renders `Page | Site`, or just `Site` when both nam
34
34
  match. Templates require `{title}` and may use `{site}`. A page's `seo.title` is a
35
35
  complete document title, overriding the template; its visible heading is unchanged.
36
36
 
37
- Social images accept an absolute HTTP(S) URL or a root-relative public asset path.
38
- Provide meaningful `alt` text. Dimensions are optional but must be provided together.
39
- A page inherits the site image, can replace it, or can set `image: false`. Pages
40
- without an image use a `summary` card; an image enables `summary_large_image`.
37
+ When no site image is configured, Cookbook generates a 1200×630 PNG preview from
38
+ the site title, description, public hostname, and light theme colors. It emits
39
+ `og:image` and `twitter:image` for every page using that preview. Set `site.url`
40
+ (or Astro's `site`) so those tags contain an absolute URL for social crawlers.
41
+ The generated image lives at `/_cookbook/social-preview.png` under the deployment
42
+ base and does not modify `public/`.
43
+
44
+ Set `site.seo.image` to replace the generated preview with your own image, or
45
+ `false` to disable the site-wide image. Custom images accept an absolute HTTP(S)
46
+ URL or a root-relative public asset path. Provide meaningful `alt` text.
47
+ Dimensions are optional but must be provided together. A page inherits the site
48
+ image, can replace it, or can set `image: false` to use a plain `summary` card.
49
+ Pages with an image use `summary_large_image`.
41
50
 
42
51
  ```yaml
43
52
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tenphi/cookbook",
3
- "version": "0.19.2",
3
+ "version": "0.20.0",
4
4
  "description": "Repository-native static documentation for Astro",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -68,8 +68,8 @@
68
68
  "author": "Andrey Yamanov",
69
69
  "license": "MIT",
70
70
  "dependencies": {
71
- "@tenphi/docs": "0.19.2",
72
- "@tenphi/renderer": "0.19.2"
71
+ "@tenphi/docs": "0.20.0",
72
+ "@tenphi/renderer": "0.20.0"
73
73
  },
74
74
  "peerDependencies": {
75
75
  "astro": "^7.3.2"