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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions