opensourceprojects.dev

A broadsheet for software that doesn't ask for your email

Extract web page content with a Readability alternative that keeps more of the p...
GitHub RepoViews24

Project Description

View on GitHub

Defuddle Wants to Keep More of the Page Than Readability Does

You've probably used a read-later tool or a web clipper and watched it quietly throw away half of what you wanted to save. Footnotes vanish, code blocks lose their formatting, math turns into gibberish. Mozilla Readability has been the default answer to this problem for years, but it errs on the side of caution—if it isn't sure an element belongs, out it goes. Defuddle is an alternative that takes the opposite approach: remove the obvious clutter, but be more forgiving about the elements it can't confidently classify.

What It Does

Defuddle extracts the main content from a web page. You hand it a URL or raw HTML, and it strips out comments, sidebars, headers, footers, and other non-essential elements, returning cleaned HTML or Markdown. The README defines the name plainly: to remove unnecessary elements from a web page and make it easily readable.

It was built for the Obsidian Web Clipper browser extension, but it's designed to run in any environment. You can use it in the browser against the current document, in Node.js against a DOM from JSDOM, linkedom, or happy-dom, or straight from the terminal via a CLI. The defuddle/node entry point accepts a Document from any DOM implementation, so you aren't locked into a particular parsing library.

Why It's Cool

It's explicitly positioned as a Readability replacement, with receipts. The README lists the differences rather than hand-waving at them, and a few of those differences are genuinely interesting design choices.

  • More forgiving. Defuddle removes fewer uncertain elements. If a parser is going to guess wrong, you'd usually rather it keep something you didn't need than delete something you did.
  • Consistent output for the tricky stuff. Footnotes, math, and code blocks get handled consistently rather than being at the mercy of whatever markup the site happens to use.
  • Mobile styles as a signal. This is the clever one. Defuddle uses a page's mobile styles to guess at which elements are unnecessary. Mobile layouts tend to strip things down aggressively, so the CSS is effectively doing some of the classification work for you.
  • More metadata. It pulls more metadata than Readability, including schema.org data. If you're building anything that cares about author, title, or structured page info, that's a meaningful difference.

The output options are practical too. You can get HTML, Markdown, or JSON with metadata, and the CLI supports YAML frontmatter—which is exactly what you'd want if you're piping clipped articles into a notes app like Obsidian.

One honest caveat, straight from the README: the project is very much a work in progress. Treat it accordingly.

How to Try It

The fastest way in is the CLI, no install required:

npx defuddle parse https://example.com/article

Want Markdown instead?

npx defuddle parse page.html --markdown

Or pipe HTML in from curl:

curl -L https://stephango.com/saw | npx defuddle parse --markdown

There's also a --json flag for metadata plus content, --frontmatter to prepend YAML, --property to pull a single field like the title, and --output to write to a file. If a site returns a 403 to the default user agent, there's a --user-agent flag for that.

For library use in the browser:

import Defuddle from 'defuddle';

const defuddle = new Defuddle(document);
const result = defuddle.parse();

console.log(result.content);
console.log(result.title);
console.log(result.author);

And in Node.js with linkedom:

import { parseHTML } from 'linkedom';
import { Defuddle } from 'defuddle/node';

const { document } = parseHTML(html);
const result = await Defuddle(document, 'https://example.com/article', {
  markdown: true
});

One gotcha worth flagging: for defuddle/node to import properly, your package.json needs { "type": "module" }.

You'll find the full docs and source at github.com/kepano/defuddle.

Final Thoughts

Defuddle is a young project, and the README says so upfront—which is refreshing. But the premise is sound: Readability's cautious deletion is a real annoyance for anyone archiving or clipping content, and being more forgiving while using mobile styles as a heuristic is a sensible way to attack it. If you're building a read-later tool, a web clipper, or any pipeline that turns messy pages into clean text, it's worth a look—especially if you've been burned by missing footnotes before. Just go in expecting a work in progress.


Follow @githubprojects for more developer tools and open source projects.

Back to Projects
Project ID: defuddleLast updated: November 16, 2026 at 02:49 AM