Organizing Your Pages

Your folder structure IS your site structure. Every Markdown file becomes a page, every folder becomes a section.

Files become pages

docs/
├── index.md              → /
├── getting-started.md    → /getting-started
└── guides/
    ├── index.md          → /guides
    ├── install.md        → /guides/install
    └── deploy.md         → /guides/deploy

That’s the core idea — one file, one page, clean URLs.

Controlling sidebar order

By default, Dorcs sorts pages alphabetically. To control the order, prefix filenames with numbers:

docs/
├── 01_intro.md       ← first in sidebar
├── 02_install.md     ← second
└── 03_deploy.md      ← third

The numbers affect sidebar order but don’t appear in URLs — 01_intro.md becomes /intro.

You can also set order in front matter:

---
title: "Introduction"
order: 1
---

Linking between pages

Use regular Markdown links with relative paths:

Check out the [install guide](/usage/guides/install) for next steps.

Dorcs automatically rewrites .md links to clean URLs. So ./guides/install.md becomes /guides/install for the reader. Links work in your editor preview AND on the rendered site.

Adding images

Put images anywhere in your docs/ folder and reference them with relative paths:

![Architecture diagram](/usage/images/overview.png)

Writing tips

• One topic per page — don’t cram everything into one file
• Use folders to group related pages — they become sidebar sections automatically
• Start with the outcome — tell readers what they’ll achieve, then show how
• Keep sections short — if it feels long, split it into another page
• Use examples over explanations — a code snippet beats a paragraph

Live reload

Run Dorcs with --watch and your browser refreshes automatically every time you save a file — including when you change dorcs.yaml:

dorcs --watch