formatYamlFrontmatter

Format YAML frontmatter using proper YAML formatting rules

Format YAML frontmatter using proper YAML formatting rules.

Options

Config

{
  "formatYamlFrontmatter": {
    "enabled": true,
    "indent": 2,
    "lineWidth": 80,
    "quotingType": "'",
    "forceQuotes": false,
    "noCompatMode": true
  }
}

Examples

Remove unnecessary quotes and extra blank lines

Before:

---
title: "Test Article"

description: "A long description"

tags:

  - tag1
  - tag2
---

# Content

After:

---
title: Test Article
description: A long description
tags:
  - tag1
  - tag2
---

# Content

Normalize inline arrays to block style

Before:

---
title:   "Article Title"
tags: [tag1, tag2, tag3]
---

After:

---
title: Article Title
tags:
  - tag1
  - tag2
  - tag3
---

Complex frontmatter

Before:

---
title:   "My Post"
date:  2024-01-15
author: "John Doe"
categories: [blog, tech]
draft:    false
---

After:

---
title: My Post
date: 2024-01-15
author: John Doe
categories:
  - blog
  - tech
draft: false
---

Unsafe Value Pre-processing

When fixUnsafeValues is enabled (default), the formatter pre-processes YAML values before parsing to prevent data corruption. Values containing : (colon-space), # (space-hash), or starting with special characters (!, &, *, %, @, backtick) are automatically wrapped in double quotes.

This prevents issues like:

• title: Acme: Best Products being parsed as nested YAML
• note: See section #3 being truncated at the # comment marker

Known Caveats

Date values lose quotes after formatting

When forceQuotes is false (the default), the formatter strips unnecessary quotes from string values. This means quoted date strings like "2024-08-03" become unquoted 2024-08-03.

Before:

---
createdAt: "2024-08-03"
---

After:

---
createdAt: 2024-08-03
---

The mdx-formatter itself handles this correctly — it uses JSON_SCHEMA internally, so the value stays as a string "2024-08-03" throughout the parse/dump cycle and is never converted to a JavaScript Date object.

However, downstream YAML parsers that use the default YAML schema (such as gray-matter) will parse unquoted 2024-08-03 as a JavaScript Date object instead of a string. This can cause runtime errors or unexpected behavior in frameworks that read frontmatter.

Workarounds:

• Set forceQuotes: true in the formatter config to keep all string values quoted
• Normalize date fields in your application code after parsing frontmatter (convert Date objects back to YYYY-MM-DD strings)
• Disable YAML formatting with formatYamlFrontmatter.enabled: false if the quote stripping causes issues