Getting Started

By the end of this page, you’ll have a working documentation site with multiple pages, a custom theme, and organized navigation. Let’s go.

Step 1: Create your site

dorcs init
dorcs --watch

Open http://localhost:8080. You’ve got a docs site. It has one page (docs/index.md) and uses the default theme.

Step 2: Add some pages

Your site needs more than a homepage. Create a few Markdown files:

docs/
├── index.md
├── 01_getting-started.md
├── 02_features.md
└── guides/
    ├── index.md
    └── first-steps.md

Each file becomes a page with a clean URL:

The sidebar navigation updates automatically — every page you add shows up. The 01_, 02_ prefixes control the order but don’t appear in URLs.

Step 3: Write real content

Open any page and write Markdown. Here’s a taste of what you can do — beyond the basics:

> **ALERT:TIP**
> Use callouts to highlight important information.

:::tabs
::tab macOS
\`\`\`bash
brew install my-tool
\`\`\`
::tab Linux
\`\`\`bash
apt install my-tool
\`\`\`
:::

This feature is NEW in version 2.0.

That gives you styled callouts, tabbed content, and inline badges — all from plain Markdown. See Extensions for everything available.

Step 4: Pick a theme

Open dorcs.yaml and change the theme:

site:
  title: "My Project Docs"

theme:
  preset: ocean
  mode: auto

Try ocean, forest, sunset, midnight, lavender, rose, or any of the other presets. Your site updates instantly thanks to --watch. Browse them all on the Themes page.

Step 5: Organize your navigation

For a small site, the automatic sidebar is fine. But once you have more pages, take control with nav.items in your config:

nav:
  items:
    - Home: index.md
    - Getting Started: 01_getting-started.md
    - Features: 02_features.md
    - Guides:
        page: guides/index.md
        items:
          - First Steps: guides/first-steps.md

This gives you custom labels and exact ordering. For even bigger sites, you can use section tabs — see Navigation.

Step 6: Ship it

Build static HTML and deploy anywhere:

dorcs build

Upload the dist/ folder to GitHub Pages, Netlify, Vercel, or any web server. See Deployment for platform-specific guides.

What you’ve built

In just a few minutes, you now have:

• A multi-page docs site with automatic navigation
• A custom theme with light/dark mode
• Clean URLs, search, code copy buttons, and a table of contents
• A static build ready for any host

Keep going