Why are ATX-style headings preferred?

ATX headings (using #) are the modern standard for Markdown, offering better readability and more consistent rendering across different platforms compared to Setext (underlined) headings.

Does it handle frontmatter for static site generators?

Yes, it includes specific rules for YAML frontmatter to ensure it is correctly placed at the start of the file with valid syntax for tools like Jekyll, Hugo, or Docusaurus.

Does this skill override my existing markdownlint settings?

No, the skill is designed to respect existing project configurations like .markdownlint.json or .markdownlint-cli2.jsonc, prioritizing those rules over its default conventions.

Can I use this for complex tables?

Yes, the skill helps align pipes and headers for readability, though it recommends restructuring tables that exceed 5 columns for better mobile and web display.

Markdown Conventions

Name: Markdown Conventions
Author: jsamuelsen11

byjsamuelsen11

0•

Learning & Documentation

Standardizes Markdown formatting and documentation structure to ensure consistent, readable, and lint-compliant content.

The Markdown Conventions skill provides a comprehensive set of rules and best practices for creating high-quality documentation. It automatically enforces ATX-style headings, proper link structures, and consistent code fence labeling while respecting existing project-specific configurations like markdownlint. This skill is particularly useful for maintaining large documentation sites, README files, and technical guides, ensuring that all Markdown content remains professional, accessible, and easy to maintain across different contributors and platforms.

Key Features

01Automated ATX-style heading hierarchy enforcement

02Compatibility with existing project markdownlint configurations

03Smart table alignment and list indentation management

04Consistent code fence language tagging and formatting

050 GitHub stars

06Relative path validation for internal documentation links

Use Cases

01Generating new documentation that aligns with established repository styles

02Refactoring messy project READMEs and technical documentation

03Performing automated audits of Markdown files for formatting consistency

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add jsamuelsen11/claude-config markdown-conventions

For use in Claude.ai and ChatGPT

Download Skill