YAML to Markdown Converter
Paste YAML or upload a .yml file. Nested keys become headings, lists of objects become tables, anchors are expanded.
Markdown output will appear here...
To convert YAML to Markdown, paste the YAML (or upload a .yml file) into the box above and copy the result. Keys that hold a mapping become headings, plain settings become - **key:** value lines, lists of values become bullets, and a list of mappings becomes a table. Anchors and << merge keys are resolved first, so the output shows the values that actually apply.
What does the output look like?
A Docker Compose file
services:
web:
image: nginx:1.27
ports:
- "8080:80"
db:
image: postgres:16
environment:
POSTGRES_DB: app# services
## web
- **image:** nginx:1.27
### ports
- 8080:80
## db
- **image:** postgres:16
### environment
- **POSTGRES_DB:** appA list of CI steps becomes a table
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test
run: npm test# steps
| name | uses | run |
| --- | --- | --- |
| Checkout | actions/checkout@v4 | |
| Test | | npm test |Anchors and merge keys are expanded
defaults: &defaults
timeout: 30
retries: 3
prod:
<<: *defaults
retries: 5# defaults
- **timeout:** 30
- **retries:** 3
# prod
## <<
- **timeout:** 30
- **retries:** 3
- **retries:** 5What happens to anchors, aliases and merge keys?
They are expanded. An alias such as *defaults is replaced by the content of the anchor, and a <<: *defaults merge copies those keys in, with keys written in the block itself winning. In the third example, prod gets timeout: 30 from the anchor and keeps its own retries: 5. The anchor names themselves do not appear in the Markdown.
Can it convert a file with several documents (---)?
No. A file with more than one document, such as a Kubernetes manifest holding a Deployment and a Service, stops with the error "expected a single document in the stream". Paste one document at a time. A single --- at the very top is fine.
Which lists become tables?
A list becomes a table when its first item is a mapping. The columns are every key used by any item, and an item without a key gets an empty cell, like run and uses in the CI example.
Cells are meant for plain values. A nested list in a cell is joined with commas ([admin, ops] becomes admin,ops) and a nested mapping shows as [object Object]. For deeply nested lists, convert the same data as JSON with JSON to Markdown, which switches to sections instead of printing that.
Why did 1.10 turn into 1.1?
Because unquoted, 1.10 is a number in YAML, and the number 1.10 is 1.1. The same goes for 0800, which becomes 800. Quote values that must stay exactly as typed, such as version strings, ZIP codes and phone numbers: version: "1.10". Words like yes, no and on are kept as words, since the parser follows YAML 1.2.
How are dates, nulls, comments and other edge cases handled?
| Input | What you get |
|---|---|
| Unquoted date (released: 2024-01-15) | Kept exactly as written, as text |
| null, ~ or an empty value | Written as null |
| Comments (# ...) | Dropped |
| Multi-line block (note: |) | Lines kept, but they render as one paragraph in the list item |
| Pipe | in a table cell | Not escaped, so the cell splits into two |
| Line break in a table cell | Written as a real line break, which splits the row |
| Nested mapping in a table cell | [object Object] |
| List mixing plain values and mappings | Garbled: [object Object] in bullets, or one column per character. Keep list items the same kind |
| Tabs used for indentation | Error: YAML only allows spaces |
| More than six levels of nesting | Headings stop at ###### |
| Accents, CJK and emoji | Passed through unchanged |
How does this compare with Pandoc and yq?
| MDConvert (this page) | Pandoc | yq | |
|---|---|---|---|
| Turns a YAML file into Markdown content | Yes | No, YAML is read only as document metadata | No, it outputs YAML, JSON and other data formats |
| Expands anchors and merge keys | Yes | Not applicable | Yes, with explode() |
| Multiple documents per file | No | Not applicable | Yes |
| Install needed | No, runs in the browser | Yes, command-line program | Yes, command-line program |
| Batch / scripting | No, one file at a time | Yes | Yes |
yq is the tool for querying and reshaping YAML in a pipeline. This page is for getting a readable page out of a config file quickly.
Maintained by Ankit Aglawe. Last updated .
Related Tools
Need a different format? See every tool on the Markdown converter page, or go back to the MDConvert home page.