---
title: "Pages"
description: "Structure the content/ directory, write frontmatter, and control how pages appear in navigation."
canonical_url: "https://docs-template.comark.dev/writing/pages"
---
# Pages

> Structure the content/ directory, write frontmatter, and control how pages appear in navigation.

Every page is a Markdown file under `content/` in your repository. The file path becomes the URL, and the directory structure becomes the [navigation](https://docs-template.comark.dev/writing/navigation).

## Directory structure

Numeric prefixes order sections and pages. They're stripped from URLs:

```
content/
├── index.md                          → /
├── 1.getting-started/
│   ├── .navigation.yml
│   ├── 1.introduction.md             → /getting-started/introduction
│   └── 2.installation.md             → /getting-started/installation
└── 2.concepts/
    ├── .navigation.yml
    └── 1.architecture.md             → /concepts/architecture
```

- `index.md` at the root is the [landing page](https://docs-template.comark.dev/writing/landing-page).
- An `index.md` inside a section becomes the section's own page (`1.getting-started/index.md` → `/getting-started`).
- Each section directory holds a `.navigation.yml` with its display title:

```yaml [content/1.getting-started/.navigation.yml]
title: Getting Started
```

## Frontmatter

Every page starts with a YAML frontmatter block:

```md [content/1.getting-started/1.introduction.md]
---
title: Introduction
description: What this project does and why it exists.
---

Welcome to the docs!
```

| Key                             | Purpose                                                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `title`                         | Page heading, sidebar label, browser title, and OG image title.                                                                |
| `description`                   | Rendered under the heading; used in search, `llms.txt`, meta tags, and OG images.                                              |
| `navigation`                    | `false` hides the page from the sidebar. An object overrides sidebar display: `navigation.title` sets a shorter sidebar label. |
| `seo.title` / `seo.description` | Override the meta tags without changing the visible heading.                                                                   |

<note>
Keep `description` to one sentence. It shows up in five places: the page header, search results, `llms.txt`, `<meta>` tags, and the generated OG image.
</note>

### Hiding a page

```md
---
title: Changelog
description: Internal draft, not ready yet.
navigation: false
---
```

The page still renders at its URL — it just doesn't appear in the sidebar or the prev/next links. The landing page uses this.

### Shorter sidebar labels

```md
---
title: Deploying to Vercel with instant content updates
navigation:
  title: Vercel
---
```

## Editing workflow

In development (`nuxt dev`), pages are read from your working tree and hot reload on save.

In production, pages are read from GitHub. Push a Markdown change to the production branch and it's live in seconds without a redeploy — see [Architecture](https://docs-template.comark.dev/concepts/architecture). Every page also gets an "Edit this page on GitHub" link in its aside, pointing at the file in your repository.

## Next steps

- [Markdown syntax](https://docs-template.comark.dev/writing/markdown) — everything you can write inside a page.
- [Components](https://docs-template.comark.dev/writing/components) — callouts, tabs, diagrams, and interactive embeds.


## Sitemap

See the full [sitemap](https://docs-template.comark.dev/sitemap.md) for all pages.