Getting the docs site up and running

Start with the end in mind. This site will be hosted as a static site on an Azure storage account and will be published there with an Azure DevOps CI/CD pipeline. So you will need a few things to make this work. If you don't want to publish it on a Azure storage count static site then skip to the section called 'Create mkdocs project'.

What you will need:

Active Azure Subscription
Azure DNS
Azure Storage Account
Azure CDN
Azure DevOps Organization and a project to save your work to.

Create a static site

For this we will use a Azure Storage account.

Create a resource group

This resource group will house both the Azure Storage Account and the CDN that you will create.

Create the Azure Storage Account

Login to your subscription and Create a Storage Account Resource. If you have not done this before it would be good to follow this document Create a storage account

Create the Static Site

The following document will show you how to create the static site on your Azure Storage Account Static website hosting in Azure Storage

Create a Content Delivery Network

I followed the following document to setup my CDN Integrate a static website with Azure CDN

Create a project

Creating a new ADO project requires an existing ADO organization if you don't have one you can create it using this document Create ADO Organization. After you created the ADO Organization create a new Project in the Organization. Follow this guide to Create a project in Azure DevOps

Clone the repo down to your workstation

Navigate to Repos and then click on the repo you created then click on the "Clone" button. If you have VS Code installed click on the Clone in VS Code button and follow the instructions.

Create an Azure DevOps Service Connection

Create a new Azure DevOps service connection that points to the resource group that you created earlier. This guide will help Create an Azure Resource Manager service connection using automated security Note the name of the service connection that you create.

Create mkdocs project

First you will need to install Chocolatey to be able to install Python which is required to run the install of MkDocs. In a powershell terminal (run as administrator) navigate to the root of the repo and run the following commands.

Install Chocolatey

Set-ExecutionPolicy Bypass -Scope Process -Force;
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Install Python

Be sure to use a elevated powershell terminal

choco install -Y python

Installing MkDocs

For full instructions on MkDocs you can visit this site MkDocs

To install MkDocs, run the following command from the command line:

pip install mkdocs

Creating a new MkDocs project

The rest of the instructions can be done on a normal PowerShell terminal. Navigate to the path where the site files will be stored.


mkdocs new my-project
cd my-project

I actually got rid o the my project folder and copied the content thereof to the root of the repo.

Create git ignore file

Add site/ in the file gitignore file content

site/

Creating the ADO Pipeline

Create a folder called ado_pipelines

New-Item -Path ".\" -Name "ado_pipelines" -ItemType "directory"
----or----
md ado_pipelines

Create a new Azure DevOps (ADO) pipeline yml file

cd ado_pipelines
New-Item -Name docs.build.yml

Add the following to the file and save

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
# Install MkDocs
- task: PowerShell@2
  displayName: PIP_Install_MkDocs
  inputs:
    targetType: 'inline'
    script: 'pip install mkdocs'

# Build MkDocs
- task: PowerShell@2
  displayName: MkDocs_Build
  inputs:
    targetType: 'inline'
    script: 'mkdocs build'

#  Listing the Azure DevOps pipeline agent directory
- powershell: |
    Write-Output "Listing the Azure DevOps pipeline agent directory with downloaded artifacts"
    Write-Output "--START----------------"
    get-childitem $(System.DefaultWorkingDirectory)/ -Recurse
    Write-Output "--END------------------"
  displayName: 'List Artifacts'
  condition: succeeded()
  continueOnError: false

- task: AzureCLI@2
  displayName: 'Copy site files to storage account'
  inputs:
    azureSubscription: '<INSERT THE NAME OF THE ADO SERVICE CONNECTION>'
    scriptType: 'pscore'
    scriptLocation: 'inlineScript'
    inlineScript: |
      az configure --defaults group='<INSERT THE NAME OF THE RESOURCE GROUP>'
      $destination = '$web'
      az storage blob upload-batch -s site -d '$web' --account-name <INSERT THE NAME OF THE STORAGE ACCOUNT>