tpmjs/packages/tools/official/markdown-lint-basic/README.md

@tpmjs/tools-markdown-lint-basic

Basic markdown linting to check for common issues.

Features

• Checks for trailing whitespace
• Detects multiple consecutive blank lines
• Validates heading hierarchy (no skipping levels)
• Ensures blank lines around headings
• Checks for consistent list marker style
• Detects hard tabs (recommends spaces)
• Validates code block language specification
• Checks link formatting (no bare URLs, no empty links)

Installation

npm install @tpmjs/tools-markdown-lint-basic

Usage

import { markdownLintBasicTool } from '@tpmjs/tools-markdown-lint-basic';

const result = await markdownLintBasicTool.execute({
  markdown: `
# Title
## Section 1
#### Subsection (skips h3)

Some text with trailing spaces

Bare URL: https://example.com
`,
});

console.log(result.passed); // false (has errors)
console.log(result.summary);
// {
//   errors: 1,
//   warnings: 2,
//   totalLines: 8,
//   rulesChecked: ['no-trailing-spaces', 'no-multiple-blanks', ...]
// }

console.log(result.issues);
// [
//   {
//     rule: 'heading-increment',
//     severity: 'error',
//     line: 4,
//     message: 'Heading level 4 skips level 3',
//     context: '#### Subsection (skips h3)'
//   },
//   ...
// ]

API

markdownLintBasicTool.execute(input)

Input

• markdown (string, required): The markdown content to lint

Output

Returns a LintResult object:

interface LintResult {
  issues: LintIssue[];
  passed: boolean;           // true if no errors (warnings are OK)
  summary: {
    errors: number;
    warnings: number;
    totalLines: number;
    rulesChecked: string[];
  };
}

interface LintIssue {
  rule: string;              // Rule identifier
  severity: 'error' | 'warning';
  line: number;              // Line number where issue occurs
  column?: number;           // Optional column number
  message: string;           // Human-readable message
  context?: string;          // Code snippet showing the issue
}

Rules

Errors (must fix)

• heading-increment: Headings must not skip levels (e.g., h1 → h3)
• no-hard-tabs: Hard tabs are not allowed (use spaces)
• no-empty-links: Link text cannot be empty

Warnings (should fix)

• no-trailing-spaces: Lines should not have trailing whitespace
• no-multiple-blanks: No more than 2 consecutive blank lines
• blanks-around-headings: Headings should have blank lines before/after
• list-marker-style: Use consistent list markers (-, *, or +)
• fenced-code-language: Code blocks should specify a language
• no-bare-urls: URLs should be formatted as markdown links

Examples

Check for Errors Only

const result = await markdownLintBasicTool.execute({ markdown });

if (!result.passed) {
  const errors = result.issues.filter(i => i.severity === 'error');
  console.error(`Found ${errors.length} errors:`);
  for (const error of errors) {
    console.error(`Line ${error.line}: ${error.message}`);
  }
}

Format Issue Report

const result = await markdownLintBasicTool.execute({ markdown });

for (const issue of result.issues) {
  const icon = issue.severity === 'error' ? '❌' : '⚠️';
  console.log(`${icon} Line ${issue.line}: ${issue.message}`);
  if (issue.context) {
    console.log(`   ${issue.context}`);
  }
}

Group by Rule

const result = await markdownLintBasicTool.execute({ markdown });

const byRule = new Map<string, LintIssue[]>();
for (const issue of result.issues) {
  if (!byRule.has(issue.rule)) {
    byRule.set(issue.rule, []);
  }
  byRule.get(issue.rule)!.push(issue);
}

for (const [rule, issues] of byRule) {
  console.log(`${rule}: ${issues.length} issues`);
}

Use Cases

• Pre-commit hooks for documentation
• CI/CD markdown validation
• Documentation quality checks
• Style guide enforcement
• Automated code review

License

MIT