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)
Ratings
4.5★★★★★10 reviews- ★★★★★Shikha Mishra· Oct 10, 2024
markdown-documentation is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
- ★★★★★Piyush G· Sep 9, 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· Aug 8, 2024
Registry listing for markdown-documentation matched our evaluation — installs cleanly and behaves as described in the markdown.
- ★★★★★Sakshi Patil· Jul 7, 2024
markdown-documentation reduced setup friction for our internal harness; good balance of opinion and flexibility.
- ★★★★★Ganesh Mohane· Jun 6, 2024
I recommend markdown-documentation for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.
- ★★★★★Oshnikdeep· May 5, 2024
Useful defaults in markdown-documentation — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.
- ★★★★★Dhruvi Jain· Apr 4, 2024
markdown-documentation has been reliable in day-to-day use. Documentation quality is above average for community skills.
- ★★★★★Rahul Santra· Mar 3, 2024
Solid pick for teams standardizing on skills: markdown-documentation is focused, and the summary matches what you get after install.
- ★★★★★Pratham Ware· Feb 2, 2024
We added markdown-documentation from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.
- ★★★★★Yash Thakker· Jan 1, 2024
markdown-documentation fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.