Common Workflows

"I added new Fortran modules"

Just re-run -- FORMAL picks up all modules in the configured source directories:

formal generate

"I want to exclude a directory from API docs"

Edit doc/formal.md and add to exclude_dir:

exclude_dir: ../src/third_party/
             ../src/experimental/     # <-- add here

"I want to add a hand-written page"

1. Create docs/my-section/my-page.md
2. Add to sidebar in docs/.vitepress/config.mts
3. Optionally add to nav bar

See Writing Pages for details.

"I want to change the landing page"

Edit docs/index.md. The hero section uses YAML frontmatter -- see VitePress home layout.

"I want to regenerate only when sources change"

Use file watching or a Makefile:

docs/api/_sidebar.json: $(wildcard src/**/*.F90) doc/formal.md
	formal generate --quiet

Or integrate with your build system.