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/catetory 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"

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¶