Skip to content

Latest commit

 

History

History
130 lines (82 loc) · 5.29 KB

check-markdown-task.md

File metadata and controls

130 lines (82 loc) · 5.29 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
  • 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 npm.

Add the dependencies by running this command:

npm install --save-dev markdown-link-check@^3.13.7 markdownlint-cli@^0.37.0

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

Configuration

Workflow

Configure the version of Node.js used for development of the project in the env.NODE_VERSION field of check-markdown-task.yml.

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 CI workflow to check Markdown files for problems

On every push and pull request that affects relevant files, and periodically, check the repository's Markdown files for
problems:

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

The Arduino tooling Markdown style is defined by the `.markdownlint.yml` file.

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 is configured via the `.markdown-link-check.json` file:
https://github.com/tcort/markdown-link-check#config-file-format

PR message

On every push and pull request that affects relevant files, and periodically, check the repository's Markdown files for
problems:

- 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.

The Arduino tooling Markdown style is defined by the `.markdownlint.yml` file.

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 is configured via the `.markdown-link-check.json` file:
https://github.com/tcort/markdown-link-check#config-file-format