Deploying MkDocs in Azure DevOps

Recommended process and best practices for deploying and maintaining MkDocs-based documentation sites on Azure using Blob Storage static website hosting and Azure DevOps CI/CD.

This article outlines the recommended process and best practices for deploying and maintaining MkDocs-based documentation sites using Azure Cloud services, primarily focusing on Azure Blob Storage with Static Website Hosting.

Overview

MkDocs is a static site generator ideal for project documentation. By leveraging Azure's static hosting capabilities and Azure DevOps for CI/CD, we can achieve automated, version-controlled, and highly available documentation deployment.

Key Azure Services Involved:

  • Azure DevOps: For Git repositories, Pipelines (CI/CD).
  • Azure Blob Storage with Static Website Hosting (Alternative): A cost-effective option for hosting static files directly from a storage account.
  • Azure CDN / Front Door: For global content delivery and performance optimisation.

Prerequisites

Before starting the deployment process, ensure the following are in place:

  1. Azure Subscription: An active Azure subscription with appropriate permissions to create resources (Resource Groups, Storage Accounts).
  2. Azure DevOps Project: A project in Azure DevOps.
  3. MkDocs Project:
    • Your MkDocs documentation source files (Markdown) are committed to a Git repository (Azure Repos).
    • A valid mkdocs.yml configuration file.
    • A requirements.txt file listing MkDocs and theme/plugin dependencies (e.g., mkdocs-material).

Azure Blob Storage with Static Website Hosting

This method involves storing the static HTML files generated by MkDocs in an Azure Storage Account configured for static website hosting.

Steps

  1. Create Azure Storage Account:

    • Navigate to the Azure Portal.
    • Search for "Storage accounts" and click "Create."
    • Basics: Choose Subscription, Resource Group, Storage Account name, region.
    • Performance/Redundancy: Select Standard performance and locally redundant storage (LRS) for basic needs. For critical docs, consider ZRS or GRS.
    • Review and create.
  2. Enable Static Website Hosting:

    • Once the Storage Account is created, navigate to it in the Azure Portal.
    • Under Data management, click on Static website.
    • Set Static website to Enabled.
    • Set Index document name to index.html.
    • Set Error document path to 404.html (if you have one in your MkDocs output).
    • Save. Note down the Primary endpoint URL; this is your site's URL. This creates a $web container.
  3. Configure Azure DevOps Pipeline:

    • Create a new YAML pipeline in Azure DevOps.
    • Tasks:
      • Python Version: UsePythonVersion@0
      • Install Dependencies: script task (pip install -r requirements.txt)
      • Build MkDocs: script task (mkdocs build)
      • Azure File Copy Task: Use AzureFileCopy@4 to copy the site directory contents to the $web container of your Storage Account.
    - task: AzureFileCopy@4
      inputs:
        SourcePath: '$(Build.SourcesDirectory)/site/*' # Path to the built MkDocs output
        azureSubscription: '<Your Azure Service Connection Name>' # Name of your Azure service connection
        Destination: 'AzureBlob'
        storage: '<Your Storage Account Name>'
        ContainerName: '$web'
      displayName: 'Deploy MkDocs to Azure Blob Storage'

    Note: Ensure your Azure Service Connection has Storage Blob Data Contributor permissions on the Storage Account.

  4. Testing and Continuous Deployment:

    • Push a change to your designated branch.
    • The pipeline will build the MkDocs site and copy the files to the $web container.
    • Access the site using the Primary endpoint URL from the Storage Account's static website settings.

Best Practices for Azure Blob Storage

  • Azure CDN Integration: For better performance and global distribution, create an Azure CDN endpoint and link it to your static website endpoint.
  • Custom Domains: Configure custom domains through Azure CDN rather than directly on the storage account for better capabilities.
  • Security: Ensure the storage account is configured for public read access to the $web container. For internal-only documentation, consider using Private Endpoints or IP restrictions.

General Best Practices for MkDocs Documentation

  1. Documentation as Code (Docs-as-Code):
    • Store all Markdown source files and mkdocs.yml in a Git repository.
    • Treat documentation like code: use version control, pull requests, and code reviews for changes.
  2. Consistency: Adhere to consistent naming conventions, formatting, and content standards throughout your documentation.
  3. Modular Content: Break down large topics into smaller, manageable Markdown files.
  4. Search Functionality: Ensure your mkdocs.yml is configured to enable the search plugin (usually enabled by default with most themes).
  5. Testing:
    • Run mkdocs serve locally to preview changes before committing.
    • Implement automated link checking in your CI/CD pipeline to catch broken links.
  6. Theme Selection: Choose an appropriate MkDocs theme (e.g., MkDocs-Material) for improved readability and user experience.
  7. Dependencies: Keep requirements.txt up to date with all MkDocs and plugin dependencies.
  8. Clear Navigation: Design a logical nav structure in mkdocs.yml for easy content discovery.

Troubleshooting Common Issues

  1. 404 Errors:
    • Verify Output location (site) in Static Web App or SourcePath in AzureFileCopy task.
    • Check index.html and 404.html names in Storage Account static website settings.
    • Ensure file paths in Markdown links are correct and relative.
  2. Build Failures:
    • Check pipeline logs for Python version issues, missing dependencies (pip install -r requirements.txt), or mkdocs build errors.
    • Ensure the mkdocs.yml syntax is valid.
  3. Deployment Failures:
    • Verify Azure Service Principal permissions.
    • Check AzureFileCopy task logs for access denied errors.
  4. Search Not Working:
    • Ensure the MkDocs search plugin is enabled in mkdocs.yml.
    • Clear browser cache after deployment.

References

On this page