Skip to content
  • Blaine Gardner's avatar
    ci: use markdownlint to enforce mkdocs compatibility · c9d99e01
    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: default avatarBlaine Gardner <blaine.gardner@ibm.com>
    c9d99e01