What counts as frontmatter?

A block of valid YAML fenced by two `---` lines at the very top of the document, the same convention Jekyll, Hugo, Astro, and most static site generators use for page metadata (title, date, tags, and so on). If your document doesn't start with one, the output simply omits the `frontmatter` key.

How is the heading outline structured?

As a nested YAML list under `headings`, where each entry has a `level` (1-6, matching the number of `#` characters) and `text`, and any headings at a deeper level become that entry's `children`. A `##` under a `#` becomes a child of it; two `##` headings in a row become siblings.

Does this parse the frontmatter's contents, or just copy it?

It parses the frontmatter as YAML (so malformed frontmatter is reported as an error) and re-serializes the resulting value, rather than copying the raw text verbatim. That means quoting style and key order can be normalized slightly, but the data itself is unchanged.

Markdown to YAML - Extract Frontmatter & Headings

Overview

Introduction

A Markdown document carries two kinds of structure most tools ignore: the YAML frontmatter block some static site generators prepend, and the implicit outline formed by its headings. Both are useful data on their own, for indexing, generating a table of contents, or feeding a build script, but neither is easy to pull out without writing a parser.

This tool extracts both into a single YAML document you can pipe into another script, commit as a generated index file, or just read directly.

What Is Markdown to YAML?

A structured-data extractor for Markdown: it reads a document's `---`-fenced frontmatter block (if present) and its heading hierarchy, and emits both as YAML rather than leaving them embedded in prose.

It's not a general Markdown-to-YAML body converter; paragraph and list content in the body isn't included, only the heading outline is, since that's the structural information YAML is actually good at representing.

How Markdown to YAML Works

Frontmatter is matched at the very top of the document (a `---` line, YAML content, then another `---` line) and parsed with the `yaml` package; if it fails to parse, that's reported as an error rather than silently dropped.

The heading outline reuses this category's Markdown Header Extractor logic (Markdown's lexer, not a regex, so a `#` inside a fenced code block is never mistaken for a heading) and rebuilds it into a nested `level`/`text`/`children` tree keyed by heading depth.

Both pieces are serialized together with the `yaml` package's block-style stringifier.

When To Use Markdown to YAML

Use it when you need a page's frontmatter as structured data outside its Markdown file, for a build script, a search index, or a content audit.

It's also useful for generating a quick table-of-contents outline for a long README or spec document without hand-transcribing every heading.

Often used alongside Markdown Header Extractor, Markdown to HTML Converter and Markdown Formatter & Pretty Printer.

Features

Advantages

Extracts both frontmatter and heading structure in one pass, instead of needing separate tools for each.
Uses a real Markdown lexer for heading detection, so headings inside fenced code blocks are never mistaken for real ones.
Runs entirely client-side; nothing you paste is uploaded anywhere.

Limitations

Only frontmatter and headings are extracted; body paragraphs, lists, and other content are not represented in the output.
Frontmatter must be valid YAML fenced by `---` lines at the very top of the document; TOML (`+++`) or JSON frontmatter variants aren't recognized.

Examples

Frontmatter plus a two-level heading outline

Input

---
title: Getting Started
date: 2026-01-05
---

# Getting Started

## Installation

## Usage

Output

frontmatter:
  title: Getting Started
  date: 2026-01-05T00:00:00.000Z
headings:
  - level: 1
    text: Getting Started
    children:
      - level: 2
        text: Installation
      - level: 2
        text: Usage

The frontmatter block is parsed and passed through, and the two H2 headings nest under the H1 as children since they're one level deeper.

Best Practices & Notes

Best Practices

Validate frontmatter YAML separately first if it came from a source you don't fully trust, since a single malformed line fails the whole extraction.
Use consistent heading depth (don't skip from H1 straight to H3) if you want the nested outline to reflect the document's real structure.
Pair this with Markdown Validator first if you're processing documents you didn't author yourself.

Developer Notes

Heading extraction deliberately reuses `extractMarkdownHeaders` from `extract-markdown-headers.ts` rather than re-walking `marked.lexer()`'s output a second time: that function's flat, indentation-encoded bullet list (`" ".repeat(depth - 1) + "- " + text`) is parsed back into a `level`/`text`/`children` tree by reading each line's indentation, so there's exactly one implementation of "what counts as a heading" across both tools.

Markdown to YAML Use Cases

Generating a table-of-contents data file from a long README or spec
Pulling a page's frontmatter metadata into a build script or content index
Auditing a batch of Markdown docs for consistent heading structure

Common Mistakes

Assuming TOML (`+++`) frontmatter is supported; only `---`-fenced YAML frontmatter is recognized.
Expecting body paragraphs or list content to appear in the output; only frontmatter and the heading outline are extracted.

Tips

If the output only has a `headings` key, that's expected for documents without a frontmatter block, it isn't an error.
Run Markdown Header Extractor on the body directly if you just want a flat outline, this tool's nested tree is more useful for headings with real hierarchy.

Markdown to YAML