Frontmatter Reference

Complete reference of all frontmatter fields available for handbook pages.

What is Frontmatter?

Frontmatter is YAML-formatted metadata placed at the beginning of a Markdown file, enclosed by --- markers.

Syntax:

Required Fields

title

Type: String Required: Yes Description: The display name of the page shown in navigation and page header.

Example:

Rules:

  • Must be unique within the same section
  • Can contain spaces and special characters
  • Appears in browser tab and navigation

weight

Type: Integer Required: Yes (recommended) Description: Controls sort order in navigation. Lower values appear first.

Example:

Rules:

  • Can be any positive integer
  • Only affects order among sibling pages/sections
  • Pages without weight may appear in unpredictable order

Common values:

  • 1 - First item
  • 5, 10, 15 - Leaving gaps for future insertions
  • 100 - Last or lowest priority

type

Type: String Required: Yes Description: Defines the layout template for the page.

Example:

Allowed values:

  • docs - Standard documentation page (use this for all handbook pages)

Optional Fields

description

Type: String Required: No Description: Brief summary of page content used for SEO and previews.

Example:

Rules:

  • Recommended length: 50-160 characters
  • Should be descriptive and contain keywords
  • Used in search engine results
  • May appear in page summaries

prev

Type: String Required: No Description: Path to the previous page in navigation sequence.

Example:

Rules:

  • Path relative to content/ directory
  • Omit .md file extension
  • Auto-generated if not specified
  • Creates previous navigation link at bottom of page

next

Type: String Required: No Description: Path to the next page in navigation sequence.

Example:

Rules:

  • Path relative to content/ directory
  • Omit .md file extension
  • Auto-generated if not specified
  • Creates next navigation link at bottom of page

sidebar

Type: Object Required: No Description: Controls sidebar navigation behavior for this page/section.

Example:

Properties:

sidebar.open

Type: Boolean Default: false Description: Whether the sidebar section is expanded by default.

Values:

  • true - Section expanded, showing child pages
  • false - Section collapsed, hiding child pages

Usage:

draft

Type: Boolean Required: No Default: false Description: Marks page as draft. Visible in development, hidden in production.

Example:

Values:

  • true - Page is a draft (hidden in production builds)
  • false - Page is published (visible everywhere)

Use cases:

  • Work-in-progress content
  • Content pending review
  • Experimental pages

Complete Example: Section File

Complete Example: Page File

Complete Example: Minimal Page

Field Order Convention

While YAML doesn’t require a specific order, this convention improves readability:

Recommended order:

  1. title
  2. description
  3. weight
  4. type
  5. prev
  6. next
  7. sidebar
  8. draft

Value Types

String

Quoted or unquoted text.

Integer

Whole number without quotes.

Boolean

true or false without quotes.

Object

Nested key-value pairs.

Special Characters in Values

Quotes Required

Use quotes when value contains:

  • Colons (:)
  • Hash symbols (#)
  • Leading/trailing spaces
  • Special characters

Example:

Quotes Not Required

Simple text without special characters:

Validation Rules

Must Have

Every page must have:

  • title
  • type: docs

Should Have

Recommended for all pages:

  • weight

Optional

Use when needed:

  • description
  • prev/next
  • sidebar
  • draft

Common Mistakes

Missing Closing Dashes

❌ Incorrect:

✅ Correct:

Incorrect Indentation

❌ Incorrect:

✅ Correct:

Unquoted Special Characters

❌ Incorrect:

✅ Correct:

Wrong Type Values

❌ Incorrect:

✅ Correct:

See Also

Edit this page on GitLab ↗