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.

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:

\n
• Dynamic Hosting in Development Environment
\n
• Static Hosting in Development Environment
\n
• Dynamic Method: Using Python Web App
\n
• Static Method: Using Node Web App
\n
• \n

  Static Method: Using Static Web App

  \n
\n
• References
\n

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\n.\\.venv\\Scripts\\Activate.ps1

Linux

python -m venv .venv\nsource .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\nmkdocs new my-project\ncd my-project\nmkdocs 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\ncd /home/site/wwwroot/my-project/\nmkdocs serve -a 0.0.0.0:8000

.deployment

[config]\nSCM_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]\nSCM_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

MkDocs

Azure Linux Web App and http server - Microsoft Community Hub

Quickstart: Build your first static web app | Microsoft Learn

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:

\n
• Dynamic Hosting in Development Environment
\n
• Static Hosting in Development Environment
\n
• Dynamic Method: Using Python Web App
\n
• Static Method: Using Node Web App
\n
• \n

  Static Method: Using Static Web App

  \n
\n
• References
\n

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

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.