diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml new file mode 100644 index 0000000..3ade3b7 --- /dev/null +++ b/.github/workflows/check-markdown-task.yml @@ -0,0 +1,89 @@ +# 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 Task + uses: go-task/setup-task@v1 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: "24.x" + + - name: Check links + run: | + task --silent markdown:check-links diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 0000000..a4cd3c6 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,24 @@ +{ + "ignorePatterns": [ + { + "pattern": "^https://app.arduino.cc/" + } + ], + "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.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}}'