Skip to content

quickstart.mdx

Latest commit

 

History

History
211 lines (158 loc) · 5.79 KB

quickstart.mdx

File metadata and controls

211 lines (158 loc) · 5.79 KB
Raw
title Quickstart
description 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:

<Tabs items={["npx (no install)", "Global install"]}> Just prefix every command with npx:

```bash
npx @cmdoss/cmdocs dev
npx @cmdoss/cmdocs check
```

On first run, npm downloads the package into a cache. Subsequent runs are instant.
If you run cmdocs often, install it once: 
```bash
npm install -g @cmdoss/cmdocs
# or: bun install -g @cmdoss/cmdocs
# or: pnpm add -g @cmdoss/cmdocs
```

Then drop the `npx` prefix:

```bash
cmdocs dev
cmdocs check
```

2. Run the dev server

npx @cmdoss/cmdocs dev

Open 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`:

```mdx title="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:

```json title="docs.json"
{
  "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" }
            ]
          }
        ]
      }
    ]
  }
}
```

<Callout type="info">
  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](/documentation/guides/writing-content) for details.
</Callout>
### 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 check

It 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](/documentation/guides/validate) 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 main

Full 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-docs

Production builds are handled by the cmdocs dashboard — there is no local build command. Push to deploy.

Next steps