Skip to content

Setting Up MkDocs with Material Theme on Linux Mint

A step-by-step guide to creating a professional documentation site using MkDocs and GitHub Pages.

📋 Prerequisites

1. Install git and github cli

  • Open terminal and input: 
    sudo apt update   
sudo apt install git gh      
gh auth login

2. Set up a new mkdocs project

mkdocs new my-new-docs

3. Create a virtual environment

  1. Open Visual Studio Code
  2. Open new terminal inside Visual Studio Code 
    cd my-new-docs
python3 -m venv venv  
source venv/bin/activate

4. Install pip

sudo apt install python3-pip

5. Install mkdocs and the material theme

pip install mkdocs mkdocs-material

6. Customize your mkdocs.yml

  • Set attributes site_name, theme, palette, font, favicon, and more
  • Find detailed customization information here
  • Add Markdown extension for Visual Studio Code compatibility: 
markdown_extensions:
  - pymdownx.mark

7. Preview your site locally

mkdocs serve
* View in browser at: http://127.0.0.1:8000

8. Push to github and deploy

git init
git remote add origin https://github.com/<your-username>/my-new-docs.git
git add .
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
git commit -m "Initial commit"
git push -u origin main
mkdocs gh-deploy

9. Enable github pages

  1. Go to repo ⚙ Settings → Pages
  2. Set branch to gh-pages, root folder, and save

    Below is what your GitHub Pages settings should look like:

GitHub Pages settings screenshot


Success!

  • Your site should be available at:
    https://<your-username>.github.io/my-new-docs/


Don't Forget to Deploy
  • After updating .md files run mkdocs serve for local updates.
  • For public updates run the following: 
    git add .  
git commit -m "My update message"  
git push  
mkdocs gh-deploy
  • ⏱️ Note public updates can take 1-3 minutes to apply.

Additional Resources