HDDS-9866. Add GitHub Actions checks for consistent Docusaurus formatting.

[errose28]

What changes were proposed in this pull request?

Use JSON schema (which also validates YAML) to enforce requirements for markdown front matter and _category_.yml sidebar config files in each directory. The current set of requirements is based on my observations while building the initial skeleton site. Further requirements can be added and enforced later if we choose (for example, require every page to have a tags field).

These checks will help us keep tens of sidebar categories and hundreds of markdown docs consistent, unlike the previous site where every page had a random assortment of front matter with no guidance on what was required.

Implementation

Ajv is used to do the schema validation for front matter and category files.

_category_.yml files are passed to avj-cli by a shell script for validation. This prints all errors at once.

My initial approach for front matter was extracting it from the markdown with yq and then passing each one individually to ajv. That turned out to be very slow (about 1 minute for every hundred pages), so instead I used the ajv JavaScript library to plug into the docusaurus build similar to this example in the docs. This runs very fast, but with a few tradeoffs:

• Validation is not performed until the build stage.
• The build fails after the first error encountered instead of displaying all errors that can be fixed at once.
• This section of the Docusaurus config looks a bit more complicated than the rest of the file.

I haven't come up with a better way to do the front matter validation, so I think these trade-offs are okay for now.

What is the link to the Apache Jira?

HDDS-9866

How was this patch tested?

I created a branch off of this one on my fork and tested a few failing runs:

• Docs page using a slug to define a URL different than its file name
• Docs page with extra front matter
• Docs page using title in the front matter
  • Markdown lint actually fails this in the static checks before the docusaurus build caught it.
• Docs directory missing a _category_.yml sidebar config file
• _category_.yml sidebar config file with an extra field
• _category_.yml sidebar config file missing a label

[adoroszlai]

Thanks @errose28 for the improvement.

[adoroszlai]

nit: I think reduce iterations by using -type d as in find "$root"/docs -type d

[errose28]

Thanks for the review @adoroszlai. I'll implement your suggestion in HDDS-10506.