Skip to content

mkdocs documentation Gitlab CI/CD Template

This template creates the jobs applicable to publishing pages to a website. The website in question is a static site built by MKDocs.

Docs ToDo

  • notate that var PAGES_ENVIRONMENT_PATH: can be set to the slug of the page to show and is used for launching the environment to the url that contains the docs index page.

  • notate that resource groups are used.

Dependencies

  • Mandatory file docs/index.md this is the index page of your dcoumentation.

Note

Docs Still under development

gitlab-ci.yml 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
# This gitlab-ci file is used for creating building pages directories for nofusscomputing.com.
# by including this file, the jobs will be autocreated and only for pages jobs.

include:
  - local: $JOB_ROOT_DIR/.gitlab-ci_common.yaml
  - local: $JOB_ROOT_DIR/mkdocs/.gitlab-ci.yml
  - local: $JOB_ROOT_DIR/lint/markdown.gitlab-ci.yaml


Documentation.Lint:
  extends: .Lint_Markdown_Docs
  needs: []


Documentation.Build:
  extends: .MKDocs_Build_Docs
  needs: [ 'Documentation.Lint' ]
  resource_group: Documentation

# this name must always be called 'pages' so that gitlab pages work
pages:
  stage: deploy
  resource_group: Documentation
  variables:
    GIT_STRATEGY: none
  script:
    - mv "$CI_PROJECT_DIR/artifacts/build/Documentation.Build/build" public
  needs: [ 'Documentation.Build' ]
  environment: 
    name: Gitlab Pages
    url: $CI_PAGES_URL/$PAGES_ENVIRONMENT_PATH
  artifacts:
    paths:
      - public
  rules:
    - if: '$JOB_STOP_GITLAB_PAGES'
      when: never

    - if:  # condition_dev_branch_push
        $CI_COMMIT_BRANCH == "development" && 
        $CI_PIPELINE_SOURCE == "push"
      exists:
        - '{docs/**,pages/**}/*.md'
      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'
      allow_failure: true
      when: manual

    - when: never

About:

This page forms part of our Project Gitlab-CI.

Page Metadata
Version: ToDo: place files short git commit here
Date Created: 2023-05-22
Date Edited: 2023-06-08

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