# Markdown, YAML, TOML & JSON

## 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.

```md
---
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)
```yaml
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`)
```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.

### JSON (Menus, Fonts, Languages, Social, Translations)
```json
{
  "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.)

<Aside type="tip">
  Most JSON errors are a missing or extra comma. VS Code underlines the
  problem in red; hover it to see the message.
</Aside>

### 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:

1. **The file path**, for example `src/content/projects/english/ceramic-forms.md`.
2. **The line number**, or the name of the field.
3. **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.