Quick guide: MkDocs-generated static site hosted on GitLab Pages#

This site (bestul.one) is built with the MkDocs static site generator and hosted via GitLab Pages (any personal project under your GitLab account can have the Pages feature enabled, which, with some configuration, will result in a subtree of that project's repository being presented to the web as a static site). Because I use the combination of MkDocs and GitLab Pages frequently, I maintain this quick guide to the process mostly for reference by me.

Prerequisites#

  • GitLab account
  • Computer with the following components installed:
    • Python
    • Python pip
    • MkDocs (usually installed with Python pip)
    • Git (you will use Git bash in particular)
  • Local SSH key created with its public key then uploaded to the profile of your GitLab account.

Site setup and cloning steps#

  1. In GitLab: create a new personal project in your GitLab Account
    1. Enable Pages for the project
    2. Create a .gitlab-ci.yml at the root of master, with the content exactly as shown here
    3. At the root of master, create a folder named public
    4. Within the public folder, create a simple "hello world" html page named index.html
    5. Use the URL of the Pages site to verify your hello world page is now viewable
  2. On your computer
    1. Create a new directory that will house your git clone of the MkDocs site
    2. cd into the new directory
    3. run the following command:
      1. git clone git@gitlab.com:<your account>/<the project name>.git

Ongoing site editing routine#

Cd into the child directory that was created by the cloning and cause mkdocs to serve up the site locally to enable you to observe your modifications as they are saved:

cd mydirectory
mkdocs serve
# copy the local web address from the "serving on" message echoed by mkdocs

Open the browser and paste the local web address into the address bar. The website will render and will be updated whenever you revise or add a .md file in the docs folder.

Use the File Manager to go to the docs directory of the cloned project.

Edit existing .md (Markdown) pages and/or add new ones using FeatherPad (or another text editor) using Markdown syntax.

Here is an excellent Markdown syntax cheatsheet to guide you when editing pages.

Whenever you add a new page, update the "nav" section of the mkdocs.yml doc accordingly.

Example prerequisites setup on an Ubuntu AWS EC2 instance#

Add user to sudoers w/o the need to supply password:

sudo nano /etc/sudoers
# User privilege specification
myusername ALL=(ALL) NOPASSWD:ALL

Install pip:

sudo apt update
sudo apt install python3-pip

Install mkdocs:

pip install mkdocs --break-system-packages

Confirm server install included git, so already present:

git --version

Take care of ssh key for git:

on endpoint
    ssh-keygen -t rsa -b 2048 -C "git key"
    cat .pub file and copy to clipboard
on git account
    edit profile
    add key in SSH Keys section
on endpoint validate key setup
    ssh -T git@gitlab.com
    (should be asked to trust key and for your passphrase, then get a welcome)

Add mkdocs supplemental stuff used by site (a couple examples):

pip install mkdocs-windmill --break-system-packages
pip install mkdocs-open-in-new-tab --break-system-packages

The .gitlab-ci.yml file#

The file contents should be exactly as provided below. This yml file defines the parameters that drive a GitLab Pages site update whenever you 'git commit and git push' content revisions to your GitLab project.

image: busybox
pages:
  stage: deploy
  script:
  - echo 'Nothing to do...'
  artifacts:
    paths:
    - public
    expire_in: 10 minutes
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Leave a comment
Submissions are subject to review and approval