Skip to content

Commit

Permalink
GH Actions: add new check for consistency in markdown files
Browse files Browse the repository at this point in the history
This new check uses the NPM MarkdownLint package via the NPM MarkdownLint-CLI2 package.

It executes a loose check for consistency and some common errors.
Some of the more annoying rules/rules which could impact display of markdown files on GitHub have been disabled.

All necessary configuration is contained in the `.markdownlint-cli2.yaml` file.

To run locally, install via:
```bash
npm install -g markdownlint-cli2
```
... and then run via:
```bash
markdownlint-cli2
```

Includes a problem matcher which _should_ allow for displaying the results inline in GitHub PR code review view.

Includes adding `node_modules` to the `.gitignore` in case anyone would install these tools locally (to prevent them committing them).

Refs:
* https://github.com/DavidAnson/markdownlint
* https://github.com/DavidAnson/markdownlint-cli2
* https://github.com/marketplace/actions/markdownlint-cli2-action
  • Loading branch information
jrfnl committed Apr 4, 2024
1 parent 82ad715 commit ce2139a
Show file tree
Hide file tree
Showing 4 changed files with 162 additions and 9 deletions.
19 changes: 10 additions & 9 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,16 @@
# https://www.reddit.com/r/PHP/comments/2jzp6k/i_dont_need_your_tests_in_my_production/
# https://blog.madewithlove.be/post/gitattributes/
#
.github/ export-ignore
scripts/ export-ignore
.cspell.json export-ignore
.gitattributes export-ignore
.gitignore export-ignore
.yamllint.yml export-ignore
phpcs.xml.dist export-ignore
phpstan.neon.dist export-ignore
phpunit.xml.dist export-ignore
.github/ export-ignore
scripts/ export-ignore
.cspell.json export-ignore
.gitattributes export-ignore
.gitignore export-ignore
.yamllint.yml export-ignore
.markdownlint-cli2.yaml export-ignore
phpcs.xml.dist export-ignore
phpstan.neon.dist export-ignore
phpunit.xml.dist export-ignore

#
# Declare files that should always have CRLF line endings on checkout.
Expand Down
39 changes: 39 additions & 0 deletions .github/workflows/markdown.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Markdown

on:
# Run on all pushes which touch markdown files and on all pull requests.
push:
paths:
- '**.md'
pull_request:
# Also run this workflow every Monday at 6:00 (to make sure the broken link check runs regularly).
schedule:
- cron: '0 6 * * 1'
# Allow manually triggering the workflow.
workflow_dispatch:

# Cancels all previous workflow runs for the same branch that have not yet completed.
concurrency:
# The concurrency group contains the workflow name and the branch name.
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
markdownlint:
name: 'Lint Markdown'
runs-on: ubuntu-latest

# Don't run the cronjob in this workflow on forks.
if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository_owner == 'PHPCSStandards')

steps:
- name: Checkout code
uses: actions/checkout@v4

# @link https://github.com/marketplace/actions/problem-matcher-for-markdownlint-cli
- name: Enable showing issue in PRs
uses: xt0rted/markdownlint-problem-matcher@v3

# @link https://github.com/marketplace/actions/markdownlint-cli2-action
- name: Check markdown with CLI2
uses: DavidAnson/markdownlint-cli2-action@v15
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,4 @@
/vendor/
composer.lock
phpstan.neon
/node_modules/
112 changes: 112 additions & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
#
# Configuration file for MarkdownLint-CLI2.
#
# Example file with all options:
# https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml
#

# Do not fix any fixable errors.
fix: false

# Define glob expressions to use (only valid at root).
globs:
- "**/*.md"
- ".github/**/*.md"

# Show found files on stdout (only valid at root)
showFound: true

# Define glob expressions to ignore.
ignores:
- "node_modules/"
- "vendor/"

# Disable inline config comments.
noInlineConfig: true

# Disable progress on stdout (only valid at root).
noProgress: false

# Adjust the configuration for some built-in rules.
# For full information on the options and defaults, see:
# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
config:
######################
# Disable a few rules.
######################
# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines.
MD031: false
# MD032/blanks-around-lists - Lists should be surrounded by blank lines.
MD032: false

##############################
# Customize a few other rules.
##############################
# MD003/heading-style/header-style - Heading style.
MD003:
# Heading style - Always use hashes.
style: "atx"

# MD004/ul-style - Unordered list style.
MD004:
# List style - each level has a different, but consistent symbol.
style: "sublist"

# MD007/ul-indent - Unordered list indentation.
MD007:
indent: 4
# Whether to indent the first level of the list.
start_indented: false

# MD012/no-multiple-blanks - Multiple consecutive blank lines.
MD012:
maximum: 2

# MD013/line-length - Line length.
MD013:
# Number of characters. No need for being too fussy.
line_length: 1000
# Number of characters for headings.
heading_line_length: 100
# Number of characters for code blocks.
code_block_line_length: 100
# Stern length checking (applies to tables, code blocks etc which have their own max line length).
stern: true

# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content.
MD024:
# Only check sibling headings.
siblings_only: true

# MD033/no-inline-html - Inline HTML.
MD033:
# Allowed elements.
allowed_elements:
- div
- details
- summary
- b
- code

# MD044/proper-names - Proper names should have the correct capitalization.
MD044:
# List of proper names.
names: ["PHP", "PHP_CodeSniffer", "CodeSniffer", "PHPUnit"]
# Include code blocks.
code_blocks: false

# MD046/code-block-style - Code block style
MD046:
style: "fenced"

# MD048/code-fence-style - Code fence style
MD048:
style: "backtick"

# MD049/emphasis-style - Emphasis style should be consistent
MD049:
style: "underscore"

# MD050/strong-style - Strong style should be consistent
MD050:
style: "asterisk"

0 comments on commit ce2139a

Please sign in to comment.