samapriya/mkdocs-preview repository overview

⁠MkDocs Material Preview

A Flask web application that provides a real-time markdown editor with MkDocs Material theme preview. Perfect for creating and editing documentation with instant visual feedback using the beautiful Material Design theme.

⁠Quick Start

⁠Minimal Setup (Testing)

Just want to try it out? No volumes needed:

docker run -d \
  --name mkdocs-material-preview \
  -p 8291:5000 \
  -p 8000:8000 \
  samapriya/mkdocs-preview:latest

⁠Development Setup (With Persistence)

For ongoing work with your own documentation:

docker run -d \
  --name mkdocs-material-preview \
  -p 8291:5000 \
  -p 8000:8000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/mkdocs.yml:/app/mkdocs.yml \
  samapriya/mkdocs-preview:latest

⁠Production Setup (Full Customization)

For complete control with custom themes and configurations:

docker run -d \
  --name mkdocs-material-preview \
  -p 8291:5000 \
  -p 8000:8000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/mkdocs.yml:/app/mkdocs.yml \
  -v $(pwd)/overrides:/app/overrides \
  -v $(pwd)/includes:/app/includes \
  -v $(pwd)/templates:/app/templates \
  samapriya/mkdocs-preview:latest

Access the application at:

• Editor Interface: http://localhost:8291⁠
• Preview Interface: http://localhost:8000⁠

⁠✨ Features

• Split-panel interface with markdown editor and live preview
• MkDocs Material theme with dark/light mode toggle
• Advanced markdown extensions including code highlighting, admonitions, and Mermaid diagrams
• Real-time preview updates as you type
• Resizable panels for optimal editing experience
• Example content to get you started quickly

⁠🛠️ Docker Compose

⁠Basic Setup

version: '3.8'
services:
  mkdocs-material-preview:
    image: samapriya/mkdocs-preview:latest
    ports:
      - "8291:5000"
      - "8000:8000"
    restart: unless-stopped

⁠With Volume Persistence

version: '3.8'
services:
  mkdocs-material-preview:
    image: samapriya/mkdocs-preview:latest
    ports:
      - "8291:5000"
      - "8000:8000"
    volumes:
      - ./docs:/app/docs
      - ./mkdocs.yml:/app/mkdocs.yml
      - ./overrides:/app/overrides  # Optional: custom theme overrides
      - ./includes:/app/includes    # Optional: snippet includes
      - ./templates:/app/templates  # Optional: custom templates
    restart: unless-stopped

⁠🐳 Portainer Stack

⁠Basic Portainer Stack

For simple testing and evaluation:

version: '3.8'
services:
  mkdocs-material-preview:
    image: samapriya/mkdocs-preview:latest
    container_name: mkdocs-material-preview
    ports:
      - "8291:5000"
      - "8000:8000"
    environment:
      - FLASK_ENV=production
      - PYTHONUNBUFFERED=1
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - mkdocs-material-network

networks:
  mkdocs-material-network:
    driver: bridge

⁠Full Portainer Stack (With Volumes)

For production use with persistent data:

version: '3.8'
services:
  mkdocs-material-preview:
    image: samapriya/mkdocs-preview:latest
    container_name: mkdocs-material-preview
    ports:
      - "8291:5000"
      - "8000:8000"
    volumes:
      - mkdocs_docs:/app/docs
      - mkdocs_includes:/app/includes
      - mkdocs_overrides:/app/overrides
      - mkdocs_templates:/app/templates
      - mkdocs_config:/app/mkdocs.yml
    environment:
      - FLASK_ENV=production
      - PYTHONUNBUFFERED=1
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - mkdocs-material-network

networks:
  mkdocs-material-network:
    driver: bridge

volumes:
  mkdocs_docs:
    driver: local
  mkdocs_includes:
    driver: local
  mkdocs_overrides:
    driver: local
  mkdocs_templates:
    driver: local
  mkdocs_config:
    driver: local

⁠Portainer Deployment Steps:

1. Copy the stack configuration above
2. Go to Portainer → Stacks → Add Stack
3. Name your stack (e.g., "mkdocs-material-preview")
4. Paste the configuration in the web editor
5. Deploy the stack and wait for it to start
6. Access the application at your server's IP on ports 8291 and 8000

⁠📁 Volume Mounts (Optional)

The container includes default directories and configurations, so volumes are optional. Use them only when you need:

💡 Pro Tip: Start without any volumes to test the application, then add volumes as needed for persistence and customization.

⁠🌐 Port Configuration

⁠📋 Supported Features

⁠Markdown Extensions

• Code highlighting with line numbers and copy buttons
• Admonitions (notes, tips, warnings, etc.)
• Tabbed content for organized information
• Task lists with checkboxes
• Tables with enhanced styling
• Footnotes and abbreviations
• Mathematical expressions with MathJax
• Emoji support with Material Design icons

⁠Diagram Support

• Mermaid diagrams for flowcharts, sequence diagrams, and more
• Mathematical expressions with MathJax rendering

⁠Theme Features

• Material Design with modern UI components
• Dark/Light mode toggle
• Responsive design for mobile and desktop
• Search functionality built-in
• Navigation with tabs and sections

⁠⚙️ Environment Variables

⁠🔧 Configuration

The application uses your existing mkdocs.yml configuration file. If none exists, a default configuration will be created with:

• Material theme with dark/light mode
• Comprehensive markdown extensions
• Mermaid diagram support
• Code highlighting and copy buttons
• Search functionality

⁠📖 Usage Guide

⁠First Time Users

1. Start with minimal setup - no volumes needed:

   docker run -p 8291:5000 -p 8000:8000 samapriya/mkdocs-preview:latest
   

   Copy
2. Open the editor at http://localhost:8291⁠
3. Try the example content by clicking "Insert Example"
4. Write your own markdown in the left panel
5. Click "Update Preview" to see changes in the right panel

⁠For Persistent Work

1. Create your project directory with docs/ folder
2. Run with volume mounts to save your work
3. Customize mkdocs.yml as needed
4. Add theme overrides in the overrides/ folder if desired

⁠🏥 Health Check

The container includes a built-in health check that monitors the Flask application:

docker ps  # Check container health status

⁠🔍 Troubleshooting

⁠Container won't start

• Ensure ports 5000 and 8000 are available
• Check that mounted directories exist
• Verify mkdocs.yml is valid YAML

⁠Preview not updating

• Wait a few seconds after clicking "Update Preview"
• Check browser console for errors
• Ensure MkDocs service is running on port 8000

⁠Permission issues

• Ensure mounted directories have proper read/write permissions
• Run container with appropriate user mapping if needed

⁠📚 Example mkdocs.yml

site_name: My Documentation
theme:
  name: material
  palette:
    - scheme: default
      primary: blue
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: blue
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

plugins:
  - search
  - mermaid2

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.details

⁠🏷️ Tags

mkdocs mkdocs-material material-design documentation markdown flask live-preview editor mermaid python technical-writing

Perfect for: Technical writers, developers, documentation teams, and anyone who wants to create beautiful documentation with real-time preview capabilities.