Skip to content

Clean up markdown lint violations in OpenBolt docs #199

@miharp

Description

@miharp

The OpenBolt documentation (docs/_openbolt_5x/) was ported from upstream Puppet Bolt docs and contains widespread markdown style violations that the project's lint rules flag. A per-directory .markdownlint.yaml suppresses these rules for now so the initial import can land, but they should be fixed in a follow-up pass.

Rules to fix

Rule Violations Description
MD060/table-column-style 260 Table columns not padded to aligned_delimiter width
MD009/no-trailing-spaces 136 Trailing spaces throughout source
MD031/blanks-around-fences 132 Fenced code blocks missing surrounding blank lines
MD030/list-marker-space 132 Extra spaces after list markers
MD040/fenced-code-language 123 Fenced code blocks without a language specifier
MD036/no-emphasis-as-heading 120 Bold/italic used as informal headings
MD033/no-inline-html 86 Inline HTML beyond what the root config permits
MD032/blanks-around-lists 64 Lists not surrounded by blank lines
MD049/emphasis-style 26 Inconsistent emphasis delimiter
MD004/ul-style 22 Inconsistent unordered list markers
MD007/ul-indent 18 Unordered list indentation
MD027/no-multiple-space-blockquote 13 Multiple spaces after blockquote marker
MD014/commands-show-output 11 Shell commands with $ prefix followed by output
MD013/line-length 9 Lines exceeding the 210-char root limit
MD051/link-fragments 6 Link fragments referencing headings that don't exist
MD055/table-pipe-style 4 Inconsistent table pipe style
MD047/single-trailing-newline 4 Files missing a trailing newline
MD045/no-alt-text 4 Images without alt text
MD034/no-bare-urls 4 Bare URLs
MD029/ol-prefix 4 Ordered list prefix style
MD022/blanks-around-headings 4 Headings not surrounded by blank lines
MD024/no-duplicate-heading 2 Duplicate sibling headings
MD025/single-title 1 Multiple H1 headings
MD056/table-column-count 1 Inconsistent column count across table rows
MD028/no-blanks-blockquote 1 Blank line inside block quote
MD010/no-hard-tabs 1 Hard tabs

Notes

  • MD036 (bold-as-heading) and MD033 (inline HTML) require human judgment — converting bold to headings changes document structure.
  • MD040 (missing code language) requires identifying the correct language for each block.
  • MD051 (broken link fragments) requires finding or correcting the target anchors.
  • The remaining rules (trailing spaces, blank lines, list spacing) are safe to auto-fix with markdownlint-cli2 --fix.

When this is resolved, remove docs/_openbolt_5x/.markdownlint.yaml.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions