Skip to content

[dmt] feat: add markdownlint documentation rule#399

Draft
fuldaxxx wants to merge 16 commits into
mainfrom
feat/markdown-lint
Draft

[dmt] feat: add markdownlint documentation rule#399
fuldaxxx wants to merge 16 commits into
mainfrom
feat/markdown-lint

Conversation

@fuldaxxx

@fuldaxxx fuldaxxx commented Jun 17, 2026

Copy link
Copy Markdown
Member

Description

Adds a new markdownlint rule to the documentation linter. The rule checks .md files in a module's docs/ directory for compliance with a unified markdown style (Deckhouse conventions) using the go-markdownlint (https://github.com/ldmonster/go-markdownlint) library.

What the rule does:

  • Recursively scans all .md files under docs/ (including nested ones, e.g. docs/internal/...)
  • Runs the built-in markdownlint rules with a fixed set of deckhouse-specific overrides (line-length limits, blanks-around-headings, duplicate-heading siblings, consistent code-fence/emphasis/strong styles, trailing newline, etc.)
  • Reports the rule name(s), description, file path and line number for each violation

Changes:

  • pkg/linters/docs/rules/markdown.go — MarkdownRule implementation with deckhouseMarkdownlintConfig()
  • pkg/linters/docs/documentation.go — invoke the new rule in Documentation.Run()
  • pkg/config.go, pkg/config/global/global.go, internal/module/module.go — add MarkdownlintRule to the config and map the impact level
  • go.mod/go.sum — github.com/ldmonster/go-markdownlint dependency
  • pkg/linters/docs/README.md — rule documentation
  • test/e2e/testdata/documentation/markdownlint-violations/ — e2e test case (duplicate h1 + missing trailing newline)

Example

🐒 [bilingual (#documentation)]
     Message:      Russian counterpart is missing: need to create a matching .ru.md in docs/
     Module:       test-markdownlint
     FilePath:     docs/README.md

🐒 [markdownlint (#documentation)]
     Message:        MD001/heading-increment Heading levels should only increment by one level at a time
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     8

🐒 [markdownlint (#documentation)]
     Message:        MD009/no-trailing-spaces Trailing spaces
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     3

🐒 [markdownlint (#documentation)]
     Message:        MD012/no-multiple-blanks Multiple consecutive blank lines
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     10

🐒 [markdownlint (#documentation)]
     Message:        MD018/no-missing-space-atx No space after hash on atx style heading
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     1

🐒 [markdownlint (#documentation)]
     Message:        MD022/blanks-around-headings Headings should be surrounded by blank lines
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     7

🐒 [markdownlint (#documentation)]
     Message:        MD022/blanks-around-headings Headings should be surrounded by blank lines
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     8

🐒 [markdownlint (#documentation)]
     Message:        MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading
     Module:         test-markdownlint
     FilePath:       /tmp/dmt-test-md/docs/README.md
     LineNumber:     1

@fuldaxxx fuldaxxx self-assigned this Jun 17, 2026
@fuldaxxx fuldaxxx added enhancement New feature or request go Pull requests that update go code labels Jun 17, 2026
@fuldaxxx fuldaxxx requested review from ipaqsa and ldmonster June 22, 2026 09:00
@fuldaxxx fuldaxxx changed the title [dmt] add markdownlint documentation rule [dmt] feat: add markdownlint documentation rule Jun 24, 2026
fuldaxxx added 13 commits July 10, 2026 19:09
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
@fuldaxxx fuldaxxx force-pushed the feat/markdown-lint branch from 8f380f2 to 8534f52 Compare July 10, 2026 16:11
fuldaxxx added 3 commits July 12, 2026 23:09
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Signed-off-by: Ruslan Gorbunov <ruslan.gorbunov@flant.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request go Pull requests that update go code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant