nicholaswilde_recipes/docs/reference/development.md

comments

comments
true

⚙️ 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.

!!! note All commands are run from the root of the repo unless otherwise specified.

🍚 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

:frame_with_picture: webp

Used to convert images from webp to png.

sudo apt install webp

dwebp file.webp -o file.png

:frame_with_picture: 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"

```shell title="Usage"
task serve
task build
```

=== "Manual"

```shell title="Usage"
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

:frame_with_picture: 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"

```shell title="Usage"
task spellcheck
task spellcheck-file FILE=path/to/file
```

=== "Script"

```shell title="Usage"
chmod +x ./scripts/spellcheck.sh
./scripts/spellcheck.sh
```

=== "Manual"

```shell title="Usage"
typos
```

echo "word to add" >> dictionary.txt

=== "Task"

```shell title="Sort dictionary"
task sort
```

=== "Manual"

```shell title="Sort dictionary"
sort dictionary.txt -u -o dictionary.txt
```

🔗 Lychee

Used to check documentation links.

# Via Homebrew
brew install lychee

# Via Cargo
cargo install lychee

=== "Task"

```shell title="Usage"
task linkcheck
```

=== "Manual"

```shell title="Usage"
lychee docs/
```

📃 rumdl

Used to lint and format Markdown files.

# Via Cargo
cargo install rumdl

=== "Task"

```shell title="Usage"
task markdownlint
```

=== "Manual"

```shell title="Usage"
rumdl check .
```

📃 yamllint-rs

Used to lint YAML files.

# Via Cargo
cargo install yamllint-rs

=== "Task"

```shell title="Usage"
task yamllint
```

=== "Manual"

```shell title="Usage"
yamllint-rs .
```

📃 yq

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

# Via Homebrew
brew install yq

=== "Task"

```shell title="Usage"
task add-comments
task add-tag
```

=== "Manual"

```shell title="Usage"
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

!!! pied-piper "Pied Piper"

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.