sake-docs

name	sake-docs
description	Use when writing or updating Sake documentation — VitePress site structure, existing pages, how to add new docs, documentation conventions.

Sake Documentation

Documentation site: sakeswift.org, built with VitePress, deployed via GitHub Pages.

Directory Structure

All docs in docs/. Key files:

docs/
  index.md                          — landing page
  about.md                          — what Sake is
  installation.md                   — brew, mint, mise
  getting-started.md                — sake init, first command
  how-it-works.md                   — sake vs SakeApp architecture
  editing-commands.md               — sake edit, manual editing
  commands-basic-rules.md           — visibility, static, type rules
  commands-dependencies.md          — deps, concurrent, CommandRunner
  commands-conditional-execution.md — skipIf
  commands-grouping.md              — @CommandGroup, SakeAppConfiguration
  commands-name-conversions.md      — case strategies
  commands-run-context.md           — Context properties, mapArguments/mapEnvironment
  passing-arguments.md              — basic argument passing
  sharing-data-between-commands.md  — context.storage
  interruption-handling.md          — InterruptionHandler, SIGINT cleanup
  advanced-argument-parsing.md      — ArgumentParser integration
  advanced-cli-tools-running.md     — swift-subprocess usage
  advanced-extensibility-of-sakeapp.md — adding SPM dependencies
  advanced-usage-example.md         — lint + ensureInstalled example
  configuration.md                  — CLI/ENV/.sake.yml cascade
  continuous-integration.md         — prebuilding, caching, setup-sake action
  shell-completion.md               — zsh/fig completion
  experimental-features.md          — SAKE_EXPERIMENTAL_FEATURES, swift-syntax prebuilts
  troubleshooting.md                — sake clean, rm -rf SakeApp/.build
  contribution-guide.md             — formatting, testing, conventional commits
  package.json                      — npm scripts and dependencies
  .vitepress/config.mts             — VitePress sidebar/nav config

VitePress Build

cd docs && npm ci && npm run docs:build

Deployed automatically on push to main (docs/** changes) via .github/workflows/docs-deploy.yml.

Documentation Conventions

• VitePress markdown with ::: tip, ::: warning, ::: info containers
• Code blocks with language + optional line highlighting: swift {4}
• outline: deep frontmatter for deep table of contents
• External tutorial links in tip blocks (Getting Started references swifttoolkit.dev articles)
• Docs reference each other via relative paths: [Configuration](/configuration)

Adding a New Doc

1. Create docs/new-page.md
2. Add to VitePress sidebar config in docs/.vitepress/config.mts
3. Cross-reference from related pages
4. Run cd docs && npm run docs:dev to preview locally

Tone

• Practical, example-driven
• Short explanations → code example → explanation of what the code does
• "In this example..." pattern for walkthroughs