Enhanced TypeDoc to VitePress documentation sync with smart caching, parallel processing, and quality validation
npm install @context-action/typedoc-vitepress-syncEnhanced TypeDoc to VitePress documentation sync with smart caching, parallel processing, and quality validation.


- š„ Smart Caching: SHA256 hash-based file change detection with 24-hour TTL
- ā” Parallel Processing: Configurable batch processing for improved performance
- š”ļø Error Recovery: Strategic error handling with automatic recovery
- ⨠Quality Validation: Markdown syntax, link integrity, and accessibility checks
- š Comprehensive Metrics: Detailed performance and quality reporting
- šØ Vue Compatibility: Automatic VitePress/Vue template processing
- š§ CLI Interface: Full-featured command-line tool
- š± Responsive Design: Works with modern documentation workflows
``bash`
npm install @context-action/typedoc-vitepress-syncor
yarn add @context-action/typedoc-vitepress-syncor
pnpm add @context-action/typedoc-vitepress-sync
`bash`
npm install -g @context-action/typedoc-vitepress-sync
`bashInitialize configuration
npx typedoc-vitepress-sync init
$3
`typescript
import { TypeDocVitePressSync } from '@context-action/typedoc-vitepress-sync'const sync = new TypeDocVitePressSync({
sourceDir: './docs/api/generated',
targetDir: './docs/en/api',
packageMapping: {
'core': 'core',
'react': 'react'
}
})
// Auto-optimize based on system resources
sync.autoOptimize()
// Perform sync
const result = await sync.sync()
console.log(
Processed ${result.filesProcessed} files in ${result.processingTime}ms)
console.log(Cache hit rate: ${result.cache.hitRate})
`āļø Configuration
$3
Create
typedoc-vitepress-sync.config.js:`javascript
export default {
sourceDir: './docs/api/generated',
targetDir: './docs/en/api',
sidebarConfigPath: './docs/.vitepress/config/api-spec.ts',
packageMapping: {
'core': 'core',
'react': 'react',
'utils': 'utilities'
},
cache: {
enabled: true,
dir: './.typedoc-vitepress-cache',
ttl: 24 60 60 * 1000, // 24 hours
hashAlgorithm: 'sha256'
},
parallel: {
enabled: true,
maxWorkers: 4,
batchSize: 10
},
quality: {
validateLinks: true,
validateMarkdown: true,
checkAccessibility: true
},
metrics: {
enabled: true,
outputFile: './reports/sync-metrics.json'
}
}
`$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
sourceDir | string | Required | Source directory containing TypeDoc output |
| targetDir | string | Required | Target directory for VitePress docs |
| sidebarConfigPath | string | ./docs/.vitepress/config/api-spec.ts | Output path for sidebar configuration |
| packageMapping | Record | {} | Map source packages to target directories |
| cache.enabled | boolean | true | Enable caching system |
| cache.dir | string | ./.typedoc-vitepress-cache | Cache directory path |
| cache.ttl | number | 86400000 | Cache TTL in milliseconds (24h) |
| parallel.enabled | boolean | true | Enable parallel processing |
| parallel.maxWorkers | number | 4 | Maximum worker threads |
| parallel.batchSize | number | 10 | Files per batch |
| quality.validateLinks | boolean | true | Validate internal links |
| quality.validateMarkdown | boolean | true | Validate markdown syntax |
| quality.checkAccessibility | boolean | true | Check accessibility compliance |
| metrics.enabled | boolean | true | Enable metrics collection |
| metrics.outputFile | string | ./reports/metrics.json | Metrics output file |šÆ CLI Commands
$3
`bash
Sync documentation
typedoc-vitepress-sync sync [options]Clean cache and generated files
typedoc-vitepress-sync clean [options]Initialize configuration
typedoc-vitepress-sync init [options]
`$3
`bash
Show cache statistics
typedoc-vitepress-sync cache statsClear cache
typedoc-vitepress-sync cache clear
`$3
| Option | Description |
|--------|-------------|
|
-c, --config | Configuration file path |
| -s, --source | Source directory override |
| -t, --target | Target directory override |
| --sidebar | Sidebar config output path |
| --no-cache | Disable caching |
| --no-parallel | Disable parallel processing |
| --no-quality | Disable quality validation |
| --no-metrics | Disable metrics collection |
| -v, --verbose | Enable verbose logging |
| --force | Force process all files |
| --dry-run | Show what would be done |š Performance
$3
| Scenario | Files | First Run | Cached Run | Improvement |
|----------|-------|-----------|------------|-------------|
| Small Project | 20 files | 150ms | 50ms | 67% faster |
| Medium Project | 76 files | 300ms | 100ms | 67% faster |
| Large Project | 200+ files | 800ms | 250ms | 69% faster |
$3
- Hit Rate: 95-100% on unchanged files
- Hash Algorithm: SHA256 for accurate change detection
- Storage: Efficient JSON manifest with file metadata
- TTL: Configurable expiration (default 24h)
š Quality Validation
$3
- Detects undefined template values
- Validates code block syntax
- Checks for unclosed markdown syntax
- Identifies malformed tables
- Reports overly long lines
$3
- Validates internal link integrity
- Checks for broken file references
- Detects empty link text
- Supports relative and absolute paths
- Ignores external URLs and anchors
$3
- Ensures images have alt text
- Validates heading hierarchy
- Checks list formatting
- Verifies table structure
- Reports accessibility issues
š Metrics & Monitoring
$3
`json
{
"filesProcessed": 76,
"filesSkipped": 0,
"processingTime": 1250,
"cache": {
"hits": 72,
"misses": 4,
"hitRate": "94.74%"
},
"quality": {
"totalIssues": 2,
"files": [...]
},
"performance": {
"filesPerSecond": "60.8",
"averageTimePerFile": "16.45ms",
"cacheEfficiency": "excellent"
}
}
`$3
`
============================================================
ā
TypeDoc VitePress Sync Complete!
============================================================
š Files processed: 76
āļø Files skipped: 72 (cache hits)
ā±ļø Processing time: 1.25sš Cache Statistics:
- Hit rate: 94.74%
- Hits: 72
- Misses: 4
ā” Performance: Excellent
`š ļø Advanced Usage
$3
`typescript
const sync = new TypeDocVitePressSync(config)sync.on('start', (config) => {
console.log('Sync starting with config:', config)
})
sync.on('fileComplete', (filePath, result) => {
if (result.cached) {
console.log(
Cache hit: ${filePath})
} else {
console.log(Processed: ${filePath})
}
})sync.on('complete', (result) => {
console.log(
Sync completed: ${result.filesProcessed} files)
})await sync.sync()
`$3
`typescript
import { QualityValidator } from '@context-action/typedoc-vitepress-sync'const validator = new QualityValidator({
validateMarkdown: true,
validateLinks: true,
checkAccessibility: true
})
const issues = await validator.validateFile('./docs/api.md')
if (issues) {
console.log('Quality issues found:', issues.issues)
}
`$3
`typescript
import { CacheManager } from '@context-action/typedoc-vitepress-sync'const cache = new CacheManager({
enabled: true,
dir: './custom-cache',
ttl: 60 60 1000 // 1 hour
})
await cache.initialize()
// Check if file needs processing
const shouldProcess = cache.shouldProcess('source.md', 'target.md')
// Update cache after processing
cache.updateCache('source.md', 'target.md')
// Get statistics
const stats = cache.getStats()
console.log(
Cache hit rate: ${stats.hitRate})
`š Integration
$3
`json
{
"scripts": {
"docs:sync": "typedoc-vitepress-sync sync",
"docs:clean": "typedoc-vitepress-sync clean",
"docs:build": "typedoc && npm run docs:sync && vitepress build docs",
"docs:dev": "vitepress dev docs"
}
}
`$3
`yaml
name: Documentationon:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Generate TypeDoc
run: npm run docs:api
- name: Sync to VitePress
run: npx typedoc-vitepress-sync sync --verbose
- name: Build documentation
run: npm run docs:build
`$3
The generated sidebar configuration can be imported directly:
`typescript
// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'
import { sidebarApiEn } from './config/api-spec'export default defineConfig({
themeConfig: {
sidebar: {
'/en/api/': sidebarApiEn(),
// ... other sidebar configs
}
}
})
`š¤ Contributing
Contributions are welcome! Please read our Contributing Guide for details.
$3
`bash
Clone repository
git clone https://github.com/mineclover/context-action.git
cd context-action/packages/typedoc-vitepress-syncInstall dependencies
pnpm installBuild package
pnpm buildRun tests
pnpm testRun tests with coverage
pnpm test:coverage
``MIT Ā© mineclover
- TypeDoc - TypeScript documentation generator
- VitePress - Static site generator
- Context-Action Framework - State management library
---
Made with ā¤ļø for the TypeScript documentation community