aj-geddes/markdown-documentation

Markdown Documentation

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

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)