---
layout: 'page'
uri: '/getting-started/markdown-frontmatter'
position: 1
slug: 'getting-started-markdown-frontmatter'
parent: 'getting-started'
navTitle: 'Frontmatter guide'
title: 'Frontmatter guide'
description: 'Complete guide to frontmatter metadata fields in Documan markdown files for navigation and layout.'
---

# Frontmatter guide

## What is Frontmatter?

Frontmatter is a section at the top of your Markdown file, enclosed between `---` delimiters, containing key-value pairs that configure the page:

```markdown
---
layout: 'page'
uri: '/getting-started/installation'
slug: 'getting-started-installation'
parent: 'getting-started'
position: 2
navTitle: 'Installation'
title: 'Installation guide'
description: 'Step-by-step guide to installing Documan.'
---

# Installation Guide

Your markdown content starts here...
```

## Required Fields

These fields are **required** for every Markdown file:

| Field    | Description                                    | Example                           |
|----------|------------------------------------------------|-----------------------------------|
| `layout` | Page layout type (`page` or `list`)           | `layout: 'page'`                    |
| `uri`    | Unique URL path for the page                   | `uri: '/getting-started/install'`   |
| `slug`   | Unique identifier (generated from URI)         | `slug: 'getting-started-install'`   |
| `title`  | Page title (shown in browser tab and content)  | `title: 'Installation guide'`       |

**Note:** The homepage must use `uri: '/'` as its unique URL path.

## Optional Fields

These fields are **optional** but recommended:

| Field         | Description                                           | Example                                    |
|---------------|-------------------------------------------------------|--------------------------------------------|
| `parent`      | Slug of parent page (for navigation hierarchy)        | `parent: 'getting-started'`                  |
| `position`    | Sort order in navbar within parent (lower = higher)   | `position: 2`                              |
| `navTitle`    | Shorter title for navigation menu                     | `navTitle: 'Install'`                        |
| `description` | Page description and summary                          | `description: 'How to install Documan.'`     |

## Layout Types

### `layout: page`

Standard documentation page with markdown content.

```yaml
---
layout: 'page'
uri: '/api/endpoints'
slug: 'api-endpoints'
title: 'API endpoints'
---
```

### `layout: list`

Index/overview page that displays links to child pages. Typically used with `.list.md` files in directories.

```yaml
---
layout: 'list'
uri: '/getting-started'
slug: 'getting-started'
title: 'Getting started'
---
```

## Auto-fixing Frontmatter

If you have Markdown files without frontmatter or with inconsistent field order, use the `fix` command:

```bash
./documan fix
```

This command will:
- **Reorder** existing frontmatter fields to the standard order: `layout`, `uri`, `position`, `slug`, `parent`, `navTitle`, `title`, `description`
- **Generate missing** `slug` from the complete URI path (e.g., `/docs/api/auth` → `docs-api-auth`)
- **Generate missing** `uri` from the file path
- **Extract** `title` from the first H1 heading (or use filename as fallback)
- **Generate missing** `navTitle` from the filename (sentence case)
- **Set** `layout` to `list` for `.list.md` files, `page` for others
- **Preserve** all existing frontmatter values

**Note:** The `parent` field is **not** auto-generated. You must set it manually to create navigation hierarchies.

## Navigation Hierarchy

Use `parent` and `position` to build navigation hierarchies:

```markdown
<!-- getting-started/.list.md -->
---
layout: 'list'
uri: '/getting-started'
slug: 'getting-started'
position: 1
title: 'Getting started'
---

<!-- getting-started/installation.md -->
---
layout: 'page'
uri: '/getting-started/installation'
slug: 'getting-started-installation'
parent: 'getting-started'
position: 1
title: 'Installation guide'
---

<!-- getting-started/configuration.md -->
---
layout: 'page'
uri: '/getting-started/configuration'
slug: 'getting-started-configuration'
parent: 'getting-started'
position: 2
title: 'Configuration'
---
```

This creates a navigation structure where "Installation guide" appears before "Configuration" under the "Getting started" section.

## Quoting Values

Always wrap string values in single quotes to avoid YAML parsing issues with special characters:

```yaml
# Correct - values in single quotes
title: 'My Guide: Getting Started'
description: 'Learn how to use Documan''s features'

# Incorrect - will cause YAML parsing errors
title: My Guide: Getting Started      # colon breaks parsing
description: Learn how to use Documan's features  # apostrophe breaks parsing
```

**Special characters that require quoting:**
- Colons (`:`) - interpreted as key-value separator
- Apostrophes (`'`) - escape by doubling: `''`
- Hash (`#`) - interpreted as comment
- Square brackets (`[]`) and curly braces (`{}`) - interpreted as YAML arrays/objects

**Note:** Numeric values like `position: 1` don't need quotes.

## Best Practices

1. **Always quote string values** - Use single quotes around all string values to prevent YAML parsing issues
2. **Use the `fix` command** - Run `./documan fix` to automatically reorder existing frontmatter fields and generate missing ones
3. **Keep slugs unique** - The slug field should be globally unique across all documentation
4. **Use URI for uniqueness** - Generate slugs from the complete URI path to ensure uniqueness (e.g., `docs-api-auth`, not just `auth`)
5. **Use `.list.md` for sections** - Create `.list.md` files in directories that contain multiple pages
6. **Set positions strategically** - Use increments of 10 (10, 20, 30) to leave room for inserting pages later
7. **Write clear descriptions** - The description field is used for page summaries and search results
8. **Parent references must exist** - The `parent` field must reference an existing page's `slug`

## Field Order

While field order doesn't affect functionality, we recommend this order for consistency:

```yaml
layout: 'page'
uri: '/path/to/page'
position: 1
slug: 'unique-slug'
parent: 'parent-slug'
navTitle: 'Short Title'
title: 'Full Page Title'
description: 'Page description and summary.'
```

---

[← 📖 Getting started](/getting-started.md) | [Showcase →](/getting-started/markdown-showcase.md)