How to build and deploy MkDocs documentation site

MkDocs is a fast, simple, and elegant static site generator designed for creating project documentation. It can produce documentation from Markdown files, supports themes, and includes features like search out of the box.

In this tutorial, I'll show you how to create a documentation site with MkDocs, add Material theme, and deploy it using Appliku.

Table of Contents

Requirements
Repository
Create a MkDocs Project
Project Structure
Configure MkDocs
Create Content
Preview Your Site
Build Your Site
Commit and Push to GitHub
Deploy with Appliku

Requirements¶

For this tutorial you need:

Python 3.12 or higher installed on your computer
git
GitHub account
Appliku Account

Repository¶

Source code is available on GitHub appliku/mkdocstutorial

Create a MkDocs Project¶

Let's set up our environment and install dependencies:

mkdir mkdocs-tutorial
cd mkdocs-tutorial
python3 -m venv env
source env/bin/activate
pip install mkdocs mkdocs-material
pip freeze > requirements.txt

Create a new MkDocs project:

mkdocs new .

Create .gitignore file:

env/
site/
.idea/
__pycache__/
*.py[cod]
*$py.class
.vscode/
.DS_Store

Project Structure¶

After initialization, you'll have this structure:

mkdocs-tutorial/
    mkdocs.yml    # Configuration file
    docs/
        index.md  # Homepage

Configure MkDocs¶

Edit mkdocs.yml to set up your documentation site:

site_name: My Project Documentation
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - admonition
  - pymdownx.details

nav:
  - Home: index.md
  - About: about.md

Create Content¶

Replace content in docs/index.md:

# Welcome to MkDocs tutorial

We have made a simple static documentation site with MkDocs.

## Author

Visit [About me](about.md) to learn more.

Create docs/about.md:

# About This Documentation

This documentation is built using MkDocs with the Material theme.

## Contact

Feel free to reach out with questions or suggestions.

Preview Your Site¶

Run the development server:

mkdocs serve

Visit http://127.0.0.1:8000 in your browser.

Build Your Site¶

Generate the static site:

mkdocs build

This creates a site directory with your static website.

Commit and Push to GitHub¶

Initialize git repository and commit your changes:

git init
git add .
git commit -m "Initial commit"

Create a new repository on GitHub and push your code:

git remote add origin your-repository-url
git push -u origin master

Deploy with Appliku¶

Go to your Appliku dashboard and create a new application from GitHub repository.

Create and add a server for Pelican Blog¶

Add an Ubuntu or a Debian server from a cloud provider of your choice, if you haven't already.

Here are guides for adding servers from different cloud providers:

Create Static Site Application¶

Go to Applications -> GitHub
Give your application a name
Choose your GitHub repository
Select the branch
Check "This is a static site"
Choose your server
Click Create Application

Configure Build Settings¶

Appliku MkDocs settings

In the application settings:

Set Base Docker Image to Python 3.12
Set build command to: mkdocs build
Set output directory to: site
Save changes
Click Deploy now

Your documentation site will be built and deployed automatically.

Go back to application dashboard and click "Open App" and click the domain name.

Your MkDocs site will open.

Static site Mkdocs Tutorial Deployed

Congratulations. Your mkdocs static site is deployed with Appliku!

MkDocs Tutorial