Versioned documentation on Azure

Peter Krighaar — Mon, 20 Dec 2021 07:10:21 +0000

MKDocs is maybe an older product when it comes to easy lightweight documentation sites. But it is so simple, for building powerful, and easy to read documentation. Built on top of ReadTheDocs

Some of the cool features:

version control
simple search (yet powerful)
easily write simple, yet powerful pages with Markdown syntax
Static, lightning fast

For a professional site, we needed a simple documentation site for the users to find helpful things.

As with all things in the real world, the documentation was not scheduled, or planned - but needed. Instead of using a PowerPoint as documentation or user guide, I remembered I once had stood in a similar situation, where we ended up using MKDocs

In order to create it using webapps, all we need is a yaml file in the root of our project azure-pipelines.yml

which will contain our pipeline behavior:

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.6'

- script: pip install mkdocs
  displayName: 'installing mkdocs'

- script: 'mkdocs build --clean'
  displayName: 'build mkdocs'

- task: AzureRmWebAppDeployment@4
  inputs:
    ConnectionType: 'AzureRM'
    azureSubscription: 'Name of subscription with ID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)'
    appType: 'webAppLinux'
    WebAppName: '{appname}'
    packageForLinux: 'site/'
    RuntimeStack: 'STATICSITE|1.0'

The first part

trigger:
- master

just sets the trigger, for the pipeline. -main is the branch we will listen for. So everytime we push changes to the main branch

DEV Community: Peter Krighaar

Versioned documentation on Azure