From b75174dcdb4f168b2f9dd5ba89fe8878becb41c9 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 13 Aug 2021 20:36:10 -0700 Subject: [PATCH] Sync Markdown checks with "template" We have assembled a collection of reusable project assets: https://github.com/arduino/tooling-project-assets These will be used in the repositories of all Arduino tooling projects. Some improvements and standardizations have been made in the upstream "template" assets for checking the general quality of Mardown files. Those are introduced to this repository here. Notable: - Make link check task Windows compatible - Use markdownlint-cli to check for common problems and style. - Bring repository into compliance with the standard Markdown style for Arduino tooling projects NOTE: the `docs:check-links` task has been renamed to `markdown:check-links` for consistency with the standard "template" task name. --- .github/workflows/check-markdown-task.yml | 66 +++++++++++++++++++++ .github/workflows/link-validation.yml | 24 -------- .markdown-link-check.json | 5 ++ .markdownlint.yml | 62 ++++++++++++++++++++ README.md | 4 +- Taskfile.yml | 71 ++++++++++++++++++----- markdown-link-check-config.json | 13 ----- 7 files changed, 192 insertions(+), 53 deletions(-) create mode 100644 .github/workflows/check-markdown-task.yml delete mode 100644 .github/workflows/link-validation.yml create mode 100644 .markdown-link-check.json create mode 100644 .markdownlint.yml delete mode 100644 markdown-link-check-config.json 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 -}