Development¶

Emoji¶

Emoji are manually added to the front of ingredients and cookware to give the pages a little bit of flare. My hopes is that eventually this can be added to cook-docs as an automated task. For now, emoji.yaml can be used as reference.

--8<-- "includes/emoji.yaml"

Workflow¶

Below is my current workflow for documenting recipes.

graph TD
  S[Change to or create ./cook/category dir];
  A{Does the source<br/>website exist?};
  B[Import recipe using cook-import];
  C[Manually write cook<br/>file using micro editor];
  D{Is the domain<br />supported by<br/>cook-import?};
  E[Visually check cook file];
  F[Test output using cook recipe read command];
  G[Download image file and rename<br/>to same base name as cook file];
  H[Run cook-docs in ./cook/category<br/>to generate markdown file];
  I[Manually check markdown file];
  J[Move markdown file to ./docs/category];
  K[Copy image to ./docs/assets/images<br/>with same base file name as markdown file];
  L[Add markdown file to mkdocs.yaml];
  M[Locally run mkdocs to test site];
  N[Commit and push to repo];
  O{Is the file<br />correct?};
  P[Edit cook file];
  Q{Is the<br/>output correct?};
  R[Edit cook file];
  T{Does the page<br/>render correctly?};
  U[CI GitHub Action workflow<br/>deploys recipe site];
  V{Is the image<br/>format webp?};
  W[Convert the image<br/>to png using dwebp];
  X[Check spelling using<br/>typos];
  Y[Check markdown links and styling<br/>using lychee and rumdl];
  Z{What is the<br/>origin of the recipe?};
  AB{What type of device<br/>is being used?}
  AC[Use the GitHub mobile app<br/>to create an issue]
  AD[Use the GitHub website<br/>to create an issue]
  AE[Use GitHub Issues to<br/>determine which recipe to document]
  AF[Close GitHub issue, if applicable.]
  AG[Identify a recipe<br/>to be documented]
  AH[Document link in issue]
  AI[Take image of cookbook/index<br/>card and add it to issue]
  AG --> AB;
  AB --> |Mobile|AC;
  AB --> |Desktop|AD;
  AC --> Z;
  AD --> Z;
  Z --> |Website|AH;
  Z --> |Cookbook/<br/>Index Card|AI;
  AH --> AE;
  AI --> AE;
  AE --> S;
  A --> |Yes|B;
  A --> |No|C;
  B --> D;
  C --> F;
  D --> |Yes|E;
  D --> |No|C;
  E --> F;
  F --> Q;
  Q --> |Yes|G;
  H --> I;
  J --> K;
  K --> L;
  L --> M;
  I --> O;
  O --> |Yes|J;
  O --> |No|P;
  P --> H;
  Q --> |No|R;
  R --> F;
  S --> A;
  M --> T;
  T --> |Yes|X;
  X --> Y;
  Y --> N;
  T --> |No|P;
  N --> U;
  G --> V;
  V --> |Yes|W;
  V --> |No|H;
  W --> H;
  U --> AF;

  click B "#cook-import"
  click C "#cooklang-micro"
  click D "#cook-import"
  click F "#cooklang"
  click H "#cook-docs"
  click U "https://github.com/nicholaswilde/recipes/blob/main/.github/workflows/ci.yaml"
  click X "#typos"
  click Y "#lychee"

Automated Import Orchestrators¶

While the flowchart above illustrates the manual step-by-step pipeline, two unified Python orchestrator scripts are available to automate this entire workflow:

1. Recipe Import Workflow (import_recipe_workflow.py)¶

Used for recipes that can be scraped from a website URL or a GitHub issue containing a recipe URL:

uv run scripts/import_recipe_workflow.py <URL_or_issue_number> [category]

Under the hood, this script:

• Scrapes the recipe into a .cook file and downloads the image.
• Compiles and organizes the files using move.sh.
• Checks and maps missing emojis using check_recipe_emojis.py --fix.
• Converts units to weights using convert_recipe_units.py.
• Spellchecks the output and whitelists proper nouns.

2. Manual Recipe Import (import_manual_recipe.py)¶

Used when importing a recipe from a manually written .cook file or from unscrapable/image-based sources:

uv run scripts/import_manual_recipe.py <cook_file> [-i <image_path>] [-c <category>] [-n <issue_number>] [--commit]

Under the hood, this script:

• Copies/moves the manual .cook and optional image file to the target category.
• Runs move.sh to compile to markdown and process/convert images.
• Updates includes/emoji.yaml with missing emojis using similarity and keyword heuristics.
• Converts units to weights and inserts emojis.
• Runs spelling checks and whitelists proper nouns.
• Offers to stage and commit the changes using conventional commit messages.

Tools¶

Tools used to develop this repository.

cooklang¶

Used to generate shopping lists and manage recipes.

brew tap cooklang/tap
brew install cooklang/tap/cook

cook recipe read file.cook

cook-import¶

Used to download recipe from website as a cooklang file, if possible.

cook-import -l <url> -f

cooklang-micro¶

Used as a cooklang syntax highlighter for the micro editor

webp¶

Used to convert images from webp to png.

sudo apt install webp

dwebp file.webp -o file.png

avif¶

Used to convert images from avif to jpg.

brew install imagemagick

magick -quality 75 input.avif output.jpg

Task¶

Used to automate tasks.

brew install go-task/tap/go-task

# List tasks

task

cook-docs¶

Used to generate markdown files from cooklang files.

brew install nicholaswilde/tap/cook-docs

/recipes/cook/category$ cook-docs

Zensical¶

A modern static site generator wrapper that builds and serves this documentation site. It wraps MkDocs and configures the theme, search, and page structure.

task docs:deps

task serve
task build

uv run zensical serve
uv run zensical build

MkDocs¶

The underlying static site generator wrapped by Zensical to render the final HTML site.

uv¶

An extremely fast Python package installer and resolver. It manages Python dependencies and virtual environments for Zensical and Python helper scripts in this repository.

# Via curl
curl -LsSf https://astral.sh/uv/install.sh | sh

uv run <script_name>.py

oxipng¶

A multithreaded lossless PNG optimizer used during image processing and relocation.

# Via Homebrew
brew install oxipng

oxipng -o 4 --strip safe image.png

typos¶

Used to check documentation spelling.

# Via Homebrew
brew install typos-cli

task spellcheck
task spellcheck-file FILE=path/to/file

chmod +x ./scripts/spellcheck.sh
./scripts/spellcheck.sh

typos

echo "word to add" >> dictionary.txt

task sort

sort dictionary.txt -u -o dictionary.txt

Lychee¶

Used to check documentation links.

# Via Homebrew
brew install lychee

# Via Cargo
cargo install lychee

task linkcheck

lychee docs/

rumdl¶

Used to lint and format Markdown files.

# Via Cargo
cargo install rumdl

task markdownlint

rumdl check .

yamllint-rs¶

Used to lint YAML files.

# Via Cargo
cargo install yamllint-rs

task yamllint

yamllint-rs .

yq¶

Used to query and modify YAML files and Markdown front-matter.

# Via Homebrew
brew install yq

task add-comments
task add-tag

yq --front-matter="process" '.comments = "true"' docs/path/to/recipe.md

Google Antigravity CLI¶

Used for AI-assisted repository management, including recipe imports and maintenance. It automates several steps of the manual workflow, such as using LiteParse to extract structured recipe information from local documents and images, fetching recipes from URLs, creating .cook files, downloading images, and updating the site configuration.

# Import a recipe from a GitHub issue
antigravity -i "Import recipe from issue #1333"

# Perform codebase maintenance
antigravity -i "Run zensical serve and fix any issues"

LiteParse¶

Used by the Google Antigravity CLI and AI coding assistants to extract text and layout-aware recipe information from local files and images without cloud or LLM dependencies.

npm install --global @llamaindex/liteparse

lit parse document.pdf

Emojipedia¶

Website used to search for emoji shortcodes.

Emoji Combos¶

Website used to search for emoji contexts.

Test Custom Admonition¶