Skip to content

YAML to Markdown Table Converter

Convert YAML to a Markdown table online, for free. This tool renders a YAML list of records — or a single mapping, from a .yaml or .yml file — as a clean Markdown table, ready to paste into a README, wiki page, or pull request description.

Drop your YAML file here

or

Supports .yaml and .yml files, processed entirely on your device

Untitled.yaml0 B0 lines0 characters
YAML →JSON
Your converted output will appear here.
Waiting for YAML input.

What to expect

  • A list of mappings becomes a table with one column per key.
  • A single mapping becomes a two-column Key / Value table.
  • Pipe characters and line breaks in values are automatically escaped.

Example

Input (YAML)
- name: Aperture Docs
  version: 1.4.2
  active: true
- name: Beacon CLI
  version: 0.9.0
  active: false
- name: Contour Sync
  version: 2.1.0
  active: true
Output (markdown)
| name | version | active |
| --- | --- | --- |
| Aperture Docs | 1.4.2 | true |
| Beacon CLI | 0.9.0 | false |
| Contour Sync | 2.1.0 | true |

Putting YAML data into Markdown tables

Documentation often needs to show structured data, such as a list of supported plugins, release notes, API parameters or environment variables, but typing a Markdown table by hand is fiddly. Every column has to line up, and a single missing pipe breaks the layout. If the data already exists as YAML, converting it produces a correct table in one step.

Markdown tables render on GitHub, GitLab, Docusaurus, MkDocs, Notion and most other documentation platforms. Pasting the generated table into a README, wiki page or pull request description keeps your docs in sync with the YAML that drives your project.

  • README and wiki tables

    Turn a YAML inventory of tools or services into a table for your project docs.

  • Changelogs and release notes

    Format a YAML list of changes into a scannable table.

  • Config reference pages

    Document option names, defaults and descriptions without hand-aligning columns.

  • Pull request summaries

    Paste a compact table of results or settings straight into a PR.

How YAML maps to Markdown Table

These are the exact rules this converter applies. Each result below was generated by the tool itself, so it matches what you will see in the output panel.

A list of mappings becomes a table

Each key is a column heading and each mapping is a row.

YAML
- tool: grep
  type: search
- tool: jq
  type: json
Markdown Table
| tool | type |
| --- | --- |
| grep | search |
| jq | json |

A single mapping is a Key / Value table

A lone mapping is shown as two columns listing each key and its value.

YAML
name: Beacon
version: 0.9.0
Markdown Table
| Key | Value |
| --- | --- |
| name | Beacon |
| version | 0.9.0 |

Pipes are escaped

A literal | would end the cell early, so it is written as \| instead.

YAML
- cmd: "a | b"
  use: pipe
Markdown Table
| cmd | use |
| --- | --- |
| a \| b | pipe |

Nested values show as JSON

Objects and lists inside a cell are written as compact JSON.

YAML
- name: app
  options: {color: true}
Markdown Table
| name | options |
| --- | --- |
| app | {"color":true} |

A trickier example: pipes, line breaks and missing fields

The first row has a pipe character in a flag value and a two-line description; the second row has a field the first one doesn't.

Input (YAML)
- tool: grep
  flags: "-i | -v"
  description: |
    Search text
    line by line
- tool: jq
  options: {color: true}
Output (Markdown Table)
| tool | flags | description | options |
| --- | --- | --- | --- |
| grep | -i \| -v | Search text<br>line by line<br> |  |
| jq |  |  | {"color":true} |

The pipe is escaped so it can't split the cell, the line break becomes an HTML <br> tag so the table stays on one row, and the columns from both records are combined, leaving blank cells where a record has no value.

Keeping a README table up to date

A simple pattern is to mark a region in your README and replace it whenever the YAML changes. This Python script swaps the content between two HTML comments:

python
import re
from pathlib import Path

readme = Path("README.md")
table = Path("tools-table.md").read_text(encoding="utf-8")

text = re.sub(
    r"(<!-- tools:start -->).*?(<!-- tools:end -->)",
    lambda m: f"{m.group(1)}\n{table}{m.group(2)}",
    readme.read_text(encoding="utf-8"),
    flags=re.S,
)
readme.write_text(text, encoding="utf-8")

YAML vs Markdown Table at a glance

A Markdown table is a presentation format, not a data format.

FeatureYAMLMarkdown Table
PurposeStore structured dataDisplay data to readers
NestingArbitrary depthFlat grid only
Machine readableYesOnly with extra parsing
Where it rendersNowhere; it is source dataGitHub, GitLab, docs sites
Cell contentAny valueText; pipes need escaping

Things to watch for when converting to Markdown Table

  • Deeply nested YAML does not become a nested table; inner structures are shown as JSON text inside a cell.
  • Very wide tables become hard to read on narrow screens, so keep the number of columns reasonable.
  • Line breaks inside values are written as <br>, which most (but not all) Markdown renderers accept.
  • Column alignment is not padded in the source; renderers handle the visual alignment.

YAML to Markdown Table Converter FAQ

What YAML structure produces the best table?

A flat list of mappings with consistent keys converts to the cleanest, most readable table.

Does it support GitHub-flavored Markdown?

Yes, the output uses standard GFM table syntax that renders on GitHub, GitLab, and most Markdown viewers.

Can nested values be shown in a cell?

Nested objects or arrays inside a cell are serialized as compact JSON so no data is lost.

Why do I see <br> in some cells?

Markdown table rows must stay on a single line, so line breaks inside a value are replaced with a <br> tag. GitHub and most renderers display that as a line break within the cell.

Will this work on GitHub?

Yes. The output uses standard pipe-table syntax with a header separator row, which GitHub-flavoured Markdown, GitLab and most documentation tools render as a table.

Can I align columns left or right?

The separator row uses plain dashes, giving default alignment. Add colons yourself (:---, ---:, :---:) after pasting if you want left, right or centred columns.

Is there a difference between .yml and .yaml?

No. ".yml" and ".yaml" are just two file extensions for the exact same format — this converter accepts either one, so a "yml to Markdown" conversion and a "yaml to Markdown" conversion produce identical results.

Related conversions

YAML to HTML Table

Need markup you can style yourself or use outside a Markdown renderer?

Try it

YAML to CSV

Want the same records in a spreadsheet instead of documentation?

Try it

YAML to JSON

Keep a machine-readable copy alongside the readable table.

Try it

Getting an error? Check your input with theYAML Validator, or tidy it first with theYAML Formatter. You can also browse all YAML converters.