# Markdown and Front Matter

> How Markdown turns a few plain signs into headings, bold words and lists. How front matter puts the title and date of a page at the top.

**Course:** [JSON, YAML and File Formats](https://learn.benibix.com/learn/development-formats)  
**Time:** 11 min

**After this lesson you can:**

- Write a heading, bold text and a list in Markdown
- Add front matter to a Markdown file
- Write a short README

## How a few plain signs become a neat page

Markdown is a way to format text with plain signs. A # at the start of a line makes a heading, two stars around a word make it bold, and a dash starts a list item. It was made in 2004. The file stays easy to read as it is, and tools turn it into a neat page.

Markdown files end in .md, and they are plain text. You can read one in any editor, even before it is turned into a page. That is the point: the signs look like what they mean.

A space matters after the #. Many tools show #Title as plain text, but # Title as a heading. Two #s make a smaller heading, and three make a smaller one again. A blank line starts a new paragraph.

A README file is the front page of a project, and it is almost always written in Markdown, as README.md. GitHub shows it under the list of files. It says what the project does, how to install it and how to use it.

Front matter is a small block of settings at the very top of a text file. It sits between two lines of three dashes. Inside, it is usually written in YAML, with facts about the file like its title, date and tags. The rest of the file is the content people read.

Site builders and note apps read the front matter. A blog tool uses the title for the page heading and the date to sort the posts. The block itself is not shown on the page.

The common mistake is putting anything above the first three dashes, even a blank line. The front matter must be the very first thing in the file. If it is not, the tool shows the dashes and settings as plain text.

```markdown
---
title: My First Post
date: 2026-03-07
tags: [travel, food]
---

# My First Post

A short trip to **Lisbon**.

- Day 1: the old town
- Day 2: the beach
```
Front matter between the dashes, then a heading, bold text and a list in Markdown.

![A file called my-first-post.md. Its top part, lit up, sits between two lines of three dashes and holds a title, a date and tags. Below it come a heading and a line of text. An arrow from the top part leads to a box that says the site builder reads it for the page title, the date and tag links. An arrow from the rest leads to a box called the content.](https://learn.benibix.com/diagrams/dev2-front-matter.svg)

### Example: Emma's blog post has no title

Emma writes her 9th blog post, and the page shows three dashes and the words title: and date: at the top.

She sees a blank line above the first dashes. She deletes it, and the post shows its title and sorts by date like the other 8.

**Words in this lesson:** [Markdown](https://learn.benibix.com/term/development/markdown), [README File](https://learn.benibix.com/term/development/readme), [Front Matter](https://learn.benibix.com/term/development/front-matter)

**Question:** Where must front matter go in a Markdown file?

**Answer:** At the very top, with nothing above the first dashes. Tools only look for front matter at the very start. Even a blank line above it makes the tool show it as plain text.

---

Source: https://learn.benibix.com/learn/development-formats/markdown-and-front-matter
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
