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.
STEP 3:
Verify that your project is running properly.
References
Azure Linux Web App and http server - Microsoft Community Hub
Quickstart: Build your first static web app | Microsoft Learn