NewMCP server 1.0.10What changed →

Blog

Convert HTML to Markdown in Node.js with Turndown

All posts
guidesmarkdownnode

Converting HTML to Markdown in Node.js takes two libraries, not one. Turndown converts HTML to Markdown, but given a whole page it faithfully converts the navigation, the adverts, the footer and even the text of inline scripts. Mozilla's Readability, the code behind Firefox's Reader View, finds the main content first. Together, with a DOM from jsdom and Turndown's GitHub-flavoured plugin for tables:

bash
npm install jsdom @mozilla/readability turndown turndown-plugin-gfm

Save this as to-markdown.mjs:

javascript
import { JSDOM } from "jsdom";
import { Readability } from "@mozilla/readability";
import TurndownService from "turndown";
import { gfm } from "turndown-plugin-gfm";

const url = process.argv[2] ?? "https://example.com";

const res = await fetch(url);
if (!res.ok) throw new Error(`${url} answered ${res.status}`);
const html = await res.text();

// The url option makes relative links and image paths absolute.
const { document } = new JSDOM(html, { url }).window;

// keepClasses preserves language-* on code blocks, which Turndown reads.
const article = new Readability(document, { keepClasses: true }).parse();
if (!article) throw new Error("No main content found");

const turndown = new TurndownService({
  headingStyle: "atx",
  codeBlockStyle: "fenced",
  bulletListMarker: "-",
});
turndown.use(gfm);

console.log(`# ${article.title}\n\n${turndown.turndown(article.content)}`);

Run it with a URL and redirect the output to a file:

bash
node to-markdown.mjs https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 > 429.md

Every script here was run with Node.js 24, jsdom 31, Readability 0.6 and Turndown 7.2, against live pages and a test page that wraps a short documentation article in a header, a navigation bar, a sidebar with an advert and a footer.

What comes out

For that test page, the output starts:

markdown
# Rate limits explained - Example Docs

Every API key has a request budget. When you exceed it, the API answers `429` and you should wait before retrying. ...

## How the budget works

... Read the [backoff guide](http://localhost:4321/guides/backoff) for a complete retry loop, and see the diagram below for how the bucket drains and refills.

![A token bucket draining and refilling](http://localhost:4321/docs/images/bucket.png)

| Plan | Requests per second | Burst |
| --- | --- | --- |
| Free | 2 | 5 |
| Pro | 10 | 20 |

The navigation, the advert, the sidebar links, the footer and its script are gone. The relative link ../guides/backoff and the image path images/bucket.png are now absolute, so the Markdown still works away from the site, and the code block further down keeps its language. The title comes from the page's title element, so it can carry a site name suffix you may want to trim.

The size difference is the point. Measured on November 19, 2026:

PageHTMLMarkdown
Wikipedia, Web scraping244,379 characters46,852 characters
MDN, 429 Too Many Requests209,262 characters2,465 characters

That is 5 times smaller for a long article and 85 times smaller for a short reference page, where most of the HTML is site furniture. If the Markdown is going into a language model, the token count falls by roughly the same factor.

Why each option is there

Each setting in the script fixes something the defaults get wrong:

  • The jsdom `url` option. Without it, links and images keep their relative paths, which point nowhere once the text leaves the site.
  • `keepClasses: true`. Readability strips class attributes by default, including the language-js class Turndown reads to label a fenced code block. Without it, the test page's code block came out as a bare fence with no language.
  • The `gfm` plugin. Turndown on its own has no Markdown table syntax. Without the plugin, the test page's table flattened into one cell per line: Plan, Requests per second, Burst, Free, 2, 5 and so on, which no reader can put back together.
  • `codeBlockStyle: "fenced"` and `headingStyle: "atx"`. Turndown defaults to indented code blocks and underlined headings. Fenced blocks and # headings are what most Markdown tools and language models expect.

Pages built with JavaScript

fetch returns the HTML the server sends. A page that builds its content in the browser sends little more than an empty div and a script, and on such a page the script above stops at "No main content found": Readability returns null when there is nothing to read. In the tests, it only did that on the client-rendered page. Even example.com, with a single paragraph, returned content.

For those pages, let a browser run the JavaScript and convert the DOM it builds. With Puppeteer (npm install puppeteer):

javascript
import puppeteer from "puppeteer";
import { JSDOM } from "jsdom";
import { Readability } from "@mozilla/readability";
import TurndownService from "turndown";
import { gfm } from "turndown-plugin-gfm";

const url = process.argv[2] ?? "https://example.com";

// Let the page run its JavaScript, then take the DOM it built.
const browser = await puppeteer.launch();
let html;
try {
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: "networkidle0" });
  html = await page.content();
} finally {
  await browser.close();
}

const { document } = new JSDOM(html, { url }).window;
const article = new Readability(document, { keepClasses: true }).parse();
if (!article) throw new Error("No main content found");

const turndown = new TurndownService({
  headingStyle: "atx",
  codeBlockStyle: "fenced",
  bulletListMarker: "-",
});
turndown.use(gfm);

console.log(`# ${article.title}\n\n${turndown.turndown(article.content)}`);

On a version of the test article that is rendered in the browser one second after load, where the fetch script found nothing, this produced the full article: headings, table, code block and links. networkidle0 waits until the page has had no open requests for half a second, which suits most pages; on a page that keeps a connection open, such as a chat widget, it never fires, so wait for an element instead.

Starting a browser costs far more than a fetch, so a pipeline over many pages usually tries fetch first and falls back to the browser only when the result comes back empty. Our JavaScript rendering checker shows which kind a given page is.

Without running either

The domscout /scrape endpoint returns the same kind of Markdown from one request, rendered in Chromium so JavaScript pages work too:

javascript
const res = await fetch("https://api.domscout.io/scrape", {
  method: "POST",
  headers: {
    "x-api-key": process.env.DOMSCOUT_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/docs/rate-limits" }),
});
if (!res.ok) throw new Error(`scrape failed: ${res.status} ${await res.text()}`);

const page = await res.json();
console.log(page.markdown);

It costs 1 credit and works on every plan, including the free one. Send renderJs: false to read the served HTML without a browser, or renderJs: "auto" to let the service start one only when the served HTML comes back thin. The free URL to Markdown tool converts a single page with no account.

Next steps