Configuration & Options
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Configuration and options in Cheerio define how HTML and XML documents are parsed, manipulated, and rendered. By providing a flexible configuration object during the loading process, developers can switch between different parsing engines (such as parse5 and htmlparser2), control entity decoding, and enable specialized features like location tracking or XML-specific rendering behaviors.
These options are primarily passed to the cheerio.load() method and influence the behavior of the resulting Cheerio instance. The configuration ensures that Cheerio can handle a wide variety of markup styles, from standard compliant HTML5 to strict XML documents, while maintaining a consistent jQuery-like API for the user.
Sources: src/cheerio.spec.ts:314-345, website/src/content/blog/2024-08-07-version-1.md:63-69
Core Configuration Logic
Cheerio utilizes options to determine the underlying parser and the serialization format. The library defaults to using parse5 for HTML parsing but can be configured to use htmlparser2 for XML or specific legacy requirements.
Parser Selection and Data Flow
The configuration flow begins when a user calls load(). The options provided dictate whether the content is treated as standard HTML or XML. If the xml option is enabled, Cheerio adjusts its internal logic to preserve case sensitivity and handle self-closing tags according to XML rules.
The diagram shows how configuration options at the loading stage branch the internal parsing logic between htmlparser2 and parse5.
Sources: src/parse.spec.ts:7-12, src/cheerio.spec.ts:347-350, website/src/content/blog/2024-08-07-version-1.md:63-69
Key Configuration Options
Cheerio supports a range of options that affect both the parsing of the input and the rendering of the output.
Parsing and Rendering Options
| Option | Type | Description |
|---|---|---|
xml | boolean | object | If true, enables XML parsing/rendering. Can be an object for specific htmlparser2 settings. |
decodeEntities | boolean | Determines if HTML entities should be decoded. Defaults to true. |
scriptingEnabled | boolean | When using parse5, determines if <noscript> content is parsed or treated as text. |
sourceCodeLocationInfo | boolean | Enables tracking of line/column numbers for elements. |
baseURI | string | Sets the base URL for resolving relative href and src properties. |
Sources: src/cheerio.spec.ts:382-424, src/parse.spec.ts:303-314, src/api/attributes.spec.ts:275-288, src/tests/xml.spec.ts:34-45
XML Mode Configuration
Enabling xml: true changes how tags and attributes are handled. In standard HTML mode, tags are typically lowercased, but XML mode preserves the original case.
// XML Mode preserves case
const $ = cheerio.load('<MixedCaseTag />', { xml: true });
$.html(); // => <MixedCaseTag/>
// Default HTML mode lowercases tags
const $html = cheerio.load('<MixedCaseTag />');
$html.html(); // => <html><head></head><body><mixedcasetag></mixedcasetag></body></html>
Sources: src/cheerio.spec.ts:333-345, src/tests/xml.spec.ts:40-45
Advanced Feature Configuration
Location Tracking
When sourceCodeLocationInfo is set to true, Cheerio instructs the underlying parser (specifically parse5) to attach location data to the generated nodes. This is useful for tools that need to map DOM nodes back to their source coordinates in the original markup string.
Sources: src/cheerio.spec.ts:409-423, src/parse.spec.ts:303-314
Scripting and Noscript Tags
The scriptingEnabled option (defaulting to true) controls how <noscript> tags are processed. When disabled, the content within <noscript> tags is parsed as standard DOM elements rather than being treated as a single text node.
The sequence shows the impact of the scriptingEnabled option on the internal parser's treatment of noscript elements.
Sources: src/cheerio.spec.ts:384-407
Integration with External Adapters
Cheerio maintains compatibility with external tree adapters and link mappings for documentation and internal type handling. The configuration in website/typedoc.json demonstrates how external symbol mappings are defined for domhandler and parse5, ensuring that classes like Document, Element, and Node are correctly referenced across the ecosystem.
Sources: website/typedoc.json:20-33
Summary
Cheerio's configuration system is designed to be "batteries included," providing sensible defaults while allowing deep customization for complex parsing scenarios. Whether switching to XML mode for RSS feeds or enabling location tracking for linting tools, the configuration options provide the necessary hooks to adjust Cheerio's behavior at the foundational level of document loading and tree construction.
Sources: website/src/content/blog/2024-08-07-version-1.md:6-12