Skip to content

Commit c7857d4

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 file. In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them via a file: https://github.com/igorshubovych/markdownlint-cli#ignoring-files markdown-link-check is configured via the file: https://github.com/tcort/markdown-link-check#config-file-format
1 parent c1ceab9 commit c7857d4

File tree

8 files changed

+1486
-50
lines changed

8 files changed

+1486
-50
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 "::set-output name=result::$RESULT"
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@v1
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 & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
# Arduino Language Server
44

55
[![Check Taskfiles status](https://github.com/arduino/arduino-language-server/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/arduino-language-server/actions/workflows/check-taskfiles.yml)
6+
[![Check Markdown status](https://github.com/arduino/arduino-language-server/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/arduino-language-server/actions/workflows/check-markdown-task.yml)
67

78
The **Arduino Language Server** is the tool that powers the autocompletion of the new [Arduino IDE 2][arduino-ide-repo]. It implements the standard [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) so it can be used with other IDEs as well.
89

@@ -62,6 +63,7 @@ To run tests:
6263
```
6364
go test -v ./...
6465
```
66+
6567
## Usage
6668

6769
The language server it's not intended for direct usage by humans via the command line terminal.
@@ -86,6 +88,7 @@ The -fqbn flag represents the board you're actually working on (different boards
8688
The support for the board must be installed with the `arduino-cli core install ...` command before starting the language server.
8789

8890
If you do not have an Arduino CLI config file, you can create one by running:
91+
8992
```
9093
arduino-cli config init
9194
```
@@ -98,6 +101,5 @@ This open source code was written by the Arduino team and is maintained on a dai
98101

99102
The code contained in this repository is licensed under the terms of the Apache 2.0 license. If you have questions about licensing please contact us at [license@arduino.cc](mailto:license@arduino.cc).
100103

101-
102104
[arduino-ide-repo]: https://github.com/arduino/arduino-ide
103105
[go-install]: https://golang.org/doc/install

‎Taskfile.yml‎

Lines changed: 63 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,42 @@ version: "3"
33
includes:
44
dist: ./DistTasks.yml
55

6+
vars:
7+
PROJECT_NAME: "arduino-language-server"
8+
DIST_DIR: "dist"
9+
DEFAULT_GO_PACKAGES:
10+
sh: |
11+
echo $(cd {{default "./" .GO_MODULE_PATH}} && go list ./... | tr '\n' ' ' || echo '"ERROR: Unable to discover Go packages"')
12+
# build vars
13+
COMMIT:
14+
sh: echo "$(git log --no-show-signature -n 1 --format=%h)"
15+
TIMESTAMP:
16+
sh: echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
17+
TIMESTAMP_SHORT:
18+
sh: echo "{{now | date "20060102"}}"
19+
TAG:
20+
sh: echo "$(git tag --points-at=HEAD 2> /dev/null | head -n1)"
21+
VERSION: "{{if .NIGHTLY}}nightly-{{.TIMESTAMP_SHORT}}{{else if .TAG}}{{.TAG}}{{else}}{{.PACKAGE_NAME_PREFIX}}git-snapshot{{end}}"
22+
CONFIGURATION_PACKAGE: "github.com/arduino/arduino-language-server/version"
23+
LDFLAGS: >-
24+
-ldflags
25+
'
26+
-X {{.CONFIGURATION_PACKAGE}}.versionString={{.VERSION}}
27+
-X {{.CONFIGURATION_PACKAGE}}.commit={{.COMMIT}}
28+
-X {{.CONFIGURATION_PACKAGE}}.date={{.TIMESTAMP}}
29+
'
30+
# test vars
31+
GOFLAGS: "-timeout 10m -v -coverpkg=./... -covermode=atomic"
32+
TEST_VERSION: "0.0.0-test.preview"
33+
TEST_COMMIT: "deadbeef"
34+
TEST_LDFLAGS: >-
35+
-ldflags
36+
'
37+
-X {{.CONFIGURATION_PACKAGE}}.versionString={{.TEST_VERSION}}
38+
-X {{.CONFIGURATION_PACKAGE}}.commit={{.TEST_COMMIT}}
39+
-X {{.CONFIGURATION_PACKAGE}}.date={{.TIMESTAMP}}
40+
'
41+
642
tasks:
743
docs:generate:
844
desc: Create all generated documentation content
@@ -124,6 +160,7 @@ tasks:
124160
desc: Check for broken links
125161
deps:
126162
- task: docs:generate
163+
- task: npm:install-deps
127164
cmds:
128165
- |
129166
if [[ "{{.OS}}" == "Windows_NT" ]]; then
@@ -140,7 +177,14 @@ tasks:
140177
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
141178
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
142179
# \ characters special treatment on Windows in an attempt to support them as path separators.
143-
for file in $(find . -regex ".*[.]md"); do
180+
for file in $(
181+
find . \
182+
-type d -name '.git' -prune -o \
183+
-type d -name '.licenses' -prune -o \
184+
-type d -name '__pycache__' -prune -o \
185+
-type d -name 'node_modules' -prune -o \
186+
-regex ".*[.]md" -print
187+
); do
144188
markdown-link-check \
145189
--quiet \
146190
--config "./.markdown-link-check.json" \
@@ -151,7 +195,14 @@ tasks:
151195
else
152196
npx --package=markdown-link-check --call='
153197
STATUS=0
154-
for file in $(find . -regex ".*[.]md"); do
198+
for file in $(
199+
find . \
200+
-type d -name '.git' -prune -o \
201+
-type d -name '.licenses' -prune -o \
202+
-type d -name '__pycache__' -prune -o \
203+
-type d -name 'node_modules' -prune -o \
204+
-regex ".*[.]md" -print
205+
); do
155206
markdown-link-check \
156207
--quiet \
157208
--config "./.markdown-link-check.json" \
@@ -165,15 +216,25 @@ tasks:
165216
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
166217
markdown:fix:
167218
desc: Automatically correct linting violations in Markdown files where possible
219+
deps:
220+
- task: npm:install-deps
168221
cmds:
169222
- npx markdownlint-cli --fix "**/*.md"
170223

171224
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
172225
markdown:lint:
173226
desc: Check for problems in Markdown files
227+
deps:
228+
- task: npm:install-deps
174229
cmds:
175230
- npx markdownlint-cli "**/*.md"
176231

232+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
233+
npm:install-deps:
234+
desc: Install dependencies managed by npm
235+
cmds:
236+
- npm install
237+
177238
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/poetry-task/Taskfile.yml
178239
poetry:install-deps:
179240
desc: Install dependencies managed by Poetry
@@ -320,39 +381,3 @@ tasks:
320381
- task: poetry:install-deps
321382
cmds:
322383
- poetry run mkdocs serve
323-
324-
vars:
325-
PROJECT_NAME: "arduino-language-server"
326-
DIST_DIR: "dist"
327-
DEFAULT_GO_PACKAGES:
328-
sh: |
329-
echo $(cd {{default "./" .GO_MODULE_PATH}} && go list ./... | tr '\n' ' ' || echo '"ERROR: Unable to discover Go packages"')
330-
# build vars
331-
COMMIT:
332-
sh: echo "$(git log --no-show-signature -n 1 --format=%h)"
333-
TIMESTAMP:
334-
sh: echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
335-
TIMESTAMP_SHORT:
336-
sh: echo "{{now | date "20060102"}}"
337-
TAG:
338-
sh: echo "$(git tag --points-at=HEAD 2> /dev/null | head -n1)"
339-
VERSION: "{{if .NIGHTLY}}nightly-{{.TIMESTAMP_SHORT}}{{else if .TAG}}{{.TAG}}{{else}}{{.PACKAGE_NAME_PREFIX}}git-snapshot{{end}}"
340-
CONFIGURATION_PACKAGE: "github.com/arduino/arduino-language-server/version"
341-
LDFLAGS: >-
342-
-ldflags
343-
'
344-
-X {{.CONFIGURATION_PACKAGE}}.versionString={{.VERSION}}
345-
-X {{.CONFIGURATION_PACKAGE}}.commit={{.COMMIT}}
346-
-X {{.CONFIGURATION_PACKAGE}}.date={{.TIMESTAMP}}
347-
'
348-
# test vars
349-
GOFLAGS: "-timeout 10m -v -coverpkg=./... -covermode=atomic"
350-
TEST_VERSION: "0.0.0-test.preview"
351-
TEST_COMMIT: "deadbeef"
352-
TEST_LDFLAGS: >-
353-
-ldflags
354-
'
355-
-X {{.CONFIGURATION_PACKAGE}}.versionString={{.TEST_VERSION}}
356-
-X {{.CONFIGURATION_PACKAGE}}.commit={{.TEST_COMMIT}}
357-
-X {{.CONFIGURATION_PACKAGE}}.date={{.TIMESTAMP}}
358-
'

0 commit comments

Comments
 (0)