mirror of
https://github.com/nicholaswilde/recipes.git
synced 2026-02-04 18:35:36 +00:00
97 lines
7.6 KiB
Markdown
97 lines
7.6 KiB
Markdown
# 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`.
|
|
* **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
|
|
|
|
1. **Create the `.cook` file:** Follow the specification in the [Cooklang Specification](#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`).
|
|
* **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.
|
|
2. **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.
|
|
3. **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).
|
|
4. **Update `zensical.toml`:** Paste the mapping entry generated by the previous step into the correct section of `zensical.toml`.
|
|
5. **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.
|
|
6. **Add Tags:** Generate relevant tags for the recipe and add them to the front matter of the generated Markdown file.
|
|
7. **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](https://www.kingarthurbaking.com/learn/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](https://cooklang.org/docs/spec/) 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`.
|
|
```cook
|
|
>> 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. |