本站支持的 Markdown 语法速查

写文章只需要会 Markdown。这篇把本站实际支持的语法和渲染效果列全，写完新文章对照着改就行。

一、frontmatter（每篇必填）

文件开头两行 --- 之间的部分叫 frontmatter，是文章的元信息：

字段	必填	说明
title	是	文章标题，最多 120 字
description	是	一句话摘要，列表、搜索结果、分享卡片都用它
date	是	发布日期，写成 2026-01-08 即可
tags	否	标签数组，例如 [Astro, 建站]，会聚合到标签页
updated	否	最后更新日期，填了会在文末显示
draft	否	写 true 就是草稿：本地能看，构建产物里没有

提示：字段名写错或者漏了必填项，构建会直接失败并告诉你是哪个文件， 不会静默上线一篇缺摘要的文章。

二、正文语法

强调与行内元素

粗体、斜体、删除线、行内代码、普通链接、 以及自动识别网址的 https://astro.build。

键盘按键可以写成 Ctrl + Shift + P 这种样式。

列表

无序列表：

• 第一项
• 第二项
  • 嵌套一层
  • 再嵌套一层
• 第三项

有序列表：

1. 先在本地写好 Markdown
2. 运行 npm run dev 预览
3. 提交推送，自动上线

任务列表：

• 搭好站点骨架
• 配好 RSS 与站点地图
• 换成自己的头像和简介
• 写满十篇文章

引用

引用适合放结论、摘录或者别人的话。 支持多行，也支持里面再放列表：

• 像这样
• 或者这样

代码块

带上语言名就会自动高亮，右上角还有复制按钮：

// 计算阅读时长：中文按字、英文按词
export function readingMinutes(text) {
  const cjk = (text.match(/[\u4e00-\u9fff]/g) ?? []).length;
  return Math.max(1, Math.round(cjk / 350));
}

npm run dev      # 本地预览 http://localhost:4321
npm run build    # 生成静态文件到 dist/
npm run check    # 校验链接、SEO、构建产物

行内代码适合写命令或变量名，例如 npm run build。

表格

左对齐	居中	右对齐
写法	:---:	---:
效果	居中	右对齐

表格太宽时可以在手机屏幕上左右滑动，不会撑破页面。

图片

把图片放进 public/images/ 目录，然后用绝对路径引用：

![图片说明](/images/我的截图.png)

下面这张是内置的占位头像（/avatar.svg）。SVG 没有固有像素尺寸，直接用 Markdown 图片语法会被拉满整栏， 所以这里用 HTML 标签限定宽度——换成自己的照片时把它替换掉即可：

分隔线

三个短横线就是一条分隔线：

---

三、脚注

脚注用来放补充说明，不影响正文阅读节奏¹。

四、写作之外的三件事

1. 标签别超过三个：太多了等于没有分类；
2. 摘要写具体：列表里只显示摘要，不要让读者点进去才知道文章讲什么；
3. 改完自己的旧文章就更新 updated：读者和搜索引擎都能看到这个变化。

需要更复杂的排版（比如在文章里嵌图表、嵌入交互组件）时，可以把 .md 换成 MDX—— 装一个 @astrojs/mdx 集成就能在 Markdown 里直接写组件，具体见 Astro 官方文档。

Footnotes

1. 这是脚注内容，会自动收在文末。鼠标悬停或点击编号可以跳转。 ↩