Deploy Mkdocs page on Azure Web App

MkDocs is a simple static site generator geared toward creating project documentation. The document source file is written in Markdown and consists of a single YAML configuration file.

This tutorial shows how to host a Mkdocs project dynamically or statically. You can choose either method to publish your project depending on your needs; the two approaches are independent of each other.

index:

Dynamic hosting of your development environment

Step 1:

Open an empty folder using VSCode. Launch a terminal and enter the following command to create a Python virtual environment and switch the current session to this environment.

windows

python -m venv .venv
.\.venv\Scripts\Activate.ps1

linux

python -m venv .venv
source .venv/Scripts/activate

Step 2:

Enter the following command to create a Mkdocs project (e.g. my-project), switch to the project directory, and start the project. You can then visit the project page in your browser. http://127.0.0.1:8000.

pip install mkdocs
mkdocs new my-project
cd my-project
mkdocs serve

Static hosting of your development environment

Step 1:

When a project is created in a development environment, the originally displayed pages must be rendered using Python and the Mkdocs package. You can run the following command to build these pages as pure static HTML and deploy them to a static website hosting service, such as Azure Static Websites or Azure Web Apps featured here.

Once the project is built, you can find the corresponding static web page in the newly created site subfolder. You can view the project pages by opening index.html in your browser.

mkdocs build

Dynamic way: Using a Python web app

Step 1:

Create a Linux Python web app on Azure.

Step 2:

Using VSCode, add two files: “mkdocs.sh” and “.deployment” to the root directory of your project.

mkdocs.sh

pip install mkdocs
cd /home/site/wwwroot/my-project/
mkdocs serve -a 0.0.0.0:8000

.deployment

[config]
SCM_DO_BUILD_DURING_DEPLOYMENT=false

Step 3:

Using VSCode, deploy the root directory of your project into the Python app you just created.

Step 4:

Find your Python app in Azure, modify the launch command as follows, and then restart the app:

bash /home/site/wwwroot/mkdocs.sh

Step 5:

Make sure your project is running correctly.

Static Method: Using Node Web App

Step 1:

Create a Linux node web app in Azure.

Step 2:

In the project’s Mkdocs subfolder, locate the site folder and add a .deployment file within it.

.deployment

[config]
SCM_DO_BUILD_DURING_DEPLOYMENT=false

Step 3:

Using VSCode, deploy the project’s “site” subdirectory into the Node app you just created.

Step 4:

Find the Node app in Azure, modify the launch command, and restart the app.

pm2 serve /home/site/wwwroot --no-daemon

Step 5:

Make sure your project is running correctly.

Static way: Use a static web app

Step 0:

You can create a GitHub repository for the entire project folder (e.g., name it mkdocs-app), or choose to upload only the “site” subdirectory as needed. For this example, we will use the entire project folder.

Step 1:

Create a static web app in Azure and specify the project’s GitHub repository and its branch during the process. You also need to rename it to “mkdocs project” (e.g. my-project) and set the app location/output location to: