Apps on Azure Blog

3 MIN READ

Deploy Mkdocs page on Azure Web App

Microsoft

Oct 18, 2024

MkDocs is a simple static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

This tutorial will demonstrate how to host an Mkdocs project dynamically or statically. You can choose either method to publish your project based on your needs, and the two approaches are independent of each other.

TOC:

Dynamic Hosting in Development Environment
Static Hosting in Development Environment
Dynamic Method: Using Python Web App
Static Method: Using Node Web App
Static Method: Using Static Web App
References

Dynamic Hosting in Development Environment

STEP 1:

Use VSCode to open an empty folder. Start a terminal and input the following commands 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 commands to create an Mkdocs project (for example, my-project), switch to the project directory, and start the project. You will then be able to visit the project page in your browser at http://127.0.0.1:8000.

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

Static Hosting in Development Environment

STEP 1:

Once the project is created in the development environment, the pages originally displayed must be rendered using Python and the Mkdocs package. We can run the following commands to build these pages into pure static HTML, making them deployable to any static website hosting service, such as Azure Static Website or the Azure Web App introduced here.

After the project is built, you will find the corresponding static web pages in the newly created site subfolder. You can open index.html in your browser to see the project page.

mkdocs build

Dynamic Method: Using 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:

Deploy the root directory of the project to the Python app you just created using VSCode.

STEP 4:

On Azure, find the Python app and modify the startup command as follows, then restart the app.

bash /home/site/wwwroot/mkdocs.sh

STEP 5:

Check if your project is running correctly.

Static Method: Using Node Web App

STEP 1:

Create a Linux Node Web App on Azure.

STEP 2:

In the Mkdocs subfolder of your project, find the site folder, and add a .deployment file inside it.

.deployment

[config]
SCM_DO_BUILD_DURING_DEPLOYMENT=false

STEP 3:

Deploy the "site" subdirectory of your project to the Node app you just created using VSCode.

STEP 4:

On Azure, find the Node app, modify the startup command, and restart the app.

command -v http-server >/dev/null 2>&1 || npm install -g http-server ; pm2-runtime http-server --name "static-server" -- /home/site/wwwroot -p 8080 -c-1

STEP 5:

Check if your project is running correctly.

Static Method: Using Static Web App

STEP 0:

You can create a GitHub repository for the entire project folder (for example, I've named it mkdocs-app), or you may choose to only upload the "site" subdirectory, depending on your needs. In this example, I'll use the entire project folder.

STEP 1:

Create a Static Web App on Azure and specify your project's GitHub repository and the corresponding branch during the process. Please note that you'll also need to set your App Location/Output Location as follows, adjusting the name to your "mkdocs project" (for example, my-project).

./my-project/site

STEP 2:

Once the SWA is created, you can check the deployment status in the GitHub repository. After the deployment is complete, you'll be able to see the actual page.