---
title: Markdown Best Practices
type: agent/instruction
tags: [markdown, documentation]
---

{{h1}}Markdown

{{h2}}Structure
- Headings hierarchically (H1 → H2 → H3)
- One H1 per document
- Blank lines between sections
- Consistent heading style (ATX `#`)

{{h2}}Formatting
- `**bold**` for emphasis, `*italic*` for stress
- `code` for inline code
- Fenced code blocks with language
- Blockquotes for citations

{{h2}}Lists
- `-` or `*` for unordered (be consistent)
- `1.` for ordered
- Indent nested with 2-4 spaces
- Blank lines for readability

{{h2}}Links
- Descriptive link text
- Reference-style for repeated URLs
- Relative links for internal docs
- Angle brackets for bare URLs

{{h2}}Code Blocks
- Always specify language
- Keep concise and focused
- Include comments for complex code
- Test examples

{{h2}}Tables
- For tabular data only
- Keep simple
- Align columns
- Use header row

{{h2}}Images
- Descriptive alt text
- Reasonable size
- Relative paths for local
- Optimise for web

{{h2}}Writing
- Clear, concise sentences
- Active voice
- Consistent terminology
- Present tense for docs

{{h2}}Organisation
- TOC for long documents
- Break into sections
- Consistent file naming
- README in directories

{{h2}}Avoid
- Don't use HTML unless necessary
- Don't use inconsistent formatting
- Don't create complex tables
- Don't use vague link text
