Publish to Azure Web App#

Markdown generated with PSDocs for Azure can be published as HTML for viewing with Azure App Service. Using Azure App Service our docs site can be secured for internal use or shared with authorized guests.

Abstract

This topic covers using a pipeline to publish HTML generated by PSDocs for Azure into an Azure Web App.

Generating docs site#

To publish documentation to an Azure Web App, we need to generate HTML from markdown. There are several widely used tools that help you do this. Two open source examples are:

MkDocs — A Python-based static site generator. MkDocs is fast and can be customized with corporate branding fairly easily. A wide-range of themes are also available.
DocFX — A .NET-based static site generator. DocFX is slightly easier to get up and running but require more work to customize and brand.

With MkDocs#

Markdown content generated with PSDocs for Azure can be published as HTML with MkDocs. MkDocs is a command-line tool that converts markdown into HTML.

Tip

We recommend you start from our Quick Start template.

GitHub Actions

Extend your GitHub Actions workflow .github/workflows/publish-docs.yaml created previously by completing the following steps:

Add the following steps to install and build documentation with MkDocs.

- name: Setup Python
  uses: actions/setup-python@v2.2.2
  with:
    python-version: '3.9'
    architecture: 'x64'

- name: Install dependencies
  run: |
    python3 -m pip install --upgrade pip
    python3 -m pip install wheel
    python3 -m pip install -r requirements-docs.txt

- name: Build site
  run: mkdocs build

Create a convention to name and add metadata to output markdown files. A conventions allows generated markdown to be modified before it is written. We use one with MkDocs to add front matter to markdown files and organize them.

Update action parameters to set output path and reference convention.

# Generate markdown files using PSDocs
# Scan for Azure template file recursively in sub-directories
- name: Generate docs
  uses: microsoft/ps-docs@main
  with:
    conventions: AddMkDocsMeta
    modules: PSDocs,PSDocs.Azure
    outputPath: docs/azure/templates/
    prerelease: true

Create a mkdocs.yaml file in the root of the repository. This file configures MkDocs. By configuring this file you can change common settings such as theme and layout.

Create a requirements-docs.txt file in the root of the repository. This file is used by Python to install the required package dependencies.

Publishing docs#

With documentation generated as HTML the content can be published to an Azure web app.

GitHub Actions

Extend your GitHub Actions workflow .github/workflows/publish-docs.yaml created previously by completing the following steps:

Add the following steps to publish documentation to Azure App Service.

- name: Azure Login
  uses: azure/login@v1.3.0
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}

- name: Publish to Azure
  run: |
    cd ./site
    az webapp up -l '<enter>' -n '<enter>' -g '<enter>' --subscription '<enter>' --html

Create an deployment credentials AZURE_CREDENTIALS for the workflow to use to authenticate to Azure.
Set -l with the location of the Web App. e.g. eastus.
Set -n with the name of the Web App.
Set -g with the name of the Resource Group containing the Web App.
Set --subscription with the name or GUID of the subscription to deploy to.

Configuring authorization#

Azure Web Apps have built-in support for integrated with Azure AD. By using this feature Azure AD takes care of all the heavy lifting in regards to auth.

Read Configure your App Service or Azure Functions app to use Azure AD login to find out how to configure it.

Last update: 2022-05-19