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:

![Alt text](./relative/path.jpg)

Blockquotes

Use quotes only when the source adds value:

The best products come from disciplined tradeoffs. — Every engineer, eventually

Tables

Useful for small comparisons:

TopicWhy it matters
ClarityFaster reviews
ConsistencyFaster onboarding
ConstraintFewer regressions

Code Blocks

Fence code with a language token:

const posts = await getCollection('blog');
npm run dev

Lists

Keep list syntax simple and stable:

  1. Define intent
  2. Structure sections
  3. 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>O
  • x<sup>2</sup>
  • <kbd>Ctrl</kbd> + <kbd>K</kbd>

If a pattern is hard to read in markdown, split it into two sentences.