---
comments: true

---

# :gear: Development

## :smiley: 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.

```yaml title="emoji.yaml"

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

## :runner: Workflow

Below is my current workflow for documenting recipes.

``` mermaid
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"
```

### :robot: 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:

```shell
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:

```shell
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.

---

## :hammer_and_wrench: Tools

Tools used to develop this repository.

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

### :rice: [`cooklang`][2]

Used to generate shopping lists and manage recipes.

```shell title="Installation"
brew tap cooklang/tap
brew install cooklang/tap/cook
```

```shell title="Usage"
cook recipe read file.cook
```

### :truck: [`cook-import`][11]

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

```shell title="Usage"
cook-import -l <url> -f
```

### :memo: [`cooklang-micro`][12]

Used as a `cooklang` syntax highlighter for the [`micro`][13] editor

### :frame_with_picture: [`webp`][1]

Used to convert images from `webp` to `png`.

```shell title="Installation"
sudo apt install webp
```

```shell title="Usage"
dwebp file.webp -o file.png
```

### :frame_with_picture: `avif`

Used to convert images from `avif` to `jpg`.

```shell title="Installation"
brew install imagemagick
```

```shell title="Usage"
magick -quality 75 input.avif output.jpg
```

### :robot: [Task][8]

Used to automate tasks.

```shell title="Installation"
brew install go-task/tap/go-task
```

```shell title="Usage"

# List tasks

task
```

### :page_with_curl: [`cook-docs`][3]

Used to generate markdown files from cooklang files.

```shell title="Installation"
brew install nicholaswilde/tap/cook-docs
```

```shell title="Usage"
/recipes/cook/category$ cook-docs
```

### :book: [Zensical][20]

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

```shell title="Installation"
task docs:deps
```

=== "Task"

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

=== "Manual"

    ```shell title="Usage"
    uv run zensical serve
    uv run zensical build
    ```

### :book: [MkDocs][7]

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

### :package: [uv][21]

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

```shell title="Installation"
# Via curl
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```shell title="Usage"
uv run <script_name>.py
```

### :frame_with_picture: [oxipng][22]

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

```shell title="Installation"
# Via Homebrew
brew install oxipng
```

```shell title="Usage"
oxipng -o 4 --strip safe image.png
```

### :abc: [typos][9]

Used to check documentation spelling.

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

```shell title="Add to dictionary"
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
    ```

### :link: [Lychee][10]

Used to check documentation links.

```shell title="Installation"
# Via Homebrew
brew install lychee

# Via Cargo
cargo install lychee
```

=== "Task"

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

=== "Manual"

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

### :page_with_curl: [rumdl][17]

Used to lint and format Markdown files.

```shell title="Installation"
# Via Cargo
cargo install rumdl
```

=== "Task"

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

=== "Manual"

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

### :page_with_curl: [yamllint-rs][18]

Used to lint YAML files.

```shell title="Installation"
# Via Cargo
cargo install yamllint-rs
```

=== "Task"

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

=== "Manual"

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

### :page_with_curl: [yq][19]

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

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

### :robot: [Google Antigravity CLI][15]

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.

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

### :scissors: [LiteParse][16]

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.

```shell title="Installation"
npm install --global @llamaindex/liteparse
```

```shell title="Usage"
lit parse document.pdf
```

### [Emojipedia][4]

Website used to search for emoji shortcodes.

### [Emoji Combos][5]

Website used to search for emoji contexts.

### [Test Custom Admonition][14]

!!! 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.

[1]: <https://developers.google.com/speed/webp/docs/precompiled>
[2]: <https://cooklang.org/>
[3]: <https://nicholaswilde.io/cook-docs/>
[4]: <https://emojipedia.org/>
[5]: <https://emojicombos.com/>
[7]: <https://www.mkdocs.org/>
[8]: <https://taskfile.dev/>
[9]: <https://github.com/crate-ci/typos>
[10]: <https://github.com/lycheeverse/lychee>
[11]: <https://github.com/cooklang/cook-import>
[12]: <https://github.com/nicholaswilde/cooklang-micro>
[13]: <https://micro-editor.github.io/>
[14]: <https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions>
[15]: <https://github.com/google-gemini/antigravity-cli>
[16]: <https://github.com/run-llama/liteparse>
[17]: <https://github.com/rvben/rumdl>
[18]: <https://github.com/AvnerCohen/yamllint-rs>
[19]: <https://github.com/mikefarah/yq>
[20]: <https://pypi.org/project/zensical/>
[21]: <https://github.com/astral-sh/uv>
[22]: <https://github.com/shpakovskiy/oxipng>