How to use markdown
Below are **current best-practice rules for authoring Markdown** that align with **modern HTML semantics, accessibility (a11y), and your chosen stack**
(`unified + remark + rehype + sanitize`, server-rendered in Next.js).
This is written as **authoring + system guidance**—what content creators should do *and* what your CMS should enforce.
---
Core Principles (Modern Markdown → HTML)
Markdown is **content**, HTML is **structure**, CSS is **presentation**.
Your pipeline should emit **semantic HTML**, not layout hacks.
---
Headings (Critical for a11y + SEO)
**Best practices**
* One `#` (H1) per document, used only for the page title
* Skip no levels (`##` → `###`, never jump to `####`)
* Do not style text to look like headings—use real headings
**Bad**
```md
**Big Title**
```
**Good**
```md
Section Title
```
Why:
* Screen readers rely on heading hierarchy
* Search engines use heading structure for page understanding
---
Lists (Use Native Semantics)
Use Markdown lists, not hyphens for formatting.
**Good**
```md
- First point
- Second point
- Subpoint
```
**Avoid**
```md
• First point
• Second point
```
Why:
* Emits proper `<ul><li>` HTML
* Keyboard and screen-reader navigable
---
Links (Accessible & Meaningful)
**Rule:** Links must be understandable *out of context*.
**Bad**
```md
[click here](...)
```
**Good**
```md
[Read the full study on trust](...)
```
Why:
* Screen readers often list links independently
* Improves SEO and usability
---
Emphasis (Do Not Overuse)
**Use sparingly**
```md
*italic* → emphasis
**bold** → strong importance
```
Avoid bolding entire paragraphs.
If everything is emphasized, nothing is.
---
Code Blocks (Language Always Required)
**Best**
````md
```ts
const trust = true
````
````
**Why**
- Enables syntax highlighting
- Improves readability
- No accessibility downside
Inline code is for **identifiers only**:
```md
Use the `renderMarkdownToHtml` function.
````
---
Blockquotes (Semantic Meaning Only)
Use blockquotes for:
* Citations
* Attributions
* Direct quotations
**Do not** use blockquotes for visual callouts.
```md
> Trust develops through repeated, consistent behavior.
```
Generates `<blockquote>` — meaningful to assistive tech.
---
Tables (GFM-Compliant Only)
Tables should be:
* Small
* Used for structured data
* Avoided for layout
```md
| Study | Finding |
|------|---------|
| Rotter (1967) | Trust as expectancy |
```
Your stack correctly emits `<table>`, `<thead>`, `<tbody>`—good for a11y.
---
Images (Even if Optional)
If images are allowed:
```md
```
Rules:
* Alt text is **required**
* Describe meaning, not appearance
* No “image of” / “picture of”
---
Line Breaks (Let HTML Do Its Job)
Do **not** rely on manual line breaks for spacing.
**Bad**
```md
Line one
Line two
Line three
```
**Good**
```md
Paragraph one.
Paragraph two.
```
Your renderer will output clean `<p>` tags.
---
What NOT to Allow (Even If Markdown Supports It)
Your sanitize step should block:
* Inline HTML from authors
* `<script>`, `<style>`
* Event handlers (`onclick`)
* Raw `<iframe>` unless explicitly whitelisted
Markdown ≠ escape hatch.
---
CMS Enforcement Rules (Recommended)
Your CMS should:
* Auto-insert H1 from title, not content
* Validate heading order
* Enforce alt text when images enabled
* Reject empty links (`[]()`)
* Normalize line endings
* Store:
* `content_raw`
* `content_html`
---
Output Guarantees (What “Good” Looks Like)
Your pipeline should consistently produce:
* Semantic HTML (`h1–h6`, `p`, `ul`, `blockquote`, `code`)
* No presentational markup
* Sanitized output
* Zero client-side parsing
* Cacheable HTML
---
Short Rule of Thumb
> If it helps screen readers, it usually helps SEO.
> If it breaks semantics, it will break performance later.