DEV Community

Peter Krighaar
Peter Krighaar

Posted on

1 1

Versioned documentation on Azure

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'
Enter fullscreen mode Exit fullscreen mode

The first part

trigger:
- master
Enter fullscreen mode Exit fullscreen mode

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

Billboard image

Deploy and scale your apps on AWS and GCP with a world class developer experience

Coherence makes it easy to set up and maintain cloud infrastructure. Harness the extensibility, compliance and cost efficiency of the cloud.

Learn more

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more