How to Install MkDocs on Debian 10

Tutorial on how to install MKDocs on Debian 10

MkDocs is a fast, simple and downright gorgeous 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.

Install MkDocs on Debian 10

Verify Python 3 is installed

$ python3 --version
Python 3.7.3

Install MkDocs

$ sudo apt install mkdocs
$ mkdocs --version
mkdocs, version 1.0.4 from /usr/lib/python3/dist-packages/mkdocs (Python 3.7)

Create a new project called mkdocs and build a new site

$ sudo mkdocs new mkdocs
$ cd mkdocs
$ sudo mkdocs build

Verify the following files are created successfully

$ ls /mkdocs
docs  mkdocs.yml  site  ssl
$ ls /mkdocs/site
404.html  css  fonts  img  index.html  js  search  sitemap.xml  sitemap.xml.gz

Install mkdocs-material

Install Python PIP and mkdocs-meterial theme

$ sudo apt install python3-pip
$ pip3 install mkdocs-material

Modify /mkdocs/mkdocs.yml to use mkdocs-meterial theme

kwyong@debian:/$ sudo nano /mkdocs/mkdocs.yml
site_name: My Docs

theme:
  name: material

Start mkdocs on IP Address = 10.10.10.240 and listening on Port 8000

$ mkdocs serve -a 10.10.10.240:8000
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 210201 01:03:15 server:298] Serving on http://10.10.10.240:8000
[I 210201 01:03:15 handlers:59] Start watching changes
[I 210201 01:03:19 handlers:132] Browser Connected: http://10.10.10.240:8000/

Verify MkDocs is accessible via http://10.10.10.240:8000

Reverse Proxy using LiteSpeed

Install LiteSpeed Web Server as Reverse Proxy to public MkDocs via HTTP & HTTPS referring to Installation Of OpenLiteSpeed

• Install LiteSpeed
• Change the Default Listening Port from 8088 to 80
• Create a new Virtual Host with SSL Certificate configured
• Create a new Listener for HTTPS (Port 443) with SSL Certificate configured

Create a New External App = Web Server in Virtual Hosts > External App > +

Configure the settings as below

• Name = mkdocs
• Address = 10.10.10.240:8000
• Max Connections = 100
• Initial Request Timeout (secs) = 60
• Retry Timeout (secs) = 0

Max Connections – Specifies the maximum number of concurrent connections that can be established between the server and an external application.

Initial Request Timeout (secs) – Specifies the maximum time in seconds the server will wait for the external application to respond to the first request over a new established connection.

Retry Timeout (secs) – Specifies the period of time that the server waits before retrying an external application that had a prior communication problem.

Create a new Context

• Type = Proxy

Configure the URI = / and Web Server = [HVHost Level]: mkdocs

Save and restart LiteSpeed Server

You should be able to access https://aventislab.com successfully now