Basics · 2

Text editor

A text editor is where you change the words on your site. This page installs one, opens the site folder in it and shows how to find a page, preview it and save.

Five minutes, no settings to learn. Any editor works; we use VS Code in the examples because it is free and the same on macOS, Windows and Linux.

In plain words

Every page of a HERON site is a plain text file ending in .md. A text editor opens such files the way a notebook opens on a page. Unlike Word, it does not add hidden formatting: what you type is exactly what is saved, and HERON reads exactly that.

When you need this page: before you change your first page. When you can skip it: if you already have an editor you like. Notepad, TextEdit in plain-text mode, Sublime Text or Zed all work.

Install VS Code

1
Download

On code.visualstudio.com press the download button. The site picks the version for your system.
2
Install

macOS: open the downloaded file and drag Visual Studio Code into Applications. Windows: run the installer and tick "Add to PATH" and "Open with Code". Linux: install the .deb or .rpm package, or VS Code from your software centre.
3
Windows with WSL

Install the extension called WSL (from Microsoft) inside VS Code. It lets the editor open folders that live in Ubuntu, where your site will be.
4
Start it

You see a welcome tab. You can close it.

Open the site folder

From the menu

The simplest way, the same on every system.

Do: File → Open Folder, find your site folder (for example my-site), press Open.
See: The left panel shows the folders: content, media, theme and the file site.yaml.
Trust: VS Code may ask whether you trust the authors of the folder. It is your folder: answer Yes.

From the terminal

Faster once you are in the site folder.

Do: In the terminal, inside the site folder, type code . (a space and a dot: "this folder").
Windows: Run it in the Ubuntu terminal: the WSL extension opens the folder from Linux.
If "command not found": On macOS open VS Code, press Command, Shift and P, type shell command, choose Install 'code' command in PATH.

What you see in the folder

The same structure in every HERON site.

content/: Your pages. Inside is one folder per language of your site (for example en/); a site in one language has one such folder. One file is one page, index.md is the home page.
media/: Photos and other files for the pages.
site.yaml: The settings: name, domain, languages, contacts.
theme/: The look of the site. You do not need to touch it to write pages.

Change a page

1
Open the page

In the left panel open content, then the folder of your language, then index.md: the home page of your site. The file opens in the middle.
2
Find the text

At the top, between two lines of three dashes, are the page settings: title, h1, description. Below them is the text of the page.
3
Change a word

Edit the h1 line or any sentence below. Keep the quotes and the colon as they are.
4
Save

Command and S on macOS, Ctrl and S on Windows and Linux. A white dot on the tab means "not saved yet"; it disappears after saving.
5
Look at the result

If the preview heron serve is running, the browser page updates by itself after a second. See Get started.

Preview Markdown in the editor

Side by side

VS Code shows how the text will look, without HERON.

Do: With an .md file open press Command, K, then V on macOS, or Ctrl, K, then V on Windows and Linux.
See: The formatted text opens on the right and follows your typing.
Remember: This preview is plain Markdown. The real look with the theme, cards and tabs is at localhost:8000 when HERON runs.

Find any text in the whole site

Useful when you want to change a phrase that appears on several pages.

Do: Command, Shift and F (macOS) or Ctrl, Shift and F.
See: Every file and line with that text. Click a line to open it.

Useful extras

Optional, but they help.

Spell checking: The extension Code Spell Checker underlines typos. Add a dictionary for your language.
YAML: The extension YAML (from Red Hat) colours site.yaml and warns about a broken indent.
Word wrap: View → Word Wrap, so long paragraphs fit the window.

Questions

Can I write pages in Word or Google Docs?

Not directly: they save formatting that HERON does not read. Write the text there if you like, then paste it into the .md file as plain text and add the Markdown marks. Markdown in 10 minutes shows them.

I broke something in the file. How do I undo?

Command and Z or Ctrl and Z undoes step by step. If the site is in git, the editor's Source Control panel shows every change and lets you discard it. See Git and GitHub.

What do the three dashes at the top mean?

They frame the page settings: title for search engines, heading, description and others. Each line has a hint. The full list is in Page format.

What next?

Learn the few marks pages are written with: Markdown in 10 minutes.

Text editor

In plain words

Install VS Code

Download

Install

Windows with WSL

Start it