mdtopdf.

Document field notes

YAML front matter in Markdown: name the PDF, show the context

How front matter becomes a printed properties panel, how its title names the downloaded PDF, and which fields you should never put there.

Published 2026-10-24 · Markdown to PDF editorial

YAML front matter looks like hidden metadata. In this converter it is not: the fields are rendered as a properties panel at the top of the document, and that panel is printed into the PDF. The same block also decides the downloaded filename. Both facts are useful — and both are easy to forget before sending a file.

What the converter documents

Markdown to PDF supports YAML front matter and shows it as a properties panel; its public product notes also state that the front matter's title names the PDF file. That is the product's own description. The checks below show what those two behaviours looked like in one browser session and one export on 24 October 2026.

A fixture with useful fields

---
title: Q4 Review Notes
author: Operations
date: 2026-10-24
tags:
  - review
  - q4
---

# Q4 review

The body starts here after the properties panel.

- One finding
- Another finding

Put the opening --- on the first line. If the block starts after a heading or a paragraph, it is no longer front matter; in the check, a block placed below an H1 was not parsed and no panel appeared.

What the checks showed

  • The panel is visible content. The preview rendered a card listing title, author, date and tags, and the exported PDF printed that card above the H1. Tags appeared as chips rather than as a comma-separated string.
  • The title named the file. The suggested download name was q4-review-notes.pdf. The browser tab title also took the form "Q4 Review Notes · MD to PDF".
  • Without a title, the first H1 was used. A document with no front matter downloaded as plain-document.pdf; a front matter block with author and date but no title downloaded as heading-fallback.pdf.
  • Punctuation was stripped from the filename. The title "Q4 / Review: Final Draft?" produced q4-review-final-draft.pdf — lowercased, spaces turned into hyphens, and the slash, colon and question mark removed.
  • The PDF's internal Title field was not set in this export. A PDF reader's document properties showed about:blank while the downloaded filename was correct. Treat the filename as the reliable output and check document properties separately if your archive depends on them.

Treat the block as visible document context

  1. Assume every field will be printed. The panel is not a private metadata store. Do not put internal ticket IDs, reviewer email addresses, draft markers, credentials or anything else you would not want on the first page.
  2. Keep the field list short. Title, author, date and a couple of tags are enough for most documents. A ten-field block pushes the actual content down the page and makes the PDF look like an export of a CMS record.
  3. Write a filename-friendly title. In the test, the filename came out lowercase and hyphenated. Avoid slashes, colons and question marks if the file will be shared or uploaded, and check the suggested name after export. Keep the title short enough to read in a file list.
  4. Decide how the title and the H1 relate. The title names the file; the H1 is the visible heading. Repeating the same words is fine. A title like "Q4 Review Notes" with an H1 like "Findings and decisions" is often clearer than duplicating both.
  5. Use tags for a few real categories. They render as chips and take horizontal space. A dozen tags will wrap and compete with the heading.
  6. Quote values that contain punctuation. Front matter is YAML; quoting a value makes its boundaries unambiguous. In the test, an unquoted colon inside the title was still parsed, but quoting is the safer habit when values contain punctuation.

Check the name and the first page

  1. Read the suggested filename before saving. If it is wrong, fix the title or the H1 and export again rather than renaming the file after the fact. A consistent name makes the next export predictable.
  2. Look at the printed panel. Confirm that every field is one you are willing to show the recipient, and that tags wrap without pushing the heading out of place.
  3. Check for duplicate titles. A front matter title plus an identical H1 can read as a repetition at the top of the page. One of them can usually be shorter.
  4. Open the PDF properties if the archive depends on metadata. Do not assume the filename is written into the document's internal Title field; in the tested export it was not.
  5. Keep a source copy without the front matter if the same text is also published on a web page where the properties panel would be redundant.

Diagnose front matter that did not apply

The block appears as text or horizontal rules
The opening --- is not on the first line, the closing delimiter is missing, or the block is indented. Move the whole block to the top and keep the delimiters on their own lines.
The filename ignores the title
The title may be missing, empty, or outside a parsed block. Check that the panel shows a title field; otherwise the first H1 becomes the fallback.
The filename contains odd punctuation
In the test, punctuation was stripped and spaces became hyphens. Rewrite the title with plain words, or accept the normalised name and check it before sending.
Private information appears on page one
Every field is printed. Remove the field from the front matter and keep that information in a separate internal note.
The PDF title properties are blank
The downloaded filename and the PDF's internal metadata are separate. Set archive metadata in the tool that manages the archive, or accept that only the filename carries the title here.

Delivery checklist

  • The opening --- is on line one and the closing delimiter is present.
  • Title is short, human-readable and filename-safe; the suggested filename was checked.
  • The H1 and the front matter title do not read as an accidental duplicate.
  • No internal IDs, private notes, credentials or personal contact details are in the block.
  • Tags are few enough to wrap cleanly above the heading.
  • The printed panel was reviewed on page one of the PDF.
  • Document properties were checked separately if the archive relies on them.

Sources and scope

Checked 24 October 2026. The workflow is editorial guidance. Observations come from one desktop browser session and a small set of one-page exports on that date; no cross-browser or PDF-archive audit is claimed.