automation.md

How to Automate Simple Checks

If you want to automate some checks on your Markdown documents, there are several tools that you could leverage. For example:

• Code Analysis / Linting

  • markdownlint to verify Markdown syntax and enforce rules that make the text more readable.
  • markdown-link-check to extract links from markdown texts and check whether each link is alive (200 OK) or dead.
  • write-good to check English prose.
  • Docker image for node-markdown-spellcheck, a lightweight docker image to spellcheck markdown files.
  • static code analysis

• VS Code Extensions

  • Write Good Linter to get grammar and language advice while editing a document.
  • markdownlint to examine Markdown documents and get warnings for rule violations while editing.

• Automation

  • pre-commit to use Git hook scripts to identify simple issues before submitting our code or documentation for review.
  • Check Build validation to automate linting for PRs.
  • Check CI Pipeline for better documentation for a sample pipeline with markdownlint, markdown-link-check and write-good.

Sample output:

On linting rules

The team needs to be clear what linting rules are required and shouldn't be overridden with tooling or comments. The team should have consensus on when to override tooling rules.