verifying-markdown-formatting

Verifying Markdown Formatting

Check a Markdown file for formatting issues and fix them.

What to Check

Structure

• [ ] Exactly one # H1 heading at the top of the file
• [ ] Headings increment by one level (no jumping from ## to ####)
• [ ] Blank line before and after every heading
• [ ] Blank line before and after every code block, list, and blockquote
• [ ] File ends with a single trailing newline

Lists

• [ ] Consistent marker style within each list (- not mixed with * or +)
• [ ] Nested items indented with 2 or 4 spaces (consistent throughout)
• [ ] Blank line before the first item in a top-level list
• [ ] No blank lines between items in a tight list (or all items separated — pick one)

Links & Images

• [ ] All links have non-empty display text: [text](url) not [](url)
• [ ] No bare URLs outside of code blocks — wrap in <url> or [text](url)
• [ ] Reference-style links have matching definitions
• [ ] Image alt text is present: ![alt](src) not ![](src)

Code Blocks

• [ ] Fenced code blocks use triple backticks, not tildes
• [ ] Language identifier is present on every fenced block ( python , bash , etc.)
• [ ] Inline code uses single backticks for short references
• [ ] No indented code blocks (use fenced instead for clarity)

Formatting

• [ ] Bold uses **text** not __text__
• [ ] Italic uses *text* not _text_
• [ ] No trailing whitespace on any line
• [ ] Lines under 120 characters where practical (prose, not tables)
• [ ] Consistent use of ATX-style headings (# Heading, not underline style)

Tables

• [ ] Header row has separator row with --- in each column
• [ ] Cell content is trimmed (no excessive padding)
• [ ] Column alignment markers (:---, :---:, ---:) used consistently if present

Horizontal Rules

• [ ] Use --- on its own line with blank lines above and below
• [ ] Consistent style (don't mix ---, ***, ___)

Workflow

1. Read the target Markdown file
2. Walk through each check above
3. Fix any issues found using exact string replacements
4. Re-read the file to confirm all fixes applied cleanly
5. Report what was fixed and what was already correct

Notes

• This skill is formatting-only — it does not validate content accuracy, broken links, or spelling
• Preserve the author's intended structure; don't reorganize sections
• When fixing list markers, match whatever style the file already uses most