Markdown Notes I Use for Publishing
A practical reference for clean markdown formatting and readability in Astro posts.
These notes are my baseline for writing posts quickly without sacrificing structure.
Headings
Use only the levels you need:
H1
H2
H3
H4
I keep body content in short blocks with one idea per section.
Paragraphs
Start with a sharp opening line, then expand with specific details.
Markdown is strongest when each paragraph moves the reader forward.
Images
Reference images with clear alt text:

Blockquotes
Use quotes only when the source adds value:
The best products come from disciplined tradeoffs. — Every engineer, eventually
Tables
Useful for small comparisons:
| Topic | Why it matters |
|---|---|
| Clarity | Faster reviews |
| Consistency | Faster onboarding |
| Constraint | Fewer regressions |
Code Blocks
Fence code with a language token:
const posts = await getCollection('blog');
npm run dev
Lists
Keep list syntax simple and stable:
- Define intent
- Structure sections
- Cut extra words
- Use bullets for options
- Keep each item concise
- Avoid nested overuse
Subtle inline elements
You can still use:
<abbr title="Progressive Web App">PWA</abbr>H<sub>2</sub>Ox<sup>2</sup><kbd>Ctrl</kbd> + <kbd>K</kbd>
If a pattern is hard to read in markdown, split it into two sentences.