# Markdown > Transform AI markdown generation to be 100% markdownlint-compliant. Use this skill whenever generating messages containing markdown, generating or editing markdown files (.md) for technical documentation, README files, guides, tutorials, or any GFM content requiring clean, professional presentation. Use when this capability is needed. - Skill: `tomevault-io/markdown-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/markdown-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/markdown-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/markdown-3 --- # 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) ```markdown Text before. - Item one - Item two Text after. ``` ### Headings (MD001, MD022) ```markdown Text. ## Heading Content. ``` ### Code Blocks (MD031, MD040) ````markdown 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 ````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: ```markdown Wrong: https://example.com Right: Right: [link](https://example.com) Wrong: user@example.com Right: ``` ### Document Structure (MD041) Start with H1 (or front matter then H1): ```markdown # Document Title First paragraph. ``` ### Ordered Lists (MD029) Use `1.` for all items: ```markdown 1. First 1. Second 1. Third ``` ### File Endings (MD047) End with single newline: ```text Last content line. [single newline] [EOF] ``` ### Table Column Style (MD060) Use consistent spacing in tables. Three styles: **Compact (recommended):** `| cell |` - single space around content ```markdown | 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 **Wrong:** ```markdown Text: - Item Text. ``` **Right:** ```markdown Text: - Item Text. ``` ### 2. Heading Without Blank Lines **Wrong:** ```markdown Text. ## Head Text. ``` **Right:** ```markdown Text. ## Head Text. ``` ### 3. Code Without Blanks/Language **Wrong:** ````markdown Text: ``` code ``` Text. ```` **Right:** ````markdown Text: ```python code ``` Text. ```` ### 4. Inconsistent Markers **Wrong:** ```markdown - Item * Item ``` **Right:** ```markdown - Item - Item ``` ### 5. Skipping Levels **Wrong:** ```markdown # Title ### Sub (skipped H2) ``` **Right:** ```markdown # Title ## Section ### Sub ``` ## Post-Generation Validation 1. Lists have blank lines before/after 2. Headings have blank lines before/after 3. Code has blank lines before/after 4. Heading progression: 1→2→3→4 5. All lists use `-` 6. All code has language 7. Lines under 80 chars 8. Document starts with H1 9. URLs wrapped properly 10. Ordered lists use `1.` 11. File ends with one newline 12. Two trailing spaces used intentionally 13. Only regular spaces (no nbsp/tabs) 14. Tables use consistent column spacing ## Mental Model Markdown is **blocks with mandatory spacing:** ```text [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:** ```markdown text - item text ``` **Heading:** ```markdown text ## Head text ``` **Code:** ````markdown text ```lang code ``` text ```` **Nested:** ```markdown - parent - child - parent ``` **Ordered:** ```markdown text 1. item 1. item text ``` **Table:** ```markdown 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 ```bash 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: 1. Add blank lines before/after blocks 2. Use `-` for lists 3. Use `#` for headings 4. Specify code language 5. Increment headings by one 6. Use regular spaces only 7. Two trailing spaces = line break --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/redondok) — claim your Tome and manage your conversions.