mkDocs on Azure App Service + CD with VSTS
10. April 2018
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.
mkDocs builds and deployments are managed by Visual Studio Team
Services using the new YAML
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.
- Create a VSTS repository that will hold all the source for your
- Follow the Getting Started guide on
the mkDocs site and perform all the initial configuration. When you’ve
finished, initialize a
gitrepository in that folder and add the VSTS repository you added in Step 1 as a remote.
- 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
- Navigate to App Services Blade in the Azure Portal and create a new App Service using the AppService Plan created in Step #1.
.vsts-ci.ymlfile in the root of your repository with the following content. Replace
$namewith 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/'
Now create a
custom_themedirectory in the root of your repository and create a file inside called
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_themeare copied to the
sitedirectory 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
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!