forked from rook/rook
Blaine Gardner
c9d99e01a0
mkdocs uses a markdown renderer that is hardcoded to 4 spaces per tab
for detecting indentation levels, including ordered- and
unordered-lists. Since we cannot easily change the renderer, begin using
a markdown linter in CI that will fail if official docs do not adhere to
the spacing rules.
As a starting point, the markdownlint config does not begin with the
default set of checks, which might overwhelm attempts to fix them.
Instead, focus on list-tab-spacing rules and a few other highly useful
checks.
markdownlint also has some gaps in its abilities that allow common Rook
doc issues to pass acceptance. However, it allows creating custom
linting plugins. Create 2 such linting plugins to check 2 things:
- all doc lines (except code blocks) must be aligned to a 4-space
boundary, without exception. This ensures that markdown will render
correctly with mkdocs. This unfortunately makes it possible to create
lists that are internally aligned strangely.
- admonitions must all follow the same format of
```
!!! header
body
```
For the strange lists, this is allowed and renders correctly, but it
looks strange:
```md
- first bullet
- second bullet
still second bullet
- third bullet
has a paragraph
of text inside
- last bullet
Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>
49 lines
1.8 KiB
JavaScript
49 lines
1.8 KiB
JavaScript
module.exports = {
|
|
"config": {
|
|
"default": false, // no default rules enabled
|
|
"extends": null, // no default rules enabled
|
|
"list-indent": true, // all list items must be indented at the same level
|
|
"ul-indent": {
|
|
"indent": 4, // mkdocs requires 4 spaces for tabs
|
|
},
|
|
"no-hard-tabs": {
|
|
"spaces_per_tab": 4, // mkdocs requires 4 spaces for tabs
|
|
},
|
|
"ol-prefix": {
|
|
// require fully-numbered lists. this rule helps ensure that code blocks in between ordered
|
|
// list items (which require surrounding spaces) don't break lists
|
|
"style": "ordered",
|
|
},
|
|
"blanks-around-lists": true, // mkdocs requires blank lines around lists
|
|
"blanks-around-fences": { // mkdocs requires blank lines around code blocks (fences)
|
|
"list_items": true, /// ... including in lists
|
|
},
|
|
"code-block-style": {
|
|
// do not allow implicit code blocks. ensure code blocks have fences so we know explicitly
|
|
// what will be rendered
|
|
"style": "fenced",
|
|
},
|
|
"fenced-code-language": {
|
|
// enforce code blocks must have language specified
|
|
// this helps ensure rendering is as intended, and it helps doc-wide searches for code blocks
|
|
language_only: true,
|
|
},
|
|
"no-duplicate-heading": true, // do not allow duplicate headings
|
|
"link-fragments": true, // validate links to headings within a doc
|
|
"single-trailing-newline": true, // require single trailing newline in docs
|
|
"no-multiple-blanks": {
|
|
// allow max 2 blank lines in markdown docs
|
|
"maximum": 2,
|
|
},
|
|
|
|
// custom rules for Rook!
|
|
"mkdocs-admonitions": true, // checking mkdocs admonitions format
|
|
"strict-tab-spacing": true, // enforce strict 4-space tabs for mkdocs
|
|
|
|
},
|
|
"customRules": [
|
|
"./tests/scripts/markdownlint-admonitions.js",
|
|
"./tests/scripts/markdownlint-tab-spacing.js",
|
|
],
|
|
};
|