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.