markdown-formatter
Format and beautify markdown documents with configurable styles. Preserve structure, fix formatting, ensure consistency.
- License 许可
- MIT
- 最近更新
- 2026-07-28
- Stars
- ★ 40
- Forks
- 1
01 前言 Front Matter
- name
- markdown-formatter
- metadata
- { "openclaw": { "tags": [ "markdown", "formatter", "beautifier", "text", "formatting", "documentation" ], "author": "Vernox", "license": "MIT", "version": "1.0.0", "category": "tools" } }
- description
- Format and beautify markdown documents with configurable styles. Preserve structure, fix formatting, ensure consistency.
02 资源文件 6
- 参考文档_meta.json137 B
- 参考文档config.json451 B
- 脚本index.js11.0 KB
- 参考文档package.json519 B
- 参考文档README.md3.7 KB
- 脚本test.js831 B
03 SKILL.md 正文
Markdown-Formatter - Beautify Your Markdown
Vernox Utility Skill - Make your markdown look professional.
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
Runtime
This workspace injects the skill at /root/skills/markdown-formatter. Use the
provided files directly; do not install the skill during the user task.
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.
Parameters:
markdown(string, required): Markdown content to formatstyle(string, required): Style guide name ('commonmark', 'github', 'commonmark', 'custom')options(object, optional):maxWidth(number): Line wrap width (default: 80)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)
Returns:
formattedMarkdown(string): Formatted markdownwarnings(array): Array of warning messagesstats(object): Formatting statisticslintResult(object): Linting errors and fixesoriginalLength(number): Original character countformattedLength(number): Formatted character count
formatBatch
Format multiple markdown files at once.
Parameters:
markdownFiles(array, required): Array of file pathsstyle(string): Style guide nameoptions(object, optional): Same as formatMarkdown options
Returns:
results(array): Array of formatting resultstotalFiles(number): Number of files processedtotalWarnings(number): Total warnings across all filesprocessingTime(number): Time taken in ms
lintMarkdown
Check markdown for issues without formatting.
Parameters:
markdown(string, required): Markdown content to lintstyle(string): Style guide nameoptions(object, optional): Additional linting optionscheckLinks(boolean): Validate links (default: true)checkHeadingLevels(boolean): Check heading hierarchy (default: true)checkListConsistency(boolean): Check list marker consistency (default: true)checkEmphasisBalance(boolean): Check emphasis pairing (default: false)
Returns:
errors(array): Array of error objectswarnings(array): Array of warning objectsstats(object): Linting statisticssuggestions(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
Consistent (default)
- Consistent ATX heading levels
- Consistent list markers
- Consistent emphasis style
- Consistent code block style
Custom
- User-defined rules
- Regex-based transformations
- Custom heading styles
Use Cases
Documentation Cleanup
- Fix inconsistent formatting in README files
- Normalize heading styles
- Fix list markers
- Clean up extra whitespace
Content Creation
- Format articles with consistent style
- Beautify blog posts before publishing
- Ensure consistent heading hierarchy
Technical Writing
- Format code documentation
- Beautify API specs
- Clean up messy markdown from LLMs
README Generation
- Format and beautify project README files
- Ensure consistent structure
- Professional appearance for open source
Markdown Conversion
- Convert HTML to markdown
- Reformat from one style to another
- Extract and format markdown from other formats
Configuration
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
}
}
Examples
Simple Formatting
const result = await formatMarkdown({
markdown: '# My Title\n\n\nThis is content.',
style: 'github'
});
console.log(result.formattedMarkdown);
Complex Beautification
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);
Linting and Fixing
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'
});
Batch Processing
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
Format markdown. Keep your docs beautiful. 🔮
04 同仓库更多 Skills
cli-anything-zoom
Command-line interface for Zoom — manage meetings, participants, and recordings from the command line via the Zoom REST API.
netease-music-cli
CLI for NetEase Cloud Music — search songs/albums/playlists, get lyrics, and manage your music library from the terminal.
google-calendar-gcalcli
Install and use gcalcli for live Google Calendar read access using the provided OAuth cache.
Excel / XLSX
Create, inspect, and edit Microsoft Excel workbooks and XLSX files with reliable formulas, dates, types, formatting, recalculation, and template preservation. Use when (1) the task is about Excel, `.xlsx`, `.xlsm`, `.xls`, `.csv`, or `.tsv`; (2) formulas, formatting, workbook structure, or compatibility matter; (3) the file must stay reliable after edits.
duckdb-en
DuckDB CLI specialist for SQL analysis, data processing and file conversion. Use for SQL queries, CSV/Parquet/JSON analysis, database queries, or data conversion. Triggers on "duckdb", "sql", "query", "data analysis", "parquet", "convert data".
automate-excel
Automates reading, writing, merging, transforming, and validating Excel (.xlsx/.xls) files. Use when the user works with spreadsheets, .xlsx files, Excel data — for cleaning, joining, validating, deduplicating, aggregating, filtering, or auditing tabular data.