markdown-documentation▌
aj-geddes/useful-ai-prompts · updated Apr 8, 2026
Comprehensive reference for markdown syntax, GitHub Flavored Markdown, and documentation best practices.
- ›Covers core markdown elements: headers, text formatting, lists, links, images, code blocks, and tables
- ›Includes GitHub Flavored Markdown extensions: collapsible sections, syntax highlighting, badges, alerts, and Mermaid diagrams
- ›Provides actionable best practices for README files, wikis, and technical documentation, including accessibility guidelines and link management
- ›Organiz
Markdown Documentation
Table of Contents
Overview
Master markdown syntax and best practices for creating well-formatted, readable documentation using standard Markdown and GitHub Flavored Markdown (GFM).
When to Use
- README files
- Documentation pages
- GitHub/GitLab wikis
- Blog posts
- Technical writing
- Project documentation
- Comment formatting
Quick Start
- Comment formatting
# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header
# Alternative H1
## Alternative H2
Reference Guides
Detailed implementations in the references/ directory:
| Guide | Contents |
|---|---|
| Text Formatting | Text Formatting |
| Lists | Lists |
| Links and Images | Links and Images, Code Blocks, Tables |
| Extended Syntax (GitHub Flavored Markdown) | Extended Syntax (GitHub Flavored Markdown) |
| Collapsible Sections | Collapsible Sections, Syntax Highlighting, Badges |
| Alerts and Callouts | Alerts and Callouts |
| Mermaid Diagrams | Mermaid Diagrams |
Best Practices
✅ DO
- Use descriptive link text
- Include table of contents for long documents
- Add alt text to images
- Use code blocks with language specification
- Keep lines under 80-100 characters
- Use relative links for internal docs
- Add badges for build status, coverage, etc.
- Include examples and screenshots
- Use semantic line breaks
- Test all links regularly
❌ DON'T
- Use "click here" as link text
- Forget alt text on images
- Mix HTML and Markdown unnecessarily
- Use absolute paths for local files
- Create walls of text without breaks
- Skip language specification in code blocks
- Use images for text content (accessibility)
Discussion
Product Hunt–style comments (not star reviews)- No comments yet — start the thread.
Ratings
4.7★★★★★58 reviews- ★★★★★Dev Gupta· Dec 28, 2024
Keeps context tight: markdown-documentation is the kind of skill you can hand to a new teammate without a long onboarding doc.
- ★★★★★Chaitanya Patil· Dec 24, 2024
markdown-documentation is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
- ★★★★★Amina Bansal· Dec 24, 2024
I recommend markdown-documentation for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.
- ★★★★★Amina Bhatia· Dec 16, 2024
Solid pick for teams standardizing on skills: markdown-documentation is focused, and the summary matches what you get after install.
- ★★★★★Arya Flores· Dec 8, 2024
Useful defaults in markdown-documentation — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.
- ★★★★★James Kapoor· Dec 8, 2024
markdown-documentation is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
- ★★★★★Amina Martinez· Nov 27, 2024
markdown-documentation has been reliable in day-to-day use. Documentation quality is above average for community skills.
- ★★★★★Nikhil Mensah· Nov 27, 2024
Keeps context tight: markdown-documentation is the kind of skill you can hand to a new teammate without a long onboarding doc.
- ★★★★★James Malhotra· Nov 19, 2024
markdown-documentation is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
- ★★★★★Piyush G· Nov 15, 2024
Keeps context tight: markdown-documentation is the kind of skill you can hand to a new teammate without a long onboarding doc.
showing 1-10 of 58