T
theringe
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
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
Linux
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.
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.
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
.deployment
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.
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
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.
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).
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
MkDocs
Azure Linux Web App and http server - Microsoft Community Hub
Quickstart: Build your first static web app | Microsoft Learn
Continue reading...
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
Code:
python -m venv .venv
.\.venv\Scripts\Activate.ps1Linux
Code:
python -m venv .venv
source .venv/Scripts/activateSTEP 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.
Code:
pip install mkdocs
mkdocs new my-project
cd my-project
mkdocs serveStatic 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 buildDynamic 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
Code:
pip install mkdocs
cd /home/site/wwwroot/my-project/
mkdocs serve -a 0.0.0.0:8000.deployment
Code:
[config]
SCM_DO_BUILD_DURING_DEPLOYMENT=falseSTEP 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.shSTEP 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
Code:
[config]
SCM_DO_BUILD_DURING_DEPLOYMENT=falseSTEP 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.
pm2 serve /home/site/wwwroot --no-daemonSTEP 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/siteSTEP 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
MkDocs
Azure Linux Web App and http server - Microsoft Community Hub
Quickstart: Build your first static web app | Microsoft Learn
Continue reading...