Development¶

Tools used to develop and maintain this repository.

Workflow¶

Below is the general workflow for adding or updating a cheatsheet.

graph TD
  A["Identify a command<br/>or tool to document"];
  B["Create or edit a<br/>sheet in ./sheets/"];
  C[Validate the sheet format];
  D{Does it pass<br/>validation?};
  E[Fix formatting issues];
  F["Run conversion to<br/>generate Zensical pages"];
  G["Serve the site<br/>locally to verify"];
  H{Does the page<br/>render correctly?};
  I[Fix the sheet or docs];
  J[Commit and push to repo];
  K["CI workflow<br/>runs validation"];
  L["Convert workflow<br/>updates Zensical pages"];
  M["Publish workflow<br/>deploys to GitHub Pages"];

  A --> B;
  B --> C;
  C --> D;
  D --> |Yes| F;
  D --> |No| E;
  E --> C;
  F --> G;
  G --> H;
  H --> |Yes| J;
  H --> |No| I;
  I --> B;
  J --> K;
  K --> L;
  L --> M;

  click C "#task"
  click F "#task"
  click G "#zensical"
  click K "https://github.com/nicholaswilde/cheatsheets/actions/workflows/ci.yml"
  click L "https://github.com/nicholaswilde/cheatsheets/actions/workflows/convert.yml"
  click M "https://github.com/nicholaswilde/cheatsheets/actions/workflows/publish.yml"

Tools¶

Task¶

Used to automate common development tasks.

# Via Homebrew
brew install go-task/tap/go-task

# Via install script
curl -sSf https://taskfile.dev/install.sh | sh

task

task all

cheat¶

The primary CLI tool used to view and edit cheatsheets.

# Via Homebrew
brew install cheat

cheat git              # view the git cheatsheet
cheat -e git           # edit the git cheatsheet
cheat -t homelab       # list all sheets tagged "homelab"
cheat -s <keyword>     # search across all sheets

Validator (validate_cheatsheets.ts)¶

A custom Bun/TypeScript script that validates all cheatsheets for correct front matter, syntax tags, and docopt-compliant placeholders.

task validate

bun run scripts/validate_cheatsheets.ts

Converter (convert_cheatsheets.ts)¶

A custom Bun/TypeScript script that converts flat cheatsheets into Zensical markdown pages and automatically updates the site navigation in zensical.toml.

task site:convert

bun run scripts/convert_cheatsheets.ts

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 site:deps

task site:serve
task site:build

uv run zensical serve
uv run zensical build

uv¶

An extremely fast Python package installer and resolver. Manages Python dependencies and virtual environments for Zensical.

curl -LsSf https://astral.sh/uv/install.sh | sh

uv sync
uv run zensical build

Lychee¶

Used to check for broken links in the documentation and cheatsheets.

# Via Homebrew
brew install lychee

# Via Cargo
cargo install lychee

task linkcheck
task linkcheck-offline
task linkcheck-file FILE=sheets/git

lychee docs/ sheets/

Bun¶

A fast JavaScript runtime and package manager used to run the TypeScript validation and conversion scripts.

curl -fsSL https://bun.sh/install | bash

bun install
bun run scripts/validate_cheatsheets.ts
bun test

GitHub CLI (gh)¶

Used to interact with the remote GitHub repository (checking workflow runs, PR status, etc.). Commands are piped to cat to suppress interactive prompts.

# Via Homebrew
brew install gh

gh run list | cat
gh run view <run-id> --log-failed | cat

Google Antigravity CLI¶

Used for AI-assisted repository management, including adding cheatsheets, updating documentation, and maintaining the static site.

agy -i "Add a new cheatsheet for tool X"
agy -i "Fix the failing GitHub Actions workflow"