Markdown Syntax Guide

This guide collects the Markdown and MDX syntax currently supported by this blog. Use .md for regular posts. Use .mdx when you need imports, JSX, or Astro components inside the article.

Frontmatter

Every post starts with YAML frontmatter. The content collection reads these fields to render the title, description, date, category, tags, cover image, and language route.

---
title: 'Post title'
description: 'A short summary used in lists and SEO metadata.'
date: 2026.05.02
updated: 2026.05.03
category: Engineering
tags: [astro, markdown]
lang: en
cover: '../../../assets/blog-placeholder-about.jpg'
draft: false
---

title, description, and date are required. Put English posts in src/content/blog/en/; lang: en is optional but useful for clarity.

Headings And TOC

Post pages automatically build the table of contents from h2 through h6, so body content usually starts at ##.

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Heading 3 Example

Heading 4 Example

Heading 5 Example

Heading 6 Example

Paragraphs, Breaks, And Rules

Separate paragraphs with a blank line.
To force a line break inside the same paragraph, add two spaces at the end of the line or use <br>.

First paragraph.

Second paragraph.  
This line stays in the second paragraph.

---

Inline Formatting

Common inline formatting works as expected:

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

[Internal link](/posts/markdown-syntax-guide-en)
[External link](https://astro.build)

Autolinks also work: https://github.github.com/gfm

Rendered output:

bold, italic, bold italic, strikethrough, inline code

Internal link External link

Autolinks also work: https://github.github.com/gfm

Inline code can also opt into Shiki syntax highlighting:

`console.log("Hello World"){:js}`

Rendered output: console.log("Hello World")

Lists

- Unordered item
- Second item
  - Nested item
  - Another nested item

1. Ordered item
2. Second step
3. Third step

- [x] Done
- [ ] Not done
- [!] Important
- [?] Question
- [+] Added
- [*] Highlight
- [i] Info
- [-] Cancelled

Rendered output:

• Unordered item
• Second item
  • Nested item
  • Another nested item

1. Ordered item
2. Second step
3. Third step

• Done
• Not done
• Important
• Question
• Added
• Highlight
• Info
• Cancelled

Supported checkbox markers:

Rendered marker preview:

• To-do
• Done
• Done uppercase
• Incomplete
• Canceled
• Forwarded
• Scheduling
• Question
• Important
• Star
• Quote
• Smart quote
• Location
• Bookmark
• Information
• Dollar
• Idea
• Pros
• Pros uppercase
• Cons
• Cons uppercase
• Win
• Win uppercase
• Up
• Down
• Add
• Bug
• Alarm
• Note
• Note uppercase
• Review
• Love

Blockquotes

> The best time to write a post is right after solving the problem.  
> The second best time is before you forget why it mattered.

The best time to write a post is right after solving the problem.
The second best time is before you forget why it mattered.

Blockquotes can include bold text, italic text, links, footnotes, and inline code.

Images

Images can reference files from src/assets with relative paths, or they can use external URLs.

![Blog placeholder](../../../assets/blog-placeholder-about.jpg)

Tables

| Syntax | Purpose | Example |
| --- | --- | --- |
| `_text_` | Italic | _text_ |
| `**text**` | Bold | **text** |
| `` `code` `` | Inline code | `code` |

Footnotes

Here is a footnote reference.[^note]

[^note]: Footnotes render in the bottom footnote section on compact layouts and as left-side sidenotes on roomy layouts.

Here is a footnote reference.¹1. Footnotes render in the bottom footnote section on compact layouts and as left-side sidenotes on roomy layouts.

HTML Elements

Markdown can include small pieces of HTML. This blog already styles these common elements:

<abbr title="Graphics Interchange Format">GIF</abbr>

H<sub>2</sub>O

X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>

Press <kbd>Ctrl</kbd> + <kbd>K</kbd>

Use <mark>highlight</mark> for emphasis.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press Ctrl + K

Use highlight for emphasis.

Code Blocks

Code blocks use Shiki highlighting and include a copy button automatically. Common supported languages include astro, bash, css, html, js, jsx, json, md, mdx, npm, sh, ts, tsx, vue, and yaml.

```ts
const message: string = "Hello";
console.log(message);
```

const message: string = "Hello";
console.log(message);

Code Block Titles

```ts title="hello.ts"
export function hello(name: string) {
  return `Hello, ${name}`;
}
```

export function hello(name: string) {
  return `Hello, ${name}`;
}

Line Numbers

```js lineNumbers
const value = 1;
console.log(value);
```

```js lineNumbers=8
function main() {
  return "line numbers start at 8";
}
```

const value = 1;
console.log(value);

function main() {
  return "line numbers start at 8";
}

Highlight, Diff, And Focus

Use Shiki transformer comments to style specific lines or words.

```tsx
const framework = "Astro"; // [\!code highlight]

// [\!code word:static]
const benefit = "static output";

console.log("old"); // [\!code --]
console.log("new"); // [\!code ++]

return benefit; // [\!code focus]
```

const framework = "Astro";

const benefit = "static output";

console.log("old");
console.log("new");

return benefit;

Code Block Tabs

Adjacent code blocks with tab="..." are automatically grouped into tabs.

```ts tab="pnpm"
pnpm add astro
```

```bash tab="npm"
npm install astro
```

```bash tab="yarn"
yarn add astro
```

pnpm add astro

npm install astro

yarn add astro

Steps

Use [step] or numeric prefixes on consecutive headings to render them as numbered guide steps. The marker is removed from the visible heading, and the same number is shown in the table of contents.

Using [step]

## Heading 2 [step]

This is the main note for the first step. Use it for prerequisites, goals, or context.

### Sub Heading 1 [step]

Nested steps can include body copy for smaller actions.

### Sub Heading 2 [step]

The second nested step stays at the same numbered level as the previous one.

## Heading 3 [step]

Returning to a level-two heading continues the outer step sequence.

Using Numbers

## 1. Heading 2

Numeric prefixes are useful when migrating existing docs. The rendered heading removes the number.

### 1. Sub Heading 1

Nested numeric prefixes are also regenerated by the renderer.

### 2. Sub Heading 2

You can focus on the document structure instead of maintaining the final marker style.

## 2. Heading 3

The outer sequence continues as the second step.

Math

This blog enables remark-math and rehype-katex, so both inline math and block math are available.

Inline math: $$c = \pm\sqrt{a^2 + b^2}$$

```math
\int_a^b f(x)\,dx
```

Inline math: $c = \pm\sqrt{a^2 + b^2}$

Callout

Both .md and .mdx files can use <Callout>, and they can also use Docusaurus / Fumadocs Remark Admonition style ::: syntax. Supported names are note, tip, info, warn, warning, caution, danger, error, success, and idea.

<Callout title="Tip" type="tip">

You can keep writing **Markdown** inside, including links, lists, code blocks, and math.

</Callout>

JSX Syntax

<Callout> is useful in MDX. note / tip / info render as info callouts, warn / warning / caution render as warning callouts, and danger / error render as error callouts.

Admonition Syntax

Admonition syntax comes from Docusaurus, and Fumadocs remarkDirectiveAdmonition supports it for migrations. The title is optional; when present, put it in square brackets. Inline Markdown is allowed in the title.

:::tip[Title with `Markdown`]

This renders as a callout.

:::

Cards

Both .md and .mdx files can use <Cards> and <Card>. href turns a card into a link, external links get safe attributes automatically, and icon can use a Lucide icon name.

<Cards>
  <Card
    title="Astro"
    description="A content-first static site framework"
    href="https://astro.build"
    icon="Rocket"
  >
    Great for blogs, docs, and portfolio sites.
  </Card>
  <Card title="Local component" description="A card without a link" icon="BookOpen">
    Cards can also group related content.
  </Card>
</Cards>

MDX Components

.mdx is a superset of Markdown. It can import Astro components and render them inline. Components render as static HTML unless the component itself opts into client-side JavaScript.

import Button from '../../../components/Button.astro';

<Button link="/" text="Back home" />

You can also write code block tabs with components when you need more control over tab attributes.

<CodeBlockTabs defaultValue="astro">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="astro" label="Astro" active />
    <CodeBlockTabsTrigger value="css" label="CSS" />
  </CodeBlockTabsList>

  <CodeBlockTab value="astro" active>
    ```astro
    ---
    const name = "Astro";
    ---

    <h2>{name}</h2>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="css">
    ```css
    h2 {
      color: currentColor;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

---
const name = "Astro";
---

<h2>{name}</h2>

h2 {
  color: currentColor;
}

Writing Notes

• Start body content at ## so the page title comes only from frontmatter.
• Keep paragraphs short; the table of contents becomes easier to scan.
• Add a language to every code block when possible, and use title="file.ts" when a filename matters.
• Use <Callout> for important notes and <Cards> for grouped links.
• Use [step] headings for procedural guides where the order matters.
• Use .md for plain writing and .mdx when you need imports or JSX.
• When adding, changing, or removing Markdown / MDX format support, update CLAUDE.md, AGENTS.md, this English guide, and the Chinese guide together.