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/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 mkdocs-material];
  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/>spellchecker-cli];
  Y[Check markdown links<br/>using markdown-link-check];
  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 "#spellchecker-cli"
  click Y "#markdown-link-check"

🛠️ 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

📖 Material for MkDocs

Used as theme for static site.

pip install mkdocs-material mkdocs-minify-plugin

📖 MkDocs

Used to generate static site.

(
  wget https://bootstrap.pypa.io/get-pip.py
  python get-pip.py
  pip install mkdocs
)

=== "Task"

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

=== "Manual"

```shell title="Usage"
mkdocs serve
```

🔤 Spellchecker CLI

Used to check documentation spelling.

npm install --global spellchecker-cli

=== "Task"

```shell title="Usage"
task spellcheck
```

=== "Script"

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

=== "Manual"

```shell title="Usage"
npx spellchecker -d dictionary.txt -f {"./cook/**/*.cook","./docs/**/*.md"}
```

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

🔗 markdown-link-check

Used to check documentation links.

npm install -g markdown-link-check

=== "Task"

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

=== "Script"

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

=== "Docker"

```shell title="Usage"
docker run --rm -v /:/tmp:ro -i -w /tmp ghcr.io/tcort/markdown-link-check:stable "/tmp/path/to/file" -c "/tmp{{ .ROOT_DIR }}/mlc_config.json"
```

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.