# Authoring

> How to write pages. Markdown, frontmatter, fenced code, live component demos, inline component tags, navigation.

Source: https://shelldocs.shellui.dev/docs/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.

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

<Callout Variant="tip">Something worth calling out.</Callout>

Live component demos:

```razor:preview
<Button Variant="primary">Click me</Button>
```
````

That's the whole surface area for authoring.

## Anatomy of a page

| Name | 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` | `fence` |  | Standard language fences render as highlighted code with a copy button and a language badge. |
| `razor:preview` | `live example` |  | A fence that renders live components with Preview and Code tabs. Its body is Razor. |
| `Inline components` | `tag` |  | Component tags in the page become real Blazor components. Their bodies are markdown. |

## Where pages live

Every `.md` under `content/docs/**` becomes a page. The URL is derived from the folder path:

```text
content/
  docs/
    introduction.md  # /docs/introduction
    getting-started/
      installation.md  # /docs/getting-started/installation
      quick-start.md  # /docs/getting-started/quick-start
```

> **index.md is special**
>
> 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.

## Seeing your edits

Run the site with `shelldocs dev` (or `dotnet watch run`).

- **Editing an existing page** shows on the next browser refresh. Pages are rendered from disk on each request.
- **Adding, renaming or deleting a page, or editing a `meta.json`,** changes the navigation graph, which is built when the app starts. Restart the dev server to pick those up.
- **Editing `.razor` or `.cs` files** goes through hot reload as in any Blazor app.

## Where to go next

- [Frontmatter](https://shelldocs.shellui.dev/docs/authoring/frontmatter.md): Every field ShellDocs reads from the YAML block.
- [Fenced code](https://shelldocs.shellui.dev/docs/authoring/fenced-code.md): Language detection, copy buttons, Shiki highlighting.
- [razor:preview](https://shelldocs.shellui.dev/docs/authoring/razor-preview.md): The live-component-demo fence.
- [Inline component tags](https://shelldocs.shellui.dev/docs/authoring/component-tags.md): Drop a Callout mid-prose : how it works.
- [Navigation](https://shelldocs.shellui.dev/docs/authoring/navigation.md): meta.json, order, dividers, hidden pages.
- [Components reference](https://shelldocs.shellui.dev/docs/components/callout.md): Every primitive you can drop into markdown.
- [Versioning](https://shelldocs.shellui.dev/docs/guides/versioning.md): One docs tree per released version.
- [Redirects](https://shelldocs.shellui.dev/docs/guides/redirects.md): Folder URLs and moved pages.