Skip to content

GitLab Pages

Publishing the mkdocs in GitLab pages

You can easily publish your docs with GitLab-CI for free!

Assuming you have a repository with mkdocs that is hosted at GitLab:

├── docs
│   └──
├── mkdocs.yml
├── requirements.txt

In the requirements.txt file you must define at least the dependency mkdocs-material.

To use GitLab CI to publish your docs, just add a .gitlab-ci.yml file to your repo. Add the following content:

# use the python latest base image
image: python:latest

# this pipeline consists of a build and deploy stage
  - build
  - deploy

# build your docs with mkdocs and keep the site folder as artifact
  stage: build
    - pip install -r requirements.txt
    - mkdocs build --strict
    expire_in: 3h
      - site/

# copy the site folder to public to publish your docs to gitlab pages
  stage: deploy
    - mv site public/
    - build
    - public
    - master

When you commit your change and push it to GitLab, a CI runner will automatically detect the pipeline definition and starts building your docs. When the build stage was successful the generated pages will be deployed to your repos GitLab pages.

GitLab Pages with mkdocs-material example

To view an example repository for the usage of mkdocs material and GitLab pages checkout

GitLab-CI builds and deploys the docs automatically to the project specific pages url:

Feel free to fork the example repo to get started on mkdocs-material with GitLab-CI.