Skip to content

Deploying a MkDocs Site with Azure Static Web Apps¶

This guide walks you through deploying a static website built with MkDocs to Azure Static Web Apps using GitHub Actions. It includes setup instructions, workflow configuration, and custom domain integration.

Project Overview¶

This site is built using MkDocs and hosted on Azure Static Web Apps. The deployment workflow is automated via GitHub Actions.

I created an MkDocs repository on my GitHub account, then cloned it locally on my Windows workstation. I use Visual Studio Code to edit content and configuration, and push changes back to GitHub for automatic deployment to Azure.

Why Azure Static Web Apps?¶

  • Free Tier: Ideal for personal projects and low-traffic sites.
  • CI/CD Integration: GitHub Actions automate deployment when changes are pushed.

Create an Azure Static Web App¶

Info

I won’t cover Terraform in depth here, but you can explore my Terraform module and configuration for inspiration.

Quick Setup for MkDocs on Azure Static Web Apps

  1. Create a Static Web App in the Azure portal
  2. Name it and choose the Free plan
  3. Select GitHub as your source and authorize access
  4. Pick your repo and branch where the MkDocs site lives
  5. Choose HTML as the framework (MkDocs outputs static HTML)
  6. Use a deployment token to let GitHub Actions publish the site to Azure

Once configured, Azure provides a randomized URL like:

https://green-smoke-0e35ce303.2.azurestaticapps.net/

SSL is automatically enabled. You can later configure a custom domain.

Azure Deployment Token¶

In your GitHub repository, go to Settings → Secrets → Actions and check for a secret named something like:

AZURE_STATIC_WEB_APPS_API_TOKEN_<SITE_NAME>

The part matches the name of your Static Web App in Azure. This token is automatically created when you link your GitHub repo during setup and is used by GitHub Actions to deploy your site securely. ' You need the name of this secret for the GitHub Action workflow in the next step.

GitHub Workflow Setup¶

Azure will have created a workflow in your GitHub repo already. You can use it for inspiration, but I prefer to make my own so I know exactly what happens. Create a new workflow file in .github/workflows, e.g., deploy-mkdocs-to-azure.yaml. Below is a working example tailored for MkDocs:

name: Deploy MkDocs to Azure Static Web Apps

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build_and_deploy_job:
    runs-on: ubuntu-latest
    name: Build and Deploy MkDocs Site
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
          cache: 'pip'

      - name: Install MkDocs and dependencies
        run: |
          pip install --upgrade pip  
          pip install --prefer-binary -r requirements.txt

      - name: Build MkDocs site
        run: mkdocs build

      - name: List contents of site folder
        run: ls -la site

      - name: Deploy to Azure Static Web Apps
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_THANKFUL_SMOKE_0EA7EBD03 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: upload
          app_location: "site"           # This is now the built folder
          skip_app_build: true           # Tells Azure not to build again

Deployment Confirmation¶

Once the workflow executes successfully, your site will be live on Azure. You can confirm deployment in the Azure portal:

Azure Static Web App Deployment Screenshot

Custom Domain Setup¶

If your DNS is hosted on Azure, just use the custom domain wizard in your web app to add your domain—Azure handles the verification for you.
If your DNS is managed elsewhere, follow your provider’s instructions to create a TXT or CNAME record that Azure can use to verify you own the domain.

To set up a custom URL for your site:

  1. Open your Azure Static Web App in the portal.
  2. Go to Custom domains.
  3. Click Add and select Custom Domain on other DNS.
  4. Enter your domain and choose TXT or CNAME for validation.
  5. Add the DNS record with your domain provider.

📚 Resources¶