Starlight Document Converter

Transform any document into beautiful Starlight documentation

A comprehensive document converter for Astro Starlight that transforms various document formats into Starlight-compatible Markdown with proper frontmatter.

Starlight Document Converter revolutionizes documentation workflows by seamlessly converting Word docs, HTML files, and other formats directly into Astro Starlight-compatible markdown. This tool helps developers migrate existing documentation and provides intelligent content analysis with automatic frontmatter generation.

Features

Multi-Format Support Convert .docx, .doc, .txt, .html, .htm, .md, .rtf files with perfect formatting preservation

Smart AI Integration Auto-generates titles, descriptions, categories, and tags using intelligent content analysis

Quality Scoring Real-time quality indicators (🟢🟡🔴) with improvement suggestions and detailed analytics

Astro Integration Seamless Astro integration with file watching, batch processing, and zero-configuration setup

MDX Conversion 🆕 Convert Markdown to MDX with JSX components (tabs, cards, alerts) automatically

Plugin System Extensible architecture for custom processors, enhancers, and validators

Quick Start

Installation

# Install globally
npm install -g @entro314labs/starlight-document-converter

# Or use directly with npx (full command)
npx @entro314labs/starlight-document-converter --help

# Shorter npx usage
npx @entro314labs/starlight-document-converter@latest
# Aliases: sdc, starvert, starlight-convert

Basic Usage

# Interactive mode with smart detection
npx @entro314labs/starlight-document-converter

# Convert directory (auto-detects output location)
npx @entro314labs/starlight-document-converter batch documents/

# Preview changes first
npx @entro314labs/starlight-document-converter batch documents/ --dry-run --verbose

# After global install, use short aliases:
sdc                          # Interactive mode
sdc batch documents/         # Batch convert
starvert --help             # Show help

That's it! Your documents are ready for Starlight.

How It Works

1. Smart Detection: Automatically detects your Starlight project structure and configuration
2. Content Analysis: Analyzes document content to generate appropriate titles, descriptions, and tags
3. Format Conversion: Converts various formats to clean, Starlight-compatible markdown
4. Quality Assessment: Provides quality scores and improvement suggestions for each document

Supported Technologies

Astro & Starlight Astro 5.x, Starlight 0.35+ Native integration support

Node.js Node.js 20+, npm/pnpm/yarn CLI and programmatic API

TypeScript Full TypeScript support Type definitions included

Document Formats Word, HTML, RTF, Markdown Text and structured content

Core Commands

Note: Commands below assume global installation. For npx usage, prefix with npx @entro314labs/starlight-document-converter

Aliases: starlight-convert, sdc (short), starvert (memorable)

# Interactive mode (recommended) - using short alias
sdc                                  # Launch guided interface with smart detection

# Project setup
sdc setup                           # Configuration wizard for new projects

# Batch processing
sdc batch <input>                   # Convert directory with auto-detection
sdc batch --dry-run                 # Preview changes without writing files

# File watching
sdc watch <directory>               # Auto-convert on file changes

# Alternative memorable alias
starvert --help                     # Same functionality, different name

Configuration

// astro.config.mjs - Astro Integration
import starlightDocumentConverter from '@entro314labs/starlight-document-converter';

export default defineConfig({
  integrations: [
    starlight({ title: 'My Docs' }),
    starlightDocumentConverter({
      enabled: true,
      watch: true,
      inputDirs: ['docs-import', 'documents'],
      converter: {
        outputDir: 'src/content/docs',
        preserveStructure: true,
        generateTitles: true,
        generateDescriptions: true
      }
    })
  ]
});

Examples

MDX Conversion (New! 🎨)

Convert Markdown to MDX with automatic JSX component transformations:

# Enable MDX mode for JSX component conversion
sdc batch docs/ --mdx

# Preview MDX conversion
sdc batch docs/ --mdx --dry-run --verbose

What gets converted:

• GitHub alerts (> [!NOTE]) → <Aside> components
• Tab patterns → <Tabs> / <TabItem>
• Code groups → Tabbed code blocks
• Docusaurus admonitions → <Aside> components
• Card patterns → <Card> components

Example transformation:

Input:

> [!NOTE]
> Important information

### Tab: JavaScript
\`\`\`javascript
console.log('hello')
\`\`\`

Output:

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';

<Aside type="note">
Important information
</Aside>

<Tabs>
  <TabItem label="JavaScript">
\`\`\`javascript
console.log('hello')
\`\`\`
  </TabItem>
</Tabs>

📖 See the complete MDX Conversion Guide for all features and examples.

Basic Document Conversion

# Create import directory and add documents
mkdir docs-import
cp ~/documents/*.docx docs-import/

# Convert all documents
npx @entro314labs/starlight-document-converter batch docs-import/

Image Handling

The converter automatically processes images during conversion:

Automatic Search Locations:

• Same directory as source file
• ./images/ subdirectory
• ./assets/ subdirectory
• Project root /images/ or /assets/
• /src/assets/ directory
• /public/ directory

For Missing Images:

# Get detailed missing image report
sdc batch docs/ --verbose

# Copy images to assets and update paths
sdc batch docs/ --process-images

# Preview image processing without changes
sdc batch docs/ --process-images --dry-run

Astro-Specific Recommendations:

• Place images in src/assets/ for optimized processing
• Use public/ for static images that don't need optimization
• Avoid bare filenames - use relative paths for better reliability

Word Document Conversion

Input (guide.docx):

# Getting Started Guide

This guide will help you set up your development environment.

## Prerequisites
- Node.js 20+
- Git

Output (guide.md):

---
title: "Getting Started Guide"
description: "This guide will help you set up your development environment."
category: "Guides"
tags:
  - guide
  - setup
---

# Getting Started Guide

This guide will help you set up your development environment.

## Prerequisites
- Node.js 20+
- Git

Programmatic Usage

import { DocumentConverter } from '@entro314labs/starlight-document-converter';

const converter = new DocumentConverter({
  outputDir: 'src/content/docs',
  generateTitles: true,
  generateDescriptions: true
});

// Convert single file
const result = await converter.convertFile('document.docx');

// Convert directory
const results = await converter.convertDirectory('documents/');

// Get conversion statistics
const stats = converter.getStats();
console.log(`Processed: ${stats.processed} files`);

Documentation

• Getting Started Guide - Complete setup instructions
• API Reference - All commands and options
• Configuration - Advanced configuration
• Examples - Real-world usage examples

Contributing

We welcome contributions! Please see our Contributing Guide for details.

• Report bugs
• Request features
• Improve documentation
• Submit pull requests

Roadmap

• [ ] Enhanced AI Analysis - Better content understanding and metadata generation
• [ ] Custom Plugins - Plugin system for extending conversion capabilities
• [ ] Starlight Components - Dashboard components for in-browser conversion
• [ ] Bulk Operations - Advanced batch processing with parallel conversion

Requirements

• Node.js: >= 20.0.0
• npm: >= 8.0.0 or pnpm >= 7.0.0
• Operating System: Windows, macOS, Linux

License

MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: GitHub Repository
• Email: Support via GitHub issues

Made with ❤️ for the Astro community

GitHub • npm • Issues • Discussions