Command Line

Choose the right lildocs command, understand each flag, and map one-off CLI choices to persistent configuration.

lildocs supports these command shapes:

lildocs <path>
lildocs build <path>
lildocs dev <path>
lildocs shuffle <path>
lildocs deploy <path>
lildocs init github-pages <path>

<path> can be a Markdown folder or a single Markdown file.

Bare Build Command

Build a static documentation site from a Markdown folder or file.

lildocs ./docs

This is the shortest form of the build command. It treats ./docs as the documentation root, finds the home page, generates navigation from the folder structure, builds a search index, and writes the site to dist.

If the path points to a Markdown file, that file becomes the home page and its parent folder becomes the docs root:

lildocs ./docs/index.md

Use this form for simple local scripts, CI jobs, or one-off builds.

Build Command

Build a static documentation site with the explicit build subcommand.

lildocs build ./docs

build does the same generation work as the bare lildocs <path> form, but it is clearer in package scripts and CI configuration:

pnpm lildocs build ./docs

Build output is self-contained. Page links are relative, local assets are copied into the output folder, and search-index.json is generated next to the HTML files.

Dev Command

Start a local development server that rebuilds the generated site when docs files change.

lildocs dev ./docs

The dev server writes generated files to .lildocs by default and serves them through Vite from 127.0.0.1:3000. Add --open to launch the preview in your default browser.

Choose a different output folder when you want to inspect generated files:

lildocs dev ./docs --out ./.docs-preview

Choose the host or port when the defaults conflict with another local service:

lildocs dev ./docs --host 0.0.0.0 --port 4173

The dev output directory must stay inside the current workspace, cannot be the repository root, and cannot contain the docs root.

Shuffle Command

Preview a randomly selected light/dark theme pair, heading/body font pair, and code font:

lildocs shuffle ./docs --open

Each run starts the development server with a new combination. The preview does not change project configuration unless you keep it with --save:

lildocs shuffle ./docs --save

Saved choices use the regular theme and font fields in config.json, so they can be edited like any other appearance settings.

Deploy Command

Build GitHub Pages-ready output.

lildocs deploy ./docs

deploy builds the same static site as build, then adds Pages deployment metadata. See GitHub Pages for the full publishing workflow.

Init GitHub Pages Command

Create a GitHub Actions workflow that deploys lildocs output to GitHub Pages.

lildocs init github-pages ./docs

This command writes .github/workflows/lildocs-pages.yml if it does not already exist. The workflow obtains the current lildocs major and minor release line with pnpm dlx, runs lildocs deploy, uploads the generated output, and publishes it with GitHub's Pages deployment action. Lildocs does not need to be a project dependency.

Options

Option	Applies to	Description
--out <dir>	build, dev, shuffle, deploy, init github-pages	Output directory for generated files. Build, deploy, and init github-pages default to dist; dev and shuffle default to .lildocs.
--theme <name>	build, dev, deploy	Built-in lildocs theme or bundled Shiki theme name.
--font.heading <name-or-file>	build, dev, deploy	Heading font from Google Fonts or a local font file.
--font.body <name-or-file>	build, dev, deploy	Body and interface font from Google Fonts or a local font file.
--font.code <name-or-file>	build, dev, deploy	Code font from Google Fonts or a local font file.
--background.image <url-or-file>	build, dev, deploy	Background image URL, CSS image function, or docs-relative image path.
--background.gradient <gradient>	build, dev, deploy	CSS background gradient.
--background.blendMode <mode>	build, dev, deploy	CSS background-blend-mode for the theme color and background layers.
--link.underline <style>	build, dev, deploy	Content link underline behavior: always, hover, or none.
--host <address>	dev, shuffle	Host address for the local development server.
--port <number>	dev, shuffle	Port for the local development server.
--open	dev, shuffle	Open the local development server in the default browser.
--save	shuffle	Save the selected theme and fonts to config.json.
--base <path>	deploy, init github-pages	GitHub Pages base path, such as /repo/ for project pages.

CLI flags override matching config.json values. See Configuration for persistent defaults.

Favicon and logo settings are configuration-only and do not have CLI flags. See Themes and styling for examples.