RuntimeeQuickstart
Edit a page, add a new one, validate, and ship to the cmdocs dashboard.
Quickstart
By the end of this page you'll have edited a page, added a new one, validated everything with cmdocs check, and pushed to a live site on the cmdocs dashboard.
Prerequisites
- Node.js 20+ or Bun 1.0+
- A terminal
1. Install the cmdocs CLI
The easiest way is to use npx — no install, always the latest version:
Just prefix every command with npx:
npx @cmdoss/cmdocs dev
npx @cmdoss/cmdocs checkOn first run, npm downloads the package into a cache. Subsequent runs are instant.
If you run cmdocs often, install it once:
npm install -g @cmdoss/cmdocs
# or: bun install -g @cmdoss/cmdocs
# or: pnpm add -g @cmdoss/cmdocsThen drop the npx prefix:
cmdocs dev
cmdocs check2. Run the dev server
npx @cmdoss/cmdocs devOpen http://localhost:3000. You'll see this site, with hot reload enabled — every save to docs.json, an .mdx file, or an asset updates the browser automatically.
If port 3000 is busy, cmdocs picks the next available port (3001, 3002, …) and logs which one it chose.
3. Edit a page
Open index.mdx and change the title:
---
title: My First Docs
description: Documentation for my project.
---
# Hello from my docs
Welcome to my new documentation site.
<Callout type="info">
Anything inside an MDX file is rendered as a page.
</Callout>Save the file. The browser updates instantly.
4. Add a new page
Create the MDX file
Add a new file at guides/setup.mdx:
---
title: Setup Guide
description: How to set up the project.
---
# Setup
Follow these steps to get started.
<Steps>
<Step>Install dependencies</Step>
<Step>Configure environment variables</Step>
<Step>Run the dev server</Step>
</Steps>Register it in docs.json
Add the new page to the pages array under your navigation group:
{
"navigation": {
"tabs": [
{
"label": "Documentation",
"path": "documentation",
"groups": [
{
"label": "Guides",
"pages": [
{ "file": "guides/writing-content" },
{ "file": "guides/components" },
{ "file": "guides/validate" },
{ "file": "guides/deploy" },
{ "file": "guides/setup" }
]
}
]
}
]
}
}Every page is an object with a file field — the MDX path without .mdx. Add path to override the URL, label to override the sidebar display. See Writing Content for details.
Verify
The new page appears in your sidebar and is reachable at /documentation/guides/setup.
5. Validate before you commit
Run cmdocs check to catch typos, broken links, and schema errors before they reach the dashboard:
npx @cmdoss/cmdocs checkIt validates:
| Check | What it catches |
|---|---|
| docs.json schema | Invalid JSON, missing fields, wrong types |
| Navigation references | Pages in docs.json that don't have a matching .mdx |
| MDX frontmatter | Missing title, malformed YAML |
| Assets | Missing favicon, logos, or images referenced in config |
| Duplicate slugs | The same page listed twice in navigation |
| Internal links | href values in MDX and navbar/footer that point to pages that don't exist |
Exit code 0 means you're good to ship. Exit code 1 prints every problem with a file and line number.
Wire cmdocs check into a git pre-commit hook so broken docs never reach main. See the Validate guide for a one-minute setup.
6. Deploy
Commit your work and push it to a GitHub repo — then connect the repo in the cmdocs dashboard. Every future push triggers a build and deploys to <your-project>.cmdocs.app automatically.
git add .
git commit -m "initial docs"
git push origin mainFull walkthrough with screenshots: Deploy guide.
CLI reference
| Command | What it does |
|---|---|
cmdocs init [name] | Scaffold a new project (you already ran this) |
cmdocs dev | Start the local dev server with hot reload and auto-port |
cmdocs check | Validate docs.json, MDX frontmatter, assets, and internal links |
Common options
# Dev server on a specific port
cmdocs dev --port 4000
# Validate a specific source directory
cmdocs check --source ./my-docsProduction builds are handled by the cmdocs dashboard — there is no local build command. Push to deploy.
Next steps
How is this guide?