MkDocs Documentation Guide

This guide explains how to build, serve, and deploy the Multi-Modal Academic Research System documentation using MkDocs with Material theme.

📋 Prerequisites

Python 3.9 or higher
pip package manager
Git (for deployment to GitHub Pages)

🚀 Quick Start

1. Install Dependencies

# Install MkDocs and Material theme
pip install -r requirements.txt

# Or install just documentation dependencies
pip install mkdocs==1.5.3 mkdocs-material==9.5.3 mkdocs-material-extensions==1.3.1 pymdown-extensions==10.7

2. Serve Documentation Locally

# From project root
mkdocs serve

# Documentation will be available at http://127.0.0.1:8000

The development server includes:

Live reload - Changes automatically reflected
Search - Full-text search functionality
Navigation - Interactive table of contents

3. Build Static Site

# Build documentation to site/ directory
mkdocs build

# Build with strict mode (fails on warnings)
mkdocs build --strict

# Clean build (remove site/ directory first)
mkdocs build --clean

🎨 Customization

Theme Configuration

Edit mkdocs.yml to customize:

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
  features:
    - navigation.tabs
    - navigation.instant
    - search.suggest

Adding Custom CSS

Create CSS file in docs/stylesheets/:

/* docs/stylesheets/custom.css */
.custom-class {
  color: #ff0000;
}

Reference in mkdocs.yml:

extra_css:
  - stylesheets/custom.css

Adding Custom JavaScript

Create JS file in docs/javascripts/:

// docs/javascripts/custom.js
console.log('Custom script loaded');

Reference in mkdocs.yml:

extra_javascript:
  - javascripts/custom.js

📚 Writing Documentation

Markdown Features

MkDocs Material supports extended Markdown syntax:

Admonitions

!!! note "Optional Title"
    This is a note admonition.

!!! tip
    This is a tip without a custom title.

!!! warning "Caution"
    This is a warning.

??? question "Collapsible Question"
    This admonition starts collapsed.

Code Blocks with Syntax Highlighting

```python
def hello_world():
    print("Hello, World!")
```

```bash
# Commands with highlighting
cd /path/to/directory
ls -la
```

Tabs

=== "Python"

    ```python
    print("Hello from Python")
    ```

=== "JavaScript"

    ```javascript
    console.log("Hello from JavaScript");
    ```

Mermaid Diagrams

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Emoji

:smile: :rocket: :tada:

📁 File Organization

project/
├── mkdocs.yml              # Main configuration
├── docs/                   # Documentation source
│   ├── index.md            # Home page
│   ├── setup/              # Setup guides
│   ├── tutorials/          # Tutorials
│   ├── api/                # API reference
│   ├── stylesheets/        # Custom CSS
│   ├── javascripts/        # Custom JS
│   └── assets/             # Images, files
└── site/                   # Built site (generated)

🔧 Navigation Structure

Edit navigation in mkdocs.yml:

nav:
  - Home: index.md
  - Getting Started:
      - Installation: setup/installation.md
      - Quick Start: setup/quick-start.md
  - Tutorials:
      - Tutorial 1: tutorials/tutorial1.md
      - Tutorial 2: tutorials/tutorial2.md

🚢 Deployment Options

Option 1: GitHub Pages

Automatic Deployment

# Deploy to GitHub Pages
mkdocs gh-deploy

# With custom commit message
mkdocs gh-deploy -m "Update documentation"

This command:

Builds the documentation
Pushes to gh-pages branch
GitHub Pages automatically serves the site

Manual Deployment

# Build the site
mkdocs build

# Commit and push site/ directory
git add site/
git commit -m "Update docs"
git push origin gh-pages

GitHub Actions

Create .github/workflows/docs.yml:

name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies
        run: |
          pip install mkdocs-material

      - name: Deploy
        run: mkdocs gh-deploy --force

Option 2: Netlify

Connect GitHub repository to Netlify
Configure build settings:
- Build command: mkdocs build
- Publish directory: site
Deploy

Option 3: Docker

Create Dockerfile.docs:

FROM python:3.9-slim

WORKDIR /docs

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]

Build and run:

# Build image
docker build -t docs -f Dockerfile.docs .

# Run container
docker run -p 8000:8000 docs

Option 4: ReadTheDocs

Create .readthedocs.yml:

version: 2

mkdocs:
  configuration: mkdocs.yml

python:
  version: "3.9"
  install:
    - requirements: requirements.txt

Connect repository to ReadTheDocs
Documentation builds automatically

🔍 Search Configuration

Built-in Search

Enabled by default in mkdocs.yml:

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|\.(?!\d)|&[lg]t;'
      lang:
        - en

Advanced Search Options

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|\.(?!\d)|&[lg]t;'
      lang:
        - en
        - es  # Multiple languages
      prebuild_index: true  # Faster search

📊 Analytics

Google Analytics

Add to mkdocs.yml:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Custom Analytics

Add tracking code in docs/javascripts/analytics.js:

// Custom analytics tracking
window.addEventListener('load', function() {
  // Your tracking code here
});

🎨 Theming

Color Schemes

theme:
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: pink
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: pink
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Logo and Favicon

theme:
  logo: assets/logo.png
  favicon: assets/favicon.png

🔧 Plugins

Essential Plugins

Already configured in mkdocs.yml:

search - Full-text search
minify - HTML/CSS/JS minification
git-revision-date-localized - Show last update dates
tags - Tag-based navigation

Additional Useful Plugins

# Install additional plugins
pip install mkdocs-awesome-pages-plugin
pip install mkdocs-macros-plugin
pip install mkdocs-redirects