# Markdown, YAML, TOML & JSON

## Markdown, YAML, TOML & JSON

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

Givo 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: "What one $25 backpack holds"
date: 2026-09-05
author: "Peter Ansah"
categories: ["How we work"]
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: "Clean water wells"            # text: use quotes
featured: true                        # yes/no: true or false, no quotes
goal: 75000                           # number: no quotes, no "$" and no commas
deadline: 2027-04-30                  # a date: YYYY-MM-DD
button:                               # a group: the next lines are indented
  label: "Donate now"
  url: "/donate/"
oneTime: [25, 50, 100, 250, 500]      # a short list in square brackets
impact:                               # a long list: each item starts with "- "
  - amount: 30
    label: "a water filter for one family"
```

**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. Givo'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.
- **Amounts are plain numbers.** Write `75000`, not `"75000"`, `$75,000`, or `75,000`. The currency comes from the donate file.

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

  [organization.hours]              # a table inside [organization]
    mon = "09:00-17:00"
    sun = ""                        # empty text

[settings.colorScheme]
  default  = "light"
  switcher = true                   # true or false

[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": "Stories",
  "weight": 4,
  "url": "/blog/"
}
```

**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/causes/english/clean-water-wells.md`.
2. **The line number**, or the name of the field.
3. **What was expected**, for example "Expected number, received string" (you wrote `"75000"` instead of `75000`).

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:

- `[organization]`: a value in `[organization]` 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.
- `[donate]`: the donate files of your languages have different numbers.
- `[forms]` and `[site]`: a form address or the site URL is still a placeholder, or the donation form is not connected yet.

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