Markdown 语法速查与实操案例

本站用 Jekyll，正文由 Kramdown 解析（和常见「GitHub Flavored Markdown」大部分兼容）。下面按书写顺序说明语法，并给可直接复制改写的实操案例。

1. 标题

行首用 #，数量表示级别（一般一篇文章只有一个一级标题，或用站点模板里的标题，正文从二级写起）。

写法：

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

效果： 下面就是真实渲染（本页下文同理）。

三级标题示例

四级标题示例

2. 段落与换行

• 空一行分隔段落。
• 行末两个空格再换行 → 软换行（同一段里折行）；多数时候更推荐直接新起一段（空一行），可读性更好。

写法：

第一段文字。

第二段文字。

3. 强调：粗体、斜体、删除线

实操： 标出术语与结论，例如：本文默认使用 **Kramdown** 解析。

4. 列表

无序列表（-、*、+ 均可，同一列表统一一种）：

- 第一项
- 第二项
  - 子项（缩进 2 或 4 个空格）
  - 子项
- 第三项

有序列表（数字 + . + 空格）：

1. 先写需求
2. 再改文档
3. 最后提交

实操： 写一篇「今日待办」：

## 今日待办

1. 整理 Markdown 笔记
2. 推送 Git

- [ ] 未勾选（若站点启用任务列表语法时；纯 Kramdown 可能按普通列表显示）

说明：GitHub 上的「勾选框」依赖 GFM；本地 Jekyll 是否显示为复选框取决于解析器与主题。写作时仍可把 - [ ] 当作书写习惯。

5. 链接与图片

行内链接： [文字](地址 "可选标题")
示例：[Jekyll 官网](https://jekyllrb.com/)

引用式链接（正文更干净，链接集中放在文末）：

常用搜索引擎是 [DuckDuckGo][ddg]。

[ddg]: https://duckduckgo.com/ "DuckDuckGo"

图片： ![替代文字](图片地址)。替代文字在图片加载失败或读屏时有用。

本站图片（Jekyll）建议：

![说明]({{ '/assets/img/example.png' | relative_url }})

这样无论 baseurl 是否为空，路径都正确。

6. 行内代码与代码块

行内代码： 用反引号包裹 `npm install`。

围栏代码块： 三个反引号 + 语言名（可选），再三个反引号结束：

```javascript
function hello() {
  console.log('Hello');
}
```

注意： 若代码块里本身要出现三个反引号，外层可用四个反引号包起来，或缩进 4 格写成缩进代码块（Kramdown 支持）。

实操： 记录一条终端命令：

本地预览本站：

```bash
bundle exec jekyll serve
```

7. 引用

行首 >，可多行、可嵌套：

> 这是一段引用。
>
> > 嵌套引用

这是一段引用。

嵌套引用

8. 分隔线

在通用 Markdown 里，单独成行、上下留有空白时，一行只有三个短横、连续星号或下划线（常见写法见下方示例）往往会被解析成横向分隔线。本站文章约定用标题分节，正文里不单独插分隔线，避免版面碎、也避免和正文里的其它 ---（例如 YAML front matter）混淆。

若在其它文档里需要分隔线，把示例放在围栏代码块里即可，例如：

上一节结束

---

下一节开始

9. 表格（Kramdown）

用 | 分隔列，第二行用 |---| 画分隔线：

| 语法   | 说明     |
|--------|----------|
| `#`    | 标题     |
| `**`   | 粗体     |

10. 转义与 HTML

• 需要显示 *、`、# 等控制字符时，前面加 反斜杠 \，如 \*。
• Markdown 里可直接写部分 HTML（视安全策略而定），例如 <kbd>Ctrl</kbd>+<kbd>C</kbd>：Ctrl+C。

实操案例：一篇「学习笔记」最小模板

把下面整段保存为 .md 文件，在 VS Code / Cursor 里预览，或放进 _posts 里改成合法 front matter 即可当文章用：

---
layout: post
title: "2026-04-05 学习笔记"
date: 2026-04-05 15:00:00 +0800
slug: study-note-example
categories: 笔记
---

## 今日目标

- [x] 弄清 Markdown 列表与代码块
- [ ] 练习 `git commit` 写好说明

## 要点摘录

> 先 **粗体** 标重点，再用列表展开。

1. 段落之间要**空行**。
2. 图片路径在 Jekyll 里用 `relative_url` 更稳。

## 命令备忘

```bash
bundle exec jekyll build
```

## 参考链接

- [Kramdown 语法](https://kramdown.gettalong.org/syntax.html)

（若真要发布，请改 title / date / slug，避免与已有文章冲突。）

小结

多写、多预览（编辑器 Markdown 预览或 Jekyll serve），比背表格更快。若你使用 Obsidian、Typora 等工具，快捷键会帮你插入这些符号，底层仍是同一套语法。