### Quick start commands for _playground

Source: https://github.com/docmd-io/docmd/blob/main/_playground/README.md

Commands to generate tarballs, start the dev server, and run a one-shot build. Requires pnpm prep to be run first if tars are missing.

```sh
pnpm prep          # generates tars into _playground/local-tars/
pnpm dev           # installs in _playground/ and starts the dev server
pnpm build         # installs in _playground/ and runs a one-shot build

```

--------------------------------

### Install @docmd/plugin-math

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/math/README.md

Installs the plugin using the docmd CLI. Run this command to add the plugin to your project.

```bash
docmd add math
```

--------------------------------

### Initialize new docmd project and start dev server

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Initializes a new docmd project in the current directory by mounting it to /workspace and running the init command, then starts the dev server with the same mount and port 3000.

```bash
# Create and initialize a new project
mkdir my-docs && cd my-docs
docker run -v $(pwd):/workspace ghcr.io/docmd-io/docmd:latest init

# Start dev server
docker run -v $(pwd):/workspace -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev
```

--------------------------------

### Install @docmd/core with npm

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/tabs.md

Use npm to install the @docmd/core package.

```bash
npm install @docmd/core
```

--------------------------------

### Use docmd CLI after global install

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Runs the dev server and build commands after global installation.

```bash
docmd dev
docmd build
```

--------------------------------

### Install @docmd/template-summer with npm

Source: https://github.com/docmd-io/docmd/blob/main/packages/templates/summer/README.md

Install the template package using npm.

```bash
npm install @docmd/template-summer
```

--------------------------------

### Legacy tab syntax example

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/tabs.md

Shows the legacy tab syntax in a standalone block.

```text
Legacy tab syntax (== tab) in standalone block
```

--------------------------------

### Start local dev server with pnpm dev

Source: https://github.com/docmd-io/docmd/blob/main/_playground/docs/index.md

Run the local playground development server. Use this command to preview the docmd 0.9.3 features interactively.

```sh
pnpm dev
```

--------------------------------

### Install docmd globally

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Installs docmd globally using npm or pnpm.

```bash
npm install -g @docmd/core

# or
pnpm add -g @docmd/core
```

--------------------------------

### Install @docmd/core with yarn

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/tabs.md

Use yarn to add the @docmd/core package.

```bash
yarn add @docmd/core
```

--------------------------------

### Install @docmd/core with bun (legacy tabs)

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/tabs.md

Use bun to add the @docmd/core package within legacy tab syntax.

```bash
bun add @docmd/core
```

--------------------------------

### Install @docmd/plugin-threads

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/threads/README.md

Installs the optional threads plugin for docmd. Run this command to add the plugin to your project.

```bash
docmd add threads
```

--------------------------------

### Use existing docs with docmd Docker image

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Mounts your existing docs into /docs and starts the dev server, or builds a static site into /site. The entrypoint only seeds the demo template when /docs is completely empty, so your content is never overwritten.

```bash
# Mount your docs and start dev server
docker run -v $(pwd)/docs:/docs -p 3000:3000 ghcr.io/docmd-io/docmd:latest

# Build static site
docker run -v $(pwd)/docs:/docs -v $(pwd)/site:/site ghcr.io/docmd-io/docmd:latest build
```

--------------------------------

### Install @docmd/core with pnpm

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/tabs.md

Use pnpm to add the @docmd/core package.

```bash
pnpm add @docmd/core
```

--------------------------------

### Run docmd demo site with built-in template

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Runs the container with no volume mount; the entrypoint copies the built-in demo template from /template into /docs on first start, so the demo site is available immediately at http://localhost:3000.

```bash
# Start with built-in demo site — works out of the box
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest

# Visit http://localhost:3000
```

--------------------------------

### Install an optional plugin with docmd add

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Use this command to install an optional docmd plugin. Replace <plugin-name> with the actual plugin identifier, such as pwa, threads, or math.

```bash
docmd add <plugin-name>
```

--------------------------------

### Configure SEO plugin in docmd.config.js

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/seo/README.md

Example configuration for the SEO plugin, including setting a default description and Twitter site username.

```js
// docmd.config.js
module.exports = {
  plugins: {
    seo: {
      defaultDescription: 'My documentation site',
      twitter: { siteUsername: '@myproject' }
    }
  }
};
```

--------------------------------

### Use inline and block math syntax

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/math/README.md

Shows how to use inline ($...$) and block ($$...$$) LaTeX math in your content. The block example displays a summation formula.

```js
$E = mc^2$

$$
\sum_{i=1}^n i^2 = \frac{n(n+1)(2n+1)}{6}
$$
```

--------------------------------

### Run docmd dev server

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Starts the docmd development server, which serves your Markdown files at http://localhost:3000. Requires Node.js 20+.

```bash
npx @docmd/core dev
```

--------------------------------

### Configure @docmd/plugin-llms in docmd.config.js

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/llms/README.md

Configuration example for the @docmd/plugin-llms plugin. Requires siteUrl to produce valid absolute links.

```javascript
// docmd.config.js
module.exports = {
  siteUrl: 'https://your-site.com',
  plugins: {
    llms: {}
  }
};
```

--------------------------------

### Configure sitemap plugin in docmd.config.js

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/sitemap/README.md

Example configuration for the sitemap plugin. Requires siteUrl to be set. Optional plugin options include defaultChangefreq and defaultPriority.

```javascript
// docmd.config.js
module.exports = {
  siteUrl: 'https://mysite.com', // required
  plugins: {
    sitemap: { defaultChangefreq: 'weekly', defaultPriority: 0.8 }
  }
};
```

--------------------------------

### Install and remove plugins via CLI

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/installer/README.md

Use these commands to add or remove plugins from your docmd project.

```bash
docmd add search
docmd remove search
```

--------------------------------

### docmd configuration JSON example

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Optional configuration file in JSON format. Add docmd.config.json to the project root to control title, URL, source directory, and output directory.

```json
{
  "title": "My Project",
  "url": "https://docs.myproject.com",
  "src": "./docs",
  "out": "./dist"
}
```

--------------------------------

### Mermaid diagram example

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/mermaid.md

An example Mermaid diagram definition showing a simple flowchart with decision points and subgraphs.

```mermaid
graph TD
  Start((Start)) --> Process1[Process One]
  Process1 --> Decision{Is it valid?}
  Decision -- No --> Error[Error Handling]
  Decision -- Yes --> Process2[Process Two]
  Process2 --> Subgraph1
  subgraph Subgraph1 [Critical Path]
  Step1[Step 1] --> Step2[Step 2]
  end
  Step2 --> End((End))
  Error --> End
```

--------------------------------

### Run the editor locally with docmd live

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/README.md

Starts the docmd Live Editor locally. Use this command in your terminal to launch the editor for local development.

```bash
# Run the editor locally
docmd live
```

--------------------------------

### Configure docmd to use the Rust engine

Source: https://github.com/docmd-io/docmd/blob/main/packages/engines/rust/README.md

Set the engine to 'rust' in the docmd.config.js file. On first run, docmd will prompt to install the appropriate native binary for your platform.

```javascript
// docmd.config.js
export default {
  engine: 'rust'
};
```

--------------------------------

### Per-page opt-out frontmatter

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/okf/README.md

Two frontmatter examples to exclude pages from the OKF bundle. The first uses noindex to also exclude from sitemap and llms.txt, the second uses okf: false to only exclude from the OKF bundle.

```markdown
---
noindex: true   # also excludes from sitemap, llms.txt, etc.
---
```

```markdown
---
okf: false       # only excludes from the OKF bundle
---
```

--------------------------------

### Initialise Project Command

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/steps.md

Run this command to scaffold your directory with a starter docmd.config.json file.

```bash
npx @docmd/core init
```

--------------------------------

### Build and Deploy Command

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/steps.md

Run this command to produce a static site under the ./site directory, which is ready for deployment to any CDN.

```bash
npx @docmd/core build
```

--------------------------------

### Build production static site with pnpm build

Source: https://github.com/docmd-io/docmd/blob/main/_playground/docs/index.md

Generate a production static build into the 'site/' directory. Use this command to produce the final deployable output.

```sh
pnpm build
```

--------------------------------

### Run dev server with loopback only (default)

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Runs the dev server bound to 127.0.0.1 by default, accessible via http://localhost:3000 from the host. This is the safer default.

```bash
# Loopback only (default) — access via http://localhost:3000 from the host
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev
```

--------------------------------

### Run build with memory limit for large sites

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Runs the build command with a 2GB memory limit, useful for large documentation sites. Mounts the local docs directory.

```bash
# For large documentation sites
docker run --memory=2g -v $(pwd)/docs:/docs ghcr.io/docmd-io/docmd:latest build
```

--------------------------------

### GitHub Actions workflow for building and deploying docs

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

CI workflow triggered on push to main. It checks out the repo, runs a docker build command mounting docs and site volumes, then deploys the generated site to GitHub Pages using peaceiris/actions-gh-pages. Pin the image tag for reproducible runs.

```yaml
name: Build Docs

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build documentation
        # Pin to a specific version (replace `:latest`) for reproducible CI runs.
        run: |
          docker run --rm \
            -v ${{ github.workspace }}/docs:/docs \
            -v ${{ github.workspace }}/site:/site \
            ghcr.io/docmd-io/docmd:latest \
            build
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
```

--------------------------------

### Enable summer template with full package name

Source: https://github.com/docmd-io/docmd/blob/main/packages/templates/summer/README.md

Alternative configuration using the full package name for the template.

```json
{
  "theme": {
    "template": "@docmd/template-summer"
  }
}
```

--------------------------------

### Inline tag container

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/containers.md

Inline tags use inline closing tags. This example shows a standalone tag with primary style and star icon.

```markdown
::: tag "Standalone Tag" style:primary icon:star ::: /tag
```

--------------------------------

### Callout container with semantic types

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/presets/containers.md

Callouts isolate information and support types: info, tip, warning, danger, success. Container comments starting with # are supported.

```markdown
::: callout info "Callout semantic types" icon:info # Container comments starting with # are supported!
Callouts isolate information that requires attention. Choose from `info`, `tip`, `warning`, `danger`, or `success`.
::: /callout
```

--------------------------------

### Run dev server with LAN access (--host 0.0.0.0)

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Binds the dev server to 0.0.0.0 inside the container, making it reachable from other devices on the host's network. Security warning: only do this on trusted networks; the WebSocket requires an Origin matching the bind host (defence against CSWSH, CWE-1385).

```bash
# LAN access — the dev server binds to 0.0.0.0 inside the container, and
# the port mapping makes it reachable from other devices on the host's network.
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev --host 0.0.0.0
```

--------------------------------

### Mermaid flowchart in Markdown code fence

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/mermaid/README.md

Use a mermaid code fence to render a Mermaid diagram directly in Markdown. The example shows a flowchart with nodes A, B, C, and D connected by edges.

```markdown
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```
```

--------------------------------

### Build command for current platform

Source: https://github.com/docmd-io/docmd/blob/main/packages/engines/rust-binaries/README.md

Builds the Rust engine for the current platform using pnpm. Requires the package to be built on each target platform separately.

```bash
# Build for current platform
pnpm --filter @docmd/engine-rust-binaries run build

# You need to build on each platform:
# - macOS ARM64 (Apple Silicon Mac)
# - macOS x64 (Intel Mac)
# - Linux x64
# - Linux ARM64
# - Windows x64
```

--------------------------------

### Build the docmd Docker image locally

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Clones the repository and builds the Docker image with the tag docmd:local using the docker/Dockerfile. Then tests the build by running the container with the docs directory mounted and checking the version.

```bash
# Clone the repository
git clone https://github.com/docmd-io/docmd.git
cd docmd

# Build the image
docker build -t docmd:local -f docker/Dockerfile .

# Test the build
docker run --rm -v $(pwd)/docs:/docs docmd:local --version
```

--------------------------------

### Architecture directory tree

Source: https://github.com/docmd-io/docmd/blob/main/packages/deployer/README.md

Shows the source layout of @docmd/deployer, with providers as pure functions and the orchestrator handling file writing.

```text
@docmd/deployer
  src/
    context.ts          Shared DeployContext type
    index.ts            Orchestrator - resolves options, writes files
    providers/
      docker.ts         Dockerfile + .dockerignore
      nginx.ts          nginx.conf
      caddy.ts          Caddyfile
      github-pages.ts   GitHub Actions deploy workflow
      vercel.ts         vercel.json
      netlify.ts        netlify.toml
```

--------------------------------

### Output structure tree

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/okf/README.md

Shows the directory structure emitted by the plugin, including the manifest, index, concepts, and meta files. The graph subdirectory is only emitted when plugins.okf.graph is true.

```text
site/okf/                          # Always emitted
├── okf.yaml                       # Typed manifest (bundle summary)
├── index.md                       # Karpathy-style catalog grouped by type
├── concepts/
│   └── <slug>.md                 # One markdown file per page
└── _meta/
    ├── bundle.json                # JSON mirror of okf.yaml
    └── lint-report.txt            # Warnings produced during generation

# Emitted only when `plugins.okf.graph: true`
├── graph/                         # Interactive viewer (open /okf/graph/)
│   ├── index.html                 # Force-directed graph viewer
│   ├── graph.json                 # Graph data (nodes + edges)
│   ├── graph.js                   # Viewer runtime (vanilla, no CDN deps)
│   └── graph.css                  # Viewer styles (theme-aware)
```

--------------------------------

### Interactive Architecture Diagram

Source: https://github.com/docmd-io/docmd/blob/main/_playground/docs/mermaid-preview.md

An interactive Mermaid graph (using the '::: mermaid' directive) showing the system architecture with client, core, parser, OpenAPI, and Mermaid components. Use this to illustrate component relationships in offline deployments.

```mermaid
graph TD
    Client["Browser / Offline Consumer"]
    Core["@docmd/core Generator"]
    Parser["@docmd/parser (Normalized URLs)"]
    OpenAPI["@docmd/plugin-openapi (Examples & Schemas)"]
    Mermaid["@docmd/plugin-mermaid (Offline Assets)"]

    Client --> Core
    Core --> Parser
    Core --> OpenAPI
    Core --> Mermaid
```

--------------------------------

### Embed the editor engine with buildLive from @docmd/core

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/README.md

Imports and invokes the `buildLive` function from `@docmd/core` to embed the editor engine in your own tooling. This is an asynchronous operation, so it must be awaited.

```javascript
// Embed the editor engine in your own tooling
import { buildLive } from '@docmd/core';
await buildLive();
```

--------------------------------

### Default engine configuration

Source: https://github.com/docmd-io/docmd/blob/main/packages/engines/js/README.md

Shows the default configuration when no engine is specified, which uses the 'js' engine.

```javascript
// docmd.config.js
export default {
  // No engine specified = uses 'js' engine
};
```

--------------------------------

### docmd migrate CLI command

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Command to migrate existing documentation from supported frameworks like Docusaurus, VitePress, MkDocs, and Starlight.

```bash
docmd migrate
```

--------------------------------

### Dependency graph

Source: https://github.com/docmd-io/docmd/blob/main/packages/deployer/README.md

Shows the dependency direction: @docmd/core to @docmd/deployer to @docmd/api, with no cycles.

```text
@docmd/core  →  @docmd/deployer  →  @docmd/api
```

--------------------------------

### Live Editor JavaScript: Syntax Highlighting, Preset Loading, Rendering, Copy, and Scroll Sync

Source: https://github.com/docmd-io/docmd/blob/main/packages/live/src/index.html

Core client-side logic for the docmd Live Editor. It initializes the editor with the 'Basics' preset, updates syntax highlighting on input, loads presets from the SNIPPETS object, compiles markdown to HTML via docmd.compile, writes the result into an iframe preview, handles the copy button, and includes a disabled-by-default scroll sync feature. The render function uses a render ID to prevent stale renders from overwriting newer ones and injects a base target and scroll restoration script into the generated HTML.

```javascript
const SNIPPETS = {};
const input = document.getElementById('input');
const preview = document.getElementById('preview');
const highlightBg = document.getElementById('highlightBg');
const highlightCode = document.getElementById('highlightCode');

function updateEditorHighlight() {
  if (window.docmd && typeof window.docmd.highlight === 'function') {
    const text = input.value || '';
    const res = docmd.highlight(text);
    highlightCode.innerHTML = res.value + (text.endsWith('\n') ? '\n' : '');
  } else {
    highlightCode.textContent = (input.value || '') + (input.value.endsWith('\n') ? '\n' : '');
  }
}

input.addEventListener('scroll', () => {
  highlightBg.scrollTop = input.scrollTop;
  highlightBg.scrollLeft = input.scrollLeft;
});

// Initialize with Basics
if (!input.value) input.value = SNIPPETS.basics;
updateEditorHighlight();

function loadPreset(key, btn) {
  if (SNIPPETS[key]) {
    input.value = SNIPPETS[key];
    updateEditorHighlight();
    if (btn) {
      document.querySelectorAll('.presets-bar button').forEach(b => b.classList.remove('active'));
      btn.classList.add('active');
    }
    render();
  }
}

let currentRenderId = 0;
async function render() {
  const renderId = ++currentRenderId;
  try {
    const scrollY = preview.contentWindow ? preview.contentWindow.scrollY : 0;
    let html = await docmd.compile(input.value, {
      siteTitle: 'Live Preview',
      search: false,
      theme: { name: 'default', appearance: 'light' },
      sidebar: { collapsible: false }
    });
    // Prevent older renders from overwriting newer ones
    if (renderId !== currentRenderId) return;
    html = html.replace('<head>', '<head><base target="_blank">');
    const scrollScript = `
      <script>
        if (window) window.scrollTo(0, ${scrollY});
      <\/script>
    `;
    html = html.replace('</body>', `${scrollScript}</body>`);
    const doc = preview.contentWindow.document;
    doc.open();
    doc.write(html);
    doc.close();
  } catch (e) {
    console.error(e);
  }
}

let timer;
input.addEventListener('input', () => {
  updateEditorHighlight();
  clearTimeout(timer);
  timer = setTimeout(render, 300);
});

// Copy Markdown Button Handler
const copyBtn = document.getElementById('copyBtn');
if (copyBtn) {
  copyBtn.addEventListener('click', async () => {
    try {
      await navigator.clipboard.writeText(input.value);
      copyBtn.textContent = 'Copied !';
      copyBtn.classList.add('copied');
      setTimeout(() => {
        copyBtn.textContent = 'Copy';
        copyBtn.classList.remove('copied');
      }, 2000);
    } catch (err) {
      console.error('Failed to copy markdown:', err);
    }
  });
}

// Auto Scroll Sync (textarea -> iframe preview) - Disabled by default
const ENABLE_SCROLL_SYNC = false;
let isSyncingInputScroll = false;
input.addEventListener('scroll', () => {
  if (!ENABLE_SCROLL_SYNC || isSyncingInputScroll) return;
  isSyncingInputScroll = true;
  const maxInputScroll = input.scrollHeight - input.clientHeight;
  if (maxInputScroll > 0 && preview.contentWindow && preview.contentWindow.document) {
    const ratio = input.scrollTop / maxInputScroll;
    const win = preview.contentWindow;
    const doc = win.document.documentElement;
    const maxPreviewScroll = doc.scrollHeight - win.innerHeight;
    if (maxPreviewScroll > 0) {
      win.scrollTo({ top: ratio * maxPreviewScroll, behavior: 'instant' });
    }
  }
  requestAnimationFrame(() => {
    isSyncingInputScroll = false;
  });
});

// Preview pane: light/dark toggle. Mutates the iframe's
// document data-theme and persists via the same localStorage
// key the theme-init script reads on next render.
```

--------------------------------

### Customize summer template with custom CSS

Source: https://github.com/docmd-io/docmd/blob/main/packages/templates/summer/README.md

Add custom CSS to override the template's styles. The custom CSS always wins at priority 15.

```json
{
  "theme": {
    "template": "summer",
    "customCss": ["/assets/css/my-summer-tweaks.css"]
  }
}
```

--------------------------------

### Add the openapi plugin via docmd CLI

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/openapi/README.md

Run this command to add the @docmd/plugin-openapi to your project. It is part of the docmd documentation engine.

```bash
docmd add openapi
```

--------------------------------

### Configure @docmd/plugin-pwa in docmd.config.js

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/pwa/README.md

All options are optional. Set themeColor, bgColor, and logo to customize the PWA manifest and service worker.

```javascript
// docmd.config.js - all options are optional
module.exports = {
  plugins: {
    pwa: {
      themeColor: '#0097ff',
      bgColor: '#ffffff',
      logo: 'assets/images/logo.png'
    }
  }
};
```

--------------------------------

### Flowchart: Offline Rendering Pipeline

Source: https://github.com/docmd-io/docmd/blob/main/_playground/docs/mermaid-preview.md

A Mermaid flowchart showing the pipeline from Markdown source through the parser, OpenAPI and Mermaid plugins, to production static HTML. Use this to visualize the offline build architecture.

```mermaid
flowchart LR
    A[Markdown Source] -->|Parser Engine| B[AST & Tokens]
    B -->|OpenAPI Plugin| C[Rendered Schema Tables & Examples]
    B -->|Mermaid Plugin| D[Offline Bundled SVG Visuals]
    C & D -->|Generator| E[Production Static HTML]
```

--------------------------------

### docmd CLI commands

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

List of docmd CLI commands for development, building, and maintenance. Includes commands for dev server, production build, live editor, init, doctor, validate, migrate, deploy, MCP server, add, and stop.

```bash
docmd dev            # Start the local development server
docmd build          # Build for production
docmd live           # Start the browser-based Live Editor
docmd init           # Create a configuration file
docmd doctor         # Check configuration and plugin status
docmd validate       # Check internal documentation links
docmd migrate        # Migrate from Docusaurus, VitePress, MkDocs, or Starlight
docmd deploy         # Generate deployment configuration
docmd mcp            # Run the MCP server over stdio
docmd add <name>     # Install a plugin or template
docmd stop           # Stop running docmd development servers
```

--------------------------------

### Run docmd with Docker

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Runs docmd in a Docker container, mapping port 3000. Pin the image to a specific release for reproducible production builds.

```bash
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest
```

--------------------------------

### Importing @docmd/api modules

Source: https://github.com/docmd-io/docmd/blob/main/packages/api/README.md

Basic import statement for loading plugins, creating action dispatchers, and initializing source tools, along with necessary type definitions.

```typescript
import { loadPlugins, createActionDispatcher, createSourceTools } from '@docmd/api';
import type { PluginDescriptor, PluginModule } from '@docmd/api';
```

--------------------------------

### Basic TUI usage with @docmd/tui

Source: https://github.com/docmd-io/docmd/blob/main/packages/tui/README.md

Import the TUI class and call its static methods to render a banner, section header, step status, and footer in the terminal.

```typescript
import { TUI } from '@docmd/tui';

TUI.banner(undefined, '0.7.7');
TUI.section('Building Site');
TUI.step('Parsing content', 'DONE');
TUI.footer();
```

--------------------------------

### Sequence Diagram: Offline Build Flow

Source: https://github.com/docmd-io/docmd/blob/main/_playground/docs/mermaid-preview.md

A Mermaid sequence diagram showing the offline build process: developer runs 'docmd build --offline', the CLI resolves plugins, the engine bundles Mermaid locally, and the browser receives portable HTML with local assets. Use this to document the offline build workflow.

```mermaid
sequenceDiagram
    autonumber
    actor User as Developer
    participant CLI as docmd CLI
    participant Engine as Build Engine
    participant Browser as Static Site (Offline/Air-gapped)

    User->>CLI: docmd build --offline
    CLI->>Engine: Resolve plugins & assets
    Engine->>Engine: Bundle Mermaid locally into assets/
    Engine->>Browser: Emit portable file:// HTML + local assets
    Browser-->>User: Instant interactive diagrams without network access
```

--------------------------------

### Configure AI plugin in docmd.config.json

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/ai/README.md

Add the AI plugin configuration to your docmd.config.json or docmd.config.js file. Set the provider, model, position, and optional suggestion pills. The provider must be one of the supported providers (e.g., openai) and the model should be a valid model for that provider.

```json
{
  "plugins": {
    "ai": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "position": "bottom-right",
      "suggestions": [
        "How do I get started?",
        "What are the main features?",
        "Show code examples"
      ]
    }
  }
}
```

--------------------------------

### docmd AI Assistant architecture diagram

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

ASCII diagram showing the flow from documentation through @docmd/plugin-ai and docmd Cloud Relay to the AI provider.

```text
Your documentation
        │
        ▼
 @docmd/plugin-ai
        │
        ▼
 docmd Cloud Relay
        │
        ▼
 Your AI provider
```

--------------------------------

### Kubernetes Deployment for docmd

Source: https://github.com/docmd-io/docmd/blob/main/docker/DOCKER.md

Defines a Deployment named docmd-server with one replica, using the ghcr.io/docmd-io/docmd:latest image. It mounts a ConfigMap named docs-content at /docs and runs the dev server with command ["docmd", "dev"]. The dev server defaults to 127.0.0.1; set DOCMD_HOST=0.0.0.0 or pass --host 0.0.0.0 for LAN access.

```yaml
# Replace `:latest` with a specific version (e.g. `0.8.7`) for reproducible
# production deploys. Update the tag when you upgrade.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docmd-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: docmd
  template:
    metadata:
      labels:
        app: docmd
    spec:
      containers:
      - name: docmd
        image: ghcr.io/docmd-io/docmd:latest
        ports:
        - containerPort: 3000
        volumeMounts:
        - name: docs
          mountPath: /docs
        # The dev server defaults to 127.0.0.1. For LAN access, set
        # DOCMD_HOST=0.0.0.0 or pass --host 0.0.0.0 explicitly.
        command: ["docmd", "dev"]
      volumes:
      - name: docs
        configMap:
          name: docs-content
```

--------------------------------

### docmd.config.json plugin configuration

Source: https://github.com/docmd-io/docmd/blob/main/packages/plugins/okf/README.md

Configuration for the okf plugin in docmd.config.json. The plugin is enabled by default.

```json
// docmd.config.json

{
  "plugins": {
    "okf": {
      // config options, okf is enabled by default
    }
  }
}
```

--------------------------------

### docmd output pipeline diagram

Source: https://github.com/docmd-io/docmd/blob/main/packages/core/README.md

Shows the compilation pipeline from Markdown through docmd to multiple output formats.

```text
Markdown
   │
   ▼
 docmd
   │
   ├── → Static documentation site
   ├── → Offline search index
   ├── → llms.txt / llms-full.txt
   ├── → Open Knowledge Format (OKF)
   ├── → Sitemap + SEO metadata
   ├── → robots.txt + Open Graph
   ├── → MCP interface for AI agents
   └── → AI Assistant context
```