Convert YAML & Frontmatter to Markdown
yaml to md with the input deciding the treatment: a config or manifest is parsed by js-yaml and re-rendered as nested bullet lists with bolded keys, while a file that opens with a --- frontmatter fence keeps that block verbatim and passes the Markdown body through untouched. Everything runs in a Web Worker on your own device — no upload, no signup.Processing happens 100% in your browser — nothing is uploaded.
How to convert YAML to Markdown
- Provide the YAML: drop a .yaml or .yml file onto the dropzone, or paste the document straight into the editor.
- Local processing: js-yaml parses the stream in a Web Worker, frontmatter is detected and preserved, and data documents are rendered as nested bullet lists.
- Copy or download: copy the Markdown to your clipboard or save it as a .md file for a runbook, a README or an Obsidian vault.
Why Convert YAML to Markdown with MD Convert?
Frontmatter preserved, not flattened
A Jekyll, Hugo or Obsidian note is detected by its opening --- fence and non-empty body: the YAML header is emitted verbatim between its fences and the Markdown after it is passed through unchanged, so the file stays a valid post. The header is test-parsed first, so a document that merely starts with a horizontal rule is not mistaken for frontmatter.
Hierarchy survives at two spaces per level
Mappings become `- **key**: value` bullets, and a mapping or sequence value becomes an indented block beneath its key. Two spaces per level is what CommonMark requires for a nested list item, so a deep Kubernetes or Ansible tree stays both readable and valid.
Multi-document streams handled per document
loadAll reads every document in a --- separated stream, and each one is converted independently and joined with a thematic break that mirrors the source marker. A warning reports the document count, so a manifest that unexpectedly holds one resource instead of five is immediately visible.
Timestamps and nulls rendered faithfully
js-yaml resolves the YAML timestamp type to a real Date; stringified naively that becomes a locale-specific string that no longer round-trips, so dates are emitted as ISO 8601. An explicit null is emitted as inline code rather than as nothing, keeping a key that exists with no value distinct from a key that was absent.
YAML to Markdown: Before and After
A data document becomes an indented bullet list with bolded keys: two spaces per nesting level, sequences as bullets in source order. The structure survives, so the reader can still see which key sits under which section.
service:
name: checkout-api
replicas: 3
ports:
- 8080
- 9090
healthcheck:
path: /healthz
timeout: 2s- **service**:
- **name**: checkout-api
- **replicas**: 3
- **ports**:
- 8080
- 9090
- **healthcheck**:
- **path**: /healthz
- **timeout**: 2sUnderstanding the YAML Format: YAML 1.2.2
- Format
- YAML Ain't Markup Language
- Specification
- YAML 1.2.2
- Media type
application/yaml- Parser used
- js-yaml
YAML 1.2.2 defines a data serialisation language whose types are mappings, sequences and scalars, expressed through significant indentation rather than delimiters. Since the 1.2 revision it is a strict superset of JSON, so anything expressible in JSON is expressible in YAML — plus comments, anchors and aliases, block scalars, explicit type tags, and multiple documents inside a single stream.
Two of those extras change what conversion can promise. Comments (`#`) are not part of the data model, so a parser that hands back a mapping has already discarded them; no tool that round-trips through a parsed object can preserve them. Anchors and aliases (`&base` / `*base`) are resolved at parse time, which means a merged block appears in the output with its values expanded in place rather than as a reference.
The parse itself is js-yaml, a mature JavaScript implementation loaded on demand into the page. `loadAll` is used rather than `load`, so a multi-document stream — the shape every `kubectl` manifest and Docker Compose override ships in — is read as the list of documents it actually is instead of failing on the second `---`.
Data documents versus frontmatter documents
The converter inspects the input before it renders anything, because `.yml` and `.yaml` cover two incompatible cases. If the file opens with a `---` fence, closes it, and has non-empty content after the closing fence, it is treated as a frontmatter document: the YAML header is emitted verbatim between its fences and the Markdown body after it is passed through completely untouched. Nothing is reformatted, so the file remains a valid Jekyll, Hugo or Obsidian note.
Everything else is treated as a data document and rendered as nested Markdown. That covers the manifests, playbooks, CI pipelines, OpenAPI fragments and lock files people actually paste in, where the YAML is the content rather than a header attached to content.
The frontmatter branch has one guard worth knowing about. A Markdown file whose first line happens to be a `---` horizontal rule would otherwise look exactly like an opening fence, so the candidate header is test-parsed as YAML first and the file only takes the frontmatter path if it parses. If it does not, the input falls through to normal data rendering rather than being silently mangled.
How mappings, sequences and scalars are rendered
Mappings become bullets with the key in bold: `- **key**: value` for a scalar, and `- **key**:` followed by an indented block when the value is itself a mapping or a sequence. Each nesting level adds exactly two spaces, which is the indentation CommonMark requires for a nested list item, so deep configuration trees stay legible and stay valid.
Sequences become bullet lists in source order. A sequence of scalars is a flat set of `-` bullets; a sequence whose items are themselves mappings emits a bare `-` for each item followed by that item's keys one level deeper, which keeps the boundary between list items visible instead of running them together.
Scalars are stringified with two deliberate exceptions. YAML has a real timestamp type, and js-yaml resolves it to a JavaScript `Date` — stringified naively that becomes a locale-flavoured string that no longer round-trips, so dates are emitted as ISO 8601 instead. An explicit `null` (or an empty value, which YAML also resolves to null) is emitted as inline code rather than as nothing, so a key that exists with no value stays visibly different from a key that was absent.
Multi-document streams, anchors and comments
A YAML stream can hold many documents separated by `---`, which is the normal shape of a multi-resource Kubernetes manifest. Each document is converted independently and the results are joined with a thematic break, mirroring the document marker in the source. A warning reports how many documents were found, so a manifest that unexpectedly contains one document rather than five is immediately obvious.
Anchors and aliases are resolved during the parse. If your file defines `&defaults` and merges it into three services with `<<: *defaults`, the output shows those values written out under each of the three services. That is the data the YAML actually describes — but if you were expecting to see the anchor itself, it is gone by the time rendering starts.
Comments are lost, and no parser-based tool can do otherwise. `#` comments live in the source text, not in the data model that a YAML parser returns, so once the document is loaded they no longer exist. If the comments are the documentation you wanted to keep, convert the file as plain text instead.
Config files that never leave the machine
Infrastructure YAML is among the most sensitive text a developer handles: a Compose file with database credentials, a CI pipeline with deploy keys, a values file naming internal hostnames. This converter reads the file with the FileReader API and parses it with js-yaml inside a Web Worker on your own device. There is no upload step, no server round trip and no account.
That is verifiable rather than a promise. Open the Network panel in DevTools, convert a file, and watch that no request is made — the only network activity on the page is the initial download of the page itself and the js-yaml chunk. Because the parse is local, conversion of a multi-thousand-line manifest completes in milliseconds and the file never exists anywhere but in your tab.
Running in a Worker rather than on the main thread matters for large inputs: a several-megabyte YAML file parses without freezing the interface, so the page stays responsive and the editor accepts input while the conversion finishes.
Known limitations of YAML to Markdown conversion
Being explicit about what a converter cannot do saves you a wasted upload. These are the boundaries of what is recoverable from YAML programmatically:
- Comments are discarded. A YAML parser returns the data model, and `#` comments are not part of it.
- Anchors and aliases are resolved, not preserved — merged values appear expanded in place at each use site.
- Sequences always render as bullet lists. There is no ordered-list output, because YAML sequences carry order but not numbering.
- Key order follows the source document. No sorting or schema normalisation is applied.
- Frontmatter is preserved verbatim only when there is a Markdown body after the closing fence. A file that is nothing but a fenced YAML document is treated as data and rendered as bullets.
- Block scalars (`|` and `>`) are resolved to their string value, so the folding style used in the source is not recoverable from the output.
Who Converts YAML to Markdown?
Platform & Ops Engineers
Turning a Kubernetes manifest, Compose file or Ansible playbook into a readable outline for a runbook or an architecture decision record.
Technical Writers
Documenting a configuration schema as a nested list, so readers can see which key nests under which section without reading raw YAML.
Jekyll & Hugo authors
Cleaning up a post's front matter without touching the Markdown body underneath it.
Obsidian & PKM users
Importing exported config or metadata into a vault as native Markdown that stays searchable and diff-able.
How You Can Verify the Privacy Claim
Zero server upload
Conversion runs inside your browser tab. Open DevTools, switch to the Network panel, and convert a file: for every format except URL to Markdown you will see no request carrying your document — because there is no endpoint to send it to.
Off the main thread
Heavy parsing is dispatched to a Web Worker, so a 500-page PDF or a large spreadsheet never freezes the interface. Everything is plain JavaScript — no native plugin, no WebAssembly toolchain, nothing to install.
Nothing to sign up for
No login, no quota, no paywall, and no tracking tied to your files. Analytics are cookieless and aggregate only. Read the privacy policy for the full data-flow breakdown, including the one proxied exception.
The parsers doing the work
No proprietary black box: each format is handled by a widely audited open-source library, running client-side at the version pinned in our lockfile.
YAML to Markdown — FAQ
Does it preserve Jekyll or Hugo frontmatter?
Yes. If the file opens with a --- fence, closes it, and has content after the closing fence, the YAML header is preserved verbatim and the Markdown body is passed through completely unchanged. The file remains a valid Jekyll, Hugo or Obsidian note. A file that is nothing but a fenced YAML document has no body, so it is treated as data and rendered as bullets instead.
What happens to comments in my YAML file?
They are lost, and no parser-based converter can do otherwise. A YAML parser returns the data model, and # comments are not part of it — they live only in the source text. If the comments were the documentation you wanted to keep, convert the file as plain text rather than as YAML.
How are anchors and aliases handled?
They are resolved during the parse, so the output shows the fully expanded values at each use site. If your file defines &defaults and merges it into three services with <<: *defaults, all three services show those values written out. The anchor itself no longer exists by the time rendering starts.
Can it convert a multi-document Kubernetes manifest?
Yes. loadAll reads every document in the stream, each is converted separately, and the results are joined with a thematic break that mirrors the --- separator in the source. A warning tells you how many documents were found so you can confirm nothing was missed.
Is my config file uploaded anywhere?
No. The file is read with the FileReader API and parsed by js-yaml in a Web Worker on your own device. This is deliberate for this format: Compose files, CI pipelines and values files routinely contain credentials and internal hostnames. Watch the Network panel in DevTools while converting — no request carries your data.