Back to Docs

Front Matter

Learn how to use YAML front matter to add metadata and customize your documents.

What is Front Matter?

Front matter is a way to add metadata to your documents using YAML syntax. It appears at the very beginning of your document, enclosed in triple dashes (---), and is not rendered as part of the visible content.

Front matter allows you to configure document settings, add metadata, and customize the appearance and behavior of your content without affecting the rendered output.

Basic Syntax

Front matter must:

  • Be at the very first line of your document
  • Start and end with --- on separate lines
  • Contain valid YAML syntax

Example

---
title: My Document
author: Jane Smith
date: 2024-12-10
---

# Your content starts here

Common Use Cases

1. Document Metadata

Add descriptive information about your document:

---
title: API Reference Guide
version: 2.1.0
author: Development Team
last_updated: 2024-12-10
status: published
---

2. Slideshow Configuration

Customize slideshow themes and transitions:

---
theme: professional
transition: fade
title: Product Launch 2024
author: Marketing Team
---

Available Themes: dark (default), light, minimal, professional
Available Transitions: slide (default), fade, none

3. Custom Properties

Define any custom metadata for your workflow:

---
status: draft
priority: high
tags: [documentation, tutorial]
reviewers:
  - alice@example.com
  - bob@example.com
---

YAML Syntax Basics

Simple Values

---
title: My Document
author: John Doe
version: 1.0
published: true
---

Lists

---
tags:
  - tutorial
  - beginner
  - markdown

# Or inline format:
tags: [tutorial, beginner, markdown]
---

Nested Objects

---
metadata:
  title: Advanced Guide
  author:
    name: Jane Smith
    email: jane@example.com
  version: 2.0
---

Slideshow Compatibility

Front matter works seamlessly with slideshows. The front matter block must be at the very beginning, before any slide content.

Correct Usage

---
theme: dark
transition: slide
---

# First Slide

Content for slide 1

---

# Second Slide

Content for slide 2

Important: The --- markers that separate slides are different from the front matter delimiters. MerDoc correctly distinguishes between front matter delimiters (at the document start) and slide separators (anywhere after the front matter).

Best Practices

  • Keep it simple - Only include metadata that's actually useful
  • Use consistent naming - Establish conventions for property names
  • Validate YAML - Ensure proper indentation (2 spaces) and syntax
  • Document your schema - If your team uses specific properties, document them
  • Include in templates - Add front matter to templates for consistency

Troubleshooting

Front Matter Appears as Content

Problem: You see the --- markers and YAML in your rendered document.

Solution: Ensure the front matter is at the very first line of the document with no spaces or content before it.

Invalid YAML Errors

Problem: Your front matter isn't being parsed correctly.

Solution: Validate your YAML syntax:

  • Use proper indentation (2 spaces)
  • Quote strings with special characters
  • Ensure colons have a space after them

Example - Wrong vs. Correct

# ❌ Wrong
---
title:My Document
tags:[one,two,three]
---

# ✅ Correct
---
title: My Document
tags: [one, two, three]
---

Related Documentation