Rendering & Serialization
Relevant source files
The following files were used as context for generating this wiki page:
Rendering and serialization in Cheerio represent the final stage of the document lifecycle, where a manipulated DOM tree is converted back into a string format, such as HTML or XML. This process is handled with high efficiency by working against a consistent DOM model based on domhandler nodes.
The library supports multiple serialization modes, including standard HTML rendering, XML serialization (useful for RSS or SVG), and text extraction. Serialization behavior is governed by the options provided during initial document loading, but can be overridden during the rendering call.
Sources: Readme.md:12-18, THREAT_MODEL.md:10-12
Core Serialization Methods
Cheerio provides several ways to convert internal DOM structures into strings, depending on whether the user requires the full document, a specific fragment, or just the text content.
HTML Rendering
The primary method for serialization is .html(). When called on the "root" selection, it renders the entire document. When called on a specific selection, it typically returns the innerHTML of that element.
The following table describes the behavior of standard rendering methods:
| Method | Target | Output Type | Description |
|---|---|---|---|
$.html() | Root | Full HTML | Renders the entire document string, including <html> and <body> if present. |
$(selector).html() | Selection | innerHTML | Renders the markup inside the first matched element. |
$(selector).prop('outerHTML') | Selection | outerHTML | Renders the markup of the element itself plus its children. |
$.xml() | Root/Selection | XML | Serializes the selection using XML rules (e.g., self-closing tags). |
Sources: Readme.md:79-106, src/static.spec.ts:7-14, website/src/content/blog/2024-08-07-version-1.md:88-91
XML Serialization
XML serialization is activated either by passing xml: true (or xmlMode: true in older versions) during the load phase, or by explicitly calling the $.xml() method. This mode ensures that tags like <media:thumbnail /> are rendered correctly with self-closing syntax and that case sensitivity is preserved for tags and attributes.
Sources: src/tests/xml.spec.ts:6-18, src/tests/xml.spec.ts:46-52
Text Extraction
Text rendering extracts the collective node values of all text nodes within a selection, recursively traversing the tree.
Text Content vs. Inner Text
Cheerio distinguishes between standard text() extraction and specialized property-based extraction:
.text(): Returns the text content of the specified elements and their children recursively. By default, it includes the content of<script>and<style>tags.innerText(via.prop()): Similar to the browser'sinnerText, this can omit content from<style>and<script>tags.
Serialization Options and Logic
The rendering engine's behavior is influenced by the options defined during document initialization or provided at the time of rendering.
Entity Encoding
Cheerio handles entity encoding to prevent XSS and ensure valid markup. By default, it encodes special characters (like < and &). Users can disable this by setting decodeEntities: false within the xml configuration object, which preserves the original character literals.
Sources: src/api/attributes.spec.ts:742-750, THREAT_MODEL.md:41-45
Data Handling
When serializing data attributes through the .data() API, Cheerio performs automatic type coercion for values found in the markup (e.g., converting "true" to true), but stores objects as-is when set via the API.
Sources: src/api/attributes.spec.ts:575-585, src/api/attributes.spec.ts:650-680
Logic Summary Table
| Option | Context | Default | Effect |
|---|---|---|---|
xml | Global/Local | false | When true, renders using XML rules (self-closing tags, case sensitivity). |
decodeEntities | Global | true | When false, preserves special characters without encoding. |
baseURI | Global | undefined | Used during serialization of href and src properties to resolve absolute URLs. |
Sources: src/api/attributes.spec.ts:400-415, src/tests/xml.spec.ts:7-10, website/src/content/blog/2024-08-07-version-1.md:104-108
Security in Serialization
As a server-side library, Cheerio's serialization produces markup strings. While it provides basic entity escaping, it is not a sanitizer. The Threat Model specifies that:
- XSS Enablement: Serialization must not make input more dangerous (e.g., via attribute injection).
- Output Responsibility: The calling application is responsible for sanitizing Cheerio's output before rendering it in a browser context to prevent XSS.
Sources: THREAT_MODEL.md:41-45, THREAT_MODEL.md:68-71
Summary
Rendering and Serialization in Cheerio bridge the gap between an in-memory DOM representation and a transferable string. By utilizing different methods like .html(), .xml(), and .text(), developers can produce structured markup or raw content suitable for a variety of use cases, from web scraping to generating XML feeds.