Markdown basics

What Is Frontmatter in Markdown?
The --- block at the top

That block at the top of your .md file, fenced by two --- lines, is YAML frontmatter: metadata about the note, such as its title, tags, or date. It belongs to the file but not to the visible text. Tools that understand it read it or tuck it away; tools that do not simply show it as text. Neither is broken.

What it looks like

---
title: Reading list
tags: [books, 2026]
aliases: [to-read]
---

# The actual note starts here

The rules are small: the first --- must be the very first line of the file, the block ends at the second ---, and what sits between is YAML, plain key: value lines. Everything after the closing dashes is the normal Markdown note. That is the whole format.

Where these blocks come from

Frontmatter started with static site generators, which read fields like title and date to build pages. But the reason you are probably looking at one is closer to home:

  • Obsidian calls this block Properties. Every tag or alias you set in its Properties panel is stored as frontmatter in the .md file itself.
  • AI tools and agents often add a frontmatter block when they generate a note, putting the title, date, or tags where other software can find them.
  • Notes apps in general use it as the standard spot for metadata that has to live inside a plain text file.

That is the quiet strength of the format: the metadata travels inside the file, so nothing is lost when the file moves. It is a big part of why Obsidian notes stay portable.

Why it sometimes renders strangely

Frontmatter is a convention, not part of the CommonMark spec, so viewers disagree about what to do with it:

  • A viewer that knows the convention hides it or shows it as a neat properties area.
  • GitHub shows it as a small table above the content when you view a regular .md in a repo.
  • A viewer that does not know it shows the raw lines as text, and may even render the second --- as a horizontal rule, since that is what --- normally means mid-document.

So a "weird table", a stray divider line, or a chunk of key: value text at the top of someone else's file is not corruption. It is the same block, met by viewers with different opinions. The file itself is fine. The rest of the looks-unrendered family works the same way: first ask what the file really contains, then ask what the viewer does with it.

How NoteLoom handles it

NoteLoom treats frontmatter the Obsidian way, so the two can share a vault without translation. What you see depends on the view:

View What you see
Source Shows the raw YAML, dashes and all
Live (editing) Hidden; edit it through the properties panel instead
Reading Hidden; the note starts clean at your first heading

In live and reading views there is a properties button on the toolbar: it opens a small form for tags, aliases, and title, and writes your edits back into the frontmatter of the local file. In the source view the button is off, because you are already looking at the YAML. And if the YAML is broken, the panel shows a warning instead of letting a form edit overwrite your fields; you repair it in source.

Related reading

Are Obsidian notes just Markdown? Frontmatter is half of that answer: where Properties actually live. Markdown not rendering? The common gotchas The diagnostic hub for everything that looks broken but is not. How to make a horizontal line in Markdown What --- means in the middle of a document, and its traps. Taking notes with Markdown Where tags and properties fit once you write notes for real.

FAQ

Is frontmatter required in a Markdown file?
No. It is optional metadata. A .md file with no frontmatter is completely normal, and a file with it is still a plain text file. Tools that understand the block use it; tools that do not just treat it as text.
Why does my .md file show a table at the top on GitHub?
When a regular .md file in a repo starts with a frontmatter block, GitHub renders that block as a small table above the content. That is GitHub displaying the metadata, not a formatting error in your file.
Can I just delete the frontmatter block?
You can, and the note text below it is untouched. But the metadata goes with it: tags, aliases, and any properties another tool saved there. If the file came from Obsidian or a notes app, deleting the block deletes those properties.
Why do AI tools put frontmatter in the files they generate?
Because it is the standard place for machine-readable metadata in a Markdown file. An AI that writes a note with a title, date, or tags will often put them in a frontmatter block so other tools can pick them up. It is safe to keep.
What happens if the YAML inside is broken?
Tools that parse it will complain or fall back to plain text. NoteLoom, for example, shows a read-only warning in its properties panel and refuses form edits, so the broken fields are not overwritten; you fix the YAML by hand in the source view.
Is the frontmatter title the same as the # heading?
No, they are independent. The title: field is metadata that tools may display or index; the # heading is part of the visible note text. A file can have both, either, or neither.

See the block and the note it belongs to

Open your .md in NoteLoom in Chrome / Edge / Arc: reading view hides the frontmatter and starts at your first heading, source view shows the raw YAML, and the properties panel edits it without hand-writing a thing. Local file in, local file out.

Open NoteLoom and try it