Markdown in 10 minutes

When you write a letter by hand, you underline the title and put dots before list items. Markdown does the same with keyboard characters. HERON reads those characters and turns them into real headings, lists and links on the site.

You never write HTML. You write text that is easy to read even before it becomes a page.

When you need this page: before you write or change your first page. When you can skip it: if you already write in Markdown; jump to the HERON part.

A paragraph is one or more lines of text. An empty line between two blocks of text makes two paragraphs. A single line break inside a paragraph is ignored, so you can wrap long sentences however you like.

This is the first paragraph.
It continues on this line.

This is the second paragraph.

The most common beginner mistake is forgetting the empty line before a list or a heading. When something looks glued together on the page, add an empty line.

A bullet list: each line starts with a dash and a space. A numbered list: a number, a dot and a space. Keep an empty line before and after the list.

What you get:

- a sitemap for search engines
- pages in two languages
- photos in every size

How to start:

1. Install Docker.
2. Create the site.
3. Open it in the browser.

In HERON a list item that starts with a bold phrase and a full stop is special: - **Sitemap.** Every page with its date. The bold part becomes a term the theme can show apart. See Section forms.

A link is the text in square brackets, then the address in round brackets. For pages of your own site write the address from the root, without the language: HERON picks the right language version itself.

Read the [first site guide](/docs/first-site/) or visit [GitHub](https://github.com/FMSTM/HERON).

A picture is the same with an exclamation mark in front. The text in square brackets describes the picture for people who cannot see it and for search engines. Put the photo in the media/ folder and refer to it from there.

![A heron standing in shallow water](media/examples/photo.jpg)

HERON makes light copies of the photo in several sizes, so it loads fast on a phone.

A word in backticks shows as code: site.yaml, heron build. A whole command goes into a block: three backticks on the line before and after it, with the language name after the first three.

```bash
heron build . --env prod --strict
```

On the site a code block gets a Copy button.

Columns are separated with a vertical line |. The second line, made of dashes, separates the header from the rows.

| Plan | Price |
|---|---|
| Basic | Free |
| Team | By request |

You do not need to line the columns up. HERON reads them anyway.

A HERON page has two parts. At the top, between two lines of three dashes, are the settings (called front matter): what search engines show, the heading, the short description. Below them is the text, split into sections.

---
title: "Dental clinic in Vienna: treatment and prices"
h1: "Your smile, our care"
description: "Treatment, implants and cleaning in Vienna. Prices, team and online booking."
---

A short introduction: two or three sentences under the heading.

## Our services {#services}

### Cleaning
Twice a year keeps your teeth healthy.

- **Takes.** 45 minutes.
- **Price.** From 90 euros.

### Implants
A new tooth that looks and works like your own.

- **Takes.** Two visits.

## Questions {#faq}

### Does it hurt?
No. We use local anaesthesia.

What happens to it:

• title goes to the browser tab and to the search result. Up to 60 characters.
• h1 is the big heading on the page. It is for people who already opened the page, so it can differ from title.
• description is the line under the search result. Up to 155 characters.
• The text before the first ## becomes the introduction under the heading.
• ## Our services {#services} starts a section. The words are the heading people see. The part in curly brackets, the anchor, is the section's name for the theme and for links like #services. Use small Latin letters, digits and dashes.
• ### groups with lists become cards; ### without lists under {#faq} become questions and answers, and search engines get them as FAQ data.

How each kind of section is drawn, with live examples, is on Section forms. All fields of the settings block are in Page format.