Tooling & Workflow

Build the book

mdbook build docs/alembic

This writes the rendered site to docs/alembic/book/, which the server serves at /alembic.

Keep examples runnable

• Tag code fences with alembic and add a small runner in CI to execute them against the compiler.
• Store fixtures alongside chapters (e.g., src/examples/route-basic.alembic) so updates stay local.
• Capture outputs and wire them back into the docs to prevent drift.

Versioning and compatibility

• Track language levels in the docs; prefer adding since = "L2" frontmatter fields.
• For breaking changes, add a short migration section and point to the previous level’s examples.
• Use site-url = "/alembic/" in book.toml to keep links stable when the book moves.