Install
Use with your agent
Install the markdown-documentation skill, then use it as build context. Run: npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill markdown-documentation. Then read the installed skill.md and follow its guidance to build or refactor my project.
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)