Hosting Recipes as a Static Website

cook build web renders your .cook files into plain HTML, CSS and JavaScript, with a search index built in. There is no server process and no database, so the result can live on any static host, on a tablet's local storage, or in an email attachment. It is the read-only sibling of cook server: the same look, minus the features that need a running process.

What you need#

• CookCLI 0.35 or newer
• A folder of .cook files (cook seed ~/recipes gives you a sample one)
• For publishing: a GitHub account, or any host that serves static files

1. Build the site#

cd ~/recipes
cook build web

Wrote index, directories, 14 recipe pages, 5 images, 24 static assets, 14 search entries

The site is in _site/. Open it without any server at all:

open _site/index.html        # macOS
xdg-open _site/index.html    # Linux

Links are relative by default, so browsing, folder navigation and search all work from file://. Re-run the command after editing recipes; it overwrites what changed and leaves the rest.

What you get, per _site/:

Two options are worth knowing before you publish:

cook build web --lang de-DE                     # UI labels in German (en-US, de-DE, nl-NL, fr-FR, es-ES, eu-ES, sv-SE)
cook build web --repo-url https://github.com/you/recipes   # "View source" link in the footer

Recipe text is rendered as written; only the chrome is translated.

2. Publish it#

GitHub Pages#

Free, and a natural fit if the recipes are already in a repository. The simplest setup builds on your machine and pushes the output to a gh-pages branch:

cook build web --base-url /recipes/     # use your repository name as the path
cd _site
git init
git add .
git commit -m "Publish recipes"
git push -f git@github.com:yourname/recipes.git HEAD:gh-pages

In the repository's settings, under Pages, choose the gh-pages branch. The site appears at https://yourname.github.io/recipes/.

--base-url is needed here because GitHub Pages serves project sites under a sub-path. Leave it out if the site will sit at the root of a domain. A site built with --base-url only works over HTTP: every asset link becomes absolute, so opening it from disk gives you unstyled pages with no search.

To rebuild on every push instead, add a workflow to the recipe repository:

# .github/workflows/publish.yml
name: Publish recipes

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install CookCLI
        run: |
          curl -L https://github.com/cooklang/cookcli/releases/latest/download/cook-x86_64-unknown-linux-gnu.tar.gz | tar xz
          sudo install -m 755 cook /usr/local/bin/cook

      - name: Build site
        run: cook build web --base-url /recipes/ --repo-url "https://github.com/${{ github.repository }}"

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

Netlify, Vercel, Cloudflare Pages#

Drag the _site/ folder onto Netlify Drop for a one-off. For continuous deploys, connect the repository and set the build command to cook build web (after a step that downloads the binary as in the workflow above) and the publish directory to _site. No --base-url is needed; these hosts serve from the root.

Your own server, S3, or anything else#

Any host that can serve files works:

aws s3 sync _site/ s3://my-recipes-bucket --delete
rsync -av --delete _site/ user@server:/var/www/recipes/

If the site ends up under a sub-path and links break, rebuild with --base-url /that/path/. Pass --sitemap https://your-domain.example to emit a sitemap.xml for search engines, and --compress for hosts that serve pre-compressed .gz files.

A tablet, a USB stick, an email#

Copy _site/ wherever you like and open index.html. Because nothing in it phones home, it keeps working with no network at all, which makes it a good format for handing a family cookbook to relatives.

3. Keep it fresh#

The site is a snapshot. Rebuild whenever the recipes change: by hand, with the GitHub workflow above, or from a cron job on a machine that has the recipes. If you also run cook server at home, both share the same templates, so the published site looks like what you cook from.

Static site or live server?#

The static site leaves out everything that needs state: shopping list and pantry pages, the editor and New recipe button, scaling controls, and Add to shopping list buttons. Readers can still download any recipe's .cook file and use those features in their own tools. For the live version at home, see the Raspberry Pi guide; many people run both.

Let the federation find it#

A published site is also a good source for the Cooklang Federation. Keep the .cook files in a public repository and register it, and your recipes become searchable at recipes.cooklang.org while the pretty version stays on your site.

Troubleshooting#

See also#

• cook build web reference: every option and the full output layout
• cook server: the live counterpart
• Publishing Your Recipes: federation registration
• Creating Cookbooks: the printable alternative