diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml new file mode 100644 index 00000000..1dd9350a --- /dev/null +++ b/.github/workflows/check-markdown-task.yml @@ -0,0 +1,66 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md +name: Check Markdown + +# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows +on: + push: + paths: + - ".github/workflows/check-markdown-task.ya?ml" + - ".markdown-link-check.json" + - "Taskfile.ya?ml" + - "**/.markdownlint*" + - "**.mdx?" + - "**.mkdn" + - "**.mdown" + - "**.markdown" + pull_request: + paths: + - ".github/workflows/check-markdown-task.ya?ml" + - ".markdown-link-check.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: + lint: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Initialize markdownlint-cli problem matcher + uses: xt0rted/markdownlint-problem-matcher@v1 + + - name: Install Task + uses: arduino/setup-task@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + version: 3.x + + - name: Lint + run: task markdown:lint + + links: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install Task + uses: arduino/setup-task@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + version: 3.x + + - name: Check links + run: task --silent markdown:check-links diff --git a/.github/workflows/link-validation.yml b/.github/workflows/link-validation.yml deleted file mode 100644 index 9662d45a..00000000 --- a/.github/workflows/link-validation.yml +++ /dev/null @@ -1,24 +0,0 @@ -name: Verifies documentation links - -on: - push: - pull_request: - schedule: - - cron: "0 3 * * 1" # Every Monday at 03:00 - -jobs: - verify-links: - # Don't trigger on schedule event when in a fork - if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository == 'arduino/arduino-fwuploader') - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - - name: Install Taskfile - uses: arduino/setup-task@v1 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - version: 3.x - - - name: Verify links - run: task docs:check-links diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 00000000..da798797 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,5 @@ +{ + "retryOn429": true, + "retryCount": 3, + "aliveStatusCodes": [200, 206] +} diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 00000000..65b6ef7d --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,62 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlint.yml +# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# The code style defined in this file is the official standardized style to be used in all Arduino projects and should +# not be modified. +# Note: Rules disabled solely because they are redundant to Prettier are marked with a "Prettier" comment. + +default: false +MD001: false +MD002: false +MD003: false # Prettier +MD004: false # Prettier +MD005: false # Prettier +MD006: false # Prettier +MD007: false # Prettier +MD008: false # Prettier +MD009: + br_spaces: 0 + strict: true + list_item_empty_lines: false # Prettier +MD010: false # Prettier +MD011: true +MD012: false # Prettier +MD013: false +MD014: false +MD018: true +MD019: false # Prettier +MD020: true +MD021: false # Prettier +MD022: false # Prettier +MD023: false # Prettier +MD024: false +MD025: + level: 1 + front_matter_title: '^\s*"?title"?\s*[:=]' +MD026: false +MD027: false # Prettier +MD028: false +MD029: + style: one +MD030: + ul_single: 1 + ol_single: 1 + ul_multi: 1 + ol_multi: 1 +MD031: false # Prettier +MD032: false # Prettier +MD033: false +MD034: false +MD035: false # Prettier +MD036: false +MD037: true +MD038: true +MD039: true +MD040: false +MD041: false +MD042: true +MD043: false +MD044: false +MD045: true +MD046: + style: fenced +MD047: false # Prettier diff --git a/README.md b/README.md index 7ff54d0c..e3674a7a 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ For guidance on installation and development, see the [User documentation] ## Quickstart 1. [Install] the Arduino Firmware Uploader -2. Follow the [Usage] guide to check out what the tool can do -3. Browse the [Commands reference] to see all the available commands +1. Follow the [Usage] guide to check out what the tool can do +1. Browse the [Commands reference] to see all the available commands ## Security diff --git a/Taskfile.yml b/Taskfile.yml index bc58fec1..74506d4d 100755 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -46,20 +46,6 @@ tasks: cmds: - npx {{ .PRETTIER }} --check "**/*.md" - docs:check-links: - desc: Verifies there are no dead links in documentation - deps: - - task: docs:generate - cmds: - - | - npx -p markdown-link-check -c ' - STATUS=0 - for file in $(find -name "*.md"); do - markdown-link-check -c markdown-link-check-config.json -q "$file" - STATUS=$(( $STATUS + $? )) - done - exit $STATUS' - docs:format: desc: Automatically formats documentation cmds: @@ -73,6 +59,61 @@ tasks: cmds: - poetry run mkdocs build -s + # 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 + deps: + - task: docs:generate + cmds: + - | + if [[ "{{.OS}}" == "Windows_NT" ]]; then + # npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows, + # so the Windows user is required to have markdown-link-check installed and in PATH. + if ! which markdown-link-check &>/dev/null; then + echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme" + exit 1 + fi + # Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero + # exit status, but it's better to check all links before exiting. + set +o errexit + STATUS=0 + # 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. + for file in $(find . -regex ".*[.]md"); do + markdown-link-check \ + --quiet \ + --config "./.markdown-link-check.json" \ + "$file" + STATUS=$(( $STATUS + $? )) + done + exit $STATUS + else + npx --package=markdown-link-check --call=' + STATUS=0 + for file in $(find . -regex ".*[.]md"); do + markdown-link-check \ + --quiet \ + --config "./.markdown-link-check.json" \ + "$file" + STATUS=$(( $STATUS + $? )) + done + exit $STATUS + ' + fi + + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:fix: + desc: Automatically correct linting violations in Markdown files where possible + cmds: + - npx markdownlint-cli --fix "**/*.md" + + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:lint: + desc: Check for problems in Markdown files + cmds: + - npx markdownlint-cli "**/*.md" + build: desc: Build the project cmds: @@ -105,6 +146,8 @@ tasks: - task: docs:check - task: config:check - task: general:check-formatting + - task: markdown:check-links + - task: markdown:lint - task: python:check config:check: diff --git a/markdown-link-check-config.json b/markdown-link-check-config.json deleted file mode 100644 index 25027703..00000000 --- a/markdown-link-check-config.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "https?://localhost:\\d*/" - }, - { - "pattern": "https?://(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?):\\d*" - } - ], - "aliveStatusCodes": [200, 206], - "retryCount": 3, - "retryOn429": true -}