Configuration

conf.py value	default	meaning
likec4_source_dir	— (required)	directory of .c4/.likec4 sources, relative to conf.py
likec4_version	pinned in src/sphinx_likec4/package.json (Dependabot keeps it current)	exact CLI version run via npx -y likec4@<version>
likec4_missing	"error"	when node/npx is absent: error fails the build, warn renders placeholders
likec4_build_args	[]	extra arguments appended to likec4 build
likec4_render	{}	default render mode per output format, keyed by builder format ("html", "latex", …; epub uses "epub"), e.g. {"latex": "jpg", "epub": "png"}; values iframe, png, jpg, text
likec4_export_images	True	set False to never run the image export: HTML renders iframes only, non-HTML builders fall back to plain text, no Chromium needed

Node ≥ 20 must be on PATH at doc-build time. The build is cached on a content hash of the sources + version + args, so incremental Sphinx builds don’t re-run the CLI. The viewer is copied into the output at _likec4/ and uses hash routing, so it works from any subpath.

The likec4_missing="warn" warning is tagged type="likec4", so it can be silenced even under -W with suppress_warnings = ["likec4"] in conf.py.

Static images and PDF

Only the views a build actually embeds are exported: a page’s directive renders its view on first use (likec4 export png --flat -f <id>), and rebuilds re-export the remembered set in one run per format when the sources changed. Plain HTML never starts a browser unless a page asks for a static image (:render: png or :render: jpg); unreferenced views are never rendered. Parallel reads (-j) are safe: the cache directories are validated once in the main process before the workers start, and concurrent exports into them coexist. A first image build pays one CLI run (browser start included) per newly referenced view; rebuilds re-export the remembered set in a single run per format only when the sources changed. The renders live under the doctree dir (likec4/images-<fmt>/), cached on the same content hash as the viewer. If the batched re-export fails on a builder whose default is the iframe, the build continues with a likec4 warning and :render: png/jpg fall back to the iframe; an export failure for an explicitly requested image is an error. Set likec4_export_images = False to disable images entirely. The export renders in headless Chromium through Playwright. If no browser is present the extension installs one once, using likec4’s own Playwright so the revision matches:

npx -y --package likec4@<pinned version> -c 'playwright install chromium'   # what it runs for you

(≈150 MB, into Playwright’s cache under your home directory.) On a minimal Linux CI image add --with-deps to that command yourself if Chromium complains about missing shared libraries.

For a PDF: sphinx-build -M latexpdf docs docs/_build — nothing LikeC4-specific to configure. The extension’s own docs use latex_engine = "xelatex" for the Unicode arrows in the text.