This post is the single source of truth for how markdown renders on our blog. Developers style against this post. Content writers reference it to know what is available and how to use it.

---

Headings

Headings structure the page and help readers navigate long articles.

Heading 2 — Major Section Title

Example paragraph text.

Heading 3 — Sub-Section Title

Example paragraph text.

Heading 4 — Minor Group Title

Example paragraph text.

Heading 5 — Label or Callout Header

Example paragraph text.

Rules for writers:

• The post title is Heading 1 and is set automatically by the CMS. Never add an H1 inside the body.
• Start every major section with H2.
• Use H3 and H4 for nesting within a section.
• Do not skip levels — for example, do not jump from H2 directly to H4.

---

Paragraphs

This is a standard paragraph. A blank line between blocks creates a new paragraph. Keep each paragraph focused on one idea — three to five sentences is a good target.

This is a second paragraph. Readers scan before they read, so short, direct paragraphs perform better than long, dense ones.

---

Text Emphasis

Use bold to highlight key terms, important numbers, or critical takeaways.

Use italic for titles, technical terms being introduced for the first time, or light emphasis.

Use bold and italic together sparingly — overuse removes all impact.

Use strikethrough when correcting outdated information inline or showing a before/after contrast.

Underline is available via HTML only — use it for definitions or special callouts, not for decoration:

This text is underlined.

Note for writers: Underlines look like links to readers. Use them only when the meaning is clearly not a hyperlink.

---

Lists

Bullet List

Use for items without a meaningful order — features, benefits, considerations.

• First item in the list
• Second item in the list
• Third item in the list
• Nested item (indent with two spaces)
• Another nested item

Numbered List

Use for sequential steps or ranked items where the order matters.

1. Identify your target audience before writing.
2. Outline the key points you want to cover.
3. Write the first draft without editing.
4. Review for clarity and cut anything redundant.

Mixed Nesting Example

1. Set up your account
   • Download the app
   • Enter your email address
2. Complete your profile
3. Invite your team

---

Links

This is a link to an external page

Within a sentence, links look like this: learn more about gamification strategies for employee engagement.

Rules for writers:

• Always use descriptive link text. Avoid "click here", "read more", or bare URLs.
• Good: "see our pricing plans"
• Bad: "click here for pricing"
• Links will open in a new tab by default.

---

Images

Images must be uploaded to the Strapi media library first. Then paste the image URL.

Rules for writers:

• Always fill in the alt text between the brackets — it is required for accessibility and SEO.
• Upload images that are at least 1200px wide for good display quality.
• Place images alone in their own paragraph — do not place two images back to back.
• Image file size should be under 500 KB. Compress at squoosh.app before uploading if needed.

---

Blockquotes

Use blockquotes for pull quotes, customer quotes, key statistics, or important callouts.

"Gamification increased our team's task completion rate by 40% in the first quarter alone." — Sarah M., HR Director at Acme Corp

Pro tip: Keep quotes to one to three sentences. Longer quotes lose emphasis.

Rules for writers:

• Start the line with > followed by a space.
• Attribute quotes with an em dash and the person's name and title.
• Do not use blockquotes for general information — they draw the eye, so use them only for genuinely important content.

---

Tables

Use tables for structured comparisons, feature matrices, or side-by-side data.

Feature	Basic Plan	Growth Plan	Enterprise
Users	Up to 10	Up to 100	Unlimited
Analytics	Basic	Advanced	Custom
Support	Email	Priority email	Dedicated CSM
Integrations	5	25	Unlimited

Rules for writers:

• Always include a header row (the first row with the bold/shaded background).
• Keep cell content brief — tables are for scanning, not reading.
• Avoid nesting bullet lists inside table cells.
• Use a table only when the information is genuinely comparative. If it is a list, use a bullet list instead.

---

Horizontal Rule

A horizontal rule creates a visual divider between major sections. Use it when headings alone feel insufficient to signal a topic shift.

---

The line above is a horizontal rule, created with three dashes (---) on their own line.

---

What Is Not Available

These elements will not render correctly — avoid them:

• Code blocks — not styled, will display as raw text
• Inline code — not styled
• Task lists (- [ ] item) — renders as plain text, not checkboxes
• Footnotes — not supported by the current markdown parser
• Embedded iframes or scripts — stripped for security

---

Writing Tips for Content Writers

1. H1 is the post title. Never put a Heading 1 inside the body — the CMS inserts it automatically from the title field.
2. Bold guides skimmers. Readers scan headings and bold text before committing to reading. Make bold words count.
3. One image per paragraph block. Do not stack multiple images without text between them.
4. Write link text that describes the destination. A reader should understand where a link goes without reading the surrounding sentence.
5. Fill in alt text for every image. A blank alt field hurts SEO and accessibility.
6. Use blockquotes sparingly. One or two per post is ideal. If everything is highlighted, nothing is.
7. Break up long sections. If an H2 section runs longer than 300 words, consider adding an H3 or splitting into two sections.

---

Developer Notes — Styling Gaps to Address

The following elements are used in the design system but may need explicit CSS rules added:

• Ordered lists (ol li) — currently only unordered lists have explicit styles. Add list-style-type: decimal and margin-left to match bullet list styling.
• Nested lists — verify both ul ul and ol ol indent correctly at two or more levels.
• <hr> horizontal rule — add a styled divider (e.g. a light grey line, 1px, with margin: 2rem 0).
• Image captions — marked does not output <figcaption> natively. Consider wrapping images in a <figure> via a custom renderer if captions are needed.
• Link underline on hover — currently links are bold and purple. Confirm hover state has underline or another affordance.
• Table overflow on mobile — wrap .single-post-txt table in an overflow-x: auto container for small screens.

---

This is the reference post. Developers style against it. Content writers refer to it before publishing.