@context-action/typedoc-vitepress-sync

Enhanced TypeDoc to VitePress documentation sync with smart caching, parallel processing, and quality validation.


🚀 Features

- 🔥 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

📦 Installation

$3

``bash
npm install @context-action/typedoc-vitepress-sync


or

yarn add @context-action/typedoc-vitepress-sync

or

pnpm add @context-action/typedoc-vitepress-sync
`

$3

`bash
npm install -g @context-action/typedoc-vitepress-sync
`

🔧 Quick Start

$3

`bash


Initialize configuration

npx typedoc-vitepress-sync init

Sync documentation

npx typedoc-vitepress-sync sync --source ./docs/api/generated --target ./docs/en/api

With custom configuration

npx typedoc-vitepress-sync sync --config ./sync.config.js

Clean cache and generated files

npx typedoc-vitepress-sync clean
`

$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 stats

Clear 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: Documentation

on:
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-sync

Install dependencies

pnpm install

Build package

pnpm build

Run tests

pnpm test

Run tests with coverage

pnpm test:coverage
``

📄 License

MIT © mineclover

🔗 Related

- TypeDoc - TypeScript documentation generator
- VitePress - Static site generator
- Context-Action Framework - State management library

---

Made with ❤️ for the TypeScript documentation community