Deployment

Cookbook always produces a static Astro build. The output in dist/ can be served by GitHub Pages, Cloudflare Pages, Netlify, Vercel static hosting, or a plain file server.

npm run validate
npm run preview

New projects include validate: preflight, production build, then built-output checks. Existing projects can add this script using the upgrade guide. Run cookbook doctor for a focused preflight.

Give the deployment workflow read access to the repository plus permission to write Pages and request an identity token:

permissions:
  contents: read
  pages: write
  id-token: write

Build the site, upload dist/ with the official Pages artifact action, and deploy it with the official Pages deploy action. Use GitHub’s github-pages environment so the deployment URL and protection rules remain visible in the repository.

For an organization or user site, keep Astro’s base: "/". For a project site served at https://owner.github.io/repository/, set Astro’s base: "/repository/"; Cookbook derives the same base for its graph and assets.

Page URLs follow Astro’s trailingSlash and build.format. The default directory output writes guide/index.html, so links, canonicals, and llms.txt use /guide/. build.format: "file" writes guide.html and uses /guide, while the home remains the directory index at the base. trailingSlash set to "always" or "never" overrides both. Either way, readers follow the URL the host serves directly instead of a redirect.

Set Cookbook’s canonical site metadata to the HTTPS origin. The integration forwards it to Astro:

export default defineConfig({
  integrations: [
    cookbook({
      config: {
        site: { url: "https://docs.example.com" },
      },
    }),
  ],
});

Configure the custom domain in the repository’s Pages settings and point DNS at the GitHub Pages host. For a custom Actions workflow, GitHub stores the domain in the Pages settings; a CNAME file in the artifact is ignored and is not required.

This site is deployed by the repository’s Pages workflow to cookbook.tenphi.me with HTTPS enforcement enabled. The Cookbook repository deploys its own documentation only after a package release. The release workflow creates a version tag and then starts the Pages workflow from that tag, so the public reference matches the published code.

The creator supports --deploy netlify, --deploy cloudflare-pages, and --deploy vercel. It writes a DEPLOYMENT.md with host settings; Netlify also gets netlify.toml. You can also use the host’s ordinary static-site settings:

• build command: npm run build
• publish directory: dist
• Node.js: 22.19 or newer

If the host serves the site below a path rather than at an origin root, set Astro’s base; Cookbook derives it automatically.

Set site.url to the public HTTPS origin before building. This enables canonical page URLs and the sitemap. The build also emits llms.txt with links to published documentation pages. At an origin root, it emits robots.txt pointing to the sitemap. Host these files with the rest of dist/; custom files in public/ take precedence. For path-hosted sites, manage the origin’s robots.txt in the hosting configuration.

Check the deployed HTML, sitemap-index.xml, and llms.txt through their public URLs. See AI agents for the setup and reading workflow.

For title templates, social images, preview noindex, older-version policies, breadcrumbs, and copy-page downloads, see Publishing metadata.

New projects include npm run validate for preflight, build, and output checks. After the host finishes deploying, run:

npx @tenphi/cookbook check-build --url https://docs.example.com/manual/

Use your actual deployment URL, including any base path, and the same local dist/ output that was deployed. See CLI checks for the exact coverage, warnings, JSON output, and custom output directories.