In breve
JSON, YAML and Markdown are three plain-text formats you will run into constantly when building anything. JSON and YAML both store structured data like settings and lists, while Markdown is for writing formatted text such as documentation and notes. None of them are programming languages; they are just agreed ways to write information so that both people and programs can read it. Once you can recognise the three, most config files stop looking scary.
JSON: data for machines
JSON (JavaScript Object Notation) stores data as key and value pairs, with curly braces and quotes. It is everywhere: API responses, package files, app settings. It is strict, so a single missing comma or quote breaks it.
{
"name": "my-app",
"version": "1.0.0",
"private": true
}YAML: data for humans
YAML stores the same kind of data as JSON but uses indentation instead of braces, which makes it easier to read and write by hand. It is common in workflow and deployment config. The catch is that spacing matters: YAML uses spaces for indentation, never tabs.
name: my-app
version: 1.0.0
private: trueMarkdown: formatted writing
Markdown is for text, not data. You add simple symbols to plain text to mark headings, bold, lists and links, and it renders as nicely formatted content. This page, most READMEs, and AI agent instruction files like CLAUDE.md are all Markdown.
# A heading
Some **bold** text and a list:
- first item
- second itemHow to tell them apart
A quick rule of thumb settles most confusion. If you see curly braces and lots of quotes, it is JSON. If you see clean indentation with colons and no braces, it is YAML. If you see "#" headings and "-" bullets meant to be read by a human, it is Markdown. You do not have to write any of them perfectly by hand, because your AI agent generates and edits these files for you. What helps is recognising which is which, so when a tool asks for "a YAML config" or "a JSON file" you know what it expects and can spot an obvious mistake at a glance.