Documentation

Installation

npm install defuddle

For Node.js use, install a DOM implementation:

npm install defuddle linkedom

Or JSDOM:

npm install defuddle jsdom

To use the CLI globally, install with -g, or use npx to run without installing globally:

# Install globallynpm install -g defuddle# Or use npxnpx defuddle parse https://example.com/article

Browser use

In the browser, create a Defuddle instance with a Document object and call parse().

import Defuddle from 'defuddle';const result = new Defuddle(document).parse();console.log(result.content);  // cleaned HTML stringconsole.log(result.title);    // page titleconsole.log(result.author);   // author name

You can also parse HTML strings using DOMParser:

const parser = new DOMParser();const doc = parser.parseFromString(htmlString, 'text/html');const result = new Defuddle(doc).parse();

Pass options as the second argument:

const result = new Defuddle(document, {  url: 'https://example.com/article',  debug: true}).parse();

Node.js use

The Node.js API accepts a DOM Document from any implementation (linkedom, JSDOM, happy-dom, etc.) and returns a promise.

import { parseHTML } from 'linkedom';import { Defuddle } from 'defuddle/node';const { document } = parseHTML(htmlString);const result = await Defuddle(document, 'https://example.com/article', {  markdown: true});

Or with JSDOM:

import { JSDOM } from 'jsdom';import { Defuddle } from 'defuddle/node';const dom = new JSDOM(htmlString, { url: 'https://example.com/article' });const result = await Defuddle(dom.window.document, 'https://example.com/article');

Note: For defuddle/node to import properly, your package.json must have "type": "module".

CLI use

Defuddle includes a CLI for parsing web pages from the terminal. You can run it with npx or install it globally with npm install -g defuddle.

# Parse a local HTML filenpx defuddle parse page.html# Parse a URLnpx defuddle parse https://example.com/article# Output as markdownnpx defuddle parse page.html --markdown# Output as JSON with metadatanpx defuddle parse page.html --json# Extract a specific propertynpx defuddle parse page.html --property title# Save output to a filenpx defuddle parse page.html --output result.html

CLI options

Using templates

Use Knap to format extracted content and metadata with a Markdown template. Pipe Defuddle's JSON output into Knap:

npx defuddle parse https://example.com/article --markdown --json \  | npx knap render template.md --data - --output note.md

Your template.md can reference Defuddle properties such as {{ title }} and {{ content }}. See the Knap CLI docs for a complete example.

API use

Use the hosted API to extract a web page without installing Defuddle. Append the page URL to https://defuddle.md/:

curl https://defuddle.md/stephango.com

The response is Markdown with YAML frontmatter containing page metadata. You can include the target URL's https:// prefix and path, for example https://defuddle.md/https://stephango.com/saw.

To return clean HTML instead, add /html/ before the target URL:

curl https://defuddle.md/html/stephango.com

For additional requests, buy a request block and pass your API key in the Authorization header. See pricing for request blocks, usage checks, and top-ups.

curl -H "Authorization: Bearer YOUR_KEY" https://defuddle.md/stephango.com

Options

Options can be passed when creating a Defuddle instance (browser) or as the third argument (Node.js).

Response

The parse() method returns an object with the following properties:

Bundles

Defuddle is available in three bundles:

The core bundle is recommended for most use cases.

HTML standardization

Defuddle standardizes HTML elements to provide a consistent input for downstream tools like Markdown converters.

Headings

• The first H1 or H2 is removed if it matches the title.
• H1s are converted to H2s.
• Anchor links in headings are removed.

Code blocks

Code blocks are standardized. Line numbers and syntax highlighting are removed, but the language is retained.

<pre>  <code data-lang="js" class="language-js">    // code  </code></pre>

Footnotes

Inline references and footnotes are converted to a standard format using sup, a, and an ordered list with class="footnote".

Math

Math elements, including MathJax and KaTeX, are converted to standard MathML with a data-latex attribute containing the original LaTeX source.

Callouts

Callout and alert elements from various sources are standardized to the Obsidian callout format. When converting to Markdown, these become Obsidian-style callouts.

Supported sources:

• GitHub markdown alerts (div.markdown-alert)
• Obsidian callouts (div.callout[data-callout])
• Callout asides (aside.callout-*)
• Bootstrap alerts (div.alert.alert-*)

<div data-callout="info" class="callout">  <div class="callout-title">    <div class="callout-title-inner">Info</div>  </div>  <div class="callout-content">    <p>This is an informational callout.</p>  </div></div>

Debugging

Debug mode

When debug mode is enabled:

• Returns a debug field in the response with detailed information about content extraction
• More verbose console logging about the parsing process
• Preserves HTML class and id attributes that are normally stripped
• Retains all data-* attributes
• Skips div flattening to preserve document structure

const result = new Defuddle(document, { debug: true }).parse();// CSS selector path of chosen main content elementconsole.log(result.debug.contentSelector);// Array of removed elements with step, reason, selector, and text previewconsole.log(result.debug.removals);

The debug field contains:

Each removal entry contains:

Pipeline toggles

Disable individual pipeline steps to diagnose content extraction issues:

// Skip content scoringconst result = new Defuddle(document, { removeLowScoring: false }).parse();// Skip hidden element removalconst result = new Defuddle(document, { removeHiddenElements: false }).parse();// Skip small image removalconst result = new Defuddle(document, { removeSmallImages: false }).parse();// Skip HTML standardizationconst result = new Defuddle(document, { standardize: false }).parse();

Content selector

Use contentSelector to bypass auto-detection and specify the main content element directly. Falls back to auto-detection if the selector doesn't match.

const result = new Defuddle(document, {  contentSelector: 'article.post-content'}).parse();