Authoring
Everything ShellDocs asks of you as an author lives here : the frontmatter fields, the fenced-code conventions, how to drop a live component demo mid-page, how the sidebar decides where things go.
The one-minute overview
A ShellDocs page is a .md file under content/. Drop one in, it appears in the sidebar automatically : no registration, no import, no meta.json edit required.
---
title: My Page
description: What this page is about.
order: 3
---
# My Page
Regular markdown. Fenced code blocks:
```csharp
var x = 1;
```
Inline components mid-prose:
<div data-shelldocs-slot="component" data-shelldocs-id="sa63d98a3c922"></div>
Live component demos:
<div data-shelldocs-slot="preview" data-shelldocs-id="s993143eb772e"></div>
That's the whole surface area for authoring.
Anatomy of a page
| Prop | Type | Default | Description |
|---|---|---|---|
Frontmatter |
YAML |
— | Top-of-file `title` / `description` / `order` (+ arbitrary keys). Controls sidebar entry, meta tags, and ordering. |
Body |
markdown |
— | CommonMark + GFM pipe tables + task lists + footnotes. Softline breaks become hard breaks (edit-friendly for prose). |
Fenced code |
``` blocks |
— | Standard language fences render as highlighted code with a copy button and a language badge. |
razor:preview |
live demo |
— | Special fence that renders as live component + reveal-on-click source view. |
Inline components |
— | — |
Where pages live
Every .md under content/docs/** becomes a page. The URL is derived from the folder path:
-
content
-
docs
- introduction.md/docs/introduction
-
getting-started
- installation.md/docs/getting-started/installation
- quick-start.md/docs/getting-started/quick-start
-
docs
An index.md in a folder gets the folder's URL. content/docs/guides/index.md → /docs/guides (not /docs/guides/index). Useful for landing pages at section roots.
Reload cadence
shelldocs dev (or dotnet watch run) watches content/**/*.md. Editing a file:
- Rebuilds the navigation graph (folder changes → sidebar changes → new URLs)
- Rebuilds the search index (new bodies → new matches)
- Re-renders any page you're currently viewing
No manual refresh needed. Hot reload also picks up .razor and .cs changes.