你的身影已远离了我的梦境。

这篇文章用来记录博客写作时常用的 Markdown / Jekyll 写法。

很多语法平时看起来简单，真正写文章时又总会忘一点：图片怎么控制宽度，代码块怎么标语言，表格怎么对齐，列表嵌套怎么缩进。

所以留一篇样例文章，写博客时直接回来复制。

一、文章头信息

每篇文章开头都需要写 front matter，也就是被 --- 包住的这一段。

---
layout: post
title: 文章标题
date: 2026-01-01
permalink: "/2026/01/example/"
tags: 笔记
---

常用字段说明：

如果文章已经发布过，后面改文件名时最好保留 permalink，避免旧链接失效。

二、标题

Markdown 使用 # 表示标题层级。

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

博客正文里一般从 ## 开始比较合适，因为文章标题已经由模板渲染出来了。

三、链接

写法：

[劉清揚的博客](http://yuqianglianshou.com)

效果：

劉清揚的博客

如果直接写网址，一般也能显示，但推荐用上面的写法，文字更干净。

四、图片

普通图片：

![头像](/images/avatar.webp)

控制宽度：

![头像](/images/avatar.webp){:width="40%"}

效果：

这里的 40% 是相对于正文区域宽度。通常只设置 width 就够了，高度会按图片比例自动变化。

如果同时写 height，图片可能会被拉伸，不推荐。

五、图片并排

Markdown 默认一张图占一行，如果想让两张图片并排，可以直接写 HTML。

<div style="display:flex; gap:16px; align-items:flex-start;">
  <img src="/images/avatar.webp" alt="头像一" style="width:30%;" />
  <img src="/images/avatar.webp" alt="头像二" style="width:30%;" />
</div>

效果：

如果是移动端截图，宽度可以写 30% 到 45%。
如果是横向截图，一般写 80% 或 100%。

六、加粗、斜体、删除线

加粗：

**山脚人多，我们山顶见。**

效果：

山脚人多，我们山顶见。

斜体：

*读书，什么时候都不晚。*

效果：

读书，什么时候都不晚。

加粗并斜体：

***我会在这个世界美丽地挣扎到底。***

效果：

我会在这个世界美丽地挣扎到底。

删除线：

~~这句话不要了。~~

效果：

这句话不要了。

七、引用

写法：

> 我会在这个世界美丽地挣扎到底。

效果：

我会在这个世界美丽地挣扎到底。

多行引用：

> 第一行。
> 第二行。
> 第三行。

效果：

第一行。
第二行。
第三行。

八、行内代码和代码块

行内代码适合写命令、文件名、变量名。

运行 `bundle exec jekyll serve` 启动本地博客。

效果：

运行 bundle exec jekyll serve 启动本地博客。

多行代码用三个反引号包起来，最好带上语言名称。

```bash
npm install -g ionic
npm install -g node-sass
```

效果：

npm install -g ionic
npm install -g node-sass

JavaScript 示例：

const siteName = '劉清揚的博客';
console.log(siteName);

九、有序列表

写法：

1. 打开终端。
2. 进入博客目录。
3. 运行本地服务。
4. 打开浏览器预览。

效果：

1. 打开终端。
2. 进入博客目录。
3. 运行本地服务。
4. 打开浏览器预览。

建议使用 1. 2. 3. 这种写法，不要写成中文顿号或括号。

十、无序列表

写法：

- 截图：command + shift + 4
- 显示隐藏文件：command + shift + .
- 强制退出应用：command + option + esc

效果：

• 截图：command + shift + 4
• 显示隐藏文件：command + shift + .
• 强制退出应用：command + option + esc

十一、嵌套列表

嵌套列表最容易乱。

关键是：子级列表前面缩进两个或四个空格。

1. 测试文字 1
   - 测试文字 1-1
   - 测试文字 1-2
2. 测试文字 2
   - 测试文字 2-1
     - 测试文字 2-1-1
     - 测试文字 2-1-2
   - 测试文字 2-2

效果：

1. 测试文字 1
   • 测试文字 1-1
   • 测试文字 1-2
2. 测试文字 2
   • 测试文字 2-1
     • 测试文字 2-1-1
     • 测试文字 2-1-2
   • 测试文字 2-2

如果列表里面要插入代码块，代码块也要跟着缩进。

1. 安装依赖

   ```bash
   npm install
   ```

2. 启动项目

   ```bash
   npm run dev
   ```

十二、表格

写法：

| 名称 | 说明 | 示例 |
| :--- | :---: | ---: |
| 左对齐 | 冒号在左边 | `:---` |
| 居中 | 两边都有冒号 | `:---:` |
| 右对齐 | 冒号在右边 | `---:` |

效果：

注意：

1. |、-、: 之间多余空格会被忽略。
2. 第二行控制对齐方式。
3. :--- 表示左对齐。
4. :---: 表示居中。
5. ---: 表示右对齐。

十三、换行和分隔线

普通换行：

第一行后面加两个空格。  
第二行就会另起一行。

效果：

第一行后面加两个空格。
第二行就会另起一行。

分隔线：

---

效果：

如果只是想留出很大空白，可以用 <br/>，但不建议滥用。

<br/>
<br/>

十四、指定字体

有时候想临时指定字体，可以写 HTML。

<font face="楷体">我是主角，怎么能死？</font>

效果：

不过这种写法不建议大量使用。

更推荐在站点 CSS 里统一控制字体，文章里只负责内容。

十五、常用写作模板

技术记录可以用这个结构：

## 背景

为什么要做这件事。

## 问题

遇到了什么问题。

## 过程

怎么排查，怎么尝试。

## 解决

最终怎么解决。

## 总结

以后遇到类似问题要注意什么。

项目介绍可以用这个结构：

## 项目地址

GitHub 地址、线上地址。

## 这个项目解决什么问题

写清楚目标。

## 怎么使用

写给第一次打开的人。

## 技术实现

写给以后回头维护的自己。

## 后续优化

记录可以继续做的方向。

写在最后

Markdown 最重要的不是语法多复杂，而是结构清楚。

标题负责分层，列表负责梳理，代码块负责保存可执行信息，图片负责展示结果。

文章写得清楚，以后的自己回来看的时候，才不会像考古。