Can one Markdown file mix TOML and YAML front matter?

No. Pick one format per file. Hugo picks the format from the fence, so it reads a +++ block as TOML and a --- block as YAML.

Why does my TOML header appear as plain text?

The tool or viewer you are using may not read TOML. Jekyll's docs name YAML only, and Eleventy treats TOML as a format you add yourself. A header that a plain viewer does not understand may print as ordinary text.

Should I ask my agent to write TOML or YAML?

YAML, unless your site runs on Hugo and your team already uses TOML there. Of the three site tools here, Hugo alone reads TOML without extra setup. Have your agent follow the YAML quoting rules too.

TOML vs YAML front matter: how to tell them apart

Bobby Huang · 2026-10-20

TOML and YAML are two formats for the header that opens a Markdown file. YAML front matter is fenced with --- lines and writes each field as key: value. TOML front matter is fenced with +++ lines and writes each field as key = value, with text values in quotes and dates left bare. Hugo reads both, per its docs. Jekyll names YAML only, and Eleventy reads YAML by default. All three site tools named here read YAML, so it is the safer pick for agent-written headers.

Key takeaways

The fence tells you the format at once. Three dashes mean YAML. Three plus signs mean TOML.
Inside the fence, YAML uses a colon plus a space, and TOML uses an equals sign.
TOML requires quotes around every text value, while YAML often lets text go unquoted.
Hugo reads both formats, Jekyll names YAML only, and Eleventy needs a custom parser for TOML, per their docs.
Planned for Sashmark v1, which has not been released, is a Frontmatter Table that lists each YAML key next to its value.

Open enough Markdown files and you will meet two kinds of header. Some open with a row of three dashes. Others open with a row of three plus signs. Both hold the same sort of data about the file. They use different formats, and a tool built for one may fail on the other.

This post covers spotting each format, the site tools that read each one, and converting a small header. The YAML rules get their own full walk-through in our front matter guide.

A simple definition

Front matter means the block of fields on the first lines of a Markdown file, when the file has one. A one-page primer on the idea lives at what is front matter.

YAML and TOML are two text formats for writing those fields. Two --- lines fence YAML front matter. Two +++ lines fence TOML front matter. The file's body starts after the closing line in both cases.

TOML stands for "Tom's Obvious, Minimal Language." Its spec says every value must be one of its listed types.

The same header in both formats

This made-up header belongs to a note an agent wrote. In YAML it reads:

---
title: Billing page fixes
status: waiting
date: 2026-10-20
owner: Jane Doe
---

A tool that reads front matter is likely to keep these lines off the page. It keeps the four fields as data, and the page starts at the body.

Here is the same header in TOML:

+++
title = "Billing page fixes"
status = "waiting"
date = 2026-10-20
owner = "Jane Doe"
+++

A tool that reads TOML front matter gets the same four fields. The date stays a date, because TOML has its own date type and writes it without quotes.

How to tell them apart at a glance

Run these checks in order.

The first line. --- means YAML. +++ means TOML. Hugo makes the same check.
The separator. YAML puts a colon, then a space, after each key. TOML puts an equals sign between key and value.
The quotes. In TOML, every text value is in quotes. In YAML, text values often appear bare.

If you see --- on top but = signs inside, the header is broken. The fence says YAML and the lines say TOML, so a YAML parser will not find the fields you meant.

The rules that differ

Text values. The TOML spec says a value must be one of its listed types, and anything else is invalid. A bare word is not a type. So status = blocked is an error, and status = "blocked" is right. YAML treats status: blocked as text with no quotes needed. That freedom has a cost. A YAML value may become a number, a date or a true/false flag when you meant text. The YAML quoting guide walks through those traps.

Dates. TOML has four date and time types: offset date-time, local date-time, local date and local time. All four are written without quotes. Hugo's docs point out that TOML supports these unquoted date and time values.

Comments. In TOML, # starts a comment, unless it sits inside a quoted string. So title = "Step #2" keeps the whole title.

Case. Capital letters count in TOML keys, so Owner and owner do not match.

Groups of fields. YAML nests fields by indenting them under a parent key, so indentation matters. TOML groups fields under a header line in square brackets, such as [review]. A repeated list of groups uses double brackets, such as [[steps]].

Encoding. A TOML file must be valid UTF-8.

Which site tools read which

Support depends on the tool, not on Markdown itself. Here is what each tool's docs say, checked October 2026.

Hugo reads front matter in TOML, YAML or JSON. It picks the format from the delimiters. YAML goes between --- lines, TOML between +++ lines, and JSON is an object in curly braces.

Jekyll requires front matter to open the file, before anything else. It must be valid YAML between triple-dashed lines. Its docs name YAML only.

Eleventy reads YAML between --- lines by default. It also reads JSON when the opening line is ---json, and JavaScript when it is ---js. Its docs show TOML as an example of adding your own front matter format. So TOML in Eleventy takes custom setup and is not there out of the box.

Outside site tools, each viewer makes its own call. Some Markdown viewers know YAML headers. A viewer that does not know TOML may print the +++ block as ordinary lines above the body.

How to convert a small header

These steps cover a flat header with text and dates. Work on a copy first.

Swap the fences. Change both --- lines to +++ to go to TOML, or the reverse to go to YAML.
Swap the separators. Replace each : after a key with =. Going back, replace = with : .
Fix the text values. For TOML, wrap every text value in double quotes. For YAML, you can drop the quotes on plain text. Keep them on any value with : or # in it. A leading @, *, & or [ also calls for quotes.
Leave dates bare. A date like 2026-10-20 needs no quotes in TOML. In YAML, check how your tool wants dates before you decide.
Rework groups. A nested YAML block becomes a [name] header line in TOML, with its fields under it. If the header has many nested groups, convert by hand slowly or ask the agent to do it and then check.
Parse the result. Build the site or run the tool that reads the file. A clean build is the real test.

If your agent keeps rewriting a header, name the format in its instructions. Otherwise the next rewrite may switch it back.

Which one to pick for agent-written notes

For files your AI agents write, YAML is the safer default. Jekyll and Eleventy read it with no setup, and Hugo reads it too.

TOML's strict quoting helps in one way. A bare no is an error in TOML, so it cannot turn into false by accident. Text that looks like a number, such as a version "1.10", still needs quotes to stay text. If your site runs on Hugo and your team likes that strictness, TOML is a fair choice.

Whichever you pick, put it in writing. Your agent's instruction file is a good home for it, such as "Front matter is YAML between --- lines; quote text values." That keeps every new file the same.

Where Sashmark fits

Sashmark is meant to help you read and touch up the notes your agent leaves. It is in development and has not been released. The app itself has no AI features. One part planned for v1 is the Frontmatter Table. It is meant to turn a YAML front matter header into rows, one key and its value per row. See the planned features, the help pages and the roadmap for where each part stands.

To see what Sashmark is and follow along, visit sashmark.com.

Questions

Can one Markdown file mix TOML and YAML front matter?: No. Pick one format per file. Hugo picks the format from the fence, so it reads a +++ block as TOML and a --- block as YAML.
Why does my TOML header appear as plain text?: The tool or viewer you are using may not read TOML. Jekyll's docs name YAML only, and Eleventy treats TOML as a format you add yourself. A header that a plain viewer does not understand may print as ordinary text.
Should I ask my agent to write TOML or YAML?: YAML, unless your site runs on Hugo and your team already uses TOML there. Of the three site tools here, Hugo alone reads TOML without extra setup. Have your agent follow the YAML quoting rules too.