Markdown Guidelines — VPN.com Content

2026-05-07 · Ben · handoff

Markdown Guidelines

For: Content team, freelance writers, AI assistants Purpose: Deliver markdown files that publish with zero conversion needed.

---

Frontmatter

---
title: "Your Page Title Here"
description: "One sentence, under 160 characters. This appears in Google results."
date: 2026-04-28
updated: 2026-04-28
author: Michael
category: vpn
readTime: 6
draft: false
focusKeyword: "your target keyword"
permalink: vpn/your-url-slug
---

Required fields

Optional fields

---

BLUF

Every post starts with a BLUF immediately after frontmatter.

> **Bottom Line:** A VPN encrypts your traffic and hides your IP address. If you use public WiFi or care about privacy, you need one.

• Always > **Bottom Line:**
• 1-2 sentences, no hedging
• Renders as a blue-border callout on the live site

---

Headings

The title frontmatter becomes the <h1> — never add your own # in content.

• Start with ## for top-level sections
• Never skip levels (## → #### without ###)
• No bold in headings: ## Security Features, not ## **Security Features**

---

Content Elements

Callouts

<div class="callout">

Warning or general emphasis here.

</div>

<div class="callout-info">

**Important:** Key fact or context.

</div>

<div class="callout-tip">

**Tip:** Actionable advice.

</div>

Blank line after opening <div> and before closing </div> — required for markdown to render inside HTML. One callout per 500–800 words.

---

Pros / Cons

<div class="pros-cons">
<div class="pros">
<h4>Pros</h4>
<ul>
<li>Fast WireGuard speeds</li>
<li>Independently audited no-logs policy</li>
</ul>
</div>
<div class="cons">
<h4>Cons</h4>
<ul>
<li>Premium pricing</li>
<li>No free tier</li>
</ul>
</div>
</div>

Always include both sides. 3–5 items each. No markdown inside the HTML block.

---

Tables

Standard markdown tables are responsive (horizontal scroll on mobile):

| Provider | Price | Speed | Key Feature |
|----------|-------|-------|-------------|
| NordVPN | $3.89/mo | 730 Mbps | Double VPN |

For 4+ columns, use sticky first column:

<table class="compare">
<thead><tr><th>Feature</th><th>Option A</th><th>Option B</th></tr></thead>
<tbody>
<tr><td>Speed</td><td>Fast</td><td>Moderate</td></tr>
</tbody>
</table>

---

Links

• Internal links: start and end with /
• Never hardcode vpn.com — use relative paths
• All affiliate links go through /out?partner=slug

---

Images

![NordVPN speed test results showing 730 Mbps download](/images/uploads/2026/04/filename.webp)

• .webp only, max 1200px wide
• Alt text required — describe what's shown, not "image" or "screenshot"
• Images go in /images/uploads/YYYY/MM/

---

CTA Blocks

<div class="callout">

**The VPN trusted by millions. Now 68% off.**

[Get NordVPN →](/vpn/nordvpn/)

</div>

One CTA per 800–1200 words. State the value, not just "click here."

---

Writing Standards

Focus keyword

Must appear in: title, description, first paragraph, at least one ## heading. Build flags failures automatically.

Description

Max 160 characters. Build flags over-length descriptions as failures.

Final verdict

Every review post ends with ## Final Verdict (not "Bottom Line" — that's the BLUF at top).

---

Translation Readiness

To include a page in translation, add to frontmatter:

translate: true

Only pages scoring 40+ on the enrichment check should be translated. routeId is auto-assigned on first publish — do not set it.

Write for translation:

• Complete grammatical sentences
• Short concrete headings: "Security Features" not "Here's Why Security Matters"
• Spell out acronyms: "WireGuard (a VPN protocol)"
• Avoid idioms and very long compound sentences

Internal links written in English are auto-resolved to localized URLs by LocalizedContent.astro — no special syntax needed.

---

URL Structure

Filename matches permalink: permalink: vpn/best-vpn-for-streaming → best-vpn-for-streaming.md

---

Quick Reference

---

When new components are added to the design system, add them here with usage examples.