microsoft/vscode PR #320984 — HTML-to-Markdown converter migration — PR #320984
microsoft/vscode · pull request #320984 ·
Transcript
PlainEnglish
We're looking at pull request 320984, which migrates the HTML-to-Markdown converter from a regex-based implementation to a DOM-based one. This change touches nine files and delivers a more robust, maintainable solution while fixing a subtle bug along the way.
PlainEnglish
Let's map out what this pull request is pursuing. The primary goal is migrating the HTML-to-Markdown converter from regex-based to DOM-based parsing. Along the way, we're simplifying the conversion logic, fixing a bug in the large input fallback, adding a security exemption for DOMParser, and updating module load declarations. And importantly, we're preserving the existing security model and API contract — no breaking changes for consumers.
PlainEnglish
The original regex-based implementation was fragile. It relied on careful regex ordering, manual entity decoding, and lots of special-case handling for nested elements. By switching to a DOM-based approach, we leverage the browser's native HTML parser, which naturally handles all of those problems. It auto-decodes entities, gracefully repairs malformed HTML, and since this module is already consumed by browser-only chat input code, it's a perfect fit.
Architecture
Here's the change surface. The old regex-based implementation in base common is deleted, and a new DOM-based version lands in base browser. The test suite moves to match. There's one consumer, chatPasteProviders, which gets an updated import path. Four HTML templates get updated module load declarations, and we add a security exemption for DOMParser to the tsec config.
Architecture
Here's the core of the new implementation. We parse the HTML string into a DOM using DOMParser and a Trusted Types policy. Then we recursively walk the tree, pushing Markdown tokens as we encounter elements. Text nodes give us auto-decoded content via textContent. Links extract their href and wrap children in Markdown link syntax. And notice that large input fallback on line two — inputs over 200 kilobytes now correctly strip HTML tags before returning.
Architecture
The flow is straightforward. HTML arrives, DOMParser converts it to a proper DOM tree and auto-repairs any malformed structure. We walk the tree recursively, extracting text content which automatically decodes HTML entities. No manual regex juggling, no fragile ordering — the browser's parser does the heavy lifting for us. That's the simplification this refactor delivers.
Architecture
During the refactor, a bug was discovered in an intermediate commit. The large input fallback was returning raw HTML with tags intact, which could allow malicious inputs to bypass sanitization. The fix was simple — add the tag-stripping regex to match the original behavior. This correction landed in commit a69fd743, and the final PR head includes the fix.
Architecture
The new implementation uses DOMParser dot parseFromString, which is flagged by the tsec security linter. We add htmlToMarkdown to the exemptions list alongside other modules that use DOMParser safely. The Trusted Types policy on line seven of the implementation ensures we're handling the HTML string correctly before parsing.
PlainEnglish
After this PR lands, the HTML-to-Markdown converter will use DOM-based parsing instead of regex manipulation. The public API remains unchanged — consumers still call convertHtmlToMarkdown with an HTML string and get Markdown back. But under the hood, it's now more robust, maintainable, and correctly handles the large input edge case. The module moved from common to browser, but since chat paste is already browser-only, that has zero impact on builds or runtime.
CodeQuality
There's one thing worth noting. The large input fallback had a bug in an intermediate commit where it was returning raw HTML instead of stripping tags. That was caught and corrected in commit a69fd743, so the final head includes the fix. Very large malicious inputs now correctly get their tags stripped, matching the original implementation's behavior. Everything checked out across the 28 test cases.
PlainEnglish
That's pull request 320984. A focused refactor that replaces regex-based HTML parsing with DOM-based parsing. The converter is now more robust, easier to maintain, and correctly handles the large input edge case. The API stays the same, the security model is preserved, and all tests pass. A clean win for the codebase.
How this was made
Lenzon read microsoft/vscode at pull request #320984 and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it