What would you like to be added:
Spellcheck on markdown files. Ignoring markup and code snippets. Should be integrated as automatic merge check and be runnable on documentation build too.

Why is this needed:
Enforce spell check rules. Avoid manual work. Be smarter than general purpose spell checkers to know the context and skip markup.

See #8

What would you like to be added:
A component analyzing markdown source files for dead links. The component should be:

• provided as a GitHub app configured as a check for merging PRs where appropriate
• optionally included in documentation builds

The component operation should provide sufficient details and context to recover from the problem of a dead link fast, i.e. report where exactly is the problematic link.

These are optional but welcome further improvements:
A good help would be to suggest the right link, e.g. by doing similarity search by names in the same source storage, and help easy recovery from typos. Or trace rename operations with git log.

Why is this needed:
A dead link is a link that has a non-existent destination. Speaking a link here can be navigable (hyperlink) or embedded (path to resource, such as image). Checking for dead links in a documentation material is an essential sanity check that guards the positive experience of the final product in that aspect. The test for dead links can be and should be fully automated and not draining expensive capacity from humans.

Few ideas:

• https://github.com/d-tsuji/markdown-link-check
• https://github.com/whxaxes/check-md

See #8

Automated Quality Control

Applying automated quality control in a documentation development process moves it even further into the documentation-as-code paradigm. The definition and scope of quality control may vary per project and process.

The goal of this epic is to adopt or deliver and validate in Gardener project a set of useful tools supporting the quality control in writing documentation.

The tools will form test suite guarding PR merges that include markdown content.

Those tools, or others but close enough, ideally are available as early in the process as possible, preferably while creating the documentation. Catching problems before opening a PR saves valuable time. IDEs often feature OSS plugins that can fit the bill or are a good basis to be adapted to a standalone tool or already are (which is the ideal case).

The build of documentation into a bundle can be a staged process where the same quality rules apply to guard against stale state (e.g. a link gone broken because between PR merge and build the destination went MIA).

The technology in which those tools are implemented is not the primary concern but preferably they should stick to Go and Python, and if really necessary NodeJS, to keep the technology stack lean.

The tools should not rely on external online web services.

Some common requirements are:

• Markdown-considerate (obviously)
• Can apply to a set of markdown files
• Provides structured output with sufficient context and detail to pin down a problem to source

The set will expand according to popular demand, but a reasonable starter pack is:

• Dead links

  Inspects markdown documents for dead links, leading to non-existent resources. It should be able to probe absolute and relative links and considers all type of links in a markdown source.

  See:

  • liche
  • Easily Find Broken Links With Broken Link Checker

• Spell check

  Performs language spell check on markdown document. There are a number of Go tools that do spellcheck for Go source code and comments. It should be easier to do that for Markdown source. The trick is to ignore markdown and HTML tags. There is something doing that in Kubernetes already that can be applied for that purpose. the tool dictionaries should be customizable.

  See:

  • go-spell
  • Many implementations out there take advantage of Hunspell

• Expressions lint

  Scans markdown for compliance with documentation language expression rules. The lint rules should be customizable.

  See:

  • write-good and blog how to apply it
  • proselint and blog how to apply it

• Markdown lint

  Checks markdown source for compliance with formatting rules.

  • markdownlint and its original

What would you like to be added:
A formatter for markdown applying a configurable set of style rules that can be enforced at build time.

Why is this needed:
Apply global governance rules on the markdown documents format and ensure it's consistent across all repositories.

See #8