Alembic · Visual Course

What Alembic Docs & Doctor do

Two new CLI commands that turn Markdown into a site and check your local setup.

Read the plain version, or open the technical layer on any section.

The big idea

alembic docs reads a folder of Markdown files and writes a small, styled HTML site. You point it at a directory of notes, READMEs, or wiki pages; it produces an index.html plus one HTML page per source file.

alembic doctor checks the local environment: Node, pnpm, git, the Higgsfield CLI, the data directory, and the local LLM gateway. It reports OK / WARN / FAIL so you know whether the next command will work.

Think of it like… a publishing desk (docs) and a pre-flight checklist (doctor) for the Alembic engine.

Under the hood

Both commands are implemented in the apps/cli package and wired through the same argument parser as the rest of the CLI. docs delegates conversion to the new @alembic/docs package, which keeps the Markdown parser independent and testable. doctor probes external binaries with which and --version, and HTTP-probes the cliproxyapi gateway when not in offline mode.

In one picture

Markdown goes in, a site comes out; doctor verifies the runway before takeoff.

In the code

The docs command needs two positional arguments: a source directory and an output directory. The doctor command needs none.

# turn notes/ into a static site at site/
alembic docs notes site --site-title "My Docs"

# check the environment
alembic doctor

Implementation notes

generateSite() in @alembic/docs recursively collects .md and .markdown files, converts each with a small custom parser (headings, paragraphs, lists, code blocks, inline formatting, links), and wraps the body in a self-contained HTML document with light/dark CSS. runDoctor() in apps/cli returns a typed report of checks; the CLI renders it as text or JSON.

Try it

Create a folder with two Markdown files and run alembic docs my-notes my-site. Then open my-site/index.html in a browser.

Run alembic doctor --json and inspect the reported checks.

Ask yourself: Which of your existing Markdown folders would benefit from a quick static site? Which check in doctor is most likely to fail on a fresh machine?