feat(docs): add initial VitePress documentation setup

[JessicaSachs]

Currently targeting master. Will backport to 7.x and 6.x manually once settled.

PR Summary: VitePress Documentation Migration

Overview

This PR introduces a partial migration of the RxJS documentation site from Angular to VitePress.

The new documentation site is located in apps/rxjs.dev-next/ and includes automated API documentation generation, marble diagram generation, and a fully redesigned user interface.

Context for Rewrite

Degeni is no longer maintained and there is no alternative provided by the ecosystem.

Scope

Key Features

1. Automated API Documentation Generation

   • TypeDoc integration for extracting documentation from TypeScript source
   • Custom TypeDoc plugin (typedoc-plugin-rxjs.mjs) for enhanced formatting:
     • Description section formatting with blockquote summaries
     • Parameter and return type rendering
     • Overload handling
     • Type parameter cleanup
     • JSDoc tag processing (@param, @returns, @example, etc.)
   • Automatic markdown generation from TypeScript JSDoc comments

2. Marble Diagram Generation

   • Automated SVG generation from text specifications using @swirly
   • Support for both light and dark theme variants
   • SVG optimization with SVGO
   • Styling for dark mode diagrams

3. UI Components

   • Tailwind-powered Nuxt UI in Standalone Vue-mode for dropdown + filtering, etc
   • Vue 3 components for enhanced interactivity:
     • ApiSection.vue: Categorized API explorer with icon-based navigation
     • Search.vue: Local search functionality
   • Color-coded API categories (functions, classes, interfaces, etc.)

4. VitePress Configuration

   • Custom theme extending VitePress default theme
   • Comprehensive sidebar navigation with TypeDoc-generated structure
   • Local search provider
   • Custom styling and branding

Tooling & Build System

Core Technologies

• VitePress 1.6.4: Modern static site generator
• TypeDoc 0.28.15: TypeScript documentation generator
• TypeDoc Plugins:
  • typedoc-plugin-markdown: Markdown output
  • typedoc-vitepress-theme: VitePress theme integration (Sidebar generation)
  • Custom typedoc-plugin-rxjs.mjs: RxJS-specific formatting

Build Scripts

{
  "marbles:generate": "tsx tools/marbles/generate-diagrams.ts",
  "preapi:generate": "npm run marbles:generate",
  "api:generate": "typedoc && tsx tools/api-generator/index.ts",
  "dev": "npm run api:generate && vitepress dev",
  "build": "npm run api:generate && vitepress build",
  "preview": "vitepress preview"
}

Build Pipeline

1. Marble Diagram Generation (tools/marbles/generate-diagrams.ts)

   • Reads .txt specifications from tools/marbles/diagrams/
   • Parses with @swirly/parser
   • Renders SVG with @swirly/renderer-node
   • Optimizes with SVGO
   • Outputs to docs/public/images/marble-diagrams/

2. API Documentation Generation (tools/api-generator/index.ts)

   • Runs TypeDoc with custom configuration
   • Processes TypeScript source from:
     • packages/rxjs/src/
     • packages/observable/src/
   • Applies custom TypeDoc plugin transformations
   • Copies generated markdown to docs/api/
   • Generates sidebar JSON for navigation

3. TypeDoc Plugin (tools/api-generator/typedoc-plugin-rxjs.mjs)

   • Custom markdown transformations:
     • Description formatting (blockquote + full description)
     • Parameter section normalization
     • Returns section extraction from JSDoc
     • Empty section cleanup
     • Horizontal rule removal
     • Type parameter simplification
   • Enhanced overload rendering

Entry Points

TypeDoc processes the following entry points:

• packages/rxjs/src/index.ts (main RxJS API)
• packages/observable/src/index.ts (Observable utilities)
• packages/rxjs/src/operators/index.ts (operators)
• packages/rxjs/src/ajax/index.ts (Ajax module)
• packages/rxjs/src/fetch/index.ts (Fetch module)
• packages/rxjs/src/webSocket/index.ts (WebSocket module)
• packages/rxjs/src/testing/index.ts (testing utilities)

File Structure

apps/rxjs.dev-next/
├── .vitepress/
│   ├── config.ts              # VitePress configuration
│   └── theme/
│       ├── index.ts           # Theme extension
│       ├── shiki.ts           # Syntax highlighting
│       └── style.css          # Custom styles
├── components/
│   ├── ApiSection.vue         # API explorer component
│   └── Search.vue             # Search component
├── docs/
│   ├── api/                   # Generated API docs (236 files)
│   │   ├── @rxjs/observable/  # Observable package docs
│   │   ├── ajax/              # Ajax module docs
│   │   ├── fetch/             # Fetch module docs
│   │   ├── operators/         # Operator docs
│   │   ├── rxjs/              # Core RxJS docs
│   │   ├── testing/           # Testing docs
│   │   └── webSocket/         # WebSocket docs
│   ├── guide/                 # User guides
│   ├── deprecations/          # Migration guides
│   └── public/
│       └── images/
│           └── marble-diagrams/ # Generated SVG diagrams
├── tools/
│   ├── api-generator/
│   │   ├── index.ts           # API generation script
│   │   ├── pages/             # Custom API pages (there's only one, the API explorer)
│   │   └── typedoc-plugin-rxjs.mjs # TypeDoc plugin
│   └── marbles/
│       ├── generate-diagrams.ts # Diagram generator
│       └── diagrams/          # Diagram specifications (.txt)
├── typedoc.config.mjs         # TypeDoc configuration
└── package.json               # Dependencies and scripts

Key Improvements

1. Developer Experience

   • Faster build times with Vite
   • Hot module replacement during development
   • Simpler build process (no Angular complexity)

2. Maintainability

   • Documentation generated directly from source code
   • Single source of truth (TypeScript JSDoc comments)
   • Automated generation reduces manual documentation drift

3. User Experience

   • Modern, fast-loading site
   • Better search functionality
   • Improved navigation with categorized API explorer
   • Responsive design
   • Dark mode support

4. Documentation Quality

   • Consistent formatting across all API docs
   • Enhanced parameter and return type documentation
   • Better code examples rendering
   • Improved type information display

Dependencies

Major Additions

• vitepress: ^1.6.4
• typedoc: ^0.28.15
• typedoc-vitepress-theme: ^1.1.2
• typedoc-plugin-markdown: ^4.9.0
• @swirly/*: ^0.18.x (marble diagram generation)
• @nuxt/ui: ^4.3.0 (UI components)
• shiki: ^1.0.0 (syntax highlighting)
• svgo: ^3.0.0 (SVG optimization)
• tsx: ^4.7.0 (TypeScript execution)

Migration Notes

• We haven't removed the old site
• Will need to figure out versioning, there's hooks + config options for it but I haven't investigated
• Need to investigate deployments and broken links
• Have not touched the Operator Decision Tree

Screenshots

Home

Guide Pages

Deprecations Section (with dedicated Sidebar nav, defined in VitePress Config)

API Explorer

With filter + search

Generated API Docs (fromFetch)

Handling overloads was a pain (TypeDoc kinda sucks at this)

Local Search

Team Page

Marble Diagrams

Old pngs work

SVGs (generated, dark + light)

[nx-cloud]

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

---

View your CI Pipeline Execution ↗ for commit 454c9d2

Command	Status	Duration	Result
nx compile rxjs	❌ Failed	28s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-01-05 17:14:29 UTC