A modern, beautiful documentation generator that converts markdown files into interactive HTML documentation sites. Built with performance, accessibility, and user experience in mind.
# Install globally
npm install -g markdown-docs-generator
# Or install locally
npm install --save-dev markdown-docs-generator# Create a new documentation project
mdocs init my-docs
# Navigate to the project
cd my-docs
# Start developing
mdocs generate --watch# Generate from current directory
mdocs generate
# Generate from specific directory
mdocs generate ./docs --output ./dist
# Watch for changes during development
mdocs generate --watch# Serve generated documentation
mdocs serve
# Serve on specific port
mdocs serve --port 8080 --openmy-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
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,
logo: './assets/logo.svg'
},
// 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,
editOnGitHub: true,
lastModified: true,
analytics: 'GA_TRACKING_ID'
},
// GitHub integration
gitHub: {
repo: 'username/repository',
branch: 'main',
docsDir: 'docs'
},
// SEO
seo: {
sitemap: true,
robots: true,
openGraph: {
image: './assets/og-image.png',
twitterCard: 'summary_large_image'
}
}
};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...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
```- ✅ Tables with sorting
- ✅ Task lists
- ✅ Footnotes
- ✅ Math expressions (KaTeX)
- ✅ Mermaid diagrams
- ✅ Custom containers
- ✅ Emoji support
::: tip
This is a helpful tip for users.
:::
::: warning
This is a warning message.
:::
::: danger
This is a danger alert.
:::Customize the appearance using CSS variables:
:root {
--primary-color: #3B82F6;
--accent-color: #10B981;
--background-color: #ffffff;
--text-color: #1f2937;
--border-color: #e5e7eb;
}Add custom styles in your config:
module.exports = {
theme: {
customCSS: './custom.css',
fonts: {
body: 'Inter, sans-serif',
heading: 'Inter, sans-serif',
mono: 'JetBrains Mono, monospace'
}
}
};Extend functionality with plugins:
module.exports = {
plugins: [
'search',
'analytics',
'sitemap',
['custom-plugin', { option: 'value' }]
]
};- Search - Full-text search with indexing
- Analytics - Google Analytics, Plausible, etc.
- Sitemap - Automatic sitemap generation
- PWA - Progressive Web App features
- Comments - Disqus, Giscus integration
- Edit Links - GitHub edit links
# Build optimized static files
mdocs build
# Build with custom config
mdocs build --config ./custom.config.js# Build command
mdocs build
# Publish directory
dist{
"buildCommand": "mdocs build",
"outputDirectory": "dist"
}# .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# 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]# 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# Initialize
mdocs init my-docs
# Add content
echo "# Welcome" > docs/index.md
echo "# API Reference" > docs/api.md
# Generate
mdocs generate --watch// mdocs.config.js
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr', 'es'],
localeConfigs: {
en: { label: 'English' },
fr: { label: 'Français' },
es: { label: 'Español' }
}
}
};---
title: User API
description: User management endpoints
---
# User API
## GET /api/users
Retrieve a list of users.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| limit | number | Number of users to return |
| offset | number | Number of users to skip |
### Response
```json
{
"users": [
{
"id": "123",
"name": "John Doe",
"email": "john@example.com"
}
],
"total": 100
}
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/username/markdown-docs-generator.git
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Build for production
npm run build
MIT License - see the LICENSE file for details.
- Markdown-it - Markdown parser
- Prism.js - Syntax highlighting
- Fuse.js - Fuzzy search
- Tailwind CSS - Styling framework
Made with ❤️ by the Documentation Team
GitHub • NPM • Documentation