Skip to content
Web Image Formats Research Web Image Formats Research

Build documentation

Preview documentation locally

Section titled “Preview documentation locally”

Generate content from source files and start the development server:

Terminal window
just docs-dev

Visit http://localhost:4321. Changes to markdown files hot-reload automatically.

Build for production

Section titled “Build for production”
Terminal window
just docs-build

The built site goes to docs-site/dist/, ready for deployment.

Available commands

Section titled “Available commands”
CommandDescription
just docs-generateGenerate docs content from docs/ and Python docstrings
just docs-installInstall documentation site npm dependencies
just docs-devStart development server (port 4321)
just docs-buildGenerate and build for production
just docs-previewPreview production build (port 4321)

How it works

Section titled “How it works”

The just docs-generate command runs scripts/generate_docs.py, which:

  1. Copies markdown files from docs/ to docs-site/src/content/docs/
  2. Generates API reference from Python docstrings in src/ using lazydocs
  3. Creates the index page from README.md

The just docs-build command runs generation first, then builds the optimized static site with Astro Starlight.

Writing documentation

Section titled “Writing documentation”

Adding new pages

Section titled “Adding new pages”

  1. Create a markdown file in the appropriate docs/ subdirectory:

    • tutorials/ — step-by-step learning guides
    • how-to/ — task-oriented solutions
    • reference/ — technical specifications
    • explanation/ — background concepts and design decisions

  2. Add frontmatter:

    ---
    title: Your Page Title
    description: Brief description for SEO
    ---

  3. Run just docs-generate to copy to the Astro site.

Linking between pages

Section titled “Linking between pages”

Use relative paths without .md extension:

See [Getting Started](../../tutorials/getting-started)

Troubleshooting

Section titled “Troubleshooting”
  • Build fails with “lazydocs not found”: Run just install-dev
  • Broken links: Ensure markdown links omit the .md extension

See also

Section titled “See also”