Skip to content

Markdown File Linting

This job lints markdown files as part of the validation CI stage. It is designated to run on all branches. If any errors are found, the generated JUnit test report will let you know what errors were found.

You can include your linting rules in .markdownlint.json which should be within the root of your repository. for the available rules please see the docs.

This job provides the following badge:

  • None

Dependencies

  • Optional file .markdownlint.json in repository root with any rules you wish to specify

your .gitlab-ci.yml changes

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

stages:
    - validation

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

Markdown Linting:
  extends:
    - .Lint_Markdown

CI/CD Variables required

var name Description
MDLINT_PATH Optional specifies the path to lint. defaults to "**/*.md"
MDLINT_EXCLUDE_PATHS optional Specifies the paths to exclude from linting. Defaults to "!gitlab-ci"
MD_LINT_CONFIG-PATH Optional Specifies a path whenre the lint config file is. defaults to none. this variable enables you to specify a config that will be copied to the project root folder. Note: if specified, the file will be deleted at the end of the linting job.

Job Workflow

  1. installs the required job dependencies

  2. Lints any markdow file found in $MDLINT_PATH, excluding paths $MDLINT_EXCLUDE_PATHS

Artifacts

  • JUnit test report located at $CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/*.junit.xml

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
.Lint_Markdown:
  image: node:alpine3.14
  stage: validation
  variables:
    MDLINT_PATHS: "**/*.md **/**/*.md **/**/**/*.md **/**/**/**/*.md **/**/**/**/**/**/*.md #CHANGELOG.md !gitlab-ci"
    DEFAULT_ROOT_DIR: "./gitlab-ci"
    MD_LINT_CONFIG_PATH: ""
  before_script:
    - mkdir -p "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/lint_markdown"
    - 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 [ "0$MD_LINT_CONFIG_PATH" != "0" ]; then cp "$MD_LINT_CONFIG_PATH/.markdownlint.json" $CI_PROJECT_DIR/.markdownlint.json; fi
    - cp -f "$ROOT_DIR/lint/.markdownlint-cli2.jsonc" "$CI_PROJECT_DIR/.markdownlint-cli2.jsonc"
    - npm install markdownlint-cli2 --global
    - npm install markdownlint-cli2-formatter-junit --global
  script:
    - echo "[DEBUG] MDLINT_PATHS=$MDLINT_PATHS"
    - markdownlint-cli2 $MDLINT_PATHS 1>&1 || EXITCODE=$?
    - echo DEBUG EXITCODE[$EXITCODE]
    - rm -f "$CI_PROJECT_DIR/.markdownlint-cli2.jsonc"
    - if [ "0$MD_LINT_CONFIG-PATH" != "0" ]; then rm -f "$CI_PROJECT_DIR/.markdownlint.json"; fi
    - mv *.junit.xml "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/lint_markdown/markdown_lint.junit.xml"
  artifacts:
    expire_in: 24 hrs
    when: always
    paths:
      - "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/lint_markdown/*"
    reports:
      junit:
        - "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/lint_markdown/*.junit.xml"
  rules:
    - if: '$JOB_STOP_LINT_MARKDOWN'
      when: never

    - if: # condition_any_branch_push
        $CI_COMMIT_BRANCH != null && 
        $CI_COMMIT_TAG == null &&
        $CI_PIPELINE_SOURCE == "push"
      exists:
        # - "**.md"
        # - "**/**.md"
        - '{!docs/**,!pages/**,!gitlab-ci/**,!website-template/**,**}/*.md'
      when: always
    - when: never


.Lint_Markdown_Docs:
  variables:
    MDLINT_PATHS: "docs/*.md docs/**/*.md docs/**/**/*.md docs/**/**/**/*.md docs/**/**/**/**/**/*.md #CHANGELOG.md !gitlab-ci !website-template"
    MD_LINT_CONFIG_PATH: "$CI_PROJECT_DIR/website-template"
  extends: .Lint_Markdown
  rules:
    - if: '$JOB_STOP_LINT_MARKDOWN_DOCS'
      when: never

    - 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:
        - '{docs/**,pages/**}/*.md'
      # 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' # works
      changes:
        paths:
          #- '{docs/*,pages/*}*.md'
          - '{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