蓝泡手记

Markdown 写作指南 —— 一篇自说明的教程

2026年6月27日
教程Markdown

本文既是一份 Markdown 使用指南，也是一篇「自说明」的示范——你读到的每一个排版效果，正是由它自己的源码渲染而来。换句话说：这篇博客在教你怎么写出它自己这样的博客。

本文档尤其面向本站的写作环境（marked 解析器 + GFM 扩展 + 本站 CSS 样式），部分效果可能与 GitHub、Notion 等平台略有差异。

前言：什么是 Markdown

Markdown 是一种轻量级标记语言，由 John Gruber 在 2004 年创建。它的设计哲学很简单：

用易读易写的纯文本格式编写文档，再转换为结构化的 HTML。

你不需要像 Word 那样选中文字再点按钮，也不用写满屏的 <h2> 标签。你只需要在文字前后加一点简单的符号，剩下的交给工具。

在这篇文章里，你将看到本站支持的每一种 Markdown 语法，并且——正因为你在读的这篇文章本身就是用 Markdown 写的——你看到的就是你将来写出来的效果。

标题：组织文章结构

Markdown 用 # 开头表示标题。# 的数量代表标题级别，从一级到六级。

实际上，本站的文章页面已经用 <h1> 显示了 front matter 里的 title，所以正文中建议从二级标题 ## 开始，这样层级更清晰。

二级标题前面会自动出现一条蓝色竖线（本站 CSS 的装饰），像你现在看到的这样。

三级标题

三级标题没有蓝色装饰线，但字号比正文大，适合作为二级标题下的子话题。

四级标题

四级标题更小一些，和正文字号接近，但仍保留加粗。一般到四级就够用了，再往下意义不大。

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

段落与换行

Markdown 中，段落就是连续的文字行。空一行即开始新段落。

这一句和上一句之间空了一行，所以它是一个新的段落。浏览器会给段落之间加上合适的间距，保证阅读舒适。

如果你想在同一段落内换行，
在行末加两个空格再回车即可（就像这两行之间那样）。不过在大多数写作场景下，让段落自然断开就很好。

文字样式：加粗、斜体、删除线

Markdown 支持几种行内文字样式：

  • 加粗 用两个星号 **加粗**
  • 斜体 用一个星号 *斜体*
  • 粗斜体 用三个星号 ***粗斜体***
  • 删除线 用两个波浪号 ~~删除线~~（GFM 扩展语法）
  • 行内代码 用反引号 `行内代码`

本站的行内代码会被渲染为红色等宽字体，带一个浅灰背景，非常醒目。适合在段落中提及变量名、命令、文件名等。

链接与图片

链接

链接的语法是 [显示文字](URL)：

这是一个指向 霞鹜文楷字体项目 的链接。本站的链接默认是蓝色，鼠标悬停时会出现下划线。

如果你要链接到本站内的其他文章，直接用相对路径：

图片

图片的语法和链接类似，前面加一个 !：

![图片描述](图片URL)

图片会自动加上圆角和阴影，居中显示，宽度不会超出阅读区域。

蓝泡的占位图

如果你有本地图片，可以放到 assets/ 目录，引用时用 /图片名.png 即可。

引用：blockquote

引用块适合展示引言、摘录或需要突出的文本。语法是在行首加 >：

简单是终极的复杂。 —— 达·芬奇（或者某位喜欢这句话的人）

多段引用只需要在空行也加上 >：

第一段引用文字。

第二段引用文字，和上一段之间有空行但 > 不能断。

本站的引用块有蓝色左边框 + 浅灰背景，视觉上很安静，适合放题记或注释。

列表

无序列表

用 -、* 或 + 开头：

  • 第一项
  • 第二项
    • 嵌套的子项（两个空格缩进）
    • 又一个子项
  • 第三项

有序列表

用数字 + 英文句点开头：

  1. 准备食材
  2. 热锅倒油
  3. 翻炒出锅
    1. 子步骤也可以有序号
    2. 依然是缩进两个空格

数字本身不需要连续，Markdown 会自动编号——但建议写对，方便在源码中阅读。

任务列表（GFM 扩展）

任务列表适合做待办清单，本站支持：

  • 搭建博客框架
  • 写好样式
  • 写一篇 Markdown 使用指南
  • 再多写几篇文章

勾选状态在渲染后会变成可读的复选框样式。

代码块

行内代码

在段落中引用 const blog = "蓝泡手记" 这样的代码片段，用单个反引号包裹即可。本站行内代码呈红色等宽字体。

围栏代码块

用三个反引号包裹多行代码，并指定语言名称（可选，但推荐加上以便阅读器做语法高亮）：

// 这是本站构建脚本的核心逻辑
const { marked } = require('marked');
const posts = loadPosts();

for (const post of posts) {
  const html = marked.parse(post.body, { gfm: true });
  fs.writeFileSync(`dist/posts/${post.slug}.html`, wrapLayout(html));
}
console.log(`✅ 构建完成，共 ${posts.length} 篇文章`);

# 一段 Python 示例
def greet(name):
    return f"你好，{name}！"

print(greet("蓝泡"))

# 终端命令
npm run build    # 构建博客
npm run dev      # 开发模式（监听变化）

# 甚至可以在代码块里展示 Markdown 本身
**加粗** 和 *斜体* 都不会被渲染，因为它们在代码块里。

本站代码块有浅色背景 + 细边框，等宽字体，横向溢出时可滚动。

表格（GFM 扩展）

表格是 GFM 的扩展语法。用管道符 | 分隔列，用 ---|--- 分隔表头与表体：

特性 语法 本站支持
标题 ## 二级 ✅
加粗 **文字** ✅
删除线 ~~文字~~ ✅
任务列表 - [ ] ✅
表格 |列1|列2| ✅
脚注 [^1] ❌ marked 默认不支持

冒号可以控制列的对齐方向：

左对齐（默认） 居中对齐 右对齐
内容 内容 1234
更长的内容 中 56

分割线

三个或更多的 ---、*** 或 ___ 单独成行会产生一条分割线：

上面这条浅灰色的线就是分割线。它很适合用来分隔文章的不同部分——比如正文和附录、不同的话题之间。

⚠️ 注意：在 front matter 之后，不要在正文开头紧接着写 ---，否则会被误解析。建议至少先写一段文字再用分割线。

其他实用语法

转义字符

如果你想显示一个 Markdown 符号本身而不触发渲染，在前面加反斜杠 \：

  • \*不是斜体\* → *不是斜体*
  • \ 代码块 ` → ` 代码块 `
  • \\ → \
  • \# → #

HTML 标签

marked 默认允许在 Markdown 中嵌入原始 HTML，本站也是如此。你可以用它来做一些 Markdown 做不到的事：

点击展开：这里藏了一段 HTML

这一段被 <details> 标签包裹，适合放附加说明或剧透内容。纯 Markdown 做不到的折叠效果，用一点 HTML 就能实现。

Ctrl + S 这种键盘按键样式也是用 <kbd> 标签实现的。

不过大多数时候你不需要用到 HTML，Markdown 本身已经足够表达。

本站专属写作建议

Front matter 必须写

每篇 .md 文件开头必须包含 front matter：

---
title: 文章标题
date: 2026-06-27
excerpt: 一句话摘要，会显示在首页文章列表
tags: [标签1, 标签2]
---
  • title：必填，会作为 <h1> 和浏览器标签页标题
  • date：必填，格式 YYYY-MM-DD，文章按日期倒序排列
  • excerpt：可选但推荐写，展示在首页文章卡片的标题下方
  • tags：可选，数组格式，会渲染为首页的标签圆角小方块

文件名就是 URL

posts/hello-world.md → /posts/hello-world.html

文件名用英文连字符，不要有空格。about.md 是保留名，不会被当作文章。

利用本站的样式特性

写作时可以善用本站 CSS 已经帮你做好的效果：

  • 引用块放题记、注释、说明——蓝色左边框很优雅
  • 代码块指定语言——虽然没有 JS 语法高亮，但源码中写清楚语言名对可读性有帮助
  • 二级标题有蓝色装饰线——用它作为文章的主要分段标记
  • 表格适合做对比、罗列——本站的表格有完整的边框和浅色表头背景

文章长度建议

没有硬性规定，但作为参考：

  • 一篇技术文章 ~1500–3000 字比较舒适
  • 一篇随笔 ~800–2000 字
  • 太短没有信息量，太长可以拆成系列

预览与发布

# 开发模式：监听文件变化，自动重新构建
npm run dev

# 配合静态服务器预览
npx serve dist

在浏览器里打开 http://localhost:3000（或 serve 给出的端口），每次保存 .md 后刷新页面就能看到效果。确认无误后：

npm run build     # 构建生产版本
# 然后上传 dist/ 到服务器

以上就是本站 Markdown 写作的完整指南。这篇文章本身的源码就是最好的参考——你可以打开 posts/markdown-guide.md，对照着源码和渲染效果来学习。

写作愉快，期待看到你的文字。 🎈