Skip to main content

Performing Style Check on YAML & Markdown Files and Link Check

· 3 min read
Jiaqi Liu

Inspired by Sous Chefs, hashistack offers a reusable workflow that performs the following code style checks:

  1. YAML file style check
  2. Markdown file style check
  3. Broken link check

Example Usage:

name: CI/CD

"on":
  pull_request:
  push:
    branches:
      - master

jobs:
  yml-md-style-and-link-checks:
    uses: QubitPi/hashistack/.github/workflows/yml-md-style-and-link-checks.yml@master
tip

The example above is all we need to run the 3 checks. The workflow has default configurations, which can be overridden

The configurations of the composing checks can be configured regularly by following their respective GitHub Actions documentations. The following sections discusses the configuration by example.

(Optional) Overriding Default Configurations​

YAML File Style Check​

The default YAML style configurations is

---
extends: default
rules:
  line-length:
    max: 256
    level: warning
  document-start: disable
  braces:
    forbid: false
    min-spaces-inside: 0
    max-spaces-inside: 1
    min-spaces-inside-empty: -1
    max-spaces-inside-empty: -1

To override the default configuration, create a file named .yamllint at the root of the downstream project and configure the workflow with use-custom-yamllint-config-file option set to true. For example

name: CI/CD

"on":
  pull_request:
  push:
    branches:
      - master

jobs:
  yml-md-style-and-link-checks:
    uses: QubitPi/hashistack/.github/workflows/yml-md-style-and-link-checks.yml@master
    with:
      use-custom-yamllint-config-file: true
tip

More configuration options can be found at yamllint documentation

Markdown File Style Check​

The configurations of markdown file style check are splitted into 2 config files whose default configurations are

rules "~MD002", "~MD003", "~MD005", "~MD007", "~MD013", "~MD022", "~MD024", "~MD029", "~MD033", "~MD034", "~MD036", "~MD041"
style "#{File.dirname(__FILE__)}/markdownlint.rb"
tip

In the example above, the first line above excludes specified rules. The second line specifies the rule configuration file (markdownlint.rb). For more native config options, please refer to its documentations

Create files named .mdlrc and markdownlint.rb at the root of the project and add use-custom-mdlrc-config-file and use-custom-markdownlint-config-file options to the workflow file like so:

name: CI/CD

"on":
  pull_request:
  push:
    branches:
      - master

jobs:
  yml-md-style-and-link-checks:
    uses: QubitPi/hashistack/.github/workflows/yml-md-style-and-link-checks.yml@master
    with:
      use-custom-mdlrc-config-file: true
      use-custom-markdownlint-config-file: true

The Broken link check pretty much configures everything for us, so we don't need to configure anything unless we need to exclude links or file by regular expression. hashistack defaults to exclude all relative file links with the following default:

.lycheeignore
file:///*
info

The ignore rule in the example above skips checks of all relative links among files. This is common in Docusaurus-based documentation

If we don't need such default, we would simply create a .lycheeignore file at our project root and setting use-custom-lycheeignore-file to true:

name: CI/CD

"on":
  pull_request:
  push:
    branches:
      - master

jobs:
  yml-md-style-and-link-checks:
    uses: QubitPi/hashistack/.github/workflows/yml-md-style-and-link-checks.yml@master
    with:
      use-custom-lycheeignore-file: true