Skip to content

Setting up MkDocs Documentation

Estimated time to read: 5 minutes

Setting up MkDocs Documentation

MkDocs is a powerful, modern documentation framework that transforms Markdown files into professional-looking websites. In this lab, you'll learn to set up, configure, and customize MkDocs for workshop documentation. You'll explore the directory structure, configuration options, and essential plugins that make MkDocs ideal for creating engaging, maintainable workshop materials.

What You'll Learn

In this lab, you will:

  • Install and configure MkDocs for workshop documentation
  • Understand the MkDocs directory structure and organization
  • Configure essential plugins for enhanced functionality
  • Customize themes and styling for your workshop brand
  • Set up live preview and development workflows

Prerequisites

  • Completion of Lab 1: Understanding Your Audience
  • Completion of Lab 2: Workshop Structure & Content Design
  • Python 3.7+ installed on your system
  • Basic familiarity with command-line operations
  • A text editor or IDE (VS Code recommended)

Introduction

While you can create documentation using any Markdown tool, MkDocs provides specific advantages for workshop creators:

  • Live Preview: See changes instantly as you write
  • Professional Theming: Beautiful, responsive layouts out of the box
  • Plugin Ecosystem: Extend functionality with specialized features
  • Multi-language Support: Create workshops in multiple languages
  • Easy Deployment: Simple publishing to GitHub Pages or other platforms

MkDocs follows a "convention over configuration" approach, making it easy to get started while providing extensive customization options when needed. The framework is specifically designed for project documentation, making it a natural fit for workshop materials that need to be both informative and navigable.

Lab Exercise

You'll set up a complete MkDocs environment for your workshop, configure essential plugins, and create your first workshop documentation site.

Step 1: Quick MkDocs Setup

Set up your MkDocs development environment quickly using this workshop's configuration.

  1. Clone or copy this workshop repository as your starting point - it already includes:
  2. Pre-configured requirements.txt with essential packages
  3. Professional mkdocs.yml configuration

  4. Proper directory structure for workshop content

  5. Install the required packages:

    Bash
    1
    pip install -r requirements.txt

  6. Test your installation:

    Bash
    1
    mkdocs serve

Your site should be available at http://localhost:8000

Quick Start

Using this workshop's configuration as a template saves hours of setup time and ensures you're following documentation best practices from the start.

Step 2: Understanding the Directory Structure

This workshop uses a proven directory structure that supports professional workshop documentation:

Text Only
1
2
3
4
5
6
7
8
9
workshop-docs/
├── docs/
│   └── docs/
│       ├── en/              # English content
│       ├── includes/        # Reusable content snippets  
│       ├── media/           # Images and assets
│       └── css/             # Custom styling
├── mkdocs.yml              # Main configuration
└── requirements.txt        # Python dependencies

Key Benefits: - Clean separation of content and configuration - Multi-language support built-in - Reusable components via includes - Professional asset organization

Step 3: Configure MkDocs for Workshop Documentation

Update the mkdocs.yml configuration file with settings optimized for workshop content.

  1. Use this workshop's configuration as your starting point: Copy the mkdocs.yml file from this workshop repository as it already contains:
  2. Professional Material theme settings
  3. Essential plugins for workshop documentation
  4. Proper navigation structure
  5. Multi-language support configuration

  6. Code highlighting and interactive features

  7. Customize the configuration by updating:

  8. site_name: Your workshop title
  9. site_url: Your workshop website URL
  10. site_author: Your name or organization
  11. repo_name and repo_url: Your repository details
  12. Navigation items to match your workshop structure

Configuration Best Practices

  • Keep your navigation shallow (2-3 levels max)
  • Use descriptive, consistent naming for lab files
  • Enable search and code copy features for better user experience
  • Include reading time estimates for participant planning

Step 4: Test Your Setup

  1. Start the development server:
Bash
1
mkdocs serve -a localhost:8100
  1. Visit your site at http://localhost:8100 and verify:
  2. Navigation menu displays correctly
  3. Pages load without errors
  4. Live editing updates when you save changes
  5. Custom styling is applied

Development Workflow

The development server automatically reloads when you save changes, making content creation fast and efficient.

Quick Verification

Test your setup by confirming:

  • ✅ Development server runs without errors at http://localhost:8100
  • ✅ Navigation displays all workshop sections correctly
  • ✅ Live preview updates when you edit markdown files
  • ✅ Pages render with professional Material theme styling

Lab 3 Complete!

You now have a professional MkDocs environment ready for workshop content creation. In Lab 4, we'll explore advanced features to make your documentation more engaging and interactive.

Next Steps

In Lab 4, you'll learn advanced MkDocs features including:

  • Creating engaging admonition boxes and callouts
  • Implementing tabbed content for multiple options
  • Using includes for reusable content snippets
  • Adding interactive elements and media