Markdown, YAML, TOML & JSON

Skill level: Complete beginner · Time: 10 minutes

Kivo 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: "Introducing durable workflows"
date: 2026-10-06
draft: false
tags:
  - "workflows"
---

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

## A heading

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

YAML (Frontmatter)

title: "Deploy and scale"        # text: use quotes
enable: true                      # yes/no: true or false, no quotes
columns: 4                        # number: no quotes
primaryButton:                    # a group: the next lines are indented
  label: "Start for free"
  url: "/pricing/"
rotatingWords:                    # a list: each item starts with "- "
  - "web apps"
  - "AI agents"

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. Kivo’s comments explain the options, so leave them.
• Keys are case-sensitive. metaTitle works, metatitle does not, and a misspelled key is silently ignored.

TOML (config.toml)

[site]                              # a table: the lines below belong to it
  title   = "Kivo"                  # text in quotes
  trailingSlash = true              # true or false
[seo]
  keywords = ["saas", "astro"]      # 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.

JSON (Menus, Fonts, Languages, Translations)

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

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/homepage/english/-index.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, contact, FAQ, and pricing files have none, so after editing them, look at the page to check the result.