Markdown 写作语法完全手册（实操预览版）

📖 Markdown 写作语法完全手册

本文与《Hexo Markdown 写作语法完全手册.docx》配套 —— 每一个语法都有对应实例，可直接预览效果

一、基础排版语法

1.1 段落与换行

这是第一段文字。你在这里可以写任意长度的内容，只要中间不空行，它们都属于同一个段落。哪怕你在编辑器里换了一行（只按一次回车），渲染出来还是同一段，文字会自动连在一起。

这是第二段。上面空了一行（两个连续回车），所以这是一个新段落。

这是第一行。
这是第二行（用 <br> 标签强制换行，不会产生段落间距）。

这是第一行。
这是第二行（行末加两个空格再回车，效果同 <br>，也是软换行）。

💡 核心： 两个回车（空行）= 新段落。一个回车 = 仍在同一段。

💡 强制换行不换段： 行末加两个空格 或 用 <br> 标签。

1.2 标题（6 级）

一级标题（最大）

二级标题

三级标题

四级标题（正文常用）

五级标题
六级标题（最小）

💡 # 号越多标题越小。# 后加空格再写标题文字。正文最常用的是 ## 和 ###。

1.3 文字强调

效果 语法
这是加粗文字 **文字**
这是斜体文字 *文字*
这是加粗+斜体 ***文字***
这是删除线文字 ~~文字~~

💡 加粗用双星号，斜体用单星号。可以叠加。

1.4 行内代码

这是一段正文，中间夹着 console.log("hello") 这行代码，非常清晰。

💡 用单个反引号（键盘 Esc 下面那个键）包裹行内代码。

1.5 分隔线

上面是三个 - 的分割线。

上面是三个 * 的分割线。

1.6 列表

无序列表

  • 项目一
  • 项目二
    • 子项目（前面两个空格缩进）
    • 子项目二
  • 项目三

有序列表

  1. 第一步：安装 Node.js
  2. 第二步：安装 Hexo
  3. 第三步：初始化博客

任务列表

  • 待办事项：安装安知鱼主题
  • 已完成：搭建 Hexo 博客框架
  • 已完成：配置 Git 密钥
  • 待办事项：绑定自定义域名

💡 任务列表需要主题支持 hexo-renderer-markdown-it。

1.7 引用

这是一段引用文字。引用可以用于标注名言、提示信息、参考资料等。

这是一段多行引用。
它跨越了多行，
但仍然属于同一个引用块。

空一行写新内容还是在引用里。

这是嵌套引用——在引用里面再引用一层。

这是第三层嵌套。

两个回车就能退出引用。

1.8 链接与图片

这是一个超链接，点我去 GitHub

图片占位

💡 图片比链接多一个感叹号 !。

1.9 表格

基本表格

姓名 年龄 职业
张三 25 程序员
李四 30 设计师
王五 28 产品经理

对齐方式

左对齐（默认） 居中对齐 右对齐
Apple 🍎 $1.00
Banana 🍌 $0.50
Cherry 🍒 $2.00

💡 第二行的冒号控制对齐：:--- 左，:---: 中，---: 右。

二、代码块

2.1 Python 代码

1
2
3
4
5
6
7
8
9
10
11
def fibonacci(n):
    """生成斐波那契数列"""
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result

print(fibonacci(10))
# [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

2.2 JavaScript 代码

1
2
3
4
5
const greet = (name) => {
  return `Hello, ${name}! 欢迎来到 Hexo 博客。`;
};

console.log(greet('小禾'));

2.3 Bash / Shell 命令

1
2
3
4
5
6
7
8
# 新建文章
hexo new "我的文章标题"

# 本地预览
hexo clean && hexo server

# 部署上线
hexo clean && hexo generate && hexo deploy

2.4 HTML 代码

1
2
3
4
5
6
7
8
9
10
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>Hexo 博客</title>
</head>
<body>
    <h1>Hello World!</h1>
</body>
</html>

2.5 YAML 配置

1
2
3
4
deploy:
  type: git
  repository: git@github.com:lqh323-glitch/lqh323-glitch.github.io.git
  branch: main

2.6 JSON 数据

1
2
3
4
5
6
{
  "name": "Hexo",
  "version": "7.3.0",
  "description": "A fast, simple & powerful blog framework",
  "author": "Tommy Chen"
}

2.7 Diff 代码差异

1
2
3
4
5
6
7
8
function calculateTotal(items) {
-   const taxRate = 0.1;
+   const taxRate = 0.13;
    return items.reduce((sum, item) => {
-       return sum + item.price;
+       return sum + item.price * (1 + taxRate);
    }, 0);
}

💡 绿色背景的是新增行（+），红色背景的是删除行（-）。

三、HTML 混写高级排版

3.1 字体颜色

  • 红色文字 — 强调 / 警告
  • 道奇蓝文字 — 链接风格
  • 绿色文字 — 成功 / 通过
  • 橙色文字 — 注意 / 提示
  • 紫色文字 — 个性点缀
  • 灰色文字 — 次要 / 补充

💡 颜色值可以用英文名（red, blue, green）或十六进制色值（#FF0000）。

3.2 字体大小

size=1（最小）

size=2

size=3（默认大小）

size=4

size=5（大标题）

size=6

size=7（最大）

3.3 字体 + 颜色 + 大小组合

黑体 + 绿色 + 5号大小

微软雅黑 + 深灰 + 4号

3.4 文字背景色

黄色背景 —— 高亮强调

浅蓝背景 —— 信息提示

浅绿背景 —— 成功标识

金色背景 —— 重要内容

3.5 文字居中 / 居右

这段文字居中显示

这段文字居右显示

🎯 居中 + 红色 + 20px + 加粗 —— 适合标题

居中 + 灰色 + 小字 —— 适合副标题或注释

3.6 首行缩进

  这是用两个半角空格（&ensp;）做的首行缩进效果。在中文写作中，段首空两格是常见的排版习惯。这里是正文内容，你可以看到开头的两个字是缩进去的。

  这是用两个全角空格（&emsp;）做的首行缩进效果。全角空格比半角更宽一些，可以根据需要选择。

3.7 键盘按键

按下 Ctrl + C 复制，按下 Ctrl + V 粘贴。

在 VSCode 中，按 F5 开始调试，按 Ctrl + Shift + P 打开命令面板。

💡 <kbd> 标签会渲染成键盘按键样式。

3.8 折叠面板

🔍 点击展开：查看 Hexo 项目目录结构详解 
1
2
3
4
5
6
7
8
9
10
blog-demo/
├── _config.yml        # 博客全局配置文件（最重要）
├── package.json       # 项目依赖信息
├── scaffolds/         # 文章模板目录
│   ├── post.md        # 普通文章模板
│   └── page.md        # 独立页面模板
├── source/            # 所有源文件
│   └── _posts/        # 你的文章都放在这里
├── themes/            # 主题目录
└── public/            # hexo g 生成的静态文件（自动生成，不用手动修改）
  • _config.yml — 整个博客的配置都在这里
  • source/_posts/ — 你写的每一篇文章都存这里
  • themes/ — 主题安装位置，可以放多个主题切换
  • public/ — 部署时上传的就是这个文件夹的内容

💡 点击展开：写博客的 5 个小建议
  1. 先列大纲再填充 — 把标题层级搭好，再往每段里填内容，不容易跑偏
  2. 多用小标题分段 — 读者浏览体验好，也能快速找到感兴趣的部分
  3. 代码必须加注释 — 不是给自己看的，是给读者看的
  4. 配图很重要 — 一张好图胜过千言万语
  5. 持续更新打磨 — 博客是活的，回头修改、补充、完善

3.9 带颜色的分割线

默认分割线：

红色分割线

蓝色粗分割线

灰色虚线分割线

四、图片处理

4.1 Markdown 基本插入

山水风景

4.2 HTML 控制尺寸

缩小到 300px 宽

上面同一张图，缩小到 300px 宽。

4.3 居中 + 圆角 + 阴影（最常用）

居中带圆角和阴影的图片

💡 border-radius 控制圆角大小，box-shadow 控制阴影。这是最推荐的卡片式图片展示。

4.4 带标题的图片（figure）

示例图片
▲ 上图：来自 Lorem Picsum 的随机风景图，演示 figure + figcaption 用法

五、Hexo 标签插件

💡 以下标签是 Hexo 核心内置插件（非主题专属），在默认 landscape 主题下也能使用。

5.1 引用块 blockquote

这是一段使用 Hexo 标签插件的引用内容。与标准 Markdown 引用不同，它可以带作者和来源信息。

5.2 代码块 codeblock（带标题）

一个简单的函数
1
2
3
def say_hello(name):
    """向用户问好"""
    return f"你好，{name}！欢迎来到我的博客。"

5.3 iframe 嵌入

语法：{% iframe URL 宽度 高度 %} 或直接用 HTML <iframe> 标签。

5.4 引用其他文章链接

语法格式：{% post_link 文章文件名 "显示文字" %}

作用：在文章内生成到本博客另一篇文章的超链接。例如引用本手册：{% post_link Markdown写作语法完全手册 "回到手册首页" %}

六、主题增强组件（HTML 通用版）

⚠️ 提示：{% note %}, {% cq %}, {% label %}, {% tabs %}, {% btn %} 等是 NexT / 安知鱼主题专属标签，需安装对应主题才能生效。
下面用 HTML 方式实现相同效果，默认 landscape 主题也能正常渲染。

6.1 提示块（HTML 模拟 Note）

📋 默认提示 — 这是一条普通信息提示框，适合一般性的说明文字。
📘 主要提示 — 这是一条主要信息，用于较为重要的内容说明。
✅ 成功提示 — 操作成功！绿色表示一切顺利。
ℹ️ 信息提示 — 这是一条信息型提示，用于补充说明或背景信息。
⚠️ 警告提示 — 请注意！这是一条警告信息，提醒你注意潜在问题。
🚨 危险提示 — 小心！这是一条危险/错误类别的提示。

💡 上面六种提示框全用 HTML <div> + style 实现，不需要安装任何主题，直接能用。

6.2 文本居中引用（HTML 模拟 centerquote）

水止无痕地，云行不计程。
到时为彼岸，过处即前生。
——《送文畅上人东游》吕温
晓看天色暮看云，行也思君，坐也思君。
——唐寅《一剪梅》

💡 上下加分割线 + 文字居中 = centerquote 效果。<div align="center"> 是核心。

6.3 文字标签（HTML 模拟 Label）

我坐在床前，望着窗外，回忆满天。生命是华丽错觉，时间是贼偷走一切。

七岁的那一年，抓住那只蝉，以为能抓住夏天。

有没有那么一种永远，永远不改变，拥抱过的美丽，都再也不破碎。让险峻岁月不能，在脸上撒野，让生离和死别都遥远，有谁能听见。

💡 用 <span> + 背景色 + 内边距即可做出标签效果。颜色随意换。

6.4 按钮 Button（HTML 版）

💡 HTML <button> 标签完全自由可控。修改 background-color / border-radius / padding 随心定制。

6.5 选项卡（折叠面板模拟 Tabs）

📂 第一页：基础介绍
这是第一个选项卡的内容。你可以在这里写任何 Markdown 内容：
  • 支持列表
  • 加粗 和 斜体
  • 行内代码
1
print("折叠面板里也可以放代码块！")
📂 第二页：对比方案
这是第二个选项卡的内容。选项卡非常适合：
  1. 对比不同方案
  2. 展示多种实现方式
  3. 不同语言的同一代码示例
📂 第三页：注意事项
这是第三个选项卡的内容。用 `
` + `` 模拟选项卡效果，所有主题都能用。

💡 open 属性让第一个面板默认展开。

💡 用 <details><summary>标题</summary>内容</details> 模拟选项卡，通用性最好。open 属性让指定面板默认展开。

6.6 FontAwesome 图标

▎ 以下需要主题引入 FontAwesome。图标名参考：fontawesome.com.cn/icons

GitHub  
Twitter  
Telegram  
Google  
YouTube



图标大小控制：

fa-lg  
fa-2x  
fa-3x  
fa-4x  
fa-5x

七、数学公式

行内公式

爱因斯坦的质能方程：$E = mc^2$

勾股定理：$a^2 + b^2 = c^2$

二次方程求根公式：$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

独立公式块

微积分基本定理：

$$
\int_{a}^{b} f(x) , dx = F(b) - F(a)
$$

巴塞尔问题：

$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$

欧拉公式：

$$
e^{i\pi} + 1 = 0
$$

高斯积分：

$$
\int_{-\infty}^{\infty} e^{-x^2} , dx = \sqrt{\pi}
$$

💡 行内公式用 $...$，独立块用 $$...$$。需在主题中开启 mathjax 或 katex。

八、文章结构技巧

8.1 文章摘要截断

下面这一行之前的内容会在主页列表中显示为摘要，点开文章才看到全部——

这里是 <!-- more --> 之后的内容，只有点进文章才能看到。

💡 这是最重要的技巧之一：控制每篇文章在首页的展示长度，给读者一个”点进去看”的理由。

8.2 页内跳转

点击 跳转到本页锚点位置 来体验页内跳转。

💡 定义锚点：<a id="anchor_name"></a>，跳转链接：[文字](#anchor_name)。

8.3 脚注

这是正文中引用脚注的位置 ^1。你可以有多个脚注引用 [^2]。

[^2]: 这是第二个脚注的内容，它更长一些。可以包含多行文字、链接，甚至可以包含代码 hexo new。

附录：速查表

你想做的 用什么语法 类别
写标题 # 标题 → ###### 标题 Markdown
分段 空一行（两个回车） Markdown
强制换行 行末两空格 或 <br> Markdown / HTML
加粗 **文字** Markdown
斜体 *文字* Markdown
删除线 ~~文字~~ Markdown
行内代码 `代码` Markdown
无序列表 - 项目 Markdown
有序列表 1. 项目 Markdown
引用 > 引用文字 Markdown
链接 [文字](URL) Markdown
图片 ![描述](URL) Markdown
分割线 --- 或 *** Markdown
表格 | 列 | 列 | Markdown
彩色文字 <font color="red">文字</font> HTML
字体大小 <font size="5">文字</font> HTML
背景色 <table><tr><td bgcolor=#XXX>文字</td></tr></table> HTML
居中 <p align="center">文字</p> HTML
居右 <p align="right">文字</p> HTML
首行缩进 &ensp;&ensp; 或 &emsp;&emsp; HTML
键盘按键 <kbd>Ctrl</kbd> HTML
折叠面板 <details><summary>标题</summary>内容</details> HTML
代码块 ```语言 ... ``` Markdown
代码差异 ```diff ... ``` Markdown
数学公式 $行内$ 或 $$独立块$$ LaTeX
摘要截断 Hexo
Note 提示 {% note 样式 %}...{% endnote %} 主题标签
选项卡 {% tabs %}...{% endtabs %} 主题标签
按钮 {% btn URL, 文字 %} 主题标签
居中引用 {% cq %}...{% endcq %} 主题标签
文字标签 {% label 样式 @文字 %} 主题标签
图标 <i class="fa fa-图标名"></i> HTML/FontAwesome
iframe {% iframe URL 宽 高 %} Hexo标签
引用文章 {% post_link 文件名 %} Hexo标签
脚注 [^1] + [^1]: 内容 Markdown
页内跳转 <a id="锚点"></a> + [跳转](#锚点) HTML

—— 全书完 ——

记住两条原则：
1. 能用 Markdown 搞定的，用 Markdown
2. Markdown 搞不定的，直接嵌 HTML