Generate interactive UI documentation from JSDoc-style comment blocks in your CSS, JavaScript, and TypeScript files.
UI-Doc combines documentation with testing by allowing you to write examples directly in your source code as comment blocks. These examples are then rendered as live, interactive documentation pages.
Design First, Document as You Build
UI-Doc addresses common challenges in component development:
- Speed up development - Build and test components in isolation before integrating them
- Document close to the code - Keep documentation and implementation in sync
- Prevent breakage - See all component variants in one place to avoid unintended changes
- Familiar syntax - Use JSDoc-style comments that feel natural to developers
- Live examples - View rendered components alongside their code
The Problem
Often developers struggle with CSS and component development because:
- Too much context switching - Moving between CMS/framework setup, markup, and styling breaks focus
- Hidden dependencies - Changes to shared components break pages you didn't know existed
- No single source of truth - Documentation drifts from implementation
The Solution
Work in your documentation. As you document and write examples, you see the results immediately:
- Design components in isolation
- Document behavior and usage
- Provide an overview of what exists and how to use it
- Test components independently
- Prevent CSS class name collisions
- Parse JSDoc-style documentation blocks from CSS, JS, and TS files
- Render live component examples with code
- Organize documentation into pages and sections
- Document colors, spacing, and icon systems
- Integrate with Rollup and Vite build pipelines
- Extensible tag system for custom documentation needs
- Zero-config HTML renderer with customizable templates
Install the packages you need for your build tool:
# For Vite projects
pnpm install --save-dev @ui-doc/vite @ui-doc/html-renderer @highlightjs/cdn-assets
# For Rollup projects
pnpm install --save-dev @ui-doc/rollup @ui-doc/html-renderer @highlightjs/cdn-assets
# For Node.js scripts
pnpm install --save-dev @ui-doc/core @ui-doc/node @ui-doc/html-renderer// vite.config.js
import uidoc from '@ui-doc/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
uidoc({
source: ['src/**/*.css'],
settings: {
texts: {
title: 'My UI Documentation',
},
},
}),
],
})// rollup.config.js
import uidoc from '@ui-doc/rollup'
export default {
plugins: [
uidoc({
source: ['src/**/*.css'],
settings: {
texts: {
title: 'My UI Documentation',
},
},
}),
],
}Add JSDoc-style comment blocks to your source files:
/**
* Typography system for the application.
*
* @page typography Typography
*/
/**
* Default text formatting elements.
*
* @location typography.format Format
* @example
* <span>Normal Text</span><br>
* <strong>Strong Text</strong><br>
* <small>Small Text</small><br>
* <em>Emphasis Text</em><br>
* <i>Italic Text</i>
*/This monorepo contains five packages that work together to generate UI documentation:
The core parsing and rendering engine. Extracts documentation from JSDoc-style comment blocks and transforms them into structured context for rendering.
Key features:
- Comment block parsing with tag transformers
- Extensible tag system (@page, @section, @example, @color, @space, @icon)
- Event system for customization
- Renderer interface for output generation
Read the @ui-doc/core documentation
File system operations for Node.js environments. Handles file discovery via glob patterns and reading source files.
Read the @ui-doc/node documentation
A lightweight HTML rendering engine with a simple template syntax. Converts UI-Doc context objects into HTML pages with zero dependencies.
Key features:
- Simple template syntax (var, if, for, page, partial)
- Customizable layouts, pages, and partials
- No external dependencies
Read the @ui-doc/html-renderer documentation
Rollup plugin integration. Generates UI documentation as part of your Rollup build process.
Key features:
- Glob-based source file discovery
- Asset management for styles and scripts
- Template customization
- Static asset copying
Read the @ui-doc/rollup documentation
Vite plugin integration. Wraps the Rollup plugin and adds Vite dev server support for live documentation preview.
Key features:
- All Rollup plugin features
- Dev server integration
- Live preview at
/ui-docduring development - Configurable base URI for production builds
Read the @ui-doc/vite documentation
@ui-doc/core # Parse doc blocks → context objects
↓
@ui-doc/node # File system operations (depends on core)
↓
@ui-doc/html-renderer # Render context → HTML (depends on core)
↓
@ui-doc/rollup # Rollup plugin (depends on core + node)
↓
@ui-doc/vite # Vite plugin (wraps rollup)
- Core parses JSDoc comment blocks from source text using
CommentBlockParser - Blocks are transformed into UI-Doc context objects via tag transformers
- Node handles file discovery and reading via glob patterns
- HTML Renderer converts context to HTML pages with styling
- Build plugins (Rollup/Vite) integrate the pipeline and output documentation
- Live Demo - See UI-Doc in action
- @ui-doc/core Documentation - Core API and tag reference
- @ui-doc/html-renderer Documentation - Template syntax
- @ui-doc/rollup Documentation - Rollup plugin options
- @ui-doc/vite Documentation - Vite plugin options
Check out the demos directory for complete examples:
- Node.js script -
demos/base.ts - Rollup configuration -
demos/rollup.config.mjs - Vite configuration -
demos/vite.config.mjs
- mise (recommended), which installs the pinned toolchain from
mise.toml - Otherwise: Node.js 24 and pnpm 11
# Install dependencies
pnpm install
# Build all packages
pnpm workspace:build
# Run tests
pnpm test
# Lint code
pnpm lint
# Fix linting issues
pnpm fix# Build a specific package
pnpm --filter @ui-doc/core build
# Test a specific package
pnpm --filter @ui-doc/core test
# Type check all packages
pnpm typecheckTests are located in packages/*/tests/ and use Vitest with TypeScript support.
# Run all tests
pnpm test
# Run tests for a specific package
pnpm --filter @ui-doc/core testThis project uses Conventional Commits with the following scopes:
release- Release-related changescore- @ui-doc/core packagehtml-renderer- @ui-doc/html-renderer packagenode- @ui-doc/node packagerollup- @ui-doc/rollup packagevite- @ui-doc/vite packagedemos- Demo applications
Example: feat(core): add custom tag transformer support
# Dry run (lint, test, version check)
pnpm release:dry
# Full release with publishing
pnpm releaseCopyright (c) 2024