Project Overview

This project is a personal recipe collection managed as a documentation site using Zensical. Recipes are primarily written in a custom .cook format and then converted to Markdown (.md) files, which are then served by Zensical. The site is deployed to GitHub Pages. The project uses various tools for linting, spellchecking, and link checking to maintain quality.

Main Technologies

Zensical: Static site generator for documentation.
Zensical Material Theme: Provides the visual theme for the documentation site.
Taskfile: A task runner for automating development and deployment workflows.
Docker: Used to containerize various development tools and the server.
Cooklang: A plain text format for writing recipes, indicated by .cook files and the cook server command.
Python: Used for Zensical and its plugins.
Git: Version control system.
GitHub Actions: For continuous integration and deployment to GitHub Pages.
Pre-commit hooks: For enforcing code quality and formatting before commits.

Building and Running

Install Zensical: task docs:deps (uses uv and pip)
Update Zensical: task docs:update
Start local development server: task serve (access at http://127.0.0.1:8000)
Start Cooklang server: task server
Deploy to GitHub Pages: The GitHub Actions workflow ci.yaml automatically deploys the docs on pushes to main branch (paths docs/**, mkdocs.**). Manually, this would involve zensical gh-deploy --force after installing dependencies.

Development Conventions

Pre-commit hooks:
- trailing-whitespace: Removes trailing whitespace.
- end-of-file-fixer: Ensures files end with a newline.
- mixed-line-ending: Standardizes line endings.
- markdownlint: Lints Markdown files for style and consistency.
- markdown-link-check: Checks for broken links in Markdown files.
Linting:
- task lint: Runs markdownlint and yamllint.
- task markdownlint: Runs markdownlint-cli.
- task yamllint: Runs yamllint.
Spellchecking: task spellcheck (uses spellchecker-cli with dictionary.txt).
Link Checking: task linkcheck (uses markdown-link-check).
Recipe Management: Recipes are stored in cook/ as .cook files and must be organized by category in subdirectories (e.g., cook/breakfast/, cook/desserts/). There are scripts to manage these, such as scripts/commit.sh and scripts/move.sh.
Markdown Formatting: Specific formatting for images (add-lazy-loading) and temperatures (deg) is applied using sed.
Front Matter: Markdown files use front matter for metadata like comments and tags.
Dependencies: Python dependencies for Zensical are managed via pip install in the CI workflow. spellchecker-cli is installed globally via npm install.
Git Commits: If a commit addresses a GitHub issue, include the issue reference in the commit message using the Fixes #123 syntax to automatically close the issue.
Zensical Navigation: Any removal of entries from zensical.toml must be confirmed by the user.
Recipe Markdown Pages: Recipe markdown pages in docs/ should use emoji from includes/emoji.yaml.
Recipe Markdown Format: Recipe markdown pages should follow a consistent format, including front matter for metadata (e.g., comments, tags), a main title with an emoji, an image with loading=lazy, a table for serving and time information, and sections for ingredients, cookware, and instructions. Each ingredient in the ingredients section should be prefixed with an emoji shortcode from includes/emoji.yaml. Instructions should be numbered steps, with !!! tip used for additional information.

Helper Tasks

Search Emojis: task emoji-search (filters includes/emoji.yaml).
List Ingredients: task list-ingredients (lists all used ingredients to help with consistency).
Validate Config: task validate (checks zensical.toml syntax).
Spellcheck File: task spellcheck-file FILE=path/to/file.

GitHub CLI Operations

List Issues: gh issue list (lists open issues in the repository).
Filter Issues by Label: gh issue list --label required (filters issues to show only those requiring action).

Recipe Import Process

Create the .cook file: Follow the specification in the Cooklang Specification section.
- Recipe Name: Use only the name of the recipe and use your best guess (e.g. My Best Friends's Mom's Paprikash -> Paprikash). If an existing recipe already exists with the same name, add the name of the recipe author to the new recipe name (e.g. Paprikash -> Jojo's Paprikash).
- Unit Abbreviations: When adding units to the cook recipe file, use the first upper case for tablespoon (e.g. Tbsp) and lowercase for teaspoon (e.g. tsp).
- Ignored Items: Before tagging an item as an ingredient (with @), check cook/config/ignored_ingredients.yaml. If the item is listed there, do not tag it as an ingredient.
Add the Image: Download an image from the source, name it the same as the cook file (e.g., Recipe Name.jpg), and place it in the same directory as the .cook file.
Run the Move Task: Execute FILES=<path/to/cookfile> task move. This converts the .cook file to Markdown, runs spellcheck and link check, and generates the zensical.toml mapping entry (copying it to clipboard if possible).
Update zensical.toml: Paste the mapping entry generated by the previous step into the correct section of zensical.toml.
Add Ingredient Emojis: Update the generated Markdown file by adding emoji shortcodes to each item in the ingredients section (referencing includes/emoji.yaml). If an ingredient is missing from includes/emoji.yaml, use your best judgement to pick one and update includes/emoji.yaml with the new mapping. Ensure that the selected emoji is compatible with mkdocs-material.
Add Tags: Generate relevant tags for the recipe and add them to the front matter of the generated Markdown file.
Volumetric to Weight Conversions: Convert volumetric measurements to grams in the Markdown file using the following rules:
- Formatting: Place the weight in parentheses after the volume, e.g., 2 cups (240 g) all-purpose flour.
- Reference: Use docs/reference/measuring.md for weight conversions.
- Missing Conversions: If a conversion is missing from the reference file, look it up on the King Arthur Baking Ingredient Weight Chart.
- Update Reference: If a new conversion is found externally, add it to docs/reference/measuring.md for future use.
- Exceptions: Ignore gram conversions for small measurements (e.g., teaspoons, tablespoons) of spices, herbs, and seasonings.

Cooklang Specification

Recipes in this project are written using the Cooklang specification. Here is a quick reference for creating .cook files:

Metadata: Defined at the top of the file using >> key: value. Common keys include source, serves, total time, time required, image, and tags.
```
>> source: https://example.com/recipe
>> serves: 4
>> total time: 30 minutes
```
Ingredients: Use @ followed by the ingredient name. If there is a quantity, use {}.
- Simple: @salt{}
- With quantity: @water{1%cup}
- With quantity (no unit): @eggs{2}
- Multi-word ingredient: @ground beef{1%lb}
Cookware: Use # followed by the cookware name.
- Simple: #pan{}
- Multi-word: #frying pan{}
Timer: Use ~ followed by the duration in {}.
- Example: ~{25%minutes}
Comments: Use [- and -] for block comments or -- for line comments.
- Example: [- This is a comment -]
Steps: Write instructions as natural text. Ingredients, cookware, and timers are embedded directly within the sentences.

8.1 KiB Raw Blame History