MDBook Documentation System

A modern GitBook-like documentation system that automatically creates beautiful documentation sites from Markdown files.

Features

• 📝 Markdown Support: All documentation written in Markdown format
• 🔍 Advanced Search: Fast search across all content
• 📱 Responsive Design: Mobile and desktop compatible
• 🎨 Modern Interface: Clean and user-friendly design
• ⚡ Fast: Optimized performance
• 🔧 Customizable: Theme and style customizations
• 📚 Auto Navigation: Automatic menu generation from file structure
• 🏷️ Categories: Organize documentation into categories
• ⚙️ Configuration: Full customization via JSON config
• 🎯 Dynamic Homepage: Category-based homepage with clickable cards
• 🔗 Breadcrumbs: Easy navigation with breadcrumb trails
• 💻 Syntax Highlighting: Code syntax highlighting with Prism.js
• 🌐 API Ready: RESTful API for programmatic access

Installation

1. Clone the project:

git clone <repository-url>
cd mdbook

2. Install dependencies:

npm install

3. Start the server:

npm start

4. Open http://localhost:3000 in your browser

Development

To run in development mode:

npm run dev

Quick Start Guide

1. Basic Setup

After installation, your documentation will be automatically generated from the docs/ folder. The system will:

• Scan all .md files in the docs/ directory
• Parse frontmatter metadata
• Generate navigation menus
• Create category-based organization

2. Adding Documentation

Simply add Markdown files to the docs/ folder:

docs/
├── README.md              # Home page
├── getting-started/       # Getting started guides
│   ├── installation.md
│   └── writing-docs.md
├── api/                   # API documentation
│   ├── authentication.md
│   └── endpoints.md
└── guides/                # Usage guides
    ├── basic-usage.md
    └── advanced-features.md

3. Frontmatter Configuration

Each Markdown file should start with YAML frontmatter:

---
title: "Page Title"
description: "Page description"
order: 1
category: "Category Name"
---

4. Customization

Edit config.json to customize your site:

{
  "site": {
    "title": "My Documentation",
    "description": "My awesome documentation"
  },
  "theme": {
    "primaryColor": "#2563eb"
  }
}

Configuration

Customize your site using the config.json file:

Site Settings

{
  "site": {
    "title": "My Documentation",
    "description": "My awesome documentation",
    "author": "My Name",
    "version": "1.0.0",
    "logo": "/images/logo.png",
    "favicon": "/images/favicon.ico"
  }
}

Theme Settings

{
  "theme": {
    "primaryColor": "#2563eb",
    "primaryHover": "#1d4ed8",
    "secondaryColor": "#64748b",
    "backgroundColor": "#ffffff",
    "sidebarBackground": "#f8fafc",
    "textColor": "#1e293b",
    "textMuted": "#64748b",
    "borderColor": "#e2e8f0",
    "hoverBackground": "#f1f5f9",
    "codeBackground": "#f1f5f9"
  }
}

Content Settings

{
  "content": {
    "welcomeTitle": "Welcome to My Documentation",
    "welcomeMessage": "Select a documentation from the left menu.",
    "loadingMessage": "Loading documentation...",
    "noDocsMessage": "No documentation found"
  }
}

Feature Settings

{
  "features": {
    "search": false,
    "breadcrumbs": true,
    "syntaxHighlighting": true,
    "responsive": true
  }
}

How to Use the System

1. Navigation System

• Sidebar Navigation: Automatically generated from your file structure
• Category Organization: Files are grouped by their category frontmatter
• Ordering: Files are sorted by their order frontmatter (default: 999)
• Icons: Automatic icon assignment based on file path and category

2. Homepage Features

• Dynamic Categories: Homepage displays all available categories as clickable cards
• Document Count: Shows number of documents in each category
• Quick Access: Click any category card to jump to its first document

3. Content Management

• Markdown Support: Full Markdown syntax support including:
  • Headers, lists, tables
  • Code blocks with syntax highlighting
  • Links, images, blockquotes
  • Custom HTML when needed
• Frontmatter: YAML metadata for each page
• Auto-reload: Changes are reflected immediately in development mode

4. Responsive Design

• Mobile-First: Optimized for mobile devices
• Collapsible Sidebar: Mobile-friendly navigation
• Touch-Friendly: Large touch targets for mobile users
• Adaptive Layout: Content adjusts to screen size

5. Search Functionality

• Full-Text Search: Search across all documentation content
• Real-Time Results: Instant search results as you type
• Highlighted Matches: Search terms are highlighted in results
• Context Snippets: Shows relevant text snippets from matches

Advanced Usage

6. File Organization

Organize your documentation using folders and frontmatter:

docs/
├── README.md              # Home page
├── getting-started/       # Getting started guides
│   ├── installation.md
│   └── writing-docs.md
├── api/                   # API documentation
│   ├── authentication.md
│   └── endpoints.md
└── guides/                # Usage guides
    ├── basic-usage.md
    └── advanced-features.md

7. Frontmatter Options

Each Markdown file can include these frontmatter options:

---
title: "Page Title"           # Display title
description: "Page description" # Meta description
order: 1                      # Sort order (lower = first)
category: "Category Name"     # Grouping category
---

8. Category Management

• Automatic Grouping: Files with the same category are grouped together
• Default Category: Files without a category go to "General"
• Category Icons: Automatic icon assignment based on category name
• Category Cards: Homepage shows clickable category cards

9. Styling and Theming

• CSS Variables: Easy theme customization via CSS custom properties
• Color Scheme: Customize primary, secondary, and background colors
• Typography: Consistent typography with system fonts
• Dark Mode Ready: CSS structure supports dark mode implementation

API Reference

The system provides a RESTful API for programmatic access:

Endpoints

• GET /api/config - Get configuration settings
• GET /api/docs - List all documentation files
• GET /api/docs/:path - Get specific documentation file
• GET /api/search?q=query - Search documentation

Example Usage

// Get configuration
const config = await fetch('/api/config');
const settings = await config.json();

// Get all documentation
const response = await fetch('/api/docs');
const docs = await response.json();

// Get specific documentation
const doc = await fetch('/api/docs/getting-started/installation');
const content = await doc.json();

// Search documentation
const results = await fetch('/api/search?q=installation');
const searchResults = await results.json();

API Response Format

Documentation List (/api/docs):

{
  "Getting Started": [
    {
      "path": "getting-started/installation.md",
      "title": "Installation",
      "description": "Learn how to install the system",
      "order": 1,
      "category": "Getting Started"
    }
  ],
  "API": [
    {
      "path": "api/authentication.md",
      "title": "Authentication",
      "description": "API authentication system",
      "order": 1,
      "category": "API"
    }
  ]
}

Document Content (/api/docs/:path):

{
  "title": "Installation",
  "description": "Learn how to install the system",
  "content": "<h1>Installation</h1><p>Follow these steps...</p>",
  "frontmatter": {
    "title": "Installation",
    "order": 1,
    "category": "Getting Started"
  }
}

Customization

Theme Customization

Edit the theme section in config.json:

{
  "theme": {
    "primaryColor": "#your-color",
    "backgroundColor": "#your-bg-color",
    "sidebarBackground": "#your-sidebar-color"
  }
}

Logo and Favicon

1. Add your logo and favicon files to the public/images/ folder
2. Specify their paths in config.json:

{
  "site": {
    "logo": "/images/your-logo.png",
    "favicon": "/images/your-favicon.ico"
  }
}

Adding New Features

1. Add new endpoints to server.js
2. Add frontend functions to public/app.js
3. Add necessary styles to public/styles.css

Development Workflow

1. Adding New Documentation

1. Create a new .md file in the docs/ folder
2. Add frontmatter with title, description, order, and category
3. Write your content in Markdown
4. The system will automatically detect and include it

2. Modifying the Interface

1. Edit public/styles.css for styling changes
2. Modify public/app.js for functionality changes
3. Update public/index.html for structural changes

3. Backend Customization

1. Add new routes in server.js
2. Modify the documentation parsing logic
3. Add new API endpoints as needed

Best Practices

Documentation Structure

• Use clear, descriptive titles
• Group related content in categories
• Use consistent frontmatter
• Keep file names lowercase with hyphens

Content Guidelines

• Write clear, concise documentation
• Use code examples where appropriate
• Include screenshots for complex procedures
• Keep content up-to-date

Performance Tips

• Optimize images before adding them
• Use relative links for internal navigation
• Keep individual pages focused and not too long
• Use the search feature to help users find content quickly

Troubleshooting

Common Issues

1. Files not appearing: Check that files are in the docs/ folder and have .md extension
2. Styling issues: Verify config.json syntax and CSS variable names
3. Navigation problems: Ensure frontmatter is properly formatted
4. Search not working: Check that search is enabled in config

Getting Help

• Check the console for error messages
• Verify file permissions and paths
• Ensure all dependencies are installed
• Review the configuration file syntax

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For issues and questions:

• Use GitHub Issues for bug reports
• Check the documentation for common solutions
• Review the configuration examples
• Test with the provided sample documentation