From 3302ab189217f56ea75654bf9e21a5433565d449 Mon Sep 17 00:00:00 2001 From: lucarin91 Date: Tue, 16 Dec 2025 11:08:39 +0100 Subject: [PATCH 1/5] chore(ci): add broken link checker --- .github/workflows/check-markdown-task.yml | 94 +++++++++++++++++++++++ .markdown-link-check.json | 19 +++++ Taskfile.yaml | 37 +++++++++ 3 files changed, 150 insertions(+) create mode 100644 .github/workflows/check-markdown-task.yml create mode 100644 .markdown-link-check.json create mode 100644 Taskfile.yaml diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml new file mode 100644 index 0000000..d49de4d --- /dev/null +++ b/.github/workflows/check-markdown-task.yml @@ -0,0 +1,94 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md +name: Check Markdown + +# See: https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows +on: + create: + push: + paths: + - ".github/workflows/check-markdown-task.ya?ml" + - ".markdown-link-check.json" + - ".npmrc" + - "go.mod" + - "go.sum" + - "package.json" + - "package-lock.json" + - "Taskfile.ya?ml" + - "**/.markdownlint*" + - "**.mdx?" + - "**.mkdn" + - "**.mdown" + - "**.markdown" + pull_request: + paths: + - ".github/workflows/check-markdown-task.ya?ml" + - ".markdown-link-check.json" + - ".npmrc" + - "go.mod" + - "go.sum" + - "package.json" + - "package-lock.json" + - "Taskfile.ya?ml" + - "**/.markdownlint*" + - "**.mdx?" + - "**.mkdn" + - "**.mdown" + - "**.markdown" + schedule: + # Run every Tuesday at 8 AM UTC to catch breakage caused by external changes. + - cron: "0 8 * * TUE" + workflow_dispatch: + repository_dispatch: + +jobs: + run-determination: + runs-on: ubuntu-latest + permissions: {} + outputs: + result: ${{ steps.determination.outputs.result }} + steps: + - name: Determine if the rest of the workflow should run + id: determination + run: | + RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x" + # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead. + if [[ + "${{ github.event_name }}" != "create" || + "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX + ]]; then + # Run the other jobs. + RESULT="true" + else + # There is no need to run the other jobs. + RESULT="false" + fi + + echo "result=$RESULT" >>$GITHUB_OUTPUT + + links: + needs: run-determination + if: needs.run-determination.outputs.result == 'true' + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Install Go + uses: actions/setup-go@v6 + with: + go-version-file: go.mod + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version-file: package.json + + - name: Check links + run: | + go tool \ + github.com/go-task/task/v3/cmd/task \ + --silent \ + markdown:check-links diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 0000000..41b3d13 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,19 @@ +{ + "httpHeaders": [ + { + "urls": [ + "https://docs.github.com/" + ], + "headers": { + "Accept-Encoding": "gzip, deflate, br" + } + } + ], + "retryOn429": true, + "timeout": "30s", + "retryCount": 3, + "aliveStatusCodes": [ + 200, + 206 + ] +} diff --git a/Taskfile.yaml b/Taskfile.yaml new file mode 100644 index 0000000..fe70de2 --- /dev/null +++ b/Taskfile.yaml @@ -0,0 +1,37 @@ +# See: https://taskfile.dev/#/usage +version: "3" + +tasks: + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:check-links: + desc: Check for broken links + vars: + # The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability. + # This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes + # standard newline escaping syntax to not work when the task is run on Windows. + # + # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows + # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives + # \ characters special treatment on Windows in an attempt to support them as path separators. + # + # prettier-ignore + CHECK_LINKS_COMMAND: + " + find . \ + -type d -name \".git\" -prune -o \ + -type d -name \".licenses\" -prune -o \ + -type d -name \"__pycache__\" -prune -o \ + -type d -name \"node_modules\" -prune -o \ + -regex \".*[.]md\" \ + -exec \ + markdown-link-check \ + --quiet \ + --config \"./.markdown-link-check.json\" \ + \\{\\} \ + + + " + cmds: + - | + npx \ + --package=markdown-link-check \ + --call='{{.CHECK_LINKS_COMMAND}}' From 008af7c2f80d88ec63c53bf86b53e77c5ef10f96 Mon Sep 17 00:00:00 2001 From: lucarin91 Date: Tue, 16 Dec 2025 11:14:24 +0100 Subject: [PATCH 2/5] fixup! chore(ci): add broken link checker --- .github/workflows/check-markdown-task.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml index d49de4d..c996e68 100644 --- a/.github/workflows/check-markdown-task.yml +++ b/.github/workflows/check-markdown-task.yml @@ -76,15 +76,13 @@ jobs: - name: Checkout repository uses: actions/checkout@v6 - - name: Install Go - uses: actions/setup-go@v6 - with: - go-version-file: go.mod + - name: Install Task + uses: go-task/setup-task@v1 - name: Setup Node.js uses: actions/setup-node@v6 with: - node-version-file: package.json + node-version: "24.x" - name: Check links run: | From 183824eeafb460e194f1c287b577395f482722ea Mon Sep 17 00:00:00 2001 From: lucarin91 Date: Tue, 16 Dec 2025 11:15:21 +0100 Subject: [PATCH 3/5] fixup! fixup! chore(ci): add broken link checker --- .github/workflows/check-markdown-task.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml index c996e68..3ade3b7 100644 --- a/.github/workflows/check-markdown-task.yml +++ b/.github/workflows/check-markdown-task.yml @@ -86,7 +86,4 @@ jobs: - name: Check links run: | - go tool \ - github.com/go-task/task/v3/cmd/task \ - --silent \ - markdown:check-links + task --silent markdown:check-links From 8a414a9f5832cdfafd85c650919aaac55de340c9 Mon Sep 17 00:00:00 2001 From: lucarin91 Date: Thu, 18 Dec 2025 12:32:10 +0100 Subject: [PATCH 4/5] use Taskfile.dist.yml --- Taskfile.dist.yml | 34 ++++++++++++++++++++++++++++++++++ Taskfile.yaml | 37 ------------------------------------- 2 files changed, 34 insertions(+), 37 deletions(-) delete mode 100644 Taskfile.yaml diff --git a/Taskfile.dist.yml b/Taskfile.dist.yml index 6a5d79b..aa8d739 100644 --- a/Taskfile.dist.yml +++ b/Taskfile.dist.yml @@ -33,3 +33,37 @@ tasks: rmdir "$licenses_dir" fi - pip-licenses --format=json --output-file=THIRD-PARTY-LICENSES.json + + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:check-links: + desc: Check for broken links + vars: + # The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability. + # This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes + # standard newline escaping syntax to not work when the task is run on Windows. + # + # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows + # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives + # \ characters special treatment on Windows in an attempt to support them as path separators. + # + # prettier-ignore + CHECK_LINKS_COMMAND: + " + find . \ + -type d -name \".git\" -prune -o \ + -type d -name \".licenses\" -prune -o \ + -type d -name \"__pycache__\" -prune -o \ + -type d -name \"node_modules\" -prune -o \ + -regex \".*[.]md\" \ + -exec \ + markdown-link-check \ + --quiet \ + --config \"./.markdown-link-check.json\" \ + \\{\\} \ + + + " + cmds: + - | + npx \ + --package=markdown-link-check \ + --call='{{.CHECK_LINKS_COMMAND}}' diff --git a/Taskfile.yaml b/Taskfile.yaml deleted file mode 100644 index fe70de2..0000000 --- a/Taskfile.yaml +++ /dev/null @@ -1,37 +0,0 @@ -# See: https://taskfile.dev/#/usage -version: "3" - -tasks: - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml - markdown:check-links: - desc: Check for broken links - vars: - # The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability. - # This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes - # standard newline escaping syntax to not work when the task is run on Windows. - # - # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows - # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives - # \ characters special treatment on Windows in an attempt to support them as path separators. - # - # prettier-ignore - CHECK_LINKS_COMMAND: - " - find . \ - -type d -name \".git\" -prune -o \ - -type d -name \".licenses\" -prune -o \ - -type d -name \"__pycache__\" -prune -o \ - -type d -name \"node_modules\" -prune -o \ - -regex \".*[.]md\" \ - -exec \ - markdown-link-check \ - --quiet \ - --config \"./.markdown-link-check.json\" \ - \\{\\} \ - + - " - cmds: - - | - npx \ - --package=markdown-link-check \ - --call='{{.CHECK_LINKS_COMMAND}}' From ed28aa054219de27b77ca10d02cac6453a3ac01b Mon Sep 17 00:00:00 2001 From: lucarin91 Date: Thu, 18 Dec 2025 13:21:11 +0100 Subject: [PATCH 5/5] ignore arduino cloud links --- .markdown-link-check.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.markdown-link-check.json b/.markdown-link-check.json index 41b3d13..a4cd3c6 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -1,4 +1,9 @@ { + "ignorePatterns": [ + { + "pattern": "^https://app.arduino.cc/" + } + ], "httpHeaders": [ { "urls": [