Skip to content

Commit 4e0e596

Browse files
per1234per1234
committed
Add template 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 The workflow is also used for this repository's own CI.
1 parent ec572a6 commit 4e0e596

File tree

11 files changed

+530
-0
lines changed

11 files changed

+530
-0
lines changed

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

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md
2+
name: Check Markdown
3+
4+
# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
5+
on:
6+
push:
7+
paths:
8+
- ".github/workflows/check-markdown-task.ya?ml"
9+
- ".markdown-link-check.json"
10+
- "Taskfile.ya?ml"
11+
- "**/.markdownlint*"
12+
- "**.mdx?"
13+
- "**.mkdn"
14+
- "**.mdown"
15+
- "**.markdown"
16+
pull_request:
17+
paths:
18+
- ".github/workflows/check-markdown-task.ya?ml"
19+
- ".markdown-link-check.json"
20+
- "Taskfile.ya?ml"
21+
- "**/.markdownlint*"
22+
- "**.mdx?"
23+
- "**.mkdn"
24+
- "**.mdown"
25+
- "**.markdown"
26+
schedule:
27+
# Run every Tuesday at 8 AM UTC to catch breakage caused by external changes.
28+
- cron: "0 8 * * TUE"
29+
workflow_dispatch:
30+
repository_dispatch:
31+
32+
jobs:
33+
lint:
34+
runs-on: ubuntu-latest
35+
36+
steps:
37+
- name: Checkout repository
38+
uses: actions/checkout@v2
39+
40+
- name: Initialize markdownlint-cli problem matcher
41+
uses: xt0rted/markdownlint-problem-matcher@v1
42+
43+
- name: Install Task
44+
uses: arduino/setup-task@v1
45+
with:
46+
repo-token: ${{ secrets.GITHUB_TOKEN }}
47+
version: 3.x
48+
49+
- name: Lint
50+
run: task markdown:lint
51+
52+
links:
53+
runs-on: ubuntu-latest
54+
55+
steps:
56+
- name: Checkout repository
57+
uses: actions/checkout@v2
58+
59+
- name: Install Task
60+
uses: arduino/setup-task@v1
61+
with:
62+
repo-token: ${{ secrets.GITHUB_TOKEN }}
63+
version: 3.x
64+
65+
- name: Check links
66+
run: task --silent markdown:check-links

‎.markdown-link-check.json

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"retryOn429": true,
3+
"retryCount": 3,
4+
"aliveStatusCodes": [200, 206]
5+
}

‎.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

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
[![Check Workflow Duplicates Sync status](https://github.com/arduino/tooling-project-assets/actions/workflows/check-dependabot-sync.yml/badge.svg)](https://github.com/arduino/tooling-project-assets/actions/workflows/check-dependabot-sync.yml)
77
[![Check CI Workflows Sync status](https://github.com/arduino/tooling-project-assets/actions/workflows/check-ci-sync.yml/badge.svg)](https://github.com/arduino/tooling-project-assets/actions/workflows/check-ci-sync.yml)
88
[![Check Configuration Files Sync status](https://github.com/arduino/tooling-project-assets/actions/workflows/check-config-sync.yml/badge.svg)](https://github.com/arduino/tooling-project-assets/actions/workflows/check-config-sync.yml)
9+
[![Check Markdown status](https://github.com/arduino/tooling-project-assets/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/tooling-project-assets/actions/workflows/check-markdown-task.yml)
910

1011
The [Arduino](https://www.arduino.cc/) Tooling Team's collection of reusable project infrastructure assets.
1112

‎Taskfile.yml

+53
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,15 @@ tasks:
77
- task: ci:sync
88
- task: config:sync
99
- task: dependabot:sync
10+
- task: markdown:fix
1011

1112
check:
1213
desc: Check for problems with the project
1314
deps:
1415
- task: general:check-formatting
1516
- task: config:validate
17+
- task: markdown:lint
18+
- task: markdown:check-links
1619

1720
general:check-formatting:
1821
desc: Check basic formatting style of all files
@@ -33,6 +36,7 @@ tasks:
3336
- |
3437
cp \
3538
"{{.WORKFLOW_TEMPLATES_PATH}}/check-general-formatting-task.yml" \
39+
"{{.WORKFLOW_TEMPLATES_PATH}}/check-markdown-task.yml" \
3640
"{{.WORKFLOWS_PATH}}"
3741
3842
config:sync:
@@ -44,6 +48,8 @@ tasks:
4448
- |
4549
cp \
4650
"{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/shared/.editorconfig" \
51+
"{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/check-markdown/.markdown-link-check.json" \
52+
"{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/check-markdown/.markdownlint.yml" \
4753
"{{.REPOSITORY_ROOT_PATH}}"
4854
4955
dependabot:sync:
@@ -75,3 +81,50 @@ tasks:
7581
cmds:
7682
- wget --quiet --output-document="{{.DEPENDABOT_SCHEMA_PATH}}" {{.DEPENDABOT_SCHEMA_URL}}
7783
- npx ajv-cli@{{.AJV_CLI_VERSION}} validate -s "{{.DEPENDABOT_SCHEMA_PATH}}" -d "{{.DEPENDABOT_DATA_PATH}}"
84+
85+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
86+
markdown:lint:
87+
desc: Check for problems in Markdown files
88+
cmds:
89+
- npx markdownlint-cli "**/*.md"
90+
91+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
92+
markdown:fix:
93+
desc: Automatically correct linting violations in Markdown files where possible
94+
cmds:
95+
- npx markdownlint-cli --fix "**/*.md"
96+
97+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
98+
markdown:check-links:
99+
desc: Check for broken links
100+
cmds:
101+
- |
102+
if [[ "{{.OS}}" == "Windows_NT" ]]; then
103+
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
104+
# so the Windows user is required to have markdown-link-check installed and in PATH.
105+
if ! which markdown-link-check &>/dev/null; then
106+
echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme"
107+
exit 1
108+
fi
109+
STATUS=0
110+
for file in $(find -name "*.md"); do
111+
markdown-link-check \
112+
--quiet \
113+
--config "./.markdown-link-check.json" \
114+
"$file"
115+
STATUS=$(( $STATUS + $? ))
116+
done
117+
exit $STATUS
118+
else
119+
npx --package=markdown-link-check --call='
120+
STATUS=0
121+
for file in $(find -name "*.md"); do
122+
markdown-link-check \
123+
--quiet \
124+
--config "./.markdown-link-check.json" \
125+
"$file"
126+
STATUS=$(( $STATUS + $? ))
127+
done
128+
exit $STATUS
129+
'
130+
fi

‎workflow-templates/assets/check-markdown-task/Taskfile.yml

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# See: https://taskfile.dev/#/usage
2+
version: "3"
3+
4+
tasks:
5+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
6+
markdown:lint:
7+
desc: Check for problems in Markdown files
8+
cmds:
9+
- npx markdownlint-cli "**/*.md"
10+
11+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
12+
markdown:fix:
13+
desc: Automatically correct linting violations in Markdown files where possible
14+
cmds:
15+
- npx markdownlint-cli --fix "**/*.md"
16+
17+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
18+
markdown:check-links:
19+
desc: Check for broken links
20+
cmds:
21+
- |
22+
if [[ "{{.OS}}" == "Windows_NT" ]]; then
23+
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
24+
# so the Windows user is required to have markdown-link-check installed and in PATH.
25+
if ! which markdown-link-check &>/dev/null; then
26+
echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme"
27+
exit 1
28+
fi
29+
STATUS=0
30+
for file in $(find -name "*.md"); do
31+
markdown-link-check \
32+
--quiet \
33+
--config "./.markdown-link-check.json" \
34+
"$file"
35+
STATUS=$(( $STATUS + $? ))
36+
done
37+
exit $STATUS
38+
else
39+
npx --package=markdown-link-check --call='
40+
STATUS=0
41+
for file in $(find -name "*.md"); do
42+
markdown-link-check \
43+
--quiet \
44+
--config "./.markdown-link-check.json" \
45+
"$file"
46+
STATUS=$(( $STATUS + $? ))
47+
done
48+
exit $STATUS
49+
'
50+
fi

‎workflow-templates/assets/check-markdown/.markdown-link-check.json

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"retryOn429": true,
3+
"retryCount": 3,
4+
"aliveStatusCodes": [200, 206]
5+
}

‎workflow-templates/assets/check-markdown/.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

0 commit comments

Comments
 (0)