# Markdown, YAML, TOML & JSON

## Markdown, YAML, TOML & JSON

**Skill level:** Complete beginner · **Time:** 10 minutes

Homio 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: "Streak-free windows: what changes when a pro does it"
date: 2026-07-14
author: "Marco D."
categories: ["Cleaning tips"]
draft: false
---

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

## A heading
```

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

### YAML (Frontmatter)
```yaml
title: "Book one job or a whole list"   # text: use quotes
enable: true                            # yes/no: true or false, no quotes
discount: 15                            # number: no quotes
button:                                 # a group: the next lines are indented
  label: "Describe the job"
  url: "/contact/"
zips: ["55501", "55502"]                # a short list in square brackets
neighborhoods:                          # a long list: each item starts with "- "
  - "Harbor Point"
  - "Pier Row"
```

**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. Homio'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.
- **Postal codes are text.** Write `"02108"` in quotes, or a leading zero can be lost.

### TOML (`config.toml`)
```toml
[business]                          # a table: the lines below belong to it
  phone       = "+15550100199"      # text in quotes
  closedDates = ["2026-12-25"]      # a list in square brackets

  [business.hours]                  # a table inside [business]
    mon = "07:30-18:00"
    sun = ""                        # empty text

[settings.booking]
  checkArea   = true                # true or false
  minLeadDays = 1                   # a number

[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": "Pricing",
  "url": "/pricing/"
}
```

**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/services/english/deep-cleaning.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. Section files (`src/content/sections/`) and the contact page file (`src/content/contact/`) 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:

- `[business]`: a value in `[business]` could not be read (for example a phone number that isn't in `+15550100199` form, or hours that aren't `"HH:MM-HH:MM"`). That value is ignored.
- `[pricing]`: the English and French price files have different numbers.
- `[forms]` and `[site]`: a form address or the site URL is still a placeholder.

`[toml-watcher] ✖ Conversion failed` is printed in red: `config.toml` has a format mistake. The site keeps the last good settings until you fix it.