CLI Reference

LitMDX exposes three commands via the litmdx binary.

`litmdx init`

Scaffolds a new LitMDX project in the current directory.

litmdx init

Behavior:

Prompts for project name (default: my-docs).
Creates package.json, litmdx.config.ts, docs/, and sample SVG assets in public/.
Safe to run in an existing directory — only creates files that do not already exist.

Tip

Prefer npm create litmdx when starting a brand-new project from scratch. litmdx init is useful when adding docs to an existing repository.

`litmdx dev`

Starts the Vite development server.

litmdx dev

Behavior:

Finds the first available port starting at 5173 (increments to 5200 if taken).
Reads litmdx.config.ts from the current working directory.
Serves all .mdx files from docsDir (default: docs/) as routes.
Supports Hot Module Replacement — edits appear instantly.

Note

The Pagefind search index is not available in dev mode. The search modal will open but return no results until you run litmdx build.

`litmdx build`

Builds the site for production.

litmdx build

Outputs to dist/. Runs three sequential steps:

Vite build

Bundles React, MDX, and CSS assets into dist/assets/ and writes the base HTML shell.

Static prerender

Renders each known documentation route to static HTML such as dist/index.html, dist/basics/index.html, and dist/reference/configuration/index.html.

Pagefind indexing

Reads all .mdx source files, extracts text content, and generates dist/pagefind/ — the full-text search index served at runtime.

If siteUrl is configured, the build also writes dist/sitemap.xml.

Deploy the dist/ directory to any static host — Netlify, Vercel, GitHub Pages, Cloudflare Pages, S3, or any CDN.

Add to `package.json`

{
  "scripts": {
    "docs:dev":   "litmdx dev",
    "docs:build": "litmdx build"
  }
}

Exit codes

Code	Meaning
`0`	Success
`1`	Build error (Vite build failure or config error)