errose28 opened a new pull request, #84: URL: https://github.com/apache/ozone-site/pull/84
## What changes were proposed in this pull request? Use [JSON schema](https://json-schema.org/) (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](https://ajv.js.org/) is used to do the schema validation for front matter and category files. `_category_.yml` files are passed to [avj-cli](https://ajv.js.org/packages/ajv-cli.html) 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](https://docusaurus.io/docs/markdown-features#front-matter). 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](https://github.com/errose28/ozone-site/actions/runs/8150313126/job/22276389275) - [Docs page with extra front matter](https://github.com/errose28/ozone-site/actions/runs/8151118419) - [Docs page using `title` in the front matter](https://github.com/errose28/ozone-site/actions/runs/8150335538/job/22276430870) - Markdown lint actually fails this in the static checks before the docusaurus build caught it. - [Docs directory missing a `_category_.yml` sidebar config file](https://github.com/errose28/ozone-site/actions/runs/8151090570/job/22278414499) - [`_category_.yml` sidebar config file with an extra field](https://github.com/errose28/ozone-site/actions/runs/8150440832/job/22276715311) - [`_category_.yml` sidebar config file missing a label](https://github.com/errose28/ozone-site/actions/runs/8150478657/job/22276815477) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
