Markdown Linter

What This Skill Does

The Markdown Linter skill for OpenClaw is a robust diagnostic and maintenance tool designed to ensure your Markdown documentation adheres to industry-standard formatting, accessibility, and style guidelines. Whether you are managing technical documentation, project README files, or complex MDX files, this agent automates the tedious process of manual review. It identifies structural inconsistencies, validates relative file paths to prevent broken documentation links, and provides actionable auto-fix suggestions. By utilizing the markdownlint-cli library for structured environments or fallback text analysis for ad-hoc checks, the skill helps maintain professional, readable, and error-free repository documentation.

Installation

To integrate the Markdown Linter into your environment, use the OpenClaw command-line interface: clawhub install openclaw/skills/skills/sa9saq/markdown-linter. While the skill operates out-of-the-box using built-in heuristic analysis, installing markdownlint-cli via npm install -g markdownlint-cli is strongly recommended for enhanced performance and advanced configuration support, such as the use of custom .markdownlint.json files for project-specific rules.

Use Cases

• Quality Assurance: Standardizing formatting across multiple contributors in a repository to ensure consistent list markers and indentation.
• Link Integrity: Automatically auditing relative file links to ensure that project documentation doesn't lead to 404 errors when navigating through a file tree.
• Accessibility Compliance: Scanning for missing alt text on images and ensuring logical heading hierarchies to make documentation accessible for assistive technology users.
• Technical Refactoring: Cleaning up legacy markdown files by removing trailing whitespace, enforcing line lengths, and fixing skipped heading levels to ensure compatibility with static site generators like Jekyll, Hugo, or Docusaurus.

Example Prompts

1. "Run a full linting check on the ./docs folder and provide a summary report of any broken links or style issues found."
2. "Review README.md for formatting errors, fix all auto-fixable issues, and generate a Table of Contents based on the current heading structure."
3. "Check if there are any skipped heading levels in the API specification file and suggest improvements for better readability."

Tips & Limitations

• Edge Case Handling: When working with MDX (React-based Markdown), ensure you set MD033: false in your configuration to avoid false positives caused by JSX syntax.
• Automated Skipping: Always exclude machine-generated files like CHANGELOG.md from linting to avoid unnecessary churn in your diffs.
• Performance: For massive documentation sets, run the linter in subdirectories rather than the root to maintain speed.
• Limitations: The text-based fallback analysis is heuristic; for complex scientific or multi-language documents, the CLI version is significantly more reliable and should be prioritized whenever possible.