Markdown Guide

Postlark supports GitHub Flavored Markdown (GFM) plus 10 extensions for rich content authoring. Everything you write in Markdown is rendered to static HTML with zero client-side JavaScript (except opt-in KaTeX, Mermaid, and highlight.js from CDN).

Basic Markdown (GFM)

These standard GFM features work out of the box.

Headings

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

Text Formatting

**bold** *italic* ~~strikethrough~~

Links and Images

[Link text](https://example.com)
![Alt text](https://example.com/image.png)

Lists

- Unordered item
- Another item

1. Ordered item
2. Another item

Tables

| Feature   | Status    |
|-----------|-----------|
| GFM       | Supported |
| Alignment | Supported |

Blockquotes

> This is a standard blockquote.

Inline Code

Wrap text in backticks for inline code: `console.log()`.

Horizontal Rule

---

Extensions

Postlark extends standard GFM with 10 features. Each is rendered server-side during publish and requires no configuration.

1. Heading IDs and Anchors

Every heading automatically receives a URL-friendly id attribute and a clickable # anchor link. This enables deep linking to any section of your post.

Syntax:

## Getting Started
### API Authentication
## 시작하기

Result:

## Getting Started becomes <h2 id="getting-started"> with an anchor link
### API Authentication becomes <h3 id="api-authentication">
Korean text is supported: ## 시작하기 becomes <h2 id="시작하기">

Link to a heading from anywhere using #heading-id:

See the [Getting Started](#getting-started) section.

The anchor # symbol appears on hover, so readers can easily copy the link.

2. Table of Contents

Place [TOC] on its own line to generate a navigation list of all headings in the post.

Syntax:

[TOC]

## Introduction
### Background
## Main Topic
### Details
## Conclusion

Result: The [TOC] placeholder is replaced with a styled <nav> element containing links to every heading. Nested headings are indented (level 2 and level 3 offsets). The Table of Contents is styled as a bordered box with the blog’s accent color.

You can also use lowercase [toc].

3. Footnotes

Add references with [^id] inline and define them anywhere in the document with [^id]: text. All footnote definitions are collected and rendered in a numbered section at the bottom of the post.

Syntax:

Postlark uses the marked library[^1] for rendering.
It supports all GFM features[^2].

[^1]: marked is a fast Markdown parser written in JavaScript.
[^2]: GitHub Flavored Markdown adds tables, task lists, and more.

Result: Superscript reference numbers appear inline (e.g., [1]) and link to the corresponding footnote at the bottom. Each footnote includes a back-arrow link to return to the reference point in the text.

4. Math (KaTeX)

Write mathematical expressions using LaTeX syntax. Inline math uses single dollar signs, and block math uses double dollar signs. Expressions are rendered client-side by KaTeX (loaded from CDN).

Inline math:

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ for any quadratic.

Block math:

$$
E = mc^2
$$

You can also use a fenced code block with language math or latex:

```math
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
```

Result: Inline math is rendered within the text flow. Block math is centered and displayed at a larger size. KaTeX CSS and JS are loaded from cdn.jsdelivr.net.

5. Mermaid Diagrams

Create diagrams using Mermaid syntax inside a fenced code block with the language mermaid. Diagrams are rendered client-side by Mermaid.js (loaded from CDN) and automatically adapt to dark mode.

Syntax:

```mermaid
graph LR
    A[Write Markdown] --> B[Publish via API]
    B --> C[Blog Renders HTML]
    C --> D[CDN Caches Response]
```

Result: The code block is replaced with an SVG diagram. Mermaid supports flowcharts, sequence diagrams, Gantt charts, class diagrams, and more. See the Mermaid documentation for full syntax.

6. Callouts

Use GitHub-style callout syntax inside blockquotes. Five types are available: NOTE, TIP, IMPORTANT, WARNING, and CAUTION. Each has a distinct color and icon.

Syntax:

> [!NOTE]
> This is a note with helpful information.

> [!TIP]
> This is a tip with a suggested best practice.

> [!IMPORTANT]
> This is important information that should not be missed.

> [!WARNING]
> This is a warning about potential issues.

> [!CAUTION]
> This is a caution about dangerous actions.

Result: Each callout renders as a colored box with a left border, icon, and label:

Type	Icon	Color
`[!NOTE]`	Info	Blue
`[!TIP]`	Lightbulb	Green
`[!IMPORTANT]`	Exclamation	Purple
`[!WARNING]`	Warning	Yellow
`[!CAUTION]`	Circle	Red

Callouts fully support dark mode with adjusted background colors.

7. Emoji Shortcodes

Type emoji shortcodes between colons and they are converted to Unicode emoji characters during rendering.

Syntax:

Launch day! :rocket: :tada: :sparkles:
Great job :thumbsup: — needs work :thumbsdown:

Result: :rocket: becomes a rocket emoji, :tada: becomes a party popper, and so on.

Available shortcodes:

Shortcode	Emoji	Shortcode	Emoji	Shortcode	Emoji
`:smile:`	Smile	`:laugh:`	Laugh	`:wink:`	Wink
`:heart:`	Heart	`:thumbsup:`	Thumbs up	`:thumbsdown:`	Thumbs down
`:clap:`	Clap	`:fire:`	Fire	`:rocket:`	Rocket
`:star:`	Star	`:check:`	Check	`:x:`	X mark
`:warning:`	Warning	`:info:`	Info	`:bulb:`	Lightbulb
`:memo:`	Memo	`:link:`	Link	`:key:`	Key
`:lock:`	Lock	`:unlock:`	Unlock	`:bug:`	Bug
`:wrench:`	Wrench	`:gear:`	Gear	`:package:`	Package
`:tada:`	Party	`:sparkles:`	Sparkles	`:zap:`	Lightning
`:boom:`	Boom	`:eyes:`	Eyes	`:thinking:`	Thinking
`:100:`	100	`:wave:`	Wave	`:pray:`	Pray
`:muscle:`	Muscle	`:coffee:`	Coffee	`:beer:`	Beer
`:pin:`	Pin	`:bell:`	Bell	`:calendar:`	Calendar
`:chart:`	Chart	`:globe:`	Globe	`:cloud:`	Cloud
`:sun:`	Sun	`:moon:`	Moon	`:rainbow:`	Rainbow
`:umbrella:`	Umbrella	`:snowflake:`	Snowflake
`:arrow_right:`	Right arrow	`:arrow_left:`	Left arrow	`:arrow_up:`	Up arrow
`:arrow_down:`	Down arrow

8. Task Lists

Create checkbox lists using GFM task list syntax. Checkboxes are rendered as read-only styled elements.

Syntax:

- [x] Design the API
- [x] Build the worker
- [ ] Write documentation
- [ ] Launch to production

Result: Each item displays a styled checkbox. Checked items show a filled blue checkbox with a checkmark. Unchecked items show an empty bordered box. Checkboxes are read-only (not interactive).

9. Enhanced Code Blocks

Fenced code blocks support three additional features: file title headers, line numbers, and diff highlighting.

File title:

Add title="filename" after the language identifier to display a filename header above the code block.

```typescript title="src/index.ts"
export default {
  async fetch(request: Request): Promise<Response> {
    return new Response('Hello, Postlark!')
  },
}
```

Line numbers:

Add showLineNumbers after the language to display line numbers in the gutter.

```python showLineNumbers
def hello():
    print("Hello, world!")
    return True
```

Diff highlighting:

Use the diff language to highlight added and removed lines. Lines starting with + are shown in green, lines starting with - are shown in red.

```diff
- const old = 'before'
+ const new = 'after'
  const unchanged = true
```

You can combine features:

```typescript title="config.ts" showLineNumbers
const config = {
  name: 'my-blog',
  theme: 'default',
}
```

10. Syntax Highlighting

Code blocks with a language identifier are highlighted using highlight.js (loaded from CDN). The language label is displayed in the top-right corner of the block, and a Copy button appears on hover.

Syntax:

```javascript
function greet(name) {
  return `Hello, ${name}!`
}
```

```sql
SELECT title, slug FROM posts
WHERE status = 'published'
ORDER BY created_at DESC;
```

Supported languages include all languages supported by highlight.js: JavaScript, TypeScript, Python, Go, Rust, SQL, HTML, CSS, Bash, JSON, YAML, and many more.

Content Limits

Maximum content size: 1 MB
Maximum 10 tags per post, each up to 50 characters
Slug: auto-generated from title, supports Unicode (Korean, Japanese, etc.)

Security

All rendered HTML is sanitized for XSS protection. The following are stripped automatically:

<script>, <iframe>, <object>, <embed>, <form>, <style> tags
on* event handler attributes (e.g., onclick, onerror)
javascript: URLs in href and src attributes