Hugo 博客写作指南（三）：Markdown 基础用法详解

2026-03-04 7 分钟 3002 字
技术教程 Hugo Markdown 写作指南 语法
Hugo 博客写作指南（三）：Markdown 基础用法详解

Hugo 博客写作指南（三）：Markdown 基础用法详解

本文是 Hugo 博客写作指南系列的第三篇，详细介绍 Markdown 语法在 Hugo 博客中的使用方法。

Markdown 是一种轻量级标记语言，易于阅读和编写，是博客写作的理想选择。本文将介绍在 ChangAn 主题中使用 Markdown 的各种技巧。

什么是 Markdown？

Markdown 由 John Gruber 于 2004 年创建，目标是让人们"使用易读易写的纯文本格式编写文档，然后转换成有效的 XHTML"。

优势：

  • ✅ 语法简单，几分钟就能学会
  • ✅ 纯文本格式，任何编辑器都能打开
  • ✅ 易读易写，专注于内容
  • ✅ 可转换为 HTML、PDF 等多种格式

基础语法

1. 标题

Markdown 使用 # 符号表示标题，# 的数量表示标题级别。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

渲染效果：

一级标题

二级标题

三级标题

四级标题

使用建议：

  • 一篇文章只使用一个一级标题（文章标题）
  • 使用二级标题划分主要章节
  • 使用三级及以下标题划分子章节
  • 避免跳过标题级别（如从 H2 直接到 H4）

2. 段落和换行

段落之间用空行分隔：

这是第一段。

这是第二段。

换行方法：

  1. 硬换行：在行尾添加两个空格，然后回车
第一行  
第二行
  1. 使用 HTML 标签：
第一行<br>
第二行

注意事项：

  • 单独的回车不会产生换行效果
  • 段落之间必须有空行

3. 文本格式化

粗体：

**粗体文本**
__粗体文本__

效果：粗体文本

斜体：

*斜体文本*
_斜体文本_

效果：斜体文本

粗斜体：

***粗斜体文本***

效果：粗斜体文本

删除线：

~~删除文本~~

效果：删除文本

下划线（使用 HTML）：

<u>下划线文本</u>

效果：下划线文本

4. 引用

使用 > 符号表示引用：

> 这是一段引用文本。
> 
> 这是引用的第二段。

效果：

这是一段引用文本。

这是引用的第二段。

嵌套引用：

> 第一层引用
> > 第二层引用
> > > 第三层引用

效果：

第一层引用

第二层引用

第三层引用

引用中包含其他元素：

> ### 引用中的标题
> 
> 这是引用内容，包含 **粗体** 和 *斜体*。
> 
> - 列表项 1
> - 列表项 2

效果：

引用中的标题

这是引用内容，包含 粗体 和 斜体。

  • 列表项 1
  • 列表项 2

5. 列表

无序列表：

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2
- 项目 3

* 也可以用星号
+ 还可以用加号

效果：

  • 项目 1
  • 项目 2
    • 子项目 2.1
    • 子项目 2.2
  • 项目 3

任务列表：

- [x] 已完成的任务
- [ ] 未完成任务
- [ ] 待办事项

有序列表：

1. 第一项
2. 第二项
3. 第三项
   1. 子项 3.1
   2. 子项 3.2

效果：

  1. 第一项
  2. 第二项
  3. 第三项
    1. 子项 3.1
    2. 子项 3.2

任务列表：

- [x] 已完成的任务
- [ ] 未完成任务
- [ ] 待办事项

效果：

  • 已完成的任务
  • 未完成任务
  • 待办事项

列表中使用其他元素：

1. **粗体项目**
   > 项目描述引用
   - 子项目 1
   - 子项目 2

2. 普通项目
   ```python
   print("代码块")


### 6. 代码

**行内代码：**
```markdown
使用 `print()` 函数输出内容。
安装命令：`pip install package-name`

效果：使用 print() 函数输出内容。

代码块：

  1. 使用缩进（不推荐）：
    def hello():
        print("Hello World")
  1. 使用代码围栏（推荐）：
```python
def hello():
    print("Hello World")
```

效果：

def hello():
    print("Hello World")

支持的语言：

```python      # Python
```javascript  # JavaScript
```java        # Java
```cpp         # C++
```go          # Go
```rust        # Rust
```bash        # Bash
```sql         # SQL
```html        # HTML
```css         # CSS
```json        # JSON
```yaml        # YAML
```markdown    # Markdown
```plaintext   # 纯文本（无高亮）

代码块特性：

  • ✅ 语法高亮
  • ✅ 一键复制按钮
  • ✅ 语言标签显示
  • ✅ macOS 风格装饰
  • ✅ 深色模式适配

7. 链接

基本链接：

[链接文字](https://example.com)

效果：链接文字

带标题的链接：

[Google](https://google.com "访问 Google")

效果：Google

相对链接：

[查看另一篇文章](/posts/other-article/)
[查看图片](/images/photo.jpg)

自动链接：

<https://example.com>
<email@example.com>

效果：https://example.com

参考式链接：

这是一个 [参考链接][1]。

[1]: https://example.com "可选标题"

8. 图片

基本语法：

![替代文字](图片路径)

效果： 默认封面

带标题的图片：

![替代文字](图片路径 "图片标题")

带尺寸的图片（使用 HTML）：

<img src="/images/photo.jpg" alt="描述" width="300">

响应式图片：

![描述](图片路径)

ChangAn 主题会自动处理为响应式。

图片最佳实践：

  • ✅ 始终添加替代文字（无障碍访问）
  • ✅ 使用相对路径
  • ✅ 优化图片大小
  • ✅ 选择合适的格式（WebP > PNG > JPG）

9. 表格

基本语法：

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| 值 1 | 值 2 | 值 3 |
| 值 4 | 值 5 | 值 6 |

效果：

列 1列 2列 3
值 1值 2值 3
值 4值 5值 6

对齐方式：

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 内容   | 内容     | 内容   |

效果：

左对齐居中对齐右对齐
内容内容内容

表格中使用其他元素：

| 名称 | 描述 | 代码 |
|------|------|------|
| Hugo | **快速**的静态网站框架 | `hugo server` |
| Markdown | *轻量级*标记语言 | - |

效果：

名称描述代码
Hugo快速的静态网站框架hugo server
Markdown轻量级标记语言-

10. 水平分割线

---
***
___

效果：

高级语法

11. 脚注

这是一段包含脚注的文字。[^1]

[^1]: 这是脚注内容。

效果：这是一段包含脚注的文字。1

12. 定义列表

术语 1
: 定义 1

术语 2
: 定义 2
: 定义 2 的另一种说法

13. 缩写

*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style Sheets

HTML 和 CSS 是网页开发的基础。

14. 数学公式

行内公式：

使用 $E = mc^2$ 计算能量。

效果：使用 $E = mc^2$ 计算能量。

块级公式：

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

15. 表情符号

这是笑脸 😀
这是火箭 🚀
这是警告 ⚠️

效果：这是笑脸 😀 这是火箭 🚀 这是警告 ⚠️

常用表情：

  • 👍 👎 - 点赞/踩
  • ✅ ❌ - 正确/错误
  • ⭐ 💡 - 星星/灯泡
  • 🔥 🎉 - 火焰/庆祝
  • 📝 📚 - 笔记/书籍

ChangAn 主题特色

代码块增强

ChangAn 主题提供了增强的代码块体验：

```python
def fibonacci(n):
    """计算斐波那契数列"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# 打印前 10 个斐波那契数
for i in range(10):
    print(fibonacci(i))
```

效果：

def fibonacci(n):
    """计算斐波那契数列"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# 打印前 10 个斐波那契数
for i in range(10):
    print(fibonacci(i))

特性：

  • 🎨 macOS 风格装饰（红黄绿按钮）
  • 🏷️ 语言标签显示
  • 📋 一键复制按钮
  • 🌓 深色模式适配
  • 📱 响应式设计

表格优化

主题对表格进行了美化：

| 功能 | ChangAn | 其他主题 |
|:-----|:-------:|:--------:|
| 响应式 | ✅ | ✅ |
| 深色模式 | ✅ | ⚠️ |
| 代码高亮 | ✅ | ✅ |
| 搜索功能 | ✅ | ❌ |

效果：

功能ChangAn其他主题
响应式✅✅
深色模式✅⚠️
代码高亮✅✅
搜索功能✅❌

写作最佳实践

1. 文章结构

# 文章标题

> 简短摘要

## 引言

介绍文章背景...

## 主要内容

### 子主题 1
详细内容...

### 子主题 2
详细内容...

## 总结

总结全文...

2. 代码示例

✅ 推荐：

```python
def greet(name):
    return f"Hello, {name}!"
```

❌ 不推荐：

    def greet(name):  # 使用缩进
        return f"Hello, {name}!"

3. 图片使用

✅ 推荐：

![项目架构图](/images/posts/project-architecture.webp)

❌ 不推荐：

![无意义文字](image.png)  # 格式不统一
![描述](https://外部链接.com/image.jpg)  # 外部链接不稳定

4. 链接使用

✅ 推荐：

参考 [Hugo 官方文档](https://gohugo.io/) 了解更多。

❌ 不推荐：

参考 https://gohugo.io/ 了解更多。  # 直接放 URL

常用工具推荐

Markdown 编辑器

  1. VS Code + Markdown 插件
  2. Typora - 所见即所得
  3. Obsidian - 知识管理
  4. Notion - 在线协作

Hugo 相关命令

# 创建新文章
hugo new posts/my-post.md

# 本地预览
hugo server -D

# 构建站点
hugo --gc --minify

# 查看配置
hugo config

小结

本文介绍了 Markdown 在 Hugo 博客中的使用方法，包括：

  • ✅ 基础语法： 标题、段落、文本格式化
  • ✅ 列表和引用： 无序列表、有序列表、引用块
  • ✅ 代码和图片： 行内代码、代码块、图片插入
  • ✅ 表格和链接： 各种表格样式、链接类型
  • ✅ 高级特性： 脚注、数学公式、表情符号

掌握这些语法，你就可以轻松写出美观的博客文章了！

上一篇： Hugo 博客写作指南（二）：hugo.toml 配置详解

下一篇： Hugo 博客写作指南（四）：ChangAn 主题特色

相关文章：

  1. 这是脚注内容。 ↩︎

版权声明

本文作者：长安

本文链接：https://changan.icecome.com/posts/hugo-writing-guide-03-markdown/