GitHub Flavored Markdown Generation
Version: 1.2.1
Generate GFM that passes markdownlint validation with zero violations.
Core Principles
1. Blank Lines Are Mandatory
- •Before/after ALL lists (MD032)
- •Before/after ALL headings except document start (MD022)
- •Before/after ALL code blocks (MD031)
- •Between ALL block-level elements
2. Consistency Required
- •Use
-for lists - •Use
#for headings (ATX) - •Regular spaces only—never tabs/nbsp
3. Structure Matters
- •Heading hierarchy: 1→2→3 (not 1→3)
- •ONE H1 per document
- •Files end with one newline
- •Lines under 80 chars
4. Invisible Characters Matter
- •Use ONLY regular spaces (U+0020)
- •Never non-breaking spaces (U+00A0, )
- •Never tabs
- •UTF-8 encoding
Pre-Generation Checklist
- • Where will lists/headings/code appear?
- • Heading levels verified (1→2→3)?
- • Using
-for all lists? - • Code languages specified?
- • Lines under 80 chars?
- • Line breaks needed? (two trailing spaces)
- • Using regular spaces only?
- • URLs wrapped in
<>or[]? - • Document starts with H1?
- • Ordered lists use
1.for all items? - • File ends with single newline?
- • Tables use consistent spacing?
Essential Rules
Lists (MD032, MD004)
Text before. - Item one - Item two Text after.
Headings (MD001, MD022)
Text. ## Heading Content.
Code Blocks (MD031, MD040)
Text. ```python code() ``` Text.
Nested Fences: When showing markdown examples that contain code blocks, use one more backtick than the deepest level:
- •Three backticks (
```): Regular code - •Four backticks (
````): Markdown examples with code - •Five backticks (
`````): Nested markdown examples
````markdown # Example ```bash command ``` ````
Line Length (MD013)
Break long lines at natural points. Use reference-style links for long URLs.
URLs and Email (MD034)
Wrap bare URLs and emails:
Wrong: https://example.com Right: <https://example.com> Right: [link](https://example.com) Wrong: user@example.com Right: <user@example.com>
Document Structure (MD041)
Start with H1 (or front matter then H1):
# Document Title First paragraph.
Ordered Lists (MD029)
Use 1. for all items:
1. First 1. Second 1. Third
File Endings (MD047)
End with single newline:
Last content line. [single newline] [EOF]
Table Column Style (MD060)
Use consistent spacing in tables. Three styles:
Compact (recommended): | cell | - single space around content
| Header 1 | Header 2 | | --- | --- | | Data | More data |
Aligned: Pipes vertically aligned with padding
Tight: |cell| - no spaces
Pick ONE style per document. Compact is preferred.
Character Encoding
Detection: View → Render Whitespace in VS Code
Fix: Find \u00A0 → Replace with space
Critical for AI: Two trailing spaces = intentional line breaks. Do NOT remove them.
Critical Error Patterns
1. List Without Blank Lines
<!-- markdownlint-disable MD032 -->Wrong:
Text: - Item Text.
Right:
Text: - Item Text.
2. Heading Without Blank Lines
<!-- markdownlint-disable MD022 -->Wrong:
Text. ## Head Text.
Right:
Text. ## Head Text.
3. Code Without Blanks/Language
<!-- markdownlint-disable MD031 MD040 -->Wrong:
Text: ``` code ``` Text.
Right:
Text: ```python code ``` Text.
4. Inconsistent Markers
<!-- markdownlint-disable MD004 -->Wrong:
- Item * Item
Right:
- Item - Item
5. Skipping Levels
<!-- markdownlint-disable MD001 -->Wrong:
# Title ### Sub (skipped H2)
Right:
# Title ## Section ### Sub
Post-Generation Validation
- •Lists have blank lines before/after
- •Headings have blank lines before/after
- •Code has blank lines before/after
- •Heading progression: 1→2→3→4
- •All lists use
- - •All code has language
- •Lines under 80 chars
- •Document starts with H1
- •URLs wrapped properly
- •Ordered lists use
1. - •File ends with one newline
- •Two trailing spaces used intentionally
- •Only regular spaces (no nbsp/tabs)
- •Tables use consistent column spacing
Mental Model
Markdown is blocks with mandatory spacing:
[Text Block] ↓ BLANK LINE ↓ [Heading Block] ↓ BLANK LINE ↓ [List Block] ↓ BLANK LINE ↓ [Code Block] ↓ BLANK LINE ↓ [Text Block] [EOF]
Every block transition = blank line required.
Quick Patterns
List:
text - item text
Heading:
text ## Head text
Code:
text ```lang code ``` text
Nested:
- parent - child - parent
Ordered:
text 1. item 1. item text
Table:
text | Header | Header | | --- | --- | | Cell | Cell | text
Common Languages
Programming: python javascript java c cpp go rust ruby
php swift kotlin typescript
Shell: bash sh powershell cmd zsh
Markup: html css xml json yaml toml markdown
Database: sql postgresql mysql
Other: text diff log
Validation
markdownlint filename.md
Goal: Zero errors/warnings.
Additional Resources
See bundled references:
- •
references/complete-rules.md- Full rule catalog - •
references/edge-cases.md- Platform quirks - •
references/examples.md- Detailed examples
Remember
Most common: Missing blank lines around lists/headings/code.
Two trailing spaces: Intentional line breaks. Do NOT remove.
When in doubt:
- •Add blank lines before/after blocks
- •Use
-for lists - •Use
#for headings - •Specify code language
- •Increment headings by one
- •Use regular spaces only
- •Two trailing spaces = line break