rp-markdown-docs/README.md

A modern, beautiful documentation generator that converts markdown files into interactive HTML documentation sites

# 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.

![Documentation Generator](https://img.shields.io/badge/docs-generator-blue?style=for-the-badge)
![Version](https://img.shields.io/npm/v/rp-markdown-docs?style=for-the-badge)
![License](https://img.shields.io/npm/l/rp-markdown-docs?style=for-the-badge)

## 🚀 Quick Start

### Installation

```bash
# 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

```bash
# Create a new documentation project
mdocs init my-docs

# Navigate to the project
cd my-docs

# Start developing
mdocs generate --watch
```

### Generate Documentation

```bash
# 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

```bash
# 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:

```javascript
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:

```markdown
---
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:

````markdown
```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:

```javascript
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

```bash
# Build optimized static files
mdocs build

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

### Deploy to Popular Platforms

#### Netlify

```bash
# Build command
mdocs build

# Publish directory
dist
```

#### Vercel

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

#### GitHub Pages

```yaml
# .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

```bash
# 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

```bash
# 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

```bash
# 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

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

# Getting Started

Welcome to the documentation!

## Installation

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

## Basic Usage

```javascript
import { MyPackage } from 'my-package';

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

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# 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](https://reactjs.org/) - UI library
- [Vite](https://vitejs.dev/) - Build tool
- [Tailwind CSS](https://tailwindcss.com/) - Styling framework
- [Fuse.js](https://fusejs.io/) - Fuzzy search
- [Highlight.js](https://highlightjs.org/) - Syntax highlighting

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

---

<div align="center">
  <p>Made with ❤️ by ratpi-studio.fr</p>
  <p>
    <a href="https://github.com/ratpi-studio/markdown-doc">GitHub</a> •
    <a href="https://npmjs.com/package/rp-markdown-docs">NPM</a>
  </p>
</div>