Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GH Actions: add markdown check workflow #93

Merged
merged 4 commits into from
Mar 10, 2023
Merged

GH Actions: add markdown check workflow #93

merged 4 commits into from
Mar 10, 2023

Commits on Mar 10, 2023

  1. 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.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
    @jrfnl
    jrfnl committed Mar 10, 2023
    Configuration menu
    Copy the full SHA
    243f2c0 View commit details
    Browse the repository at this point in the history

  2. Docs: minimal changes to pass the markdownlint check

    @jrfnl
    jrfnl committed Mar 10, 2023
    Configuration menu
    Copy the full SHA
    092d150 View commit details
    Browse the repository at this point in the history

  3. 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 `.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
    jrfnl committed Mar 10, 2023
    Configuration menu
    Copy the full SHA
    5b01ae7 View commit details
    Browse the repository at this point in the history

  4. Docs: minimal changes to pass the remark check

    @jrfnl
    jrfnl committed Mar 10, 2023
    Configuration menu
    Copy the full SHA
    b6d80f2 View commit details
    Browse the repository at this point in the history