FILE005

Error

Markdown file has formatting issues that may affect rendering.

Why this matters

Inconsistent Markdown renders differently across platforms, and some issues (like malformed tables) break rendering entirely.

How to fix

Tables

Tables need consistent column widths with proper alignment markers:

| Name | Description |
|:-----|:------------|
| foo  | bar         |

The separator row must:

• Start with |: for left-align, | for default, or |- followed by :
• Have dashes filling the width
• End with |

Headers

Headers need blank lines before and after:

## Header

Content here

Lists

Lists need a blank line before the first item:

Some text:

- item 1
- item 2

Configuration

Configure in config.toml:

[validators.file.markdown]
use_markdownlint = true   # Enable linting (default: true)
timeout = "10s"
context_lines = 2

Disable Markdown linting:

[validators.file.markdown]
use_markdownlint = false

Related

• markdownlint Rules

Hook output

When this error is triggered, klaudiush writes JSON to stdout:

permissionDecisionReason (shown to Claude): [FILE005] Markdown formatting errors. Check markdown formatting and structure.

systemMessage (shown to user): Formatted error with fix hint and reference URL.

additionalContext (behavioral guidance): Automated klaudiush validation check. Fix the reported errors and retry the same command.