Skip to content

Commit e1b5521

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 1600801 commit e1b5521

File tree

8 files changed

+1371
-3
lines changed

8 files changed

+1371
-3
lines changed

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
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+
outputs:
45+
result: ${{ steps.determination.outputs.result }}
46+
steps:
47+
- name: Determine if the rest of the workflow should run
48+
id: determination
49+
run: |
50+
RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
51+
# The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
52+
if [[
53+
"${{ github.event_name }}" != "create" ||
54+
"${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
55+
]]; then
56+
# Run the other jobs.
57+
RESULT="true"
58+
else
59+
# There is no need to run the other jobs.
60+
RESULT="false"
61+
fi
62+
63+
echo "result=$RESULT" >> $GITHUB_OUTPUT
64+
65+
lint:
66+
needs: run-determination
67+
if: needs.run-determination.outputs.result == 'true'
68+
runs-on: ubuntu-latest
69+
70+
steps:
71+
- name: Checkout repository
72+
uses: actions/checkout@v3
73+
74+
- name: Setup Node.js
75+
uses: actions/setup-node@v3
76+
with:
77+
node-version: ${{ env.NODE_VERSION }}
78+
79+
- name: Initialize markdownlint-cli problem matcher
80+
uses: xt0rted/markdownlint-problem-matcher@v2
81+
82+
- name: Install Task
83+
uses: arduino/setup-task@v1
84+
with:
85+
repo-token: ${{ secrets.GITHUB_TOKEN }}
86+
version: 3.x
87+
88+
- name: Lint
89+
run: task markdown:lint
90+
91+
links:
92+
needs: run-determination
93+
if: needs.run-determination.outputs.result == 'true'
94+
runs-on: ubuntu-latest
95+
96+
steps:
97+
- name: Checkout repository
98+
uses: actions/checkout@v3
99+
100+
- name: Setup Node.js
101+
uses: actions/setup-node@v3
102+
with:
103+
node-version: ${{ env.NODE_VERSION }}
104+
105+
- name: Install Task
106+
uses: arduino/setup-task@v1
107+
with:
108+
repo-token: ${{ secrets.GITHUB_TOKEN }}
109+
version: 3.x
110+
111+
- name: Check links
112+
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: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
# Arduino pluggable discovery for dfu devices
2+
23
[![Sync Labels status](https://github.com/arduino/dfu-discovery/actions/workflows/sync-labels.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/sync-labels.yml)
34
[![Check Go Dependencies status](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-dependencies-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-dependencies-task.yml)
45
[![Check License status](https://github.com/arduino/dfu-discovery/actions/workflows/check-license.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-license.yml)
56
[![Check Go status](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-task.yml)
67
[![Publish Tester Build status](https://github.com/arduino/dfu-discover/actions/workflows/publish-go-tester-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/publish-go-tester-task.yml)
78
[![Check Taskfiles status](https://github.com/arduino/dfu-discovery/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-taskfiles.yml)
89
[![Check Workflows status](https://github.com/arduino/dfu-discovery/actions/workflows/check-workflows-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-workflows-task.yml)
10+
[![Check Markdown status](https://github.com/arduino/dfu-discovery/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-markdown-task.yml)
911

1012
The `dfu-discovery` tool is a command line program that interacts via stdio. It accepts commands as plain ASCII strings terminated with LF `\n` and sends response as JSON.
1113

@@ -15,6 +17,7 @@ The `dfu-discovery` tool is a command line program that interacts via stdio. It
1517

1618
Just run `task download-dfu-util` to download dfu-util source code and then `task dist:<platform-to-build>`
1719
The platform to build can be one of:
20+
1821
- Windows_32bit
1922
- Windows_64bit
2023
- Linux_32bit

‎Taskfile.yml

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ tasks:
5656
# for some reason quirks.c has the exec flag set
5757
chmod -x dfu-util_quirks.c
5858
fi
59-
59+
6060
download-libusb:
6161
desc: download libusb and copy the files in the correct dir
6262
cmds:
@@ -206,3 +206,83 @@ tasks:
206206
else
207207
echo "{{.RAW_PATH}}"
208208
fi
209+
210+
docs:generate:
211+
desc: Create all generated documentation content
212+
# This is an "umbrella" task used to call any documentation generation processes the project has.
213+
# It can be left empty if there are none.
214+
215+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
216+
markdown:check-links:
217+
desc: Check for broken links
218+
deps:
219+
- task: docs:generate
220+
- task: npm:install-deps
221+
cmds:
222+
- |
223+
if [[ "{{.OS}}" == "Windows_NT" ]]; then
224+
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
225+
# so the Windows user is required to have markdown-link-check installed and in PATH.
226+
if ! which markdown-link-check &>/dev/null; then
227+
echo "markdown-link-check not found or not in PATH."
228+
echo "Please install: https://github.com/tcort/markdown-link-check#readme"
229+
exit 1
230+
fi
231+
# Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero
232+
# exit status, but it's better to check all links before exiting.
233+
set +o errexit
234+
STATUS=0
235+
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
236+
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
237+
# \ characters special treatment on Windows in an attempt to support them as path separators.
238+
for file in $(
239+
find . \
240+
-type d -name '.git' -prune -o \
241+
-type d -name '.licenses' -prune -o \
242+
-type d -name '__pycache__' -prune -o \
243+
-type d -name 'node_modules' -prune -o \
244+
-regex ".*[.]md" -print
245+
); do
246+
markdown-link-check \
247+
--quiet \
248+
--config "./.markdown-link-check.json" \
249+
"$file"
250+
STATUS=$(( $STATUS + $? ))
251+
done
252+
exit $STATUS
253+
else
254+
npx --package=markdown-link-check --call='
255+
STATUS=0
256+
for file in $(
257+
find . \
258+
-type d -name '.git' -prune -o \
259+
-type d -name '.licenses' -prune -o \
260+
-type d -name '__pycache__' -prune -o \
261+
-type d -name 'node_modules' -prune -o \
262+
-regex ".*[.]md" -print
263+
); do
264+
markdown-link-check \
265+
--quiet \
266+
--config "./.markdown-link-check.json" \
267+
"$file"
268+
STATUS=$(( $STATUS + $? ))
269+
done
270+
exit $STATUS
271+
'
272+
fi
273+
274+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
275+
markdown:fix:
276+
desc: Automatically correct linting violations in Markdown files where possible
277+
deps:
278+
- task: npm:install-deps
279+
cmds:
280+
- npx markdownlint-cli --fix "**/*.md"
281+
282+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
283+
markdown:lint:
284+
desc: Check for problems in Markdown files
285+
deps:
286+
- task: npm:install-deps
287+
cmds:
288+
- npx markdownlint-cli "**/*.md"

0 commit comments

Comments
 (0)