Markdown Style Guide

Consistent formatting rules for clear, maintainable documentation

  • • Use 1-6 # symbols for heading levels
  • • Keep heading lengths <80 characters
  • • Avoid all caps and excessive punctuation
  • • Use spaces between # and heading text

# H1 Heading
## H2 Heading
### H3 Heading - Keep it concise
#### H4 is rarely needed unless required
  • • Use blockquotes for quotes >2 lines
  • • Add 2 spaces before line continuation
  • • Use > symbol followed by 1 space
  • • Attribute sources when quoting external content

> This is a blockquote
> with multiple lines
> 
> -- John Doe
  • • Use triple backticks for code blocks
  • • Specify language for syntax highlighting
  • • Add line numbers for >5 line code examples
  • • Use indentation for nested code examples

const example = () => {
  console.log('Multiple lines');
  return 'with indentation';
};
  • • Align columns with pipes and dashes
  • • Use colons for column alignment
  • • Keep table descriptions concise
  • • Use headers that clearly describe content

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
  • • Add alt text for embedded images
  • • Use semantic markdown elements for headers
  • • Avoid color-only emphasis for important info
  • • Use proper spacing for readability