Skip to content

Commit 01c74e9

Browse files
MatteoPologrutoMatteoPologruto
committed
Add CI workflow to check Markdown files for problems
On every push and pull request that affects relevant files, and periodically, 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 66fc6aa commit 01c74e9

8 files changed

+2151
-38
lines changed

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

+117
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/[0-9]+.[0-9]+.x"
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@v3
76+
77+
- name: Setup Node.js
78+
uses: actions/setup-node@v3
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@v3
104+
105+
- name: Setup Node.js
106+
uses: actions/setup-node@v3
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

+13
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

+62
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

+4
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

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
[![Check Taskfiles status](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/check-taskfiles.yml)
1010
[![Check Workflows status](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/check-workflows-task.yml/badge.svg)](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/check-workflows-task.yml)
1111
[![Release status](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/release-tag.yml/badge.svg)](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/release-tag.yml)
12+
[![Check Markdown status](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/check-markdown-task.yml)
1213

1314
<!--[![Test Go status](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/test-go-task.yml/badge.svg)](https://github.com/arduino/fwuploader-plugin-helper/actions/workflows/test-go-task.yml)-->
1415
<!--[![Codecov](https://codecov.io/gh/arduino/fwuploader-plugin-helper/branch/main/graph/badge.svg)](https://codecov.io/gh/arduino/fwuploader-plugin-helper)-->

‎Taskfile.yml

+80
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ tasks:
4343
-s "{{.WORKFLOW_SCHEMA_PATH}}" \
4444
-d "{{.WORKFLOWS_DATA_PATH}}"
4545
46+
docs:generate:
47+
desc: Create all generated documentation content
48+
# This is an "umbrella" task used to call any documentation generation processes the project has.
49+
# It can be left empty if there are none.
50+
4651
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-dependencies-task/Taskfile.yml
4752
general:cache-dep-licenses:
4853
desc: Cache dependency license metadata
@@ -118,6 +123,81 @@ tasks:
118123
cmds:
119124
- go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
120125

126+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
127+
markdown:check-links:
128+
desc: Check for broken links
129+
deps:
130+
- task: docs:generate
131+
- task: npm:install-deps
132+
cmds:
133+
- |
134+
if [[ "{{.OS}}" == "Windows_NT" ]]; then
135+
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
136+
# so the Windows user is required to have markdown-link-check installed and in PATH.
137+
if ! which markdown-link-check &>/dev/null; then
138+
echo "markdown-link-check not found or not in PATH."
139+
echo "Please install: https://github.com/tcort/markdown-link-check#readme"
140+
exit 1
141+
fi
142+
# Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero
143+
# exit status, but it's better to check all links before exiting.
144+
set +o errexit
145+
STATUS=0
146+
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
147+
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
148+
# \ characters special treatment on Windows in an attempt to support them as path separators.
149+
for file in $(
150+
find . \
151+
-type d -name '.git' -prune -o \
152+
-type d -name '.licenses' -prune -o \
153+
-type d -name '__pycache__' -prune -o \
154+
-type d -name 'node_modules' -prune -o \
155+
-regex ".*[.]md" -print
156+
); do
157+
markdown-link-check \
158+
--quiet \
159+
--config "./.markdown-link-check.json" \
160+
"$file"
161+
STATUS=$(( $STATUS + $? ))
162+
done
163+
exit $STATUS
164+
else
165+
npx --package=markdown-link-check --call='
166+
STATUS=0
167+
for file in $(
168+
find . \
169+
-type d -name '.git' -prune -o \
170+
-type d -name '.licenses' -prune -o \
171+
-type d -name '__pycache__' -prune -o \
172+
-type d -name 'node_modules' -prune -o \
173+
-regex ".*[.]md" -print
174+
); do
175+
markdown-link-check \
176+
--quiet \
177+
--config "./.markdown-link-check.json" \
178+
"$file"
179+
STATUS=$(( $STATUS + $? ))
180+
done
181+
exit $STATUS
182+
'
183+
fi
184+
185+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
186+
markdown:fix:
187+
desc: Automatically correct linting violations in Markdown files where possible
188+
deps:
189+
- task: npm:install-deps
190+
cmds:
191+
- npx markdownlint-cli --fix "**/*.md"
192+
193+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
194+
markdown:lint:
195+
desc: Check for problems in Markdown files
196+
deps:
197+
- task: npm:install-deps
198+
cmds:
199+
- npx markdownlint-cli "**/*.md"
200+
121201
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
122202
npm:install-deps:
123203
desc: Install dependencies managed by npm

0 commit comments

Comments
 (0)