diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml deleted file mode 100644 index ddc3ff0b7..000000000 --- a/.github/workflows/check-links.yml +++ /dev/null @@ -1,63 +0,0 @@ -name: Check documentation links - -on: - push: - paths: - - ".github/workflows/check-links.yml" - - "Taskfile.yml" - - "**.md" - pull_request: - paths: - - ".github/workflows/check-links.yml" - - "Taskfile.yml" - - "**.md" - schedule: - # Run every Tuesday at 03:00 UTC to catch broken links caused by external changes - - cron: "0 3 * * 2" - -jobs: - check-links: - runs-on: ubuntu-latest - - env: - DOCUMENTATION_REQUIREMENTS_PATH: ./docs/requirements_docs.txt - - steps: - - name: Checkout local repository - uses: actions/checkout@v2 - - - name: Install Taskfile - uses: arduino/setup-task@v1 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - version: 3.x - - - name: Install Go - uses: actions/setup-go@v2 - with: - go-version: "1.14" - - - name: Install Python - uses: actions/setup-python@v2 - with: - python-version: "3.8" - - - name: Cache dependencies - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles(env.DOCUMENTATION_REQUIREMENTS_PATH) }} - restore-keys: | - ${{ runner.os }}-pip- - - - name: Install Poetry - run: | - python -m pip install --upgrade pip - python -m pip install poetry - - - name: Build documentation website - # Ensure the documentation can build. These docs won't be published. - run: task docs:build - - - name: Check links - run: task --silent docs:check-links diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml new file mode 100644 index 000000000..1dd9350ae --- /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/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 000000000..da7987976 --- /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 000000000..65b6ef7d6 --- /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 2c3f40798..5cadd73e3 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ [![Tests Status](https://github.com/arduino/arduino-lint/workflows/Run%20tests/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Run+tests) [![Check Go status](https://github.com/arduino/arduino-lint/actions/workflows/check-go-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-go-task.yml) [![Nightly Status](https://github.com/arduino/arduino-lint/workflows/Nightly%20build/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Nightly+build) +[![Check Markdown status](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml) [![Docs Status](https://github.com/arduino/arduino-lint/workflows/Publish%20documentation/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Publish+documentation) [![Codecov](https://codecov.io/gh/arduino/arduino-lint/branch/main/graph/badge.svg?token=nprqPQMbdh)](https://codecov.io/gh/arduino/arduino-lint) [![Check Certificates status](https://github.com/arduino/arduino-lint/actions/workflows/check-certificates.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-certificates.yml) diff --git a/Taskfile.yml b/Taskfile.yml index 26ce413f9..4b5970d90 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -110,6 +110,61 @@ tasks: cmds: - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + # 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" + + # 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: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 + python:check: cmds: - task: python:lint @@ -126,6 +181,11 @@ tasks: - poetry install --no-root - poetry run black . + docs:generate: + desc: Create all generated documentation content + deps: + - task: docs:gen + docs:gen: desc: Generate command reference dir: ./docsgen @@ -161,7 +221,9 @@ tasks: desc: Lint and check formatting of documentation files cmds: - task: docs:check-formatting - - task: docs:check-links + - task: markdown:lint + - task: markdown:fix + - task: markdown:check-links docs:lint: desc: Lint documentation files @@ -192,18 +254,6 @@ tasks: exit 1 fi - docs:check-links: - desc: Check for dead links in documentation - cmds: - - | - npx --package markdown-link-check --call ' - STATUS=0 - for file in $(find -name "*.md"); do - markdown-link-check --quiet "$file" - STATUS=$(( $STATUS + $? )) - done - exit $STATUS' - docs:check-formatting: desc: Check formatting of documentation files cmds: