Skip to content

About this website: GitLab Pages & MkDocs

A quick word about this site, as it reflects a technical challenge I set for myself.

This project brings together several passions of mine: innovation, experimentation, and open-source technologies.

These pages are all written in markdown—the most readable of markup languages—and archived on a GitLab repository, the open-core software forge. The whole site is powered by the open-source project MkDocs and styled with the Material for MkDocs theme.

MkDocs

mkdocs

MkDocs is an open-source project that lets you create beautiful and easy-to-use documentation with Markdown and YAML. You can customize your site with themes, plugins, and extensions, and host it anywhere you want.

The previous version of this site was powered by the Hugo engine, which is richer and more complex. MkDocs is better suited for creating a simple static site with no technical or functional pretensions. Its installation and maintenance are straightforward, and the site configuration is centralized in a single yaml file.

For MkDocs, I chose to install the enhanced version with Material for MkDocs.

Install MkDocs

On Linux, install the mkdocs-material package, then run the command mkdocs new . to create your site:

sudo apt install mkdocs-material
mkdir ~/Gitlab/mkdocs
cd ~/Gitlab/mkdocs
mkdocs new .

Build Your Site

Here’s the basic structure of an MkDocs site:

.
├─ docs/
│ └─ index.md
│ └─ page1.md
│ └─ page2.md
└─ mkdocs.yml

mkdocs.yml is the only site configuration file—simple and effective.

Within /docs, create as many subfolders and markdown documents as you like. Each subfolder can have an index.md file that will serve as its homepage.

The menu is created in mkdocs.yml, under the nav: entry:

nav:
  - home: index.md
  - page: page.md
  - folder1:
    - pageA.md
    - pageB.md
  - folder2:
    - PageC.md
    - PageD.md
  - about: about.md

Test Locally

Run the local server by launching the following command from the site directory: mkdocs serve.

The site will be accessible locally at http://127.0.0.1:8000, and changes will appear live.

Deploy on GitLab Pages

For GitLab Pages setup, create the following file at the root of your site: .gitlab-ci.yml

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Publish on the Root URL

Some settings are needed to reference the site at the root of your GitLab Pages domain (username.gitlab.io):

  1. Settings: Name your project username.gitlab.io, where username is your GitLab handle. Be sure to set the same baseurl in the site’s config mkdocs.yml file.
  2. Settings/Visibility: Ensure your site is private and that Pages access is set to "Everyone."
  3. Settings/Advanced: Set your baseurl (username.gitlab.io) as your project path (Settings > Advanced): username.gitlab.io.
  4. Publish your site via Git.
  5. Deploy/Pages: Uncheck "Use unique domain."
  6. Update your site.

Enjoy!