Markdown Documentation Generator

A modern, beautiful documentation generator that converts markdown files into interactive HTML documentation sites. Built with performance, accessibility, and user experience in mind.

🚀 Quick Start

Installation

# Install globally
npm install -g rp-markdown-docs

# Or install locally
npm install --save-dev rp-markdown-docs

# Or use with npx (no installation required)
npx rp-markdown-docs init my-docs
npx mdocs generate --watch

Initialize a New Project

# Create a new documentation project
mdocs init my-docs

# Navigate to the project
cd my-docs

# Start developing
mdocs generate --watch

Generate Documentation

# Generate from current directory
mdocs generate

# Generate from specific directory
mdocs generate ./docs --output ./dist

# Watch for changes during development
mdocs generate --watch

Serve Locally

# Serve generated documentation
mdocs serve

# Serve on specific port
mdocs serve --port 8080 --open

📁 Project Structure

my-docs/
├── docs/                    # Your markdown files
│   ├── index.md            # Homepage
│   ├── getting-started/
│   │   └── installation.md
│   ├── api/
│   │   └── overview.md
│   └── guides/
│       └── configuration.md
├── mdocs.config.js         # Configuration file
└── package.json

⚙️ Configuration

Create a mdocs.config.js file in your project root:

module.exports = {
  // Basic settings
  title: 'My Documentation',
  description: 'Comprehensive documentation for my project',
  baseUrl: '/',
  
  // Theme customization
  theme: {
    primaryColor: '#3B82F6',
    accentColor: '#10B981',
    darkMode: true
  },
  
  // Navigation
  navigation: {
    logo: 'My Docs',
    links: [
      { text: 'GitHub', url: 'https://github.com/username/repo' },
      { text: 'NPM', url: 'https://npmjs.com/package/my-package' }
    ]
  },
  
  // Features
  features: {
    search: true,
    tableOfContents: true,
    lastModified: true
  }
};

📝 Markdown Features

Frontmatter Support

Add metadata to your markdown files:

---
title: Getting Started
description: Learn how to get started with our platform
tags: [guide, beginner]
author: John Doe
date: 2024-01-15
---

# Getting Started

Your content here...

Code Syntax Highlighting

Supports all major programming languages:

```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

```python
def hello(name):
    print(f"Hello, {name}!")
```

```bash
npm install my-package
```

Advanced Markdown Features

• ✅ Tables
• ✅ Task lists
• ✅ Code syntax highlighting
• ✅ Emoji support

🎨 Theming

Theme Customization

Customize colors and appearance:

module.exports = {
  theme: {
    primaryColor: '#3B82F6',
    accentColor: '#10B981',
    darkMode: true
  }
};

🔍 Features

• Search - Full-text search with fuzzy matching
• Table of Contents - Automatic TOC generation with active section highlighting
• Theming - Multiple themes with dark/light mode support
• Responsive Design - Mobile-friendly interface
• Code Highlighting - Syntax highlighting for multiple languages
• Live Reload - Watch mode for development

📦 Build & Deploy

Build for Production

# Build optimized static files
mdocs build

# Build with custom config
mdocs build --config ./custom.config.js

Deploy to Popular Platforms

Netlify

# Build command
mdocs build

# Publish directory
dist

Vercel

{
  "buildCommand": "mdocs build",
  "outputDirectory": "dist"
}

GitHub Pages

# .github/workflows/docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: mdocs build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

🛠️ CLI Reference

Commands

# Initialize new project
mdocs init [directory] [options]

# Generate documentation
mdocs generate [input] [options]

# Build for production
mdocs build [input] [options]

# Serve locally
mdocs serve [directory] [options]

Options

# Global options
--config, -c     Configuration file path
--help, -h       Show help
--version, -v    Show version

# Generate options
--output, -o     Output directory
--watch, -w      Watch for changes
--base-url       Base URL for the site

# Serve options
--port, -p       Port to serve on
--open, -o       Open browser automatically

🎯 Examples

Basic Documentation Site

# Initialize
mdocs init my-docs

# Add content
echo "# Welcome" > docs/index.md
echo "# Getting Started" > docs/getting-started.md

# Generate and watch
mdocs generate --watch

Documentation with Code Examples

---
title: Getting Started
description: Learn how to get started
---

# Getting Started

Welcome to the documentation!

## Installation

```bash
npm install my-package

Basic Usage

import { MyPackage } from 'my-package';

const instance = new MyPackage();
instance.init();

🤝 Contributing

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

Development Setup

# Clone the repository
git clone https://github.com/ratpi-studio/markdown-doc-generator.git

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

🙏 Acknowledgments

• React - UI library
• Vite - Build tool
• Tailwind CSS - Styling framework
• Fuse.js - Fuzzy search
• Highlight.js - Syntax highlighting

📄 License

MIT License - see the LICENSE file for details.