#docs
The manual is Markdown in docs/, and the platform renders it with its own builder — no third-party generator, no network access, no npm. aegis docs builds that site to HTML and, when you want it, serves it locally so a change to a page is one command away.
There are two actions: build writes the site, web writes it and serves it. Nothing here touches a running service; the panel only serves what build leaves in public/docs.
#aegis docs
aegis docs <action> options| Action | Purpose |
|---|---|
build | generate the static site |
web | build, then serve it until interrupted |
aegis docs without an action is a usage error and exits 2; aegis docs --help lists the actions.
#aegis docs build
Renders every Markdown document under docs/ into HTML, writes the shared stylesheet and script, and builds The CLI Book as its own site under <out>/cli-book/. It overwrites the files it writes and deletes nothing.
#Syntax
aegis docs build --out DIR#Options
| Option | Default | Effect |
|---|---|---|
--out DIR | public/docs | output directory, created when missing |
The default is relative to the project root, because the launcher changes there before running the command.
#What gets written
| Path | Content |
|---|---|
<out>/index.html | the landing page, rendered from docs/README.md |
<out>/<page>.html | one page per document, at its relative path |
<out>/cubes/<cube>.html | the per-cube pages |
<out>/cli-book/index.html | the landing page of The CLI Book |
<out>/cli-book/*.html | one page per book document |
<out>/assets/site.css | the stylesheet every page links |
<out>/assets/site.js | the script every page links |
<out>/cli-book/assets/ | the book's own copy of both, so it stands alone |
app/modules/docs/pages.py. A document on disk that is not listed there is appended under "Other", so a new page is never silently dropped.
app/modules/docs/book.py. A file underdocs/cli-book/ that is not listed there is not part of the book site, but the main build still writes it under "Other".
docs/cli-book/ itself is absent, the book step is skipped and the count covers the manual only.
README.md is written twice: as README.html and as index.html.docs/ (images, data) are notcopied to the output.
the output directory is cleaned. Treat public/docs as disposable output, never as a source.
public/docs at /docs/, so the book is at/docs/cli-book/ there. It only serves what build has written.
#Examples
aegis docs buildEvery page of the manual and of the book into public/docs.
aegis docs build --out /tmp/aegis-docsA throwaway copy, for checking a page without touching the one the panel serves.
#Output
✔ 85 pages written to public/docsℹ open public/docs/index.htmlThe first number is the pages written in that run: the manual plus the book. It changes whenever a document is added, so treat it as a sanity check rather than a constant. It counts pages written, not distinct files — the book lives under docs/cli-book/, so the main build discovers its documents too and writes them once before the book build writes them again with the book's sidebar.
The second line prints the entry point of the generated site, using the --out value as given.
There is no per-page report. A directory it cannot create, or a file it cannot write, ends the run with the operating system's error and a non-zero exit; a page that is missing is simply skipped.
#aegis docs web
Builds the same site, then serves the output directory over HTTP until you stop it. This is a preview server: static files, plain HTTP, no authentication and no TLS.
#Syntax
aegis docs web --host HOST --port PORT --out DIR#Options
| Option | Default | Effect |
|---|---|---|
--host HOST | 0.0.0.0 | interface to bind |
--port PORT | 0 | TCP port; 0 lets the operating system pick a free one |
--out DIR | public/docs | output directory; the same tree is served |
#Examples
aegis docs webBuild, then listen on every interface on a free port — the quickest way to read the site from another machine on the same network.
aegis docs web --host 127.0.0.1 --port 8080Loopback only, on a port you chose. Open http://127.0.0.1:8080/ for the manual and http://127.0.0.1:8080/cli-book/ for the book.
#Output
✔ 62 pages on http://0.0.0.0:41273/⚠ listening on every interface; press Ctrl+C to stop✔ 62 pages on http://127.0.0.1:8080/The success line carries the address and the port actually used, which is how you learn the free port chosen for --port 0. It counts the pages of the manual; the book is served next to them at /cli-book/ and is not included in that number. The warning appears only when the host is 0.0.0.0.
Press Ctrl+C to stop:
ℹ stopped#Notes
aegis docs buildin another shell updates what the browser receives. Reload the page.
stopped and exits 0. This is the exceptionto the 130 convention: the command owns the interrupt.
0.0.0.0 exposes the manual to every network the host is on. There is nopassword, so bind 127.0.0.1 unless the network is trusted.
command with a non-zero exit; the site is already built at that point.
served.
#Exit codes
| Code | Meaning |
|---|---|
0 | the site was built and the server ran until Ctrl+C stopped it |
| non-zero | the build failed, or the address and port could not be bound |
See Writing documentation for the Markdown subset the builder accepts and where a new page has to be registered, and Conventions for the global options and the exit codes used across the whole CLI.