Skip to content

Commit 12ca286

Browse files
per1234per1234
committed
Add infrastructure to check Markdown files for problems
Tasks and a GitHub Actions workflow are added for detecting problems in the project's Markdown files. On every push and pull request that affects relevant files, and periodically, the workflow will check the repository's Markdown files for problems: - Use markdownlint to check for common problems and formatting. - Use markdown-link-check to check for broken links. The Arduino tooling Markdown style is defined by the `.markdownlint.yml` file. In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them via a `.markdownlintignore` file: https://github.com/igorshubovych/markdownlint-cli#ignoring-files markdown-link-check is configured via the `.markdown-link-check.json` file: https://github.com/tcort/markdown-link-check#config-file-format
1 parent fe15060 commit 12ca286

File tree

8 files changed

+2041
-47
lines changed

8 files changed

+2041
-47
lines changed

‎.github/workflows/check-markdown-task.yml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md
2+
name: Check Markdown
3+
4+
env:
5+
# See: https://github.com/actions/setup-node/#readme
6+
NODE_VERSION: 16.x
7+
8+
# See: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
9+
on:
10+
create:
11+
push:
12+
paths:
13+
- ".github/workflows/check-markdown-task.ya?ml"
14+
- ".markdown-link-check.json"
15+
- "package.json"
16+
- "package-lock.json"
17+
- "Taskfile.ya?ml"
18+
- "**/.markdownlint*"
19+
- "**.mdx?"
20+
- "**.mkdn"
21+
- "**.mdown"
22+
- "**.markdown"
23+
pull_request:
24+
paths:
25+
- ".github/workflows/check-markdown-task.ya?ml"
26+
- ".markdown-link-check.json"
27+
- "package.json"
28+
- "package-lock.json"
29+
- "Taskfile.ya?ml"
30+
- "**/.markdownlint*"
31+
- "**.mdx?"
32+
- "**.mkdn"
33+
- "**.mdown"
34+
- "**.markdown"
35+
schedule:
36+
# Run every Tuesday at 8 AM UTC to catch breakage caused by external changes.
37+
- cron: "0 8 * * TUE"
38+
workflow_dispatch:
39+
repository_dispatch:
40+
41+
jobs:
42+
run-determination:
43+
runs-on: ubuntu-latest
44+
permissions: {}
45+
outputs:
46+
result: ${{ steps.determination.outputs.result }}
47+
steps:
48+
- name: Determine if the rest of the workflow should run
49+
id: determination
50+
run: |
51+
RELEASE_BRANCH_REGEX="^refs/heads/v[0-9]+$"
52+
# The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
53+
if [[
54+
"${{ github.event_name }}" != "create" ||
55+
"${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
56+
]]; then
57+
# Run the other jobs.
58+
RESULT="true"
59+
else
60+
# There is no need to run the other jobs.
61+
RESULT="false"
62+
fi
63+
64+
echo "result=$RESULT" >> $GITHUB_OUTPUT
65+
66+
lint:
67+
needs: run-determination
68+
if: needs.run-determination.outputs.result == 'true'
69+
runs-on: ubuntu-latest
70+
permissions:
71+
contents: read
72+
73+
steps:
74+
- name: Checkout repository
75+
uses: actions/checkout@v4
76+
77+
- name: Setup Node.js
78+
uses: actions/setup-node@v4
79+
with:
80+
node-version: ${{ env.NODE_VERSION }}
81+
82+
- name: Initialize markdownlint-cli problem matcher
83+
uses: xt0rted/markdownlint-problem-matcher@v2
84+
85+
- name: Install Task
86+
uses: arduino/setup-task@v1
87+
with:
88+
repo-token: ${{ secrets.GITHUB_TOKEN }}
89+
version: 3.x
90+
91+
- name: Lint
92+
run: task markdown:lint
93+
94+
links:
95+
needs: run-determination
96+
if: needs.run-determination.outputs.result == 'true'
97+
runs-on: ubuntu-latest
98+
permissions:
99+
contents: read
100+
101+
steps:
102+
- name: Checkout repository
103+
uses: actions/checkout@v4
104+
105+
- name: Setup Node.js
106+
uses: actions/setup-node@v4
107+
with:
108+
node-version: ${{ env.NODE_VERSION }}
109+
110+
- name: Install Task
111+
uses: arduino/setup-task@v1
112+
with:
113+
repo-token: ${{ secrets.GITHUB_TOKEN }}
114+
version: 3.x
115+
116+
- name: Check links
117+
run: task --silent markdown:check-links

‎.markdown-link-check.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"httpHeaders": [
3+
{
4+
"urls": ["https://docs.github.com/"],
5+
"headers": {
6+
"Accept-Encoding": "gzip, deflate, br"
7+
}
8+
}
9+
],
10+
"retryOn429": true,
11+
"retryCount": 3,
12+
"aliveStatusCodes": [200, 206]
13+
}

‎.markdownlint.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlint.yml
2+
# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
3+
# The code style defined in this file is the official standardized style to be used in all Arduino projects and should
4+
# not be modified.
5+
# Note: Rules disabled solely because they are redundant to Prettier are marked with a "Prettier" comment.
6+
7+
default: false
8+
MD001: false
9+
MD002: false
10+
MD003: false # Prettier
11+
MD004: false # Prettier
12+
MD005: false # Prettier
13+
MD006: false # Prettier
14+
MD007: false # Prettier
15+
MD008: false # Prettier
16+
MD009:
17+
br_spaces: 0
18+
strict: true
19+
list_item_empty_lines: false # Prettier
20+
MD010: false # Prettier
21+
MD011: true
22+
MD012: false # Prettier
23+
MD013: false
24+
MD014: false
25+
MD018: true
26+
MD019: false # Prettier
27+
MD020: true
28+
MD021: false # Prettier
29+
MD022: false # Prettier
30+
MD023: false # Prettier
31+
MD024: false
32+
MD025:
33+
level: 1
34+
front_matter_title: '^\s*"?title"?\s*[:=]'
35+
MD026: false
36+
MD027: false # Prettier
37+
MD028: false
38+
MD029:
39+
style: one
40+
MD030:
41+
ul_single: 1
42+
ol_single: 1
43+
ul_multi: 1
44+
ol_multi: 1
45+
MD031: false # Prettier
46+
MD032: false # Prettier
47+
MD033: false
48+
MD034: false
49+
MD035: false # Prettier
50+
MD036: false
51+
MD037: true
52+
MD038: true
53+
MD039: true
54+
MD040: false
55+
MD041: false
56+
MD042: true
57+
MD043: false
58+
MD044: false
59+
MD045: true
60+
MD046:
61+
style: fenced
62+
MD047: false # Prettier

‎.markdownlintignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlintignore
2+
.licenses/
3+
__pycache__/
4+
node_modules/

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# `arduino/report-size-deltas` action
22

3+
[![Check Markdown status](https://github.com/arduino/report-size-deltas/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-markdown-task.yml)
34
[![Check npm status](https://github.com/arduino/report-size-deltas/actions/workflows/check-npm-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-npm-task.yml)
45
[![Check Poetry status](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml)
56
[![Check Python status](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml)

‎Taskfile.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ tasks:
1212
deps:
1313
- task: npm:validate
1414
- task: general:check-spelling
15+
- task: markdown:check-links
16+
- task: markdown:lint
1517
- task: npm:validate
1618
- task: poetry:validate
1719
- task: python:lint
@@ -21,9 +23,15 @@ tasks:
2123
desc: Make automated corrections to the project's files
2224
deps:
2325
- task: general:correct-spelling
26+
- task: markdown:fix
2427
- task: poetry:sync
2528
- task: python:format
2629

30+
docs:generate:
31+
desc: Create all generated documentation content
32+
# This is an "umbrella" task used to call any documentation generation processes the project has.
33+
# It can be left empty if there are none.
34+
2735
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml
2836
general:check-spelling:
2937
desc: Check for commonly misspelled words
@@ -40,6 +48,59 @@ tasks:
4048
cmds:
4149
- poetry run codespell --write-changes
4250

51+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
52+
markdown:check-links:
53+
desc: Check for broken links
54+
vars:
55+
# The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability.
56+
# This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes
57+
# standard newline escaping syntax to not work when the task is run on Windows.
58+
#
59+
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
60+
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
61+
# \ characters special treatment on Windows in an attempt to support them as path separators.
62+
#
63+
# prettier-ignore
64+
CHECK_LINKS_COMMAND:
65+
"
66+
find . \
67+
-type d -name \".git\" -prune -o \
68+
-type d -name \".licenses\" -prune -o \
69+
-type d -name \"__pycache__\" -prune -o \
70+
-type d -name \"node_modules\" -prune -o \
71+
-regex \".*[.]md\" \
72+
-exec \
73+
markdown-link-check \
74+
--quiet \
75+
--config \"./.markdown-link-check.json\" \
76+
\\{\\} \
77+
+
78+
"
79+
deps:
80+
- task: docs:generate
81+
- task: npm:install-deps
82+
cmds:
83+
- |
84+
npx \
85+
--package=markdown-link-check \
86+
--call='{{.CHECK_LINKS_COMMAND}}'
87+
88+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
89+
markdown:fix:
90+
desc: Automatically correct linting violations in Markdown files where possible
91+
deps:
92+
- task: npm:install-deps
93+
cmds:
94+
- npx markdownlint-cli --fix "**/*.md"
95+
96+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
97+
markdown:lint:
98+
desc: Check for problems in Markdown files
99+
deps:
100+
- task: npm:install-deps
101+
cmds:
102+
- npx markdownlint-cli "**/*.md"
103+
43104
# Parameter variables:
44105
# - PROJECT_PATH: path of the npm-managed project. Default value: "./"
45106
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml

0 commit comments

Comments
 (0)