Markdown Formatter

Markdown-Formatter - Beautify Your Markdown

Overview

Markdown-Formatter is a powerful tool for formatting, linting, and beautifying markdown documents. Supports multiple style guides (CommonMark, GitHub Flavored Markdown, custom rules) and handles everything from simple cleanup to complex reformatting.

Features

✅ Formatter Engine

• -Multiple style guides (CommonMark, GitHub, custom)
• -Preserves document structure
• -Handles nested lists, code blocks, tables
• -Configurable line width and indentation
• -Smart heading normalization
• -Link reference optimization

✅ Linting & Cleanup

• -Remove trailing whitespace
• -Normalize line endings (LF vs CRLF)
• -Fix inconsistent list markers
• -Remove empty lines at end
• -Fix multiple consecutive blank lines

✅ Beautification

• -Improve heading hierarchy
• -Optimize list formatting
• -Format code blocks with proper spacing
• -Wrap long lines at configured width
• -Add proper spacing around emphasis

✅ Validation

• -Check markdown syntax validity
• -Report linting errors
• -Suggest improvements
• -Validate links and references

Installation

clawhub install markdown-formatter

Quick Start

Format a Document

const result = await formatMarkdown({
  markdown: '# My Document\n\n\n## Section 1\nContent here...',
  style: 'github',
  options: {
    maxWidth: 80,
    headingStyle: 'atx'
  }
});

console.log(result.formattedMarkdown);

Beautify Multiple Files

const results = await formatBatch({
  markdownFiles: ['./doc1.md', './doc2.md', './README.md'],
  style: 'github',
  options: { wrapWidth: 80 }
});

results.forEach(result => {
  console.log(${result.file}: ${result.warnings} warnings);
});

Lint and Fix

const result = await lintMarkdown({
  markdown: '# My Document\n\n\nBad list\n\n- item 1\n- item 2',
  style: 'github'
});

console.log(Errors found: ${result.errors});
console.log(Fixed: ${result.fixed});

Tool Functions

formatMarkdown

Format markdown content according to style guide.

• -markdown (string, required): Markdown content to format
• -style (string, required): Style guide name ('commonmark', 'github', 'commonmark', 'custom')
• -options (object, optional):

- headingStyle (string): 'atx' | 'setext' | 'underlined' | 'consistent' (default: 'atx')

- listStyle (string): 'consistent' | 'dash' | 'asterisk' | 'plus' (default: 'consistent')

- codeStyle (string): 'fenced' | 'indented' (default: 'fenced')

- emphasisStyle (string): 'underscore' | 'asterisk' (default: 'asterisk')

- strongStyle (string): 'asterisk' | 'underline' (default: 'asterisk')

- linkStyle (string): 'inline' | 'reference' | 'full' (default: 'inline')

- preserveHtml (boolean): Keep HTML as-is (default: false)

- fixLists (boolean): Fix inconsistent list markers (default: true)

- normalizeSpacing (boolean): Fix spacing around formatting (default: true)

• -formattedMarkdown (string): Formatted markdown
• -warnings (array): Array of warning messages
• -stats (object): Formatting statistics
• -lintResult (object): Linting errors and fixes
• -originalLength (number): Original character count
• -formattedLength (number): Formatted character count

formatBatch

Format multiple markdown files at once.

• -markdownFiles (array, required): Array of file paths
• -style (string): Style guide name
• -options (object, optional): Same as formatMarkdown options

• -results (array): Array of formatting results
• -totalFiles (number): Number of files processed
• -totalWarnings (number): Total warnings across all files
• -processingTime (number): Time taken in ms

lintMarkdown

Check markdown for issues without formatting.

• -markdown (string, required): Markdown content to lint
• -style (string): Style guide name
• -options (object, optional): Additional linting options

- checkHeadingLevels (boolean): Check heading hierarchy (default: true)

- checkListConsistency (boolean): Check list marker consistency (default: true)

- checkEmphasisBalance (boolean): Check emphasis pairing (default: false)

• -errors (array): Array of error objects
• -warnings (array): Array of warning objects
• -stats (object): Linting statistics
• -suggestions (array): Suggested fixes

Style Guides

CommonMark (default)

• -Standard CommonMark specification
• -ATX headings (ATX-style)
• -Reference-style links [text]
• -Underscore emphasis
• -Asterisk emphasis

GitHub Flavored Markdown

• -Fenced code blocks with \\\
• -Tables with pipes
• -Task lists [ ] with x
• -Strikethrough ~~text~~
• -Autolinks with <https://url>

Edit config.json:

{
  "defaultStyle": "github",
  "maxWidth": 80,
  "headingStyle": "atx",
  "listStyle": "consistent",
  "codeStyle": "fenced",
  "emphasisStyle": "asterisk",
  "linkStyle": "inline",
  "customRules": [],
  "linting": {
    "checkLinks": true,
    "checkHeadingLevels": true,
    "checkListConsistency": true
  }
}

const result = await formatMarkdown({
  markdown: '# My Title\n\n\nThis is content.',
  style: 'github'
});

console.log(result.formattedMarkdown);

const result = await formatMarkdown({
  markdown: '# Header 1\n## Header 2\n\nParagraph...',
  style: 'github',
  options: {
    fixLists: true,
    normalizeSpacing: true,
    wrapWidth: 80
  }
});

console.log(result.formattedMarkdown);

const result = await lintMarkdown({
  markdown: '# Title\n\n- Item 1\n- Item 2\n\n## Section 2',
  style: 'github'
});

console.log(Errors: ${result.errors.length});

result.errors.forEach(err => {
  console.log(  - ${err.message} at line ${err.line});

});

// Fix automatically
const fixed = await formatMarkdown({
  markdown: result.fixed,
  style: 'github'
});

const results = await formatBatch({
  markdownFiles: ['./doc1.md', './doc2.md', './README.md'],
  style: 'github'
});

console.log(Processed ${results.totalFiles} files);

console.log(Total warnings: ${results.totalWarnings}`);

Performance

Speed

• -Small documents (<1000 words): <50ms
• -Medium documents (1000-5000 words): 50-200ms
• -Large documents (5000+ words): 200-500ms

Accuracy

• -Structure preservation: 100%
• -Style guide compliance: 95%+
• -Whitespace normalization: 100%

Error Handling

Invalid Input

• -Clear error message
• -Suggest checking file path
• -Validate markdown content before formatting

Markdown Parsing Errors

• -Report parsing issues clearly
• -Suggest manual fixes
• -Graceful degradation on errors

File I/O Errors

• -Clear error with file path
• -Check file existence
• -Suggest permissions fix
• -Batch processing continues on errors

Troubleshooting

Format Not Applied

• -Check if style is correct
• -Verify options are respected
• -Check for conflicting rules
• -Test with simple example

Linting Shows Too Many Errors

• -Some errors are style choices, not real issues
• -Consider disabling specific checks
• -Use custom rules for specific needs

Tips

Best Results

• -Use consistent style guide
• -Enable fixLists, normalizeSpacing options
• -Set maxWidth appropriate for your output medium
• -Test on small samples first

Performance Optimization

• -Process large files in batches
• -Disable unused linting checks
• -Use simpler rules for common patterns

License

MIT

---