MkDocs Material - Install

Guide: Installing MkDocs Material on Ubuntu

Abstract

This guide explains how to install MkDocs Material on Ubuntu using two methods: Docker Compose and Native Installation. Choose the method that best suits your environment.

---

Method 1: Install MkDocs Material with Docker Compose

Prerequisites:

• Ubuntu virtual machine
• Docker Compose installed

Steps:

1. Prepare the directory structure
   Create a directory for MkDocs Material:

   mkdir /home/docker
   cd /home/docker
   mkdir mkdocs
   cd mkdocs
   

2. Create the Docker Compose file
   Create a compose.yml file:

   nano compose.yml
   

   Example content for compose.yml:

   services:
    mkdocs:
        image: squidfunk/mkdocs-material
        restart: unless-stopped
        ports:
        - "8000:8000"
        volumes:
        - /home/docker/mkdocs/data:/docs
        stdin_open: true
        tty: true
   

   Save and exit: Ctrl + X, then Y, and press Enter.

3. Set up MkDocs data structure
   Create directories and files for MkDocs:

   mkdir /home/docker/mkdocs/data
   cd /home/docker/mkdocs/data
   nano mkdocs.yml
   

   Add content to mkdocs.yml as needed. Save and exit.

Create a directory for your documentation:

mkdir /home/docker/mkdocs/data/docs

1. Start the container
   Navigate back to the MkDocs directory:

   cd /home/docker/mkdocs
   docker-compose up -d
   

2. Access MkDocs
   Open a browser and go to http://<server-ip>:8000 to view your MkDocs Material site.

---

Method 2: Install MkDocs Material Natively

Prerequisites:

• Python and pip installed. If not, install them first:

  sudo apt update
  sudo apt install python3 python3-pip
  

Steps:

1. Install MkDocs Material
   Use pip to install the MkDocs Material package:

   pip install mkdocs-material
   

2. Create a new MkDocs project
   Run the following command to create a new site:

   mkdocs new <site-name>
   

   Replace <site-name> with your desired project name.

3. Navigate to the project folder
   

   cd <site-name>
   

4. Serve the site locally
   Start the development server:

   mkdocs serve
   

5. Access MkDocs
   Open a browser and go to http://127.0.0.1:8000 to view your MkDocs Material site.

Tip

By adding the parameter -a <ip address:port> you can specify on with ip address and port the site will be hosted. Example is mkdocs serve -a 192.168.0.123:7976

---

Conclusion

You’ve now set up MkDocs Material on Ubuntu using either Docker Compose or native installation. Choose Docker Compose for isolated and repeatable setups or native installation for simplicity.