# Starlight Document Converter
[![npm version](https://badge.fury.io/js/%40entro314labs%2Fstarlight-document-converter.svg)](https://badge.fury.io/js/%40entro314labs%2Fstarlight-document-converter) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
**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
## Quick Start ### Installation ```bash # 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 ```bash # 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) ```bash # 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 # Convert directory with auto-detection sdc batch --dry-run # Preview changes without writing files # File watching sdc watch # Auto-convert on file changes # Alternative memorable alias starvert --help # Same functionality, different name ``` ## Configuration ```javascript // 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 ### Basic Document Conversion ```bash # 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:** ```bash # 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`): ```yaml --- 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 ```javascript 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](./docs/getting-started.md)** - Complete setup instructions - **[API Reference](./docs/api-reference.md)** - All commands and options - **[Configuration](./docs/configuration.md)** - Advanced configuration - **[Examples](./docs/examples.md)** - Real-world usage examples ## Contributing We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. - [Report bugs](https://github.com/entro314-labs/starlight-document-converter/issues) - [Request features](https://github.com/entro314-labs/starlight-document-converter/issues) - [Improve documentation](./docs/) - [Submit pull requests](https://github.com/entro314-labs/starlight-document-converter/pulls) ## 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](LICENSE) file for details. ## Support - **Issues**: [GitHub Issues](https://github.com/entro314-labs/starlight-document-converter/issues) - **Discussions**: [GitHub Discussions](https://github.com/entro314-labs/starlight-document-converter/discussions) - **Documentation**: [GitHub Repository](https://github.com/entro314-labs/starlight-document-converter) - **Email**: Support via GitHub issues ---
**Made with ❤️ for the Astro community** [GitHub](https://github.com/entro314-labs/starlight-document-converter) • [npm](https://www.npmjs.com/package/@entro314labs/starlight-document-converter) • [Issues](https://github.com/entro314-labs/starlight-document-converter/issues) • [Discussions](https://github.com/entro314-labs/starlight-document-converter/discussions)