Markdown Syntax

Every markdown feature, component block, and inline modifier sitemd supports — in one page. Use this as the canonical reference and click through to component-specific docs for deeper coverage.

How does sitemd parse markdown?

sitemd builds on marked.js, a fast CommonMark-compliant parser, with a custom preprocessor that handles sitemd's component blocks before markdown rendering. The pipeline runs in this order:

1. Fenced code blocks are extracted and protected so syntax inside them is never preprocessed
2. Component blocks (button:, card:, embed:, gallery:, form:, modal:, etc.) are converted to HTML
3. Layout fences (center:, hidden:, gated:, mobile:, desktop:) are wrapped in styled <div>s
4. Standard markdown is rendered through marked with a custom heading and link renderer
5. Code blocks are restored, and literal <br> becomes a <br>

This means you can mix markdown, HTML, and sitemd components in the same file without escaping anything inside code blocks.

What standard markdown is supported?

All CommonMark features work, plus GitHub-flavored extensions for tables and strikethrough.

# Heading 1
## Heading 2
### Heading 3

**bold**, *italic*, ~~strikethrough~~, `inline code`

- Unordered list item
- Another item
  - Nested item

1. Ordered list item
2. Second item

> A blockquote with **inline formatting**.

[A link](/docs/getting-started)
![An image](/media/og-image.png)

---

| Column | Column |
|---|---|
| Cell | Cell |

Fenced code blocks support language hints for syntax highlighting:

```js
function build() {
  return 'website';
}
```

Escape any special character with a backslash: \*not bold\* renders literally. Raw HTML tags pass through untouched, so <details>, <span>, <kbd>, and any other element work inline. See Inline HTML for details.

What frontmatter fields are recognized?

Every page starts with YAML frontmatter between --- delimiters. Lines starting with # are treated as comments, which is how the auto-injected syntax reference at the top of every page file works.

---
title: My Page
titleSuffix: " | sitemd"
tabTitle: My Page
tabTitleSuffix: " | sitemd"
description: A short summary under 160 characters.
slug: /my-page
sidebarGroupShown: docs
groupMember:
  - docs
updated: 2026-04-08
---

See Pages & Content for the full authoring reference.

How do headings and anchors work?

Every heading automatically gets a URL-friendly id derived from its text. ## Getting Started becomes id="getting-started", and duplicate IDs within the same page get a numeric suffix (-2, -3).

The first # H1 in a page renders as a true <h1>. Every subsequent # H1 renders as <h2 class="h1-style"> — visually identical but SEO-correct (one H1 per page).

Add an inline anchor anywhere with {#id} on its own line:

{#pricing}

## Plans

Link to anchors with the standard markdown syntax:

[Jump to pricing](#pricing)
[See the themes docs](/docs/themes#custom-colors)

See Headings for the full reference.

How do I add links and buttons?

Inline links use standard markdown. External URLs (https://...) automatically open in a new tab. Override that with +newtab or +sametab appended directly to the URL:

[A normal link](/docs/getting-started)
[Force new tab](/docs/headings+newtab)
[Force same tab](https://example.com+sametab)

Open a modal from any link by pointing at #modal:id:

[Open the pricing modal](#modal:pricing)

For block-level call-to-action buttons, prefix any line with button: followed by a label and target. Consecutive button: lines auto-group into a row:

button: Get Started: /docs/getting-started
button: View on GitHub: https://github.com/sitemd-cc/sitemd
button: Pricing: /pricing +outline

Button modifiers chain freely:

The same button: prefix works in settings/header.md, settings/footer.md, and settings/groups.md. See Buttons & Links for the full reference.

How do I add images and media?

Standard markdown images work as-is. Append space-separated +modifier flags inside the URL parentheses to resize, crop, filter, or expand them:

![Logo](/media/sitemd-logo-dark.svg +width:200)
![Hero](/media/og-image.png +crop:1200x600 +corner:curve +expand)
![Profile](/media/profile-pic-cropped.jpeg +width:160 +circle +bw)

Self-hosted video files (.mp4, .webm, .ogv, .mov, .m4v) automatically render as <video> instead of <img>. Video-only modifiers: +autoplay (implies muted + loop + playsinline), +muted, +loop, +nocontrols, +poster:url.

Group images side-by-side with image-row:, or grid them with gallery::

image-row:
  ![Light theme](/media/content/themes/theme-light.png)
  ![Dark theme](/media/content/themes/theme-dark.png)
  ![Paper theme](/media/content/themes/theme-paper.png)

gallery:
  ![Analytics dashboard](/media/content/cards/analytics-dashboard-786d29e8.png)
  ![API gateway](/media/content/cards/api-gateway-2da99fe0.png)
  ![Cloud storage](/media/content/cards/cloud-storage-0ab92466.png)
  ![Bulk sites use case](/media/content/use-cases/bulk-sites.png)

gallery: accepts flags before the colon: gallery +noexpand +corner:curve: disables the lightbox and rounds corners.

Embed third-party content with embed: followed by a URL on its own line. sitemd auto-detects YouTube, Vimeo, X/Twitter, Reddit, Instagram, LinkedIn, TikTok, Spotify, and CodePen. Any other URL gets a generic iframe fallback.

embed: https://www.youtube.com/watch?v=dQw4w9WgXcQ
embed: https://x.com/sitemdcc/status/1234567890
embed: https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT

See Images and Embeds for the full references.

What rich components are available?

Each component has its own deep-dive doc. The summary table lists the minimum syntax for each:

A card example to anchor the pattern:

card: Zero Config
card-text: Write markdown, get a website.
card-icon: zap
card-link: Get Started: /docs/getting-started

card: Deploy Anywhere
card-text: Cloudflare, GitHub Pages, Vercel, Netlify — or any static host.
card-icon: rocket
card-link: See Deploy: /docs/deploy

Consecutive card: blocks auto-group into a responsive grid. The same auto-grouping rule applies to button: and author: blocks.

How do I align, hide, or gate content?

Layout fences open with name: on its own line and close with /name. The content between is wrapped in a styled container.

center:
# A Centered Heading
button: Centered CTA: /docs/getting-started
/center

right:
A right-aligned paragraph.
/right

hidden:
# SEO Title for Search Engines
/hidden

mobile:
This block only appears on small screens.
/mobile

desktop:
This block only appears on larger screens.
/desktop

gated: subscriber, member
This paragraph only renders for logged-in subscribers or members.
/gated

What other inline syntax exists?

A few smaller pieces don't fit anywhere else:

{#section-id}
A line that becomes <div id="section-id"></div> for anchor linking.

[hover this]{tooltip definition shown on hover or focus}

A line with a hard<br>line break in the middle.

Quick reference

Everything in one table for fast lookup:

Related

• Markdown — what markdown is and why AI agents prefer it
• Pages & Content — page authoring, file organization, and frontmatter
• Headings — heading levels, anchor IDs, and the multiple-H1 rule
• Agent Onboarding — how the auto-injected syntax reference teaches AI agents this surface area