Markdown 语法演示：本站文章的书写指南

这篇文章本身就是一份「活演示」：你现在看到的标题层级、文字样式、列表、表格、代码高亮和链接卡片，全部来自正文的 Markdown 源码。每一段示例都会先给出书写方式，再紧跟着展示真实渲染效果，方便对照学习。

Frontmatter 与文章结构

每篇文章都以 --- 包裹的 frontmatter 开头，声明标题、日期、描述、标签等元信息，例如本文的开头：

---
title: "Markdown 语法演示：本站文章的书写指南"
pubDatetime: 2026-08-19T14:05:00+08:00
description: "这篇文章以真实渲染效果演示本站文章的 Markdown 语法。"
tags:
  - Markdown
  - Astro
  - 博客
draft: false
---

文章由 frontmatter 和正文组成，正文就是普通 Markdown。文件放在 src/data/blog/ 下，文件名即文章的 slug，对应 /posts/<slug>/ 路由；如果文章带本地图片，需要改成「<slug>/index.md + 图片」的文件夹结构（详见下方「图片」一节）。

常用字段一览：

标题与段落

# 的数量代表标题层级。文章标题本身已是页面的一级标题（来自 frontmatter），正文一般从二级开始：

## 二级标题
### 三级标题
#### 四级标题

三级标题的渲染效果

这是三级标题下的正文。每个标题都会自动生成锚点链接，鼠标悬停会出现 #；右侧（移动端在顶部折叠菜单里）的「本页目录」同样是根据标题自动生成的，本文的目录恰好演示了多级嵌套。

四级标题的渲染效果

四级标题在目录中会进一步缩进。段落之间用空行分隔；如果要在同一段落内强制换行，可以在行尾加两个空格再回车。

文字样式

在 .mdx 文章里还可以直接写 <u>、<sub>、<sup> 这类小标签（会被当作 JSX 元素渲染）：下划线、水的化学式 H₂O、质能方程 E = mc²。

链接

站内链接直接用相对路径，例如 年前小记：一次加班，一场尴尬，与一些过年随想；站外链接（http/https）会被自动处理成在新标签页打开：

• Astro 官网 —— 外链，新窗口打开
• Margin 博客源码 —— 外链，新窗口打开
• Markdown 标签页 —— 站内标签页

除了行内链接，也支持引用式链接，把目标地址统一放在文末：

[Astro 官网][astro]

[astro]: https://astro.build

引用块

行首加 > 即可引用，支持多层嵌套。本站的引用块使用独立字体与强调色：

纸上得来终觉浅，绝知此事要躬行。

—— 陆游《冬夜读书示子聿》

外层引用

嵌套的内层引用

列表

无序列表以 -、* 或 + 开头，支持多级嵌套：

• 一级列表项
• 嵌套列表
  • 二级列表项
    • 三级列表项
• 回到一级

有序列表以 1. 开头，序号会自动递增：

1. 安装依赖
2. 编写内容
3. 构建发布

任务列表是 GitHub 风格的勾选框，适合列待办：

• 写完基础语法
• 写完代码块扩展
• 等待读者反馈

表格

表格用 | 分隔列，第二行声明对齐方式（:--- 左对齐、:---: 居中、---: 右对齐）：

图片

图片语法为 ![替代文本](图片地址)。本地图片放在文章目录中（<slug>/index.md 旁边的 01-xxx.png 等），构建时经 astro:assets 自动优化并生成响应式尺寸；远程图片直接写 URL 即可。正文中的图片都可以点击，在灯箱里放大查看：

本地图片的写法示例：

![release-it 生成版本号的效果](./01-release-version-changelog.png)

分割线

三个及以上的 -、* 或 _ 独立成行即可生成分割线：

代码块

代码块用三个反引号包裹，声明语言后由 Shiki 高亮，自动跟随 Light / Dark 双主题，右上角还会出现复制按钮：

const greeting = "你好，世界";
console.log(greeting);

文件名徽章

在语言标识后追加 file=文件名，代码块左上角会显示文件名徽章：

export const hello = (name: string): string => `你好，${name}`;src/utils/hello.ts

高亮行

在行尾加 // [!code highlight] 标记需要高亮的行：

const accent = "var(--accent)"; 
const normal = "var(--foreground)";

增删标记

// [!code ++] 与 // [!code --] 分别表示新增行与删除行，常用于展示改动前后：

const oldValue = 1; 
const newValue = 2; 

词高亮

// [!code word:关键词] 会把当前代码块里所有出现的该关键词标亮：

const repo = "margin";
console.log(repo);

自建语法：链接卡片 ::link-card

::link-card 是本站自建的 remark 插件指令：独立成段写一行，构建时自动抓取（外链）或从本地 frontmatter 解析（站内链接）出标题与描述，渲染成可点击的卡片。写法有三种：

::link-card[URL]
::link-card[URL 说明文字]
::link-card[URL] title="覆盖标题" description="覆盖描述"

外链卡片

最简写法，只给一个 URL，构建时会自动抓取对方页面的标题与描述：

带说明文字的外链卡片

方括号里 URL 之后的文字作为兜底标题，抓取失败时同样可以展示：

站内文章卡片

站内链接直接解析本地 frontmatter，不发出任何网络请求：

画廊卡片

画廊与文章一样支持链接卡片：

手动覆盖标题与描述

title 与 description 参数优先级最高，适合需要精确控制文案的场景：

抓取失败时的降级卡片

外链抓取失败（超时、被拒、域名不存在）时会降级为「域名 + URL」卡片，绝不会影响构建：

自建组件：GalleryEmbed（MDX）

在 .mdx 文章里可以直接内嵌画廊（组件已由 PostDetails 全局注册，无需 import）。下面内嵌了「金沙湾」画廊的前三张照片：

参数一览：

写法示例：

<GalleryEmbed slug="jinshawan" limit={3} cols={3} />

MDX：在文章里写 JSX

.mdx 是 Markdown 的超集，除了上面的全部语法，还能直接书写 JSX 表达式、注释与元素：

一加一等于 2。

也可以给文字套上样式类，例如 等宽强调文字，或者插入 Ctrl + C 这样的键盘按键。

自动化能力一览

写完后无需任何额外配置，以下能力会自动生效：

• 目录（TOC）与标题锚点自动生成
• 标签页、RSS、sitemap 自动收录
• 站内搜索（Pagefind）构建期自动索引正文
• draft: true 的文章不会进入线上，便于发布前预览
• 文章底部自动出现上一篇 / 下一篇导航

结语

到这里，本站文章的书写语法就完整过了一遍：基础排版（标题、文字、链接、引用、列表、表格、图片、分割线）、代码块扩展（文件名徽章、高亮行、增删标记、词高亮）、自建语法（::link-card 链接卡片、GalleryEmbed 画廊内嵌），以及 MDX 的 JSX 能力。

如果还有想了解的写法，欢迎在评论区留言，我会继续补充这份指南。