GH Actions: add markdown check workflow #93
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jrfnl
force-pushed
the
feature/ghactions-add-markdown-broken-link-check
branch
from
43e007b
to
288db67
Compare
This new check uses the NPM MarkdownLint package via the NPM MarkdownLint-CLI2 package. It executes a loose check for consistency and some common errors. Some of the more annoying rules/rules which could impact display of markdown files on GitHub have been disabled. All necessary configuration is contained in the `.markdownlint-cli2.yaml` file. To run locally, install via: ```bash npm install -g markdownlint-cli2 ``` ... and then run via: ```bash markdownlint-cli2 ``` Includes a problem matcher which _should_ allow for displaying the results inline in GitHub PR code review view. Includes adding `node_modules` to the `.gitignore` in case anyone would install these tools locally (to prevent them committing them). Refs: * https://github.com/DavidAnson/markdownlint * https://github.com/DavidAnson/markdownlint-cli2
While MarkdownLint is absolutely great for finding formatting issues, Remark offers some additional "rules" which are useful, such as checking that links and link definitions match up, verifying all used links work and some additional formatting checks which markdownlint just doesn't offer. An extensive effort has been made to prevent duplication of messages between the Markdownlint and the Remark check. This includes ensuring there are no conflicting rules. The rule configuration is contained in the `.remarkrc` file. Files/directories to be ignored can be listed in the `.remarkignore` file which supports glob syntax, like `.gitignore`. Note: `.`-prefixed files and directories are excluded by default. To include those in the scan, they have to be passed explicitly on the command-line. To run locally, follow the same steps as per the GitHub actions workflow. Note: the workflow contains a double-run of remark-lint to allow viewing the results both in a human readable way in the actions transscripts, as well as getting annotations for found issue in PRs. Refs: * https://github.com/remarkjs/remark/tree/main/packages/remark-cli * https://github.com/remarkjs/remark-lint * https://github.com/remarkjs/remark-gfm * https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent * https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended * https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide Additional (external) plugins included: * https://github.com/vhf/remark-lint-heading-whitespace * https://github.com/wemake-services/remark-lint-list-item-punctuation * https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-match-punctuation * https://github.com/olizilla/remark-lint-no-hr-after-heading * https://github.com/wemake-services/remark-lint-are-links-valid * https://github.com/remarkjs/remark-validate-links
jrfnl
force-pushed
the
feature/ghactions-add-markdown-broken-link-check
branch
from
288db67
to
b6d80f2
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
While primarily intended to find broken links in the
READMEfile, the checks being run in these markdown workflows will also ensure consistency and correctness of the markdown.The workflow will runs once a week on a cron job to provide early detection of broken links.
GH Actions: add new check for consistency in markdown files
This new check uses the NPM MarkdownLint package via the NPM MarkdownLint-CLI2 package.
It executes a loose check for consistency and some common errors.
Some of the more annoying rules/rules which could impact display of markdown files on GitHub have been disabled.
All necessary configuration is contained in the
.markdownlint-cli2.yamlfile.To run locally, install via:
... and then run via:
Includes a problem matcher which should allow for displaying the results inline in GitHub PR code review view.
Includes adding
node_modulesto the.gitignorein case anyone would install these tools locally (to prevent them committing them).Refs:
Docs: minimal changes to pass the markdownlint check
GH Actions: add new check with additional QA for markdown files
While MarkdownLint is absolutely great for finding formatting issues, Remark offers some additional "rules" which are useful, such as checking that links and link definitions match up, verifying all used links work and some additional formatting checks which markdownlint just doesn't offer.
An extensive effort has been made to prevent duplication of messages between the Markdownlint and the Remark check. This includes ensuring there are no conflicting rules.
The rule configuration is contained in the
.remarkrcfile.Files/directories to be ignored can be listed in the
.remarkignorefile which supports glob syntax, like.gitignore.Note:
.-prefixed files and directories are excluded by default. To include those in the scan, they have to be passed explicitly on the command-line.To run locally, follow the same steps as per the GitHub actions workflow.
Note: the workflow contains a double-run of remark-lint to allow viewing the results both in a human readable way in the actions transscripts, as well as getting annotations for found issue in PRs.
Refs:
Additional (external) plugins included:
Docs: minimal changes to pass the remark check