@bfra.me/doc-sync

@bfra.me/doc-sync

Intelligent documentation synchronization engine for automatic Astro Starlight site updates

Overview

@bfra.me/doc-sync monitors package source code, README files, and JSDoc comments to automatically update Astro Starlight documentation sites with zero manual intervention. It bridges the gap between your codebase and documentation, ensuring they stay in sync.

Features

• 📝 TypeScript/JSDoc Parsing — Extracts documentation from source files using the TypeScript Compiler API via ts-morph
• 📖 README Integration — Parses and incorporates README content into documentation pages
• 🔄 Incremental Updates — Only regenerates documentation for changed packages using content hashing
• 👁️ Watch Mode — Monitors for changes and syncs automatically during development
• ✨ MDX Generation — Creates Starlight-compatible MDX files with proper frontmatter
• 🛡️ Content Preservation — Protects manual content sections using sentinel markers
• 🎨 Modern CLI — Interactive terminal UI powered by @clack/prompts
• 🔒 Security — Sanitizes content to prevent XSS and validates file paths

Installation

pnpm add @bfra.me/doc-sync

CLI Usage

The doc-sync CLI provides three main commands for managing documentation synchronization.

Sync Command

Synchronize documentation for all or specific packages:

# Sync all packages
doc-sync sync

# Sync specific packages
doc-sync sync @bfra.me/es @bfra.me/eslint-config

# Interactive package selection
doc-sync sync --interactive

# Preview changes without writing files
doc-sync sync --dry-run

# With verbose output
doc-sync sync --verbose

Watch Command

Monitor for changes and sync automatically during development:

# Watch all packages
doc-sync watch

# Watch specific packages
doc-sync watch @bfra.me/es

# Watch with verbose logging
doc-sync watch --verbose

Validate Command

Check documentation freshness and validate MDX syntax:

# Validate all packages
doc-sync validate

# Validate specific packages
doc-sync validate @bfra.me/es

Global Options

Option	Alias	Description
--root <dir>	-r	Root directory of the monorepo (default: cwd)
--dry-run	-d	Preview changes without writing files
--verbose	-v	Enable verbose output
--quiet	-q	Suppress non-error output
--interactive	-i	Use interactive package selection
--watch	-w	Watch for changes (on default command)

Programmatic API

Basic Usage

import {createPackageScanner, createSyncOrchestrator} from '@bfra.me/doc-sync'

const scanner = createPackageScanner({
  rootDir: process.cwd(),
  includePatterns: ['packages/*'],
})

const orchestrator = createSyncOrchestrator({
  rootDir: process.cwd(),
  outputDir: 'docs/src/content/docs/packages',
})

const packages = await scanner.scan()
const result = await orchestrator.sync(packages)

if (result.success) {
  console.log(`Synced ${result.data.synced.length} packages`)
}

Parsing APIs

import {extractJSDoc, parseReadme, parseTypeScript} from '@bfra.me/doc-sync/parsers'

const tsResult = parseTypeScript('src/index.ts')
const jsDocResult = extractJSDoc(sourceFile)
const readmeResult = parseReadme('README.md')

Generator APIs

import {
  generateAPIReference,
  generateFrontmatter,
  generateMDXDocument,
  mergeContent,
} from '@bfra.me/doc-sync/generators'

const frontmatter = generateFrontmatter({
  title: '@bfra.me/es',
  description: 'ES utilities package',
})

const apiRef = generateAPIReference(packageAPI)
const mdx = generateMDXDocument({frontmatter, sections: [apiRef]})

File Watching

import {createDocDebouncer, createDocWatcher} from '@bfra.me/doc-sync'

const watcher = createDocWatcher({
  rootDir: process.cwd(),
  patterns: ['packages/*/src/**/*.ts', 'packages/*/README.md'],
})

const debouncer = createDocDebouncer({
  delayMs: 300,
  onBatch: async (events) => {
    console.log(`Processing ${events.length} file changes`)
  },
})

watcher.on('change', debouncer.add)
await watcher.start()

Configuration

Package-Level Configuration

Configure documentation generation per package in package.json:

{
  "name": "@bfra.me/example",
  "docs": {
    "title": "Custom Package Title",
    "description": "Override the default description",
    "sidebar": {
      "label": "Short Name",
      "order": 1,
      "hidden": false
    },
    "excludeSections": ["internal-api"],
    "frontmatter": {
      "tableOfContents": {
        "minHeadingLevel": 2,
        "maxHeadingLevel": 3
      }
    }
  }
}

Configuration Fields

Field	Type	Description
title	string	Custom title for the documentation page
description	string	Custom description override
sidebar.label	string	Label shown in sidebar navigation
sidebar.order	number	Sort order in sidebar (lower = earlier)
sidebar.hidden	boolean	Whether to hide from sidebar
excludeSections	string[]	Sections to exclude from auto-generation
frontmatter	object	Additional frontmatter fields

Content Preservation

Use sentinel markers to preserve manual content sections during regeneration:

{/* AUTO-GENERATED-START */}

This content is automatically generated and will be replaced on sync.

{/* AUTO-GENERATED-END */}

{/* MANUAL-CONTENT-START */}

Your custom content here will be preserved during regeneration.
Add examples, notes, or any additional documentation.

{/* MANUAL-CONTENT-END */}

Marker Types

• {/* AUTO-GENERATED-START */} / {/* AUTO-GENERATED-END */} — Marks auto-generated content
• {/* MANUAL-CONTENT-START */} / {/* MANUAL-CONTENT-END */} — Marks manually maintained content

TypeScript Types

The package exports comprehensive types for type-safe usage:

import type {
  DocConfig,
  DocConfigSource,
  ExportedFunction,
  ExportedType,
  MDXDocument,
  MDXFrontmatter,
  PackageAPI,
  PackageInfo,
  ParseError,
  ParseResult,
  SyncResult,
  SyncSummary,
} from '@bfra.me/doc-sync'

Subpath Exports

The package provides granular imports for tree-shaking:

Export	Description
@bfra.me/doc-sync	Main entry with all exports
@bfra.me/doc-sync/generators	MDX and content generation utilities
@bfra.me/doc-sync/parsers	TypeScript, JSDoc, and README parsers
@bfra.me/doc-sync/types	Type definitions only

Architecture

doc-sync/
├── src/
│   ├── cli/           # CLI commands and TUI
│   ├── generators/    # MDX and content generators
│   ├── orchestrator/  # Sync coordination
│   ├── parsers/       # Source code and README parsers
│   ├── watcher/       # File system monitoring
│   └── types.ts       # Core type definitions

Requirements

• Node.js 20+
• TypeScript 5.0+
• pnpm (recommended) or npm

Related Packages

• @bfra.me/es — ES utilities including Result types and watcher utilities
• @astrojs/starlight — Documentation framework (peer dependency)

License

MIT