Documentation Website

The Cheerio documentation website is a comprehensive resource designed to provide guides, API references, and project updates for the Cheerio library. Built as a modern static site, it serves as the primary gateway for developers to learn about parsing and manipulating HTML/XML using Cheerio's jQuery-like API. The site is structured to support different learning paths, from high-level conceptual guides to detailed technical API documentation.

The website was revamped as part of the Cheerio 1.0 release cycle to include a blog, updated tutorials, and a move towards a "batteries included" documentation approach. It utilizes technologies like Astro, React, and TypeDoc to generate content from source files and markdown.

Sources: website/src/content/blog/2023-02-13-new-website.md:1-26, website/src/content/blog/2024-08-07-version-1.md:10-21, website/package.json:1-40

Architecture and Build Pipeline

The website architecture follows a static site generation (SSG) model primarily powered by Astro. The build process involves two main stages: the generation of technical API references from TypeScript source code using TypeDoc, and the subsequent compilation of all pages (guides, blog posts, and API docs) into static assets.

Build Workflow

The following diagram illustrates the data flow from source code and markdown files to the final static build:

The build pipeline transforms raw source code into structured documentation and blog content.
Sources: website/package.json:8-12, website/typedoc.json:1-10

Core Build Scripts

The project uses npm (and previously yarn) to manage the build lifecycle.

Sources: website/package.json:8-16, website/README.md:16-30

Content Structure and Navigation

The website content is divided into three major pillars: Guides, API Documentation, and the Blog. Navigation is managed programmatically to ensure consistency between the sidebar and pagination.

Navigation Logic

Navigation is defined in website/src/lib/docs-nav.ts. It uses a structured sidebar array that serves as the single source of truth for the documentation hierarchy.

The relationship between sidebar sections and items ensures the reading order is maintained throughout the site.
Sources: website/src/lib/docs-nav.ts:1-47

Content Categories

1. Guides: Hand-written tutorials covering the basics (Loading, Selecting, Traversing, Manipulating, Extracting) and advanced topics (Configuring, Security).
2. API Docs: Reference material automatically generated from Cheerio's src/index.ts. These are located under /docs/api/.
3. Blog: Project updates and release announcements (e.g., Version 1.0 release).

Sources: website/src/content/blog/2023-02-13-new-website.md:30-49, website/src/lib/docs-nav.ts:24-43

API Reference Generation (TypeDoc)

The API documentation is generated using typedoc with the typedoc-plugin-markdown and typedoc-plugin-mdn-links plugins. This ensures that the documentation is not only accurate to the source but also properly linked to external MDN resources for standard DOM types.

TypeDoc Configuration Summary

The typedoc.json file controls how the documentation is rendered:

• Entry Points: Targets ../src/index.ts.
• Format: Uses markdown tables for parameters, enum members, and type declarations to improve readability.
• External Mappings: Maps types from domhandler (e.g., Document, Element, Node) and parse5 to their respective external documentation.
• Output Path: Files are generated into src/content/docs/api with a .md extension.

Sources: website/typedoc.json:1-36

Content Transformation and Styling

The website employs custom Remark plugins to enhance the markdown authoring experience and maintain link integrity.

Remark Plugins

• remark-internal-links: Normalizes absolute internal links to a lowercase, trailing-slash format. This prevents 404s on case-sensitive hosting environments like GitHub Pages and ensures compatibility with search crawlers.
• remark-admonitions: Processes Docusaurus-style callouts (e.g., :::note, :::tip) and transforms them into custom HTML div structures styled via Tailwind CSS.

Sources: website/src/plugins/remark-internal-links.ts:10-44, website/src/plugins/remark-admonitions.ts:32-88

Styling System

The site uses Tailwind CSS for layout and design. A global stylesheet defines a sophisticated design system including:

• Typography: Primary fonts include "Inter" for headings and "Rubik" for sans-serif text.
• Color Palette: A brand-specific primary color (#e88c1f) with defined shades for primary-dark and primary-lightest.
• Animations: Specialized animations for the landing page such as fade-up, pulse-glow, and a grain texture overlay.
• Documentation Prose: Specific classes like .prose (max 65ch) and .prose-wide (max 90ch) optimize readability for long-form text and wide API tables.

Sources: website/src/styles/global.css:1-140

Conclusion

The Cheerio documentation website is a modern, SSG-based platform that balances automated API reference generation with manually curated guides. By leveraging Astro, TypeDoc, and a suite of custom Remark plugins, it provides a consistent and styled experience for developers, ensuring that both high-level usage and low-level technical details remain accessible and up-to-date with the project's source code.