# Markdown, YAML, TOML & JSON

## Markdown, YAML, TOML & JSON

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

Taskly 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: "The two-list method for a calmer workday"
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)
```yaml
title: "Pricing that grows"      # text: use quotes
enable: true                      # yes/no: true or false, no quotes
days: 31                          # number: no quotes
button:                           # a group: the next lines are indented
  label: "Start for free"
  url: "/pricing/"
notes:                            # a list: each item starts with "- "
  - "Drag tasks between days"
  - "Every deadline this week"
```

**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. Taskly'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`)
```toml
[site]                              # a table: the lines below belong to it
  title   = "Taskly"                  # 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)
```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.

<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/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 reported too: by `npm run astro-check` in page files, and by `npm run dev` when the page opens for section files. A misspelled **key** is never reported, it is just ignored, so after editing, look at the page to check the result.