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:
- Azure Subscription: An active Azure subscription with appropriate permissions to create resources (Resource Groups, Storage Accounts).
- Azure DevOps Project: A project in Azure DevOps.
- MkDocs Project:
- Your MkDocs documentation source files (Markdown) are committed to a Git repository (Azure Repos).
- A valid
mkdocs.ymlconfiguration file. - A
requirements.txtfile 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
-
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.
-
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
$webcontainer.
-
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@4to copy thesitedirectory contents to the$webcontainer of your Storage Account.
- Python Version:
- 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.
-
Testing and Continuous Deployment:
- Push a change to your designated branch.
- The pipeline will build the MkDocs site and copy the files to the
$webcontainer. - 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
$webcontainer. For internal-only documentation, consider using Private Endpoints or IP restrictions.
General Best Practices for MkDocs Documentation
- Documentation as Code (Docs-as-Code):
- Store all Markdown source files and
mkdocs.ymlin a Git repository. - Treat documentation like code: use version control, pull requests, and code reviews for changes.
- Store all Markdown source files and
- Consistency: Adhere to consistent naming conventions, formatting, and content standards throughout your documentation.
- Modular Content: Break down large topics into smaller, manageable Markdown files.
- Search Functionality: Ensure your
mkdocs.ymlis configured to enable the search plugin (usually enabled by default with most themes). - Testing:
- Run
mkdocs servelocally to preview changes before committing. - Implement automated link checking in your CI/CD pipeline to catch broken links.
- Run
- Theme Selection: Choose an appropriate MkDocs theme (e.g., MkDocs-Material) for improved readability and user experience.
- Dependencies: Keep
requirements.txtup to date with all MkDocs and plugin dependencies. - Clear Navigation: Design a logical
navstructure inmkdocs.ymlfor easy content discovery.
Troubleshooting Common Issues
- 404 Errors:
- Verify Output location (
site) in Static Web App orSourcePathin AzureFileCopy task. - Check
index.htmland404.htmlnames in Storage Account static website settings. - Ensure file paths in Markdown links are correct and relative.
- Verify Output location (
- Build Failures:
- Check pipeline logs for Python version issues, missing dependencies (
pip install -r requirements.txt), ormkdocs builderrors. - Ensure the
mkdocs.ymlsyntax is valid.
- Check pipeline logs for Python version issues, missing dependencies (
- Deployment Failures:
- Verify Azure Service Principal permissions.
- Check AzureFileCopy task logs for access denied errors.
- Search Not Working:
- Ensure the MkDocs search plugin is enabled in
mkdocs.yml. - Clear browser cache after deployment.
- Ensure the MkDocs search plugin is enabled in
References
- How to use MkDocs features while drafting content in any IDE (for example, Cursor or VS Code).