在 Jekyll 中写 Markdown：语法、方言与常见问题

Markdown 的优点不是语法多，而是纯文本本身仍然可读。真正容易踩坑的地方，往往不是粗体和列表，而是不同渲染器对扩展语法的支持并不完全一致。

本站使用 Jekyll 4 和 kramdown。GitHub README 常见的是 GFM（GitHub Flavored Markdown），其它编辑器还可能使用 CommonMark、Pandoc Markdown 或自己的扩展。复制语法前，先确认最终发布环境。

一篇 Jekyll 文章的基本结构

文件名通常使用：

YYYY-MM-DD-slug.markdown

文件顶部是 YAML Front Matter：

---
layout: post
title: 示例文章
date: 2026-07-19 10:00:00 +0800
excerpt: 用一句话说明文章内容
categories: devtools
---

Front Matter 中包含冒号、井号或特殊字符的值，建议加引号。日期应带时区，避免本地预览和线上构建出现日期偏移。

本站使用  作为摘要分隔符。它属于站点约定，不是通用 Markdown 语法。

标题

# 一级标题
## 二级标题
### 三级标题

文章模板通常已经输出页面主标题，所以正文一般从二级标题开始。标题层级应按结构递进，不要因为字号好看直接从二级跳到四级。

段落与换行

空一行表示新段落。普通换行在很多 Markdown 方言中仍会合并为同一段。

如果确实需要硬换行，可以在行尾添加两个空格，或使用 <br>。长文写作更推荐分段，而不是大量手工换行。

强调

*斜体*
**粗体**
~~删除线~~
`行内代码`

下划线并不是标准的“下划线语法”。_text_ 通常表示斜体。需要下划线时只能使用 HTML，并先确认站点样式和可访问性是否合适。

列表

- 第一项
- 第二项
  - 子项

1. 第一步
2. 第二步

子列表至少缩进两个到四个空格，具体取决于渲染器。混用 Tab 和空格容易让结构在不同编辑器中表现不一致。

任务列表属于 GFM 扩展。kramdown 是否渲染成复选框取决于站点配置和插件，不应默认所有环境都支持：

- [ ] 未完成
- [x] 已完成

链接与图片

[Python 文档](https://docs.python.org/3/)
![图片替代文本](/images/example.png)

图片的替代文本不是装饰，它会在图片加载失败时显示，也帮助使用读屏软件的读者理解内容。不要把所有图片都写成空的 ![](...)。

站内链接可以使用绝对路径，也可以通过 Liquid 的 relative_url 过滤器适配 baseurl。如果站点将来可能部署在子路径，后者更稳妥。

引用

> 第一层引用
>
> 仍然属于同一段引用。

引用应当用于原话或明确的摘录，不要只拿来做彩色提示框。引用外部内容时注明作者和来源，并控制篇幅。

代码

短代码使用行内反引号。多行代码可以使用围栏代码块，也可以使用 Jekyll 的 highlight 标签：

{% highlight python %}
def hello(name: str) -> str:
    return f"Hello, {name}"
{% endhighlight %}

代码块应标明语言，便于高亮和辅助工具识别。示例尽量做到可运行，并说明依赖、输入和失败边界。

Markdown 中展示 Liquid

Jekyll 会在 Markdown 转换前处理 Liquid。即使 Liquid 标签写在代码块里，也可能先被执行。要原样展示 {{ ... }} 或 {% ... %}，可用 raw 包裹：

{{ page.title }}

这是 Jekyll 写作中比 Markdown 本身更常见的坑。

表格

| 名称 | 作用 |
| --- | --- |
| kramdown | Markdown 渲染器 |
| Liquid | Jekyll 模板语言 |

Markdown 表格适合字段少、内容短的数据。单元格里放长段落、复杂列表或大量代码时，移动端阅读体验很差，通常改成小节更清楚。

脚注

kramdown 支持脚注：

这是一段需要补充说明的文字。[^note]

[^note]: 脚注内容。

脚注属于扩展语法，在 CommonMark 基础规范中并非必选能力。文章要发布到多个平台时应实际预览。

数学公式、流程图和 Mermaid

数学公式、sequence、flow、Mermaid 都不是 Markdown 基础语法。它们需要页面额外加载 MathJax、KaTeX、Mermaid 或对应插件。

写作时应区分两件事：

编辑器能够预览；
最终站点能够构建和展示。

只有前者成立时，发布后仍可能显示为普通代码块。新增扩展语法前，应先在站点构建产物里验证。

HTML 可以用，但要克制

kramdown 允许在 Markdown 中混用 HTML。本站的图片说明、资料卡片等样式会用到这一能力。

使用 HTML 时注意：

属性值正确转义；
不重复页面已有的一级标题；
交互元素具备键盘操作与可访问标签；
外链使用 rel="noopener"；
不为简单文本结构引入大段不可维护的内联样式。

发布前检查

Front Matter 能被 YAML 正确解析；
标题层级连续；
代码块和 Liquid 标签成对闭合；
站内链接、图片路径有效；
手机宽度下表格和代码不会破坏页面；
执行 bundle exec jekyll build，检查构建警告；
打开生成后的页面，而不只看编辑器预览。

Markdown 负责让正文保持简单，Jekyll、kramdown 和站点样式负责把它变成网页。把这几层分清，语法问题通常就容易定位。