mkDocs on Azure App Service + CD with VSTS

Our team uses mkDocs as an internal wiki; a simple static site generator, it’s easy to host anywhere. At Microsoft, Azure is our go-to for internal services like this, and so we use Azure App Service as our deployment target. Though a PaaS offering, it works quite well for static sites as well - files deployed to the server root are served up by the IIS proxy that sits in front of the site.

Our mkDocs builds and deployments are managed by Visual Studio Team Services using the new YAML Builds. Every time a commit is made to the master branch, a new build is triggered; if succesful, the contents of the site directory on the build server are pushed to our docs site, ensuring it’s always up-to-date.

This is how we got everything up and running.

1. Create a VSTS repository that will hold all the source for your mkDocs site.
2. Follow the Getting Started guide on the mkDocs site and perform all the initial configuration. When you’ve finished, initialize a git repository in that folder and add the VSTS repository you added in Step 1 as a remote.
3. Create an Azure AppService plan that will host your App Service; the free SKU should be sufficient: az appservice plan create --name $name --resource-group $rg --sku f1
4. Navigate to App Services Blade in the Azure Portal and create a new App Service using the AppService Plan created in Step #1.

5. Create a .vsts-ci.yml file in the root of your repository with the following content. Replace $name with the name of the AppService you created in the previous step:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
       resources:
       - repo: self
       queue:
         name: Hosted Linux Preview
       steps:
       - task: CmdLine@1
         inputs:
           filename: pip
           arguments: 'install -U setuptools'
       - task: CmdLine@1
         inputs:
           filename: pip
           arguments: 'install -r requirements.txt'
       - task: CmdLine@1
         inputs:
           filename: mkdocs
           arguments: build
       - task: AzureRmWebAppDeployment@3
         inputs:
           azureSubscription: 'your subscription ID'
           WebAppName: $name
           Package: 'site/'

6. Now create a custom_theme directory in the root of your repository and create a file inside called web.config like so:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   <?xml version="1.0"?>
   <configuration>
     <system.webServer>
       <staticContent>
         <mimeMap fileExtension=".json" mimeType="application/json" />
         <mimeMap fileExtension=".mustache" mimeType="text/template" />
         <remove fileExtension=".woff" />
         <remove fileExtension=".woff2" />
         <mimeMap fileExtension=".woff" mimeType="application/font-woff" />
         <mimeMap fileExtension=".woff2" mimeType="application/font-woff2" />
       </staticContent>
     </system.webServer>
   </configuration>

   The contents of custom_theme are copied to the site directory on build; in this case, it’s used to tell the IIS proxy that the listed file extensions should be served as static files. Without this, search will be broken for your mkDocs site.

7. Commit and push your changes. VSTS should automatically create a build definition and trigger the build for you. You should now be able to navigate to your App Service URL and test out your site. Happy documenting!