Understanding Readability.js: A Deep Dive into Mozilla’s Standalone Readability Library

Readability.js stands as a standalone implementation of the same technology that powers Firefox’s Reader View. It’s designed to extract the meaningful, article-like content from cluttered web pages so that readers can focus on the text, images, and essential metadata without the surrounding chrome. This detailed guide walks you through installation, usage, API details, Node.js integration, security considerations, and how to contribute to the project. We’ll blend practical examples with explanations to help you leverage Readability.js in web projects, server-side rendering pipelines, and experimental readers.

Why Readability.js matters

The web is full of pages with dense navigation, ads, sidebars, and other noise that can overwhelm a reader. Readability.js provides a structured way to:

• Identify the main article content on a page
• Produce a cleaned, readable HTML snippet you can display in a reader mode
• Return meta information such as the title, byline, site name, and language
• Offer flexibility through options to tailor parsing behavior to your needs

By separating content from presentation, Readability.js makes it easier to render a consistent, distraction-free reading experience across devices and environments.

---

Installation

Getting started with Readability.js is straightforward. It’s published as an npm package, making it easy to integrate into modern JavaScript projects.

• Install via npm:

• npm install @mozilla/readability

• Usage in your project:

• In a Node-based or bundler-based workflow, you can require the library:

  • const { Readability } = require('@mozilla/readability');

• For web-based projects, you may load the Readability.js script directly into your page and use it as a global.

If you prefer exploring the library’s code or using it in a browser environment, the repository and the script provide clear entry points for integrating Readability into your DOM-driven workflows.

---

Basic usage

To parse a document, you create a new Readability object from a DOM document and then call the parse() method. The core idea is simple: feed Readability a document, and it returns a structured article object containing the processed content and metadata.

• Core usage example:
• var article = new Readability(document).parse();

If you’re operating inside a web browser, you’ll typically have access to a document object from the current page or from a fetched resource (e.g., via XMLHttpRequest) within the same-origin policy.

In Node.js, you’ll rely on an external DOM library (see Node.js usage) to provide a document-like interface that Readability can consume.

Example snippet:

• This illustrates the straightforward approach:
• var article = new Readability(document).parse();

Note that the parse() method modifies the DOM of the provided document. That means it will remove or rearrange some elements in the process of extracting the article content. If you’d like to avoid mutating the original document, pass a clone of the document to Readability, like this:

• var documentClone = document.cloneNode(true);
• var article = new Readability(documentClone).parse();

The result is an object with structured data about the article, which we’ll detail in the API section.

---

API Reference

Readability.js exposes a constructor with a rich options object, a parse() method, and a helper for quick checks of readerability. Here’s a closer look at the API and what it enables.

new Readability(document, options)

The constructor accepts two parameters:

• document: a DOM document-like object (the root of the HTML you want to analyze)
• options: an optional configuration object with a set of properties

Key options (all optional) and their defaults:

• debug (boolean, default false): enables logging to help you diagnose how Readability is choosing or discarding elements.
• maxElemsToParse (number, default 0): caps the maximum number of elements Readability will parse. A value of 0 means no limit.
• nbTopCandidates (number, default 5): defines how many top candidates to consider during the analysis of competition among potential article blocks.
• charThreshold (number, default 500): the minimum character length an article must have to be considered valid for output.
• classesToPreserve (array): a set of CSS classes to preserve on HTML elements when keepClasses is false.
• keepClasses (boolean, default false): if false, Readability preserves only classes listed in classesToPreserve. If true, all classes are kept.
• disableJSONLD (boolean, default false): when extracting metadata, Readability gives precedence to Schema.org fields found in JSON-LD. Set this to true to skip JSON-LD parsing.
• serializer (function, default el => el.innerHTML): controls how the content property is produced from the root DOM element. By default, you get HTML as a string. If you want to obtain a DOM element instead of a string, you can set serializer to the identity function (el => el) and process the element further.
• allowedVideoRegex (RegExp, default undefined): a regular expression that matches video URLs permitted to be included in the article content. If undefined, a default regex is used (the default is embedded in the library’s code).
• linkDensityModifier (number, default 0): a numerical modifier added to the base link density threshold during shadiness checks. This can be used to penalize nodes with high link density or reward lower density.

These options give you fine-grained control over what Readability considers as article content, how strict the extraction should be, and how the resulting content should be delivered to your application.

parse()

The parse() method runs the extraction and returns an object with the article’s data. The typical fields you’ll receive include:

• title: the article’s title
• content: the processed article content, produced according to the serializer you chose
• textContent: the textual content of the article (HTML tags removed)
• length: the number of characters in the article text
• excerpt: a short description or excerpt derived from the content
• byline: the author or byline information
• dir: the text direction (e.g., ltr or rtl)
• siteName: the site name, if detectable
• lang: content language
• publishedTime: the published timestamp if available

A note about DOM side effects: parse() works by modifying the DOM. If you want to avoid this side effect, you can supply a clone of the document as shown earlier.

isProbablyReaderable(document, options)

This helper provides a quick “readerability” check. It’s designed to be fast and to avoid initiating the full, heavier parsing logic in time-sensitive contexts (like rapid page transitions). It’s not perfect and may yield false positives or false negatives, but it’s useful for gating expensive operations.

Options for isProbablyReaderable (all optional):

• minContentLength (number, default 140): the minimum content length of a node to be considered for readerability.
• minScore (number, default 20): the minimum cumulative score needed to decide the document is readerable.
• visibilityChecker (function, default isNodeVisible): the function used to determine if a node is visible. This influences whether content is considered sufficiently prominent to be an article.

Example:

• /* Only instantiate Readability if we suspect the parse() method will produce a meaningful result. */
• if (isProbablyReaderable(document)) {
• let article = new Readability(document).parse();
• }

---

Node.js usage

Node.js does not include a native DOM, so you’ll typically rely on a library such as jsdom to provide a document object for Readability to process.

Example workflow using jsdom:

• var { Readability } = require('@mozilla/readability');
• var { JSDOM } = require('jsdom');
• var doc = new JSDOM(" Look at this cat: ", { url: "https://www.example.com/the-page-i-got-the-source-from" });
• Let reader = new Readability(doc.window.document);
• let article = reader.parse();

Important notes:

• Pass the page’s URI as the url option in JSDOM constructor. This ensures Readability can resolve relative URLs for images, hyperlinks, and other resources to absolute URLs, which is critical for reliable output.
• jsdom can run scripts embedded in the HTML and fetch remote resources. For security reasons, these features are disabled by default. It’s strongly recommended to keep script execution disabled unless you have a compelling reason to enable it.

In the input, an example shows an image embedded in the sample HTML:

• Look at this cat:

In a real Node.js environment, you’d typically serve or fetch content and let the URL resolution and resource loading happen under controlled conditions.

---

Security considerations

When using Readability.js with untrusted input—whether HTML strings or DOM documents—security is a critical concern. The Readability project itself focuses on extracting readable content and preserving the structure; it does not sanitize or scrub potentially dangerous scripts in the content it outputs.

Best practices:

• Sanitize the input or output: Use a dedicated sanitizer library such as DOMPurify to remove script tags or other executable content from the input before feeding it to Readability, or sanitize the produced content before rendering it in your application.
• Apply Content Security Policy (CSP): Enforce a strong CSP to limit what the resulting content can execute or access. CSP helps mitigate cross-site scripting (XSS) and other injection-style attacks.
• Treat Readability output as trusted or untrusted judiciously: While Readability reduces the surface area of clutter and danger by removing most extraneous elements, the resulting content may still contain dynamic features or links. Sanitation and policy-based restrictions are still advisable.
• Note the separation of concerns: It’s explicitly stated that sanitized content is not the responsibility of Readability itself. Rely on established sanitizers and security policies to maintain a safe rendering environment.

The Firefox integration of reader mode demonstrates these approaches in practice, combining sanitization strategies with a restrictive execution environment.

---

Contributing

If you’re interested in improving Readability.js, the project maintains a contributor-focused workflow. The project’s CONTRIBUTING.md document outlines how to contribute code, report issues, and participate in reviews. Whether you want to refine parsing heuristics, improve metadata extraction, or extend support for edge cases, your contributions are welcome.

---

License

Readability.js is released under the Apache License, Version 2.0. This license text indicates that the library is provided “as is” without warranties or conditions of any kind, and it sets forth permissions and limitations for use, modification, and distribution. The project’s licensing ensures that developers can build on top of Readability.js while respecting the terms of the license.

---

Practical tips for using Readability.js effectively

• Start with a clone: When you’re integrating Readability into an editor, extension, or content aggregator, consider passing a clone of the document to avoid side effects on the original page.
• Tune the thresholds: If you’re targeting shorter articles or more aggressively extracting content from noisy pages, experiment with charThreshold and maxElemsToParse to balance completeness and performance.
• Preserve or prune classes: If you rely on specific styling or need to maintain certain attributes, adjust keepClasses and provide a carefully chosen classesToPreserve.
• Image and media handling: If your target content often includes embedded media, consider customizing allowedVideoRegex to permit video content you deem safe or useful, and be mindful of how media is embedded in the extracted content.
• Security-first mindset: Always sanitize and apply CSP policies when rendering content produced by Readability. Treat the content as potentially risky if it originates from untrusted sources.

---

Summary

Readability.js is a powerful, standalone tool designed to extract clean, readable article content from cluttered pages. From installation to deep API customization, it provides a robust toolkit for building reader-friendly experiences in both client-side and server-side contexts. Its thoughtful options allow you to tailor parsing behavior, control output formats, and integrate seamlessly with existing DOM environments.

By following best practices for security and by leveraging examples such as the Node.js/jsdom workflow, you can incorporate Readability.js into a variety of projects—from browser extensions that present a distraction-free reading view to server-side content processors that prepare articles for offline consumption. The library’s clear API, documentation, and licensing support thoughtful reuse and collaboration, inviting developers to contribute improvements that keep the project resilient and adaptable to evolving web content.

Image used in context:

• Look at this cat:

Whether you’re building a personal reading tool or integrating a robust content extraction pipeline into a larger system, Readability.js offers a solid foundation. With careful handling of input, prudent security measures, and an understanding of its parsing logic, you can deliver a streamlined, accessible reading experience that respects authorship, layout, and user preferences.