HTML to clean Markdown optimized for LLMs. One function: HTML in, token-efficient Markdown out.

Replaces the common @mozilla/readability + turndown two-package setup with a single dependency.

# JSR (recommended)
npx jsr add @zcag/readdown

# npm (from GitHub)
npm install github:zcag/readdown

import { readdown } from 'readdown';

const html = await fetch('https://example.com/article').then(r => r.text());
const result = readdown(html, { url: 'https://example.com/article' });

console.log(result.markdown);  // Clean markdown
console.log(result.tokens);    // ~1,250
console.log(result.metadata);  // { title, author, date, ... }

# Install globally
npx jsr add -g @zcag/readdown

# Convert a URL
readdown https://example.com/article

# Pipe HTML
curl -s https://example.com | readdown

# From file
cat page.html | readdown

1. Extracts main content — strips nav, sidebars, footers, ads (like @mozilla/readability)
2. Converts to Markdown — headings, lists, tables, code blocks, links, images (like turndown)
3. Estimates tokens — approximate token count + context window usage for GPT-4o, Claude, Gemini

All in one function call, one dependency.

Tested against real web pages (March 2026):

readdown wins on speed 4/5 pages and extracts more document structure (headings, code blocks) than alternatives. defuddle requires a browser DOM and produces broken output with server-side parsers like linkedom.

Run benchmarks yourself: node benchmark.js

• Headings (h1-h6)
• Paragraphs, line breaks, horizontal rules
• Bold, italic, strikethrough, inline code, ==highlights==
• Superscript (10^2^), subscript (H2O), abbreviations
• Links (with relative URL resolution)
• Images (with data-src lazy-loading fallback, spacer/tracking pixel filtering)
• Unordered, ordered, and nested lists (with proper indentation)
• Blockquotes
• Tables (data tables rendered, layout tables unwrapped)
• Code blocks (with language detection from language-*, lang-*, highlight-* classes)
• Definition lists (dl/dt/dd)
• <details>/<summary> (preserved as HTML)
• <figure>/<figcaption>

Returns ReaddownResult:

{
  markdown: string;       // Clean markdown output
  metadata: {             // Extracted from meta tags, JSON-LD, etc.
    title: string;
    author?: string;
    date?: string;
    description?: string;
    siteName?: string;
    url?: string;
    image?: string;
    lang?: string;
  };
  tokens: number;         // Approximate token count
  chars: number;          // Character count
  contextUsage: {         // % of context window used
    'gpt-4o': number;
    'claude-4': number;
    'gemini-2.5': number;
  };
}

Individual functions are exported for custom pipelines:

import { findMainContent, elementToMarkdown, extractMetadata, estimateTokens } from 'readdown';

- uses: zcag/[email protected]
  with:
    url: 'https://example.com/article'

MIT