-
由 Blaine Gardner 创作于
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>