The closer for the whole quest
You now know all four formats. The last skill is choosing well. The matrix below summarizes when each format wins.
Choose by audience and lifecycle
- Markdown — when the primary audience is a human reader, and the document is long enough that prose matters.
- JSON — when the primary audience is software, the medium is the network or storage, and machine round-trip is required.
- YAML — when humans edit the file, the structure is deeply nested, and indentation discipline is acceptable.
- TOML — when humans edit the file, the structure is shallow-to-medium, and clarity-per-line beats compactness.
Anti-patterns to avoid
- JSON for human config — no comments, trailing-comma traps, deep nesting reads like alphabet soup.
- YAML for the wire — slower to parse, indentation-sensitive across systems, security risks with unsafe parsers.
- TOML for deeply nested data — table headers stack up; YAML or JSON wins past 4 levels.
- Markdown for structured data alone — use front matter for the structure, body for prose. Don't try to encode tables-as-data in Markdown body alone.
The fluency you've earned
You read all four. You convert between them. You write JSON Schema once and validate everywhere. You spot the Norway problem at a glance, the trailing-comma trap, the YAML tab. You know when to reach for jq, when for yq, when for an MDX component. That is markup literacy.
Closing principle: formats are tools. The literacy is knowing which tool fits which job, and knowing how to translate when the wrong tool is in your hand. The four-format fluency you now carry will compound across every project — README, API spec, deploy manifest, build manifest, training data — for the rest of your career.