GitLab CI template for MkDocs

This project implements a GitLab CI/CD template to build your static website with MkDocs.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/mkdocs/gitlab-ci-mkdocs@2.7.0
    # 2: set/override component inputs
    inputs:
      site-dir: "build" # ⚠ this is only an example

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/mkdocs'
    ref: '2.7.0'
    file: '/templates/gitlab-ci-mkdocs.yml'

variables:
  # 2: set/override template variables
  MKD_SITE_DIR: "build" # ⚠ this is only an example

Global configuration

The MkDocs template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
image / MKD_IMAGE	The Docker image used to run MkDocs	docker.io/squidfunk/mkdocs-material:latest
workspace-dir / MKD_WORKSPACE_DIR	MkDocs sources directory	.
requirements-file / MKD_REQUIREMENTS_FILE	Requirements file. If the file is not found in the repository, requirements are read from the MKD_REQUIREMENTS variable	requirements.txt
requirements / MKD_REQUIREMENTS	Space separated requirements (ignored if a requirement file is found)	mkdocs
site-dir/ MKD_SITE_DIR	MkDocs generated site directory (relative to $MKD_WORKSPACE_DIR), the path will be declared as artifact	site
prebuild-script / MKD_PREBUILD_SCRIPT	Pre-build hook script	mkdocs-pre-build.sh
PIP_INDEX_URL	Python repository url	none
pip-opts / PIP_OPTS	pip extra options	none

Jobs

mkdocs job

This job performs MkDocs build. It uses the following variable:

Input / Variable	Description	Default value
build-args / MKD_BUILD_ARGS	Arguments used by the build job	none

The built documentation is generated in the ${MKD_WORKSPACE_DIR}/${MKD_SITE_DIR} folder. Be sure to update MKD_SITE_DIR if you change the output directory (via the MKD_BUILD_ARGS variable or the mkdocs.yml file).

mkdocs-lychee job

This job checks links with lychee. It uses the following variable:

Input / Variable	Description	Default value
lychee-enabled / MKD_LYCHEE_ENABLED	Set to true to enable this job	none (disabled)
lychee-image / MKD_LYCHEE_IMAGE	The Docker image used to run lychee	docker.io/lycheeverse/lychee:latest
lychee-args / MKD_LYCHEE_ARGS	lychee arguments to execute	docs/

Publishing

this template is not a deployment template and it only builds a MkDocs project.

You might deploy the generated site using a GitLab pages job (there is a variant for that) or any other method you see fit.

Variants

GitLab Pages variant

Basically it copies the content of the mkdocs generated site folder (site by default) to the public folder which is published by GitLab pages.

If you wish to use it, Add the following to your .gitlab-ci.yml:

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/mkdocs/gitlab-ci-mkdocs@2.7.0
  # GitLab pages variant
  - component: $CI_SERVER_FQDN/to-be-continuous/mkdocs/gitlab-ci-mkdocs-pages@2.7.0