elastic / elastic/docs-builder
[cumulative docs] Identify opportunities for automation and linting
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
## Context
In #1614 we added a bunch of new guidance for writing cumulative documentation including `applies_to` usage and placement. These guidelines are quite complicated. I think there are opportunities to build some automation and/or linting rules that could help us provide guidance in context at build time and reduce the amount of content docs contributors need to read and internalize.
## Opportunities for automation / assertions
- [x] Sort `applies_to` badges. This is already in progress:
* Within a single key in `applies_to`, always order versions from newest to oldest ([docs-builder#1726](https://github.com/elastic/docs-builder/pull/1726))
* Across all keys in `applies_to`, always use the same order for keys ([docs-builder](https://github.com/elastic/docs-builder/pull/1727)#1727)
- [ ] Sort tabs with `applies_to`. This is dependent on #1436.
- [ ] Render `applies_to` badge at the beginning of a list item regardless of where it is added in the source.
* Note: I'm not sure if we actually want to do this or if we should just lint for badges that are not at the beginning of a list item and prompt the contributor to move the badge via a hint or warning.
- [ ] Render `applies_to` badge at the beginning of a paragraph regardless of where it is added in the source
* Note: I'm not sure if we actually want to do this or if we should just lint for badges that are not at the beginning of a paragraph and prompt the contributor to move the badge via a hint or warning.
- [ ] Throw a warning on section applies_to in h1 (title)
* Use `applies_to` in the frontmatter instead
- [ ] Throw a warning on inline applies_to in h1 (title)
* Use `applies_to` in the frontmatter instead
- [x] Throw a warning on inline applies_to in any h2+ (https://github.com/elastic/docs-builder/pull/1777)
* Use section `applies_to` instead
_I'll keep adding more as needed._
cc @theletterf (since we talked about this a bit)
Contributor guide
Assessment
This issue has not been assessed yet.