MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. The source documentation files are written in Markdown and set up with a single YAML configuration file.


  • Ubuntu 20.04 or Ubuntu 20.10
  • 1024MB or above Ram.
  • 10GB Disk Space.
  • 1 vCPU or above CPU.
  • root privileges

Step 1 - Log in to your server on SSH

Use the following command to log in to your server on SSH:


╭─ ╰─➤ ssh root@server_ip

Also, check if your system package database is up to date before continuing this tutorial.

Step 2 - Update Ubuntu

Log in to your server via SSH and before starting the installation of MkDocs, it is always recommended updating the system packages.

So let's go to the command:


╭─ ╰─➤ sudo apt update

Then type:


╭─ ╰─➤ sudo apt upgrade

Step 3 - Install Python 3 or plus

Verify Python 3 is installed

╰─➤ python3 --version
Python 3.7.3

You need Python 3 or more for this installation!

Step 4 - Install MkDocs

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

Step 5 - Create a new project called mkdocs and build a new site

╰─➤ sudo mkdocs new mkdocs
╰─➤ cd mkdocs
╰─➤ sudo mkdocs build

Step 6 - Verify the following files are created successfully

╰─➤ ls -la /mkdocs

docs  mkdocs.yml  site  ssl

╰─➤ ls -la /mkdocs/site

404.html  css  fonts  img  index.html  js  search  sitemap.xml  sitemap.xml.gz

Step 7 - Install Python PIP and mkdocs-meterial theme

╰─➤ sudo apt install python3-pip
╰─➤ pip3 install mkdocs-material

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

╰─➤ sudo vim /mkdocs/mkdocs.yml
site_name: My Docs
  name: material

Step 9 - Start mkdocs

IP Address = and listening on Port 8000

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

Verify MkDocs is accessible on


That’s all, I hope that this tutorial is useful for you, if so, clap your hands! (:


Image With a Dockerfile

The above approach is hands-on. If you must do it over and over, then create a Dockerfile to take a picture of it. It will be more productive.

To follow all the same steps as you did earlier but in a Dockerfile, just write this:

FROM python:3

RUN pip install mkdocs
RUN mkdocs new letscloud


WORKDIR /letscloud

ENTRYPOINT ["mkdocs"]

CMD ["serve", "--dev-addr="]

In the folder where the Dockerfile resides, run the command below to build the image:

You can replace *letscloud* with your own preferred image name.

╰─➤ docker build -t letscloud .

After you have the image, you can just run it:

╰─➤ docker run -itd -p 8089:8000 --rm letscloud

You’re all done. You can browse it in localhost:8089, and it will be the same as what you did interactively just now!


In this tutorial, you installed and managed the mkdocs. Now that you have your mkdocs installed. It is so easy that even the most experienced are using it daily in their projects.

If you have any suggestions feel free to contact me or just leave a comment below.

Read more about: CentOSUbuntu