Add linting for docs

[GuySartorelli]

We don't currently have any automated checks to validate the quality of our documentation. This means we might potentially have now - or could easily introduce in the future - markdown formatting issues, incorrectly formatted links, etc. This is especially likely to happen with some of the custom markdown syntax such as API links.

Proposed automated checks:

• Markdown linting
  • e.g. all code blocks have a syntax-highlighting hint (use text for plain text blocks)
• Ensure custom functionality is formatted correctly
  • links (e.g. api links use the api:Namespace\Class::someMethod() syntax instead of a hardcoded links, links to other docs sections are relative)
  • [info] and similar are formatted correctly and are never left unclosed
  • Custom anchors (i.e. {#some-anchor} in headings)
  • no malformed title, description, icons
  • e.g. backticks in these causes errors in the netlify build
  • Probably others (part of the work will be looking at what functionality docs.silverstripe.org has and adding to this list)
• Changelog marked as "unreleased" (in title and header) unless it has an actual commit changelog included
• code blocks should be standardised (e.g. allow either yaml or yml but not both)
• Standardised namespace declarations in php code examples
• Any broken links are identified (e.g. at a minimum this would be broken relative links to other doc pages - but could expand to include absolute URLs and api docs)
• Either enforce a character limit for lines of documentation (our guide says "keep documentation lines shorter than 120 characters" at the time of writing) OR enforce that paragraphs must not be split into multiple lines.
• Everything in our contributing documentation page that can be linted should be linted.
• Code inside code blocks for at least PHP and Javascript are linted

This should be run on all PRs automatically via github actions.

NOTE: Linting should respect Silverstripe's writing style guide (only accessible to Silverstripe employees currently)

potentially useful tools

• https://vale.sh/ for linting docs generally
• various suggestions which can work in combination to fulfill various requirements
• eslint-plugin-markdown for linting js examples in markdown
• DavidAnson/markdownlint or markdownlint/markdownlint for linting the markdown itself
• phpcs allows you to add a bootstrapper which might be one way to use that tool for linting php code blocks

Related issues

• https://github.com/silverstripe/developer-docs/issues/37

Notes

• I am taking custom markdown syntax out-of-scope as it's non-trivial. See https://github.com/silverstripe/developer-docs/issues/388
• Linting language structure has been pulled out of scope and will be handled in https://github.com/silverstripe/developer-docs/issues/390

Acceptance criteria

• Where feasible, the proposed automated checks are implemented.
• Developer doc is in Rhino (if it isn't already) and if linting fails, a blroken build is shown in Rhino.
• Validate that module standardiser does not conflict with this new build.
• This applies to developer docs only.

TODO

These will be done after the first lot of PRs are merged.

• [x] Merge up to CMS 5 - this will be a whole process of its own and may need to even be a "undo all of the changes and fix issues from scratch" scenario.
• [ ] Create a new PR which only applies the MD013 line-length rule, to limit lines to 120 characters.

PRs

• https://github.com/silverstripe/developer-docs/pull/387
• https://github.com/silverstripe/markdown-php-codesniffer/pull/1
• https://github.com/silverstripe/rhino/pull/4
• https://github.com/silverstripe/github-issue-search-client/pull/123
• https://github.com/silverstripe/gha-generate-matrix/pull/70
• https://github.com/silverstripe/cow/pull/249
• https://github.com/silverstripe/markdown-php-codesniffer/pull/3
• https://github.com/silverstripe/module-standardiser/pull/25

DO NOT CLOSE UNTIL ALL TODO ITEMS ARE COMPLETE

[maxime-rainville]

Ping @silverstripe/core-team

[maxime-rainville]

That sounds imminently sensible. If no one raises concern over the next week or so, I would just say go ahead and do it.

[GuySartorelli]

Found this issue which points out some issues that might be detectable with this (and some which probably aren't as I assume we don't want to pay for grammarly): https://github.com/silverstripe/developer-docs/issues/37

[GuySartorelli]

Also relevant: https://github.com/silverstripe/developer-docs/issues/13

[emteknetnz]

Don't think we need an RFC for maintenance tasks

Was this only for markdown files in the developer-docs repo, or would it also apply to the userhelp docs, and maybe even module readmes (probably not required?)

[GuySartorelli]

I was only thinking about developer docs specifically, but I guess it could apply to userhelp too - that's hosted by the same app so the linting rules should all be the same. I don't think it would apply to readmes in repos.

[GuySartorelli]

I'm gonna go ahead and mark this accepted

[GuySartorelli]

Note that while we could use something like https://github.com/greyscaled/markdownlint-rule-title-case-style to lint the heading style to ensure it's always using sentence style, we'd have to either:

1. Implement an "ignore code" feature for the rule and only allow exceptions within code tags (e.g. ## My `ModelAdmin` heading)
2. add a whooole load of "words" (e.g. PHP, ModelAdmin, etc) to the ignore list
3. add a whooool load of "ignore the rule for the next line" comments in the docs (ew)
4. Explicitly not allow any exceptions

That first option is feasible but out of scope for this first card. The other options are non-starters IMO. So for now we won't lint heading style.

EDIT: The maintainer of that package has kindly implemented that for us.

[GuySartorelli]

I've made a wrapper around php code sniffer which lets you lint code blocks inside markdown files https://github.com/GuySartorelli/md-php-cs

[emteknetnz]

Assigned back to @GuySartorelli for the other TODO items

[GuySartorelli]

Merged up to 5. I looked at the line length changes and it was just waaaaaay too much to do in one go. If we really care about that rule we can do it in chunks, but that's basically an epic in itself.