Skip to content

Follower license release commits downloads forks stars watchers issues issues-closed issues-pr issues-pr-closed


MkDocs is a great way to host a simple, static website. This website uses Material for MkDocs. Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation.

Use docker or python to quickly create and host a static website:

Host MkDocs locally with docker

git clone # clone repo
cd # Go to main folder
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/MkDocs-material # run the container

Serve MkDocs locally with python

Run this once to install all requirements:

choco install -y python
python -m pip install --upgrade pip
pip install MkDocs
pip install MkDocs-material

Run this in the folder of the MkDocs.yml file to host the MkDocs page:

MkDocs serve

Create page

Overriding template blocks:


MkDocs-material is a great theme and comes integrated with the pymkdown extensions, which lets you add tabbed code blocks, progress bars, task lists, keyboard symbols and more.

Further plugins:

Static Website Hosting Services

This website is hosted/built using the following services:

Service Direct Link 0xfab1 CNAME
GitHub Pages 0xfab1@github
IPFS with fleek 0xfab1@IFPS
Netlify 0xfab1@netlify
Azure 0xfab1@azure
Digital Ocean 0xfab1@digitalocean
Vercel 0xfab1@vercel
cloudflare 0xfab1@cloudflare
Render 0xfab1@render
Railway 0xfab1@railway
Gitlab Pages TODO TODO

I tried these services but they didn't suit me for my deployment at the time tested*:

  • Heroku - php workaround breaks other builds
  • - annoying DNS and build setup
  • - complicated build/requires extra files and github action changes
  • Surge - complicated build/requires extra files and github action changes
  • Firebase - complicated build/requires extra files and github action changes
  • Feta - complicated build/requires extra files and github action changes
  • Hostman - no free option
  • Qovery - looks great but didn't get it to work for simple static websites
  • Statically - great for one-pagers, not suitable for
  • Linode - no free option
  • koyeb - account closed for unknown reason

*happy to learn from you how I can use them using a simple, automated deployment method for my static website :)

Github Pages

To honor this post (and ensure the message remains true) I will use my own website as an example and show how I configured the static web app and make it to work the way it does.

I am using Github Pages to host the content, Mkdocs to create the website from markdown files as input and have own domain for a nicer URL.

Github Pages Repo

I created a repo named (Replace "FullByte" with your github username). Enable github pages for this repo in settings page of the repo. You will by default have a page available at

Custom Domain

Mkdocs specifically uses the branch "gh-pages" by default to build the static website that will be served.

I added a custom domain "" and added a file in the main folder of my repo called CNAME with one line containing my domain "".

I added the following IPv4 DNS records (dig +noall +answer -t A):             0       IN      A             0       IN      A             0       IN      A             0       IN      A

as well as these IPv6 DNS records (dig +noall +answer -t AAAA):             0       IN      AAAA    2606:50c0:8000::153             0       IN      AAAA    2606:50c0:8001::153             0       IN      AAAA    2606:50c0:8002::153             0       IN      AAAA    2606:50c0:8003::153

and a CNAME record for (dig +noall +answer -t CNAME):         0       IN      CNAME

Github Actions

Every time I commit to main I want the page to re-build so that the page is up-to-date. I currently don't use branches but this could be a good method to commit changes that should not yet be published. Once ready to publish, create a pull request of your branch and merge it to main.

My github action to build the static webpage using mkdocs looks as follows and is based on this documentation:

name: mkdocs gh-deploy

    branches: [main]
    branches: [main]

    name: Build and Deploy Documentation
    runs-on: ubuntu-latest
      - name: Checkout main
        uses: actions/checkout@v2

      - name: Set up Python 3.10
        uses: actions/setup-python@v2
          python-version: '3.10'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs-material
      - name: Deploy
        run: |
          git pull
          mkdocs gh-deploy

Additionally, I am running a security scan on every push and check the URLs I share regularly via cron job triggered github action.

There are many other nice things that could be done here. The main important part is to trigger the markdown to static website generator as github action on new commits so that the site is automatically built whenever you commit new content.