CmdocsQuickstart
Build, edit, and ship a documentation site in under 5 minutes.
Quickstart
By the end of this page you'll have a running cmdocs site, edited a page, added a new page, and validated it for deployment.
Prerequisites
- Node.js 20+ or Bun 1.0+
- A terminal
Install the CLI
The fastest way is npx — no install required, always the latest version. Every command in this guide is prefixed with npx, but if you install cmdocs globally once (npm install -g @cmdoss/cmdocs) you can drop the prefix. See Installation for all options.
1. Create a project
Initialize
npx @cmdoss/cmdocs init my-docs
cd my-docscmdocs scaffolds a starter project for you:
| File / Folder | Purpose |
|---|---|
docs.json | Site configuration — name, theme, navigation, navbar |
*.mdx | Your documentation pages, written in MDX |
public/ | Static assets — logos, images, favicons |
Start the dev server
npx @cmdoss/cmdocs devOpen http://localhost:3000. You'll see your starter site, with hot reload enabled — every save updates the browser automatically.
2. 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.
3. 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:
{
"name": "My Docs",
"navigation": {
"tabs": [
{
"label": "Documentation",
"path": "documentation",
"groups": [
{
"label": "Getting Started",
"pages": [
{ "file": "index" },
{ "file": "quickstart" },
{ "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.
Verify
Your project now looks like this:
The new page appears in your sidebar at /guides/setup.
4. Validate before deploying
Run cmdocs check to validate your project before pushing:
npx @cmdoss/cmdocs checkThis verifies:
- docs.json schema is valid
- All pages referenced in navigation exist
- MDX frontmatter has required fields (
title) - Assets (favicon, logos) exist
If everything passes, you're ready to deploy.
5. Deploy
The fastest way to go live is the cmdocs Dashboard — connect your GitHub repo and every push triggers a build automatically.
Sign in at cmdocs.sh with GitHub.
Create a project and select your docs repository.
Push to deploy. Every commit to your tracked branch produces a new deployment at <slug>.cmdocs.app.
For the full walkthrough, see Deployment.
What's next
How is this guide?