Markdown, YAML, TOML & JSON

Skill level: Complete beginner · Time: 10 minutes

Margo uses four text formats. They look different, but the rules are short, and almost every error comes from the same few mistakes.

Content Files: Frontmatter + Markdown

A content file has two parts. The frontmatter at the top, between two --- lines, holds settings in YAML. The body below it is Markdown text.

---
title: "How I price a project"
description: "Fixed prices with a written scope."
image: "/images/blog/desk-paper.jpg"
date: 2026-08-18
author: "Hugo Merrin"
categories:
  - Business
draft: false
---

This is the body. It is written in **Markdown**.

## A heading

Section files, project files, and most page files are frontmatter only: everything is a setting, and there is no body.

YAML (Frontmatter)

title: "Brands that\nsell the *craft*."   # text: use quotes
enable: true                            # yes/no: true or false, no quotes
weight: 1                               # number: no quotes
availability:                           # a group: the next lines are indented
  enable: true
  label: "Taking two new projects in November"
services: ["Brand identity", "Packaging"]  # a short list in square brackets
metrics:                                # a long list: each item starts with "- "
  - value: "40"
    label: "Glazes on one layout"
  - value: "6"
    label: "Vessel shapes"

The rules

Indent with 2 spaces. Never tabs. Items inside a group are indented 2 spaces more than the group’s name.
Put text in quotes, especially when it contains :, #, ', or starts with a special character.
A # starts a comment. Everything after it on the line is ignored. Margo’s comments explain the options and list the allowed values, so leave them.
Keys are case-sensitive. metaTitle works, metatitle does not, and a misspelled key is silently ignored.
Numbers you show as text stay in quotes. Write year: "2025" and value: "40", as in the sample files.

TOML (`config.toml`)

[site]                              # a table: the lines below belong to it
  title    = "Margo"                # text in quotes
  logoText = "Margo"

[settings.layout]                   # a table inside [settings]
  header = "bar"
  frame  = true                     # true or false

[settings.multilingual]
  disableLanguages = [""]           # a list in square brackets

[head]
  content = """
  <script></script>
  """                               # multi-line text between triple quotes

The rules: key = value, text in quotes, one key per line, and a key belongs to the [table] above it. Indentation doesn’t matter in TOML, but keep it tidy. A key under the wrong table is ignored, so check which [table] line is above the key you edit.

{
  "enable": true,
  "name": "About",
  "url": "/about/"
}

The rules

Keys and text values use double quotes.
Items are separated by commas, and the last item has no comma.
Every { has a matching } and every [ a matching ].
No comments allowed. (The "_comment" keys in src/i18n/en.json are ordinary values used as notes.)

Reading An Error Message

When a file has a mistake, the terminal running npm run dev (and the browser) shows an error. Look for three things:

The file path, for example src/content/projects/english/ceramic-forms.md.
The line number, or the name of the field.
What was expected, for example “Expected boolean, received string” (you wrote "true" instead of true).

Fix that line and save. If the message is unclear, copy the whole error into your AI assistant and ask it to explain and fix it.

A broken format (bad indentation, a missing quote or comma) shows an error in any file. A wrong value, such as "true" instead of true or a misspelled layout name, is only reported in files that have a schema. The files in src/content/sections/, src/content/contact/, src/content/faq/, and src/content/pricing/ have none, so after editing them, look at the page to check the result.

Some mistakes print a yellow warning instead of an error, and the site still builds:

[forms]: a form still posts to a placeholder address.
[site]: the site URL is still the placeholder https://example.com.

[toml-watcher] ✖ Conversion failed is printed in red: config.toml has a format mistake. While npm run dev is running, the site keeps the last good settings until you fix it.

Markdown, YAML, TOML & JSON