--- title: "What front matter is and when you need it" author: Pedro Thomaz source: https://coffeetext.app/blog/what-is-front-matter --- # What front matter is and when you need it > Checked November 2026 against the [Jekyll](https://jekyllrb.com/docs/front-matter/), [Hugo](https://gohugo.io/content-management/front-matter/), [Obsidian](https://obsidian.md/help/properties) and [pandoc](https://pandoc.org/MANUAL.html) documentation and the [CommonMark spec](https://spec.commonmark.org/0.31.2/). Coffee isn't affiliated with any of them. Front matter is a block of data at the very top of a Markdown file, usually YAML between two lines of three dashes. It holds facts about the file, such as its title, date or tags, as opposed to the writing itself. You need it when a tool reads those facts, as a static site generator does. If your notes are only for you, you can happily do without it. ## What it looks like ``` --- title: Notes from the March meeting date: 2026-03-14 tags: [work, planning] --- # Notes from the March meeting ``` Each line is a name, a colon and a value. It isn't part of the Markdown language. [CommonMark](https://spec.commonmark.org/0.31.2/) doesn't mention it, so a tool either knows about front matter or doesn't. One that doesn't will take the first `---` as a divider and the closing `---` as the underline of a heading, and you'll see your data on the page as a big bold line. ## Who reads it **Static site generators.** This is where most people meet it. [Jekyll](https://jekyllrb.com/docs/front-matter/) treats any file with a front matter block as a special file to process, even if the block is empty, and reads values like `layout`, `permalink`, `published`, `date` and `tags`. [Hugo](https://gohugo.io/content-management/front-matter/) uses `title`, `date` and `draft`, among others, and accepts YAML between `---`, TOML between `+++`, or a JSON object. **Note apps.** [Obsidian](https://obsidian.md/help/properties) calls these properties and stores them as YAML at the top of the file, with `tags` and `aliases` among its defaults. **Converters.** [Pandoc](https://pandoc.org/MANUAL.html) reads a YAML metadata block and uses values like `title` and `author` in its output. So a `title` in the block saves you passing it on the command line when you [make an HTML page](https://coffeetext.app/blog/markdown-to-html-mac). **Scripts of your own.** Plain text at the top of a file is easy for a small script to read, so it's a common place to keep a status or a date. ## When you need it You need it if a tool you use asks for it, which usually means a site generator's template wants a `title` or `date`, or you want to tag notes in a way that travels between apps. You can skip it when none of that applies. A first-line heading names a note perfectly well, a file's name and dates are already on the disk, and adding fields no tool reads gives you upkeep with no return. It's easy to add later, one file or a whole folder at a time. ## Mistakes that break it **It isn't first.** [Jekyll](https://jekyllrb.com/docs/front-matter/) says the front matter must be the first thing in the file. A blank line or a stray character above the opening `---` is enough to stop it working there. Jekyll also warns against a byte order mark in UTF-8 files, which you can't see. **A colon in a value.** [Pandoc's manual](https://pandoc.org/MANUAL.html) notes that YAML's own rules apply, so a title containing a colon must be quoted: ``` title: "Coffee: a review" ``` **A blank line straight after the opening dashes.** Pandoc says the first `---` must not be followed by a blank line. **No closing line.** Without one, it isn't a block at all. **Different tools, different fields.** Each tool decides which names mean something. Jekyll's `published` and Hugo's `draft` do similar jobs under different names. A tool usually ignores what it doesn't recognise, so one file can carry fields for two tools. ## How Coffee handles it Coffee's handling is deliberately small. It hides the block in the page view, reads your tags from it, and leaves everything else alone. **What counts as front matter.** The first line must be exactly `---`, and a later line must be exactly `---`. If there's no closing line, the first `---` is shown as a divider, so a stray one can't make your whole note vanish. Pandoc's other closing form, `...`, isn't recognised, and neither are Hugo's `+++` and JSON forms, which appear as ordinary text. **Where you see it.** The page view hides the block completely, so a note opens on its first real line. Press ⌘/ to switch to the Markdown view, where it's visible and editable. **What Coffee reads.** Only `tags`, which it accepts in any of these forms: ``` tags: [work, planning] tags: work tags: - work - planning ``` **What it leaves alone.** Every other line stays exactly as you wrote it. Coffee doesn't check that your YAML is valid, so it won't warn you about an unquoted colon, and the tool that later reads the file may be the first to complain. A `title` field doesn't rename the note either. A note's title in Coffee comes from its file name. **Changing tags.** The Tags panel, under Tags in the Note menu, edits the tags for you. It writes them as `tags: [work, planning]` at the top of the block, creates the block if there isn't one, and removes it if the tags were all that it held. A tag list in the longer form is rewritten on one line when you do this. **Search.** Tags are indexed, but the other lines in the block aren't part of the searchable text, so searching for a word that appears only in a `date` or `author` field won't find the note. **Exports.** PDF, HTML and plain text exports leave the block out. A Markdown export keeps it, as that's simply the note's own text. Coffee's link updates also skip the block, so a `[[link]]` inside front matter isn't rewritten when a note is renamed. Since Coffee keeps every line, you can use it to edit files for Jekyll, Hugo or Obsidian. If you do, just remember that the block is hidden in the page view, so ⌘/ is how to check or change `date` and the rest. ## Questions ### Is front matter part of Markdown? No. Neither CommonMark nor GitHub Flavored Markdown's core rules define it. It's a convention that tools such as Jekyll, Hugo, Obsidian and pandoc have adopted, and each decides which fields it reads. ### Does front matter have to be YAML? Usually, but not always. Jekyll asks for valid YAML between triple dashes. Hugo also accepts TOML and JSON. Coffee recognises only the `---` form. ### Why does my front matter appear on the page? The tool you're viewing it in probably doesn't support it, or the block isn't the first thing in the file. Check for a blank line above the opening dashes. ### Does Coffee delete front matter? No. It hides the block in the page view and keeps every line in the file. When you change tags in the Tags panel, only the tags line is rewritten. --- Written by Pedro Thomaz, who makes Coffee, a Markdown editor for the Mac on macOS 15 or later. It's free for 14 days with no card or account, then €3 a month, €29 a year, or €79 once with two years of updates. More at https://coffeetext.app/llms-full.txt