Skip to content

check-markdown-task.md

Latest commit

 

History

History
145 lines (91 loc) · 5.76 KB

check-markdown-task.md

File metadata and controls

145 lines (91 loc) · 5.76 KB

"Check Markdown" workflow (Task)

Check the repository's Markdown files for problems:

NOTE: This workflow is focused on linting. Formatting checks for Markdown are provided by the "Check Prettier Formatting" workflow, so both should be used.

This is the version of the workflow for projects using the Task task runner tool.

Installation

Workflow

Install the check-markdown-task.yml GitHub Actions workflow to .github/workflows/

Assets

  • .markdown-link-check.json - markdown-link-check configuration file.
    • Install to: repository root
  • .markdownlint.yml - markdownlint configuration file.
    • Install to: repository root
  • .markdownlintignore - markdownlint configuration file.
    • Install to: repository root
  • .npmrc - npm configuration file.
    • Install to: repository root.
  • Taskfile.yml - Markdown tasks.
    • Install to: repository root (or merge into the existing Taskfile.yml).
  • Taskfile.yml - npm tasks.
    • Install to: repository root (or merge into the existing Taskfile.yml).

The code style defined in .markdownlint.yml is the official standardized style to be used in all Arduino tooling projects and should not be modified.

Dependencies

The tool dependencies of this workflow are managed by Go and npm.

Go Module-Managed Dependencies

If the project does not already have a go.mod file, install Go and then run the following command:

go mod init <module path>

(where <module path> is the URL of the project repository without the scheme e.g., github.com/foo/bar)

Add the tool dependencies by running the following command:

go get -tool github.com/go-task/task/v3/cmd/task@v3.44.1

Commit the resulting changes to the go.mod and go.sum files.

npm-Managed Dependencies

Add the dependencies by running this command:

npm install --save-dev markdown-link-check@^3.14.2 markdownlint-cli@^0.47.0

Commit the resulting changes to the package.json and package-lock.json files.

Configuration

Node.js

Configure the version of Node.js used for development of the project by running the following command from a terminal in the project repository folder:

npm pkg set engines.node=22.x

Taskfile

Add any documentation generation processes to the docs:generate umbrella task.

markdownlint

In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them via a .markdownlintignore file: https://github.com/igorshubovych/markdownlint-cli#ignoring-files

markdown-link-check

Advanced configuration of markdown-link-check can be done via the .markdown-link-check.json configuration file: https://github.com/tcort/markdown-link-check#config-file-format

.gitignore

Add the following to /.gitignore:

/node_modules/

Readme badge

Markdown badge:

[![Check Markdown status](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/check-markdown-task.yml)

Replace the TODO_REPO_OWNER and TODO_REPO_NAME placeholders in the URLs with the final repository owner and name (example).

Asciidoc badge:

image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-markdown-task.yml/badge.svg["Check Markdown status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-markdown-task.yml"]

Define the {repository-owner} and {repository-name} attributes and use them throughout the readme (example).

Commit message

Add infrastructure to check for problems in Markdown files

Tasks are provided to check for problems in the project's Markdown files:

- Use markdownlint to check for common problems and formatting.
- Use markdown-link-check to check for broken links.

A GitHub Actions workflow is included to automatically run the tasks. The workflow is triggered on any push or pull that
changes relevant project files, in order to avoid the introduction of problems with the project filesystem. It is also
triggered periodically, in order to catch breakage caused by external changes.

PR message

Add infrastructure to check for problems in Markdown files

Tasks are provided to check for problems in the project's Markdown files:

- Use [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) to check for common problems and formatting.
- Use [markdown-link-check](https://github.com/tcort/markdown-link-check) to check for broken links.

A GitHub Actions workflow is included to automatically run the tasks. The workflow is triggered on any push or pull that changes relevant project files, in order to avoid the introduction of problems with the project filesystem. It is also triggered periodically, in order to catch breakage caused by external changes.