Skip to content

MKDocs Static Site Build

Build a MKDocs site from the config specified in mkdocs.yml. Only runs if mkdocs.yml exists in the repository root directory. This job is designated to run on all branchs so that you can use the artifacts for deployment to staging and/or production as required.

This job provides the following badge:

  • None

Dependencies

  • Mandatory file mkdocs.yml in the repository root directory with your MKDocs configuration

your .gitlab-ci.yml changes

To use this job add the following to your .gitlab-ci.yml file

stages:
    - build

include:
    - local: CI/build/.gitlab-ci.yml

MKDocs build:
  variables:
    MKDOCS_BUILD_PATH: "build"
  extends:
    - .MKDocs_Build

CI/CD Variables required

var name Description
MKDOCS_BUILD_PATH Mandatory, if different from default The path where MKDocs places the build files. Defaults to build
MKDOCS_INCLUDE_SOURCE Optional Include the build source files in the artifacts. Default is Not set. Any value in this variable, will include the source files.
MKDOCS_SOURCE_PATH Optional, if source files are not to be included Set to the path where mkdocs uses to build the static html.

Job Workflow

  1. install mkdocs

    1. if file requirements.txt exists in the repository root directory, use this fill to also install additional dependencies.

    2. if no requirements.txt file exists, only install mkdocs.

  2. run mkdocs to build the static pages

  3. if variable $MKDOCS_INCLUDE_SOURCE is set, then copy $MKDOCS_SOURCE_PATH to the artifacts location.

  4. copy directory $MKDOCS_BUILD_PATH to the artifacts location.

Artifacts

  • files in "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME"

Gitlab job Definition

When you include this definition the following makes up the job definition

.gitlab-ci.yml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
.MKDocs_Build:
  image: python:3.11.2-bullseye
  stage: build
  variables:
    GIT_DEPTH: 0
    MKDOCS_BUILD_PATH: build
    MKDOCS_SOURCE_PATH: docs
    DEFAULT_ROOT_DIR: './gitlab-ci'
  before_script:
    - mkdir -p "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME"
    - if [ "0$JOB_ROOT_DIR" == "0" ]; then ROOT_DIR=$DEFAULT_ROOT_DIR; else ROOT_DIR=$JOB_ROOT_DIR ; fi
    - echo "[DEBUG] ROOT_DIR[$ROOT_DIR]"
    - if [ ! -f "requirements.txt" ]; then pip install --upgrade pip -r $ROOT_DIR/mkdocs/requirements.txt; fi
    - if [ -f "requirements.txt" ]; then pip install --upgrade pip -r $ROOT_DIR/mkdocs/requirements.txt; pip install -r requirements.txt; fi
    - if [ -f "website-template/requirements.txt" ]; then pip install --upgrade pip -r $ROOT_DIR/mkdocs/requirements.txt; pip install -r website-template/requirements.txt; fi
  script:
    - mkdocs build --clean --strict
    - mv "$MKDOCS_BUILD_PATH" "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/$MKDOCS_BUILD_PATH"
    - if [ "0$MKDOCS_INCLUDE_SOURCE" != "0" ]; then cp $MKDOCS_SOURCE_PATH "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/$MKDOCS_SOURCE_PATH"; fi
    - ls -laR "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME"
  artifacts:
    expire_in: 24 hrs
    paths:
      - "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME"
  rules:

    - if: '$JOB_STOP_MKDOCS_BUILD'
      when: never

    - if:  # condition_git_tag
        $CI_COMMIT_TAG != null &&
        $CI_COMMIT_BRANCH == null
      exists:
        - 'mkdocs.{yaml,yml}'
      when: always

    # - if:  # condition_master_branch_push
    #     $CI_COMMIT_BRANCH == "master" && 
    #     $CI_PIPELINE_SOURCE == "push"
    #   exists:
    #     - 'mkdocs.{yaml,yml}'
    #   when: always

    - if:  # condition_dev_branch_push
        $CI_COMMIT_BRANCH == "development" && 
        ( 
          $CI_PIPELINE_SOURCE == "pipeline"
            ||
          $CI_PIPELINE_SOURCE == "push"
            ||
          $CI_PIPELINE_SOURCE == "schedule"
        )
        # See nofusscomputing/projects/gitlab-ci#34 for extra $CI_PIPELINE_SOURCE
      exists:
        - 'mkdocs.{yaml,yml}'
      # No changes check # See nofusscomputing/projects/gitlab-ci#34
      # changes:
      #   paths:
      #     - '{docs/**,pages/**}/*.md'
      #   compare_to: 'master'
      when: always

    - if:  # condition_not_master_or_dev_push
        $CI_COMMIT_BRANCH != "master" && 
        $CI_COMMIT_BRANCH != "development" && 
        $CI_PIPELINE_SOURCE == "push"
      exists:
        - 'mkdocs.{yaml,yml}'
      changes:
        paths:
          - '{docs/**,pages/**}/*.md'
        compare_to: 'development'
      when: always

    - when: never


.MKDocs_Build_Docs:
  extends: .MKDocs_Build
  variables:
    MKDOCS_SOURCE_PATH: docs
  rules:
    - if: '$JOB_STOP_MKDOCS_BUILD'
      when: never

      # Build docs on tag so they can be downloaded from the tag job and are always available.
    - if:  # condition_git_tag
        $CI_COMMIT_TAG != null &&
        $CI_COMMIT_BRANCH == null
      exists:
        - '{docs/**,pages/**}/*.md'
      when: always

    # - if:  # condition_master_branch_push
    #     $CI_COMMIT_BRANCH == "master" && 
    #     $CI_PIPELINE_SOURCE == "push"
    #   exists:
    #     - '{docs/**,pages/**}/*.md'
    #   when: always

    - if:  # condition_dev_branch_push
        $CI_COMMIT_BRANCH == "development" && 
        ( 
          $CI_PIPELINE_SOURCE == "pipeline"
            ||
          $CI_PIPELINE_SOURCE == "push"
            ||
          $CI_PIPELINE_SOURCE == "schedule"
        )
        # See nofusscomputing/projects/gitlab-ci#34 for extra $CI_PIPELINE_SOURCE
      exists:
        - 'mkdocs.{yaml,yml}'
      # No changes check # See nofusscomputing/projects/gitlab-ci#34
      # changes:
      #   paths:
      #     - '{docs/**,pages/**}/*.md'
      #   compare_to: 'master'
      when: always


    - if:  # condition_not_master_or_dev_push
        $CI_COMMIT_BRANCH != "master" && 
        $CI_COMMIT_BRANCH != "development" && 
        $CI_PIPELINE_SOURCE == "push"
      exists:
        - '{docs/**,pages/**}/*.md'
      changes:
        paths:
          - '{docs/**,pages/**}/*.md'
        compare_to: 'development'
      when: always

    - when: never

Note

Docs Still under development

About:

This page forms part of our Project Gitlab-CI.

Page Metadata
Version: ToDo: place files short git commit here
Date Created: 2021-08-11
Date Edited: 2023-05-23

Contribution:

Would You like to contribute to our Gitlab-CI project? You can assist in the following ways:

 

ToDo: Add the page list of contributors