markdown-documentation
aj-geddes/useful-ai-prompts
Master markdown formatting and GitHub Flavored Markdown for professional documentation.
What is markdown-documentation?
A comprehensive guide to markdown syntax, GitHub Flavored Markdown, and documentation best practices. Use this skill when writing README files, project documentation, wikis, or any technical content that requires well-formatted markdown.
- Format headers, text styling, and semantic structure
- Create lists, tables, links, and images with proper syntax
- Use GitHub Flavored Markdown extensions including collapsible sections and alerts
- Embed code blocks with syntax highlighting and Mermaid diagrams
- Apply accessibility best practices like alt text and descriptive link text
- Organize long documents with table of contents and semantic line breaks
How to install markdown-documentation
npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill markdown-documentationHow to use markdown-documentation
- 1.Review the quick start section to understand basic markdown syntax (headers, text formatting)
- 2.Consult the reference guides in the references/ directory for specific formatting needs (text, lists, links, tables, GFM extensions)
- 3.Apply best practices: use descriptive link text, include alt text on images, specify language in code blocks, keep lines under 80-100 characters
- 4.Test all links and verify formatting renders correctly on your target platform (GitHub, GitLab, etc.)
- 5.Use semantic line breaks and include table of contents for longer documents
Use cases
- Writing and formatting README files for GitHub projects
- Creating technical documentation and API guides
- Building project wikis and knowledge bases
- Formatting blog posts and technical articles
- Structuring multi-page documentation with internal links
- Software developers writing project documentation
- Technical writers and content creators
- Open source maintainers managing README files
- Teams building internal knowledge bases
- Anyone creating markdown-based documentation
markdown-documentation FAQ
GFM is an extension of standard Markdown that adds features like tables, strikethrough, task lists, and collapsible sections. It's the markdown flavor used by GitHub and is supported in most modern documentation platforms.
Generally avoid mixing HTML and Markdown unnecessarily. Use pure Markdown when possible for better readability and portability. Only use HTML when Markdown doesn't support the specific formatting you need.
Always include alt text for images using the syntax . Alt text describes the image content for screen readers and displays if the image fails to load.
Include a table of contents at the top with links to sections, use semantic line breaks to separate ideas, keep lines under 80-100 characters, and use descriptive headers to structure content logically.
Yes, GitHub Flavored Markdown supports Mermaid diagrams for flowcharts, sequence diagrams, and other visualizations. Use code blocks with the 'mermaid' language identifier.
Full instructions (SKILL.md)
Source of truth, from aj-geddes/useful-ai-prompts.
name: markdown-documentation description: > Master markdown formatting, GitHub Flavored Markdown, README files, and documentation formatting. Use when writing markdown docs, READMEs, or formatting documentation.
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)
Related skills
More from aj-geddes/useful-ai-prompts and the wider catalog.
mobile-app-testing
>
mobile-first-design
>
nginx-configuration
Configure Nginx for reverse proxy, load balancing, SSL/TLS, caching, and API gateway functionality.
nodejs-express-server
Build production-ready Express.js servers with routing, middleware, authentication, and database integration.
penetration-testing
>
responsive-web-design
>