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.

---
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)

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`)

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

{
  "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.)

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/services/english/deep-cleaning.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. 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.

Markdown, YAML, TOML & JSON