Overview
Introduction
Comments often carry the most important context in a config file, why a value is set the way it is, a TODO, a warning about a workaround, but they're invisible to every tool that works with parsed YAML, since comments simply don't exist once a document is parsed. This tool reads the raw text instead, specifically to recover them.
It's the direct complement to this site's other parse-based tools: where those tools necessarily drop comments as a side effect of parsing, this one exists purely to surface them.
What Is YAML Comment Extractor?
A YAML comment extractor scans source text line by line, looking for a `#` character that starts a comment (as opposed to one that's part of a quoted string or glued onto a value with no preceding whitespace), and collects the text that follows it on each line.
Both full-line comments (where the `#` is the first character) and trailing inline comments (where the `#` follows a value on the same line) are captured, in the order they appear in the document.
How YAML Comment Extractor Works
Each line is scanned character by character, tracking whether the scan is currently inside a single- or double-quoted string. A `#` is only treated as a comment marker when it's outside any string and is either the first character of the line or immediately preceded by whitespace, the same rule YAML's own spec uses to distinguish a comment from a `#` that's just part of a value (like a URL fragment).
Everything after a recognized comment marker, trimmed of leading whitespace, becomes one entry in the output list.
When To Use YAML Comment Extractor
Use it before running a YAML file through any tool that reformats or re-serializes it, to capture the comments' content somewhere before they're inevitably dropped.
It's also useful for auditing a large config for TODOs, warnings, or undocumented assumptions left in comments.
Often used alongside YAML Comment Remover, YAML Formatter & Prettifier and YAML Value Extractor.
Features
Advantages
- Recovers information (comment text) that every parse-based YAML tool necessarily discards.
- Distinguishes real comments from `#` characters inside quoted strings or glued onto values.
- Captures both full-line and trailing inline comments in one pass.
- Runs entirely client-side as plain text processing, so file contents never leave your browser.
Limitations
- This is a line-based heuristic, not a full YAML parse, so it doesn't track quoted strings or block scalars that span multiple lines; a `#` inside such a value could be misread as a comment.
- It doesn't handle every YAML string-quoting edge case, like a doubled single-quote (`''`) representing an escaped quote inside a single-quoted string.
- Comment ordering reflects line order in the source, not any structural relationship to the surrounding YAML, there's no attempt to associate a comment with the specific key it was written next to.
Examples
Best Practices & Notes
Best Practices
- Run this before formatting or minifying a heavily-commented file, so you have a record of what the comments said.
- Review the output for TODOs or warnings when inheriting an unfamiliar config from another team.
- Treat results involving multi-line quoted values with extra scrutiny, this heuristic's known blind spot.
Developer Notes
Unlike every other tool in this category, this one deliberately avoids `parseYaml`, since the whole point is to recover something the parser discards. The quote-tracking scan resets at the start of every line (no cross-line string tracking), which is the source of the documented multi-line limitation; a full fix would require a proper YAML tokenizer rather than a line-oriented heuristic.
YAML Comment Extractor Use Cases
- Preserving comment content before reformatting or minifying a YAML file
- Auditing a large or inherited config for TODOs, warnings, or undocumented assumptions
- Reviewing what context previous authors left behind before making changes
- Building a changelog or documentation snippet from comments scattered across a config
Common Mistakes
- Assuming this tool performs a full YAML parse, it doesn't; it's a text scan specifically because parsing would discard the comments it's trying to find.
- Expecting comments inside multi-line quoted or block scalar values to be handled perfectly, that's this heuristic's known limitation.
- Forgetting that a # immediately after a non-space character (like `v1#build`) is correctly treated as part of the value, not a comment, matching YAML's own rule.
Tips
- Run this before Remove Comments from YAML if you want to keep a record of what's being stripped.
- Use the output as a quick TODO list when picking up an unfamiliar config for the first time.
- If a comment you expected is missing, check whether it sits inside a multi-line string value, this heuristic's documented blind spot.