skills.rest
jwvdvuurst
jwvdvuurstCOMMUNITY
Explore all skills by this author →
GitHub

markdown-formatter

Formats markdown files according to style guidelines covering headers, lists, code blocks, links, and spacing.

Updated Dec 26, 2025
Search Tags:#linting#documentation#markdown#validation#formatting#style guide#readme
One-click install
npx skills add https://github.com/jwvdvuurst/CalculatorCollection --skill markdown-formatter-jwvdvuurst
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: markdown-formatter
Source: https://github.com/jwvdvuurst/CalculatorCollection/tree/main/skills/markdown-formatter
Command: npx skills add https://github.com/jwvdvuurst/CalculatorCollection --skill markdown-formatter-jwvdvuurst

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Markdown documents often accumulate inconsistent formatting: mixed list markers, skipped header levels, code blocks without language identifiers, missing alt text, and irregular spacing. This Skill standardizes markdown files against common style guidelines without altering their content. ## Core Features & Use Cases - Modular Formatting Guidance: Five focused reference resources cover headers and hierarchy, lists and nesting, code and emphasis, links and images, and spacing and tables. - Four-Phase Workflow: A structured process of structural scan, block-level formatting, final polish, and validation ensures systematic cleanup. - Automated Validation: A bundled shell script checks for trailing whitespace, missing language identifiers, inconsistent list markers, bad link text, and missing alt text. - Use Case: Given a messy README with underline-style headers, mixed * and - list markers, and unlabeled code fences, the Skill reformats it into clean ATX-style markdown and verifies the result with the validation script. ## Quick Start Format the attached README.md file according to markdown best practices and run the validation script to confirm all issues are fixed.

Frequently Asked Questions about markdown-formatter

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix inconsistent markdown formatting in a README file?▼

Apply a four-phase workflow: scan the document structure for header issues, fix block-level elements like lists and code blocks, polish spacing and tables, then validate. A validation script automates detection of common problems like mixed list markers and missing language identifiers.

What markdown style rules should documentation follow?▼

Use ATX-style headers with no skipped levels, dash markers for unordered lists with 2-space indentation, fenced code blocks with language identifiers, descriptive link text, alt text on all images, and single blank lines between blocks. End files with exactly one newline.

How do I check markdown files for formatting errors automatically?▼

Run the included validate-markdown.sh bash script against any markdown file. It checks for trailing whitespace, tabs, code blocks without language identifiers, mixed list markers, 'click here' link text, images missing alt text, and underscore-style emphasis.

Does markdown formatting validation work with linters and CI pipelines?▼

Yes, the formatting rules are compatible with markdownlint and similar tools, and the validation script can run in pre-commit hooks or CI/CD pipelines. The guidelines target standard markdown rendered by GitHub, GitLab, and static site generators.

What are the limitations of automated markdown formatting?▼

This approach does not check spelling or grammar, validate that external links resolve, optimize images, or enforce strict line length limits. It focuses purely on structural and syntactic formatting while preserving the original content meaning.

Related Skills

Explore More Software Engineering Skills→
Berkay2002Berkay2002

markdown-documentation

Format and standardize Markdown documentation and READMEs using GitHub Flavored Markdown.

Community
Basic
kettleofketchupkettleofketchup

zensical

Migrate mkdocs-material projects to Zensical and manage their documentation.

Community
Intermediate
fgrehmfgrehm

blog-proofreading

Proofread blog posts for flow, broken links, and formatting issues.

Community
Basic
CERTCCCERTCC
21

format-markdown

Run markdownlint-cli2 to lint and auto-fix markdown files.

Official
Basic