Convert a directory of notes into a styled, navigable HTML site in one command.
alembic docs walks the source directory, converts every Markdown file it finds, and writes a matching .html file. It also builds an index page that links to every generated page, using the first # heading as the page title.
Think of it like… a photocopier that takes loose pages and binds them into a booklet with a table of contents.
The converter supports headings up to four levels, paragraphs, unordered and ordered lists, fenced code blocks with language classes, inline code, bold, italic, and links. It escapes HTML entities and wraps the output in a complete HTML document with a responsive, light/dark stylesheet. The implementation lives in packages/docs/src/markdown.ts and packages/docs/src/site.ts.
# basic usage alembic docs ./docs ./site # with a custom site title alembic docs ./docs ./site --site-title "Project Docs" # machine-readable output alembic docs ./docs ./site --json
The --site-title argument is optional and defaults to "Documentation". The --json flag prints {"pages": N, "indexPath": "..."} so CI steps can parse the result without scraping text. Subdirectories are preserved: docs/api/core.md becomes site/api/core.html.
Write a Markdown file with a heading, a list, and a fenced code block. Run alembic docs and verify the generated HTML keeps the structure and styling.