2026年10月16日

21 min

Chinese

markdown /

博客 /

写作技巧

Markdown 写作与高级样式实用教程

从基础语法到图片尺寸、对齐、多图网格、表格、提示框、折叠内容和任务列表，整理一套可以直接复制的 Markdown 写作模板。

views | comments

前言#

Markdown 的基础语法很简单，但真正写博客时，常常还会遇到图片大小、图片对齐、多图并列、表格美化、提示框和折叠内容等问题。本文把常用写法集中整理在一起，代码可以直接复制到文章中，再替换文字和图片路径即可。

本文会区分三种写法：

标准 Markdown：跨平台最稳定；
Markdown 扩展：某些编辑器支持，换平台前要测试；
HTML/CSS：控制能力最强，适合本站这种自建博客。

这篇文章使用《Ubuntu 常用命令大全》的封面作为演示图片。相同图片重复出现只是为了展示排版效果，实际写作时换成自己的图片即可。

一、Markdown 基础语法#

1. 标题#

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

markdown

正文中建议从 ## 开始写，因为文章标题已经由 frontmatter 的 title 生成。

2. 强调、删除线和行内代码#

**加粗文字**

*斜体文字*

~~删除线文字~~

使用 `npm run build` 构建项目。

markdown

效果：加粗文字、斜体文字、~~删除线文字~~，以及 npm run build。

3. 链接#

[Astro 官方文档](https://astro.build/)

markdown

效果：Astro 官方文档 ↗。

4. 列表#

- 无序列表项目一
- 无序列表项目二

1. 有序列表第一步
2. 有序列表第二步

markdown

效果：

无序列表项目一
无序列表项目二

有序列表第一步
有序列表第二步

5. 引用、分隔线和代码块#

> 这是一段引用，适合记录结论或摘录。

---

```bash
sudo apt update
sudo apt install git
```

markdown

代码块的语言标记可以使用 bash、python、javascript、json、yaml 等，本站会自动进行语法高亮。

6. 表格#

| 命令 | 作用 |
| --- | --- |
| `pwd` | 显示当前目录 |
| `ls` | 查看目录内容 |

markdown

效果：

命令	作用
`pwd`	显示当前目录
`ls`	查看目录内容

表格对齐方式也可以设置：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| 文本 | 文本 | 文本 |

markdown

7. 任务列表#

任务列表属于 GFM 扩展，当前博客支持：

- [x] 整理文章结构
- [ ] 补充图片
- [ ] 发布文章

markdown

效果：

整理文章结构
补充图片
发布文章

二、图片文件和路径#

1. 推荐的目录结构#

一篇文章的图片放在文章目录下独立的文件夹中：

src/content/tech/tools/
├── markdown-image-layout.md
└── images/
    └── markdown-image-layout/
        ├── demo-cover.jpg
        ├── step-01.png
        └── step-02.png

text

正文使用相对路径：

![图片说明](images/markdown-image-layout/demo-cover.jpg)

markdown

不要写电脑上的绝对路径：

D:/Pictures/demo.jpg
/home/user/Pictures/demo.jpg

text

绝对路径只在自己的电脑上有效，换电脑或发布到网站后就会失效。

2. 文件命名建议#

图片文件名建议使用小写英文、数字、连字符或下划线，例如：

cover.jpg
install-step-01.png
config_before.png

text

尽量避免空格、中文、括号和特殊字符。文件名越简单，不同编辑器、GitHub、PDF 导出工具之间越不容易出现路径问题。

三、最基本的图片写法#

1. 标准 Markdown 图片#

![Ubuntu 常用命令文章封面](images/markdown-image-layout/demo-cover.jpg)

markdown

效果：

Ubuntu 常用命令文章封面

这里的 alt 是替代文字，用于图片加载失败、无障碍阅读和搜索引擎理解图片内容。它不是鼠标悬停提示。

2. 图片说明#

如果需要写更完整的图注，可以使用 figure 和 figcaption：

<figure>
  <img
    class="zoomable"
    src="images/markdown-image-layout/demo-cover.jpg"
    width="720"
    alt="Ubuntu 常用命令文章封面"
  />
  <figcaption>图 1：Ubuntu 常用命令大全的文章封面。</figcaption>
</figure>

html

也可以直接在 Markdown 图片下面写一行文字：

![Ubuntu 常用命令文章封面](images/markdown-image-layout/demo-cover.jpg)

*图 1：Ubuntu 常用命令大全的文章封面。*

markdown

当前博客会为单独成段的 Markdown 图片自动生成 figure 和图注，图注内容来自 alt。因此同一张图不需要同时写两套说明，以免重复。

3. 鼠标悬停提示#

alt 不会产生鼠标提示。需要提示文字时可以增加 title：

<img
  class="zoomable"
  src="images/markdown-image-layout/demo-cover.jpg"
  alt="Ubuntu 常用命令文章封面"
  title="点击图片可以放大"
/>

html

alt 和 title 的用途不同：alt 是图片的替代描述，title 是浏览器可能显示的悬停提示。

四、图片大小和缩放#

1. Markdown 扩展写法：`=200x`#

部分编辑器支持在图片路径后添加尺寸参数，等号前需要有一个空格：

![示例图片](images/example.png =200x)
![示例图片](images/example.png =200x300)
![示例图片](images/example.png =x300)

markdown

一般可以理解为：

写法	含义
`=200x`	宽度为 200，高度按比例缩放
`=200x300`	宽度 200，高度 300
`=x300`	高度为 300，宽度按比例缩放

这不是标准 Markdown。不同渲染器可能把它当作普通文字，或者完全不处理。当前博客使用的 Markdown 解析器不会把这类参数转换成图片尺寸，所以本站文章不要依赖它。

2. HTML 设置固定宽度#

HTML 是控制图片大小更稳定的方式：

<img
  class="zoomable"
  src="images/markdown-image-layout/demo-cover.jpg"
  width="720"
  alt="Ubuntu 常用命令文章封面"
/>

html

只设置 width 时，高度一般会按原图比例显示。也可以用 CSS：

<img
  class="zoomable"
  src="images/markdown-image-layout/demo-cover.jpg"
  style="width: 60%; max-width: 100%; height: auto;"
  alt="Ubuntu 常用命令文章封面"
/>

html

效果：

Ubuntu 常用命令文章封面

其中：

width: 60%：图片宽度占正文区域的 60%；
max-width: 100%：防止图片超出手机屏幕；
height: auto：保持原始比例。

3. 同时设置宽度和高度#

<img
  class="zoomable"
  src="images/markdown-image-layout/demo-cover.jpg"
  width="720"
  height="438"
  alt="Ubuntu 常用命令文章封面"
/>

html

宽高比例不一致时图片会变形，因此只有在明确知道原图比例，或者确实需要裁剪时才同时指定两者。普通截图更建议只设置宽度。

不建议使用下面这些写法：

<img src="images/example.png" width="200x" />
<img src="images/example.png" style="zoom: 20%;" />

html

width="200x" 不是规范的 HTML 属性值，zoom 也可能影响页面布局和图片点击放大。

五、图片位置和对齐#

1. 居中#

推荐使用包裹元素控制对齐：

<p style="text-align: center;">
  <img
    class="zoomable"
    src="images/markdown-image-layout/demo-cover.jpg"
    width="600"
    alt="Ubuntu 常用命令文章封面"
  />
</p>

html

也可以使用旧式写法：

<p align="center">
  <img class="zoomable" src="images/example.png" width="600" alt="示例图片" />
</p>

html

<center> 在不少平台仍然有效，但已经是旧式 HTML，不建议作为新文章的默认写法。

2. 右对齐#

<p style="text-align: right;">
  <img
    class="zoomable"
    src="images/markdown-image-layout/demo-cover.jpg"
    width="400"
    alt="Ubuntu 常用命令文章封面"
  />
</p>

html

3. `align="left"` 的区别#

<img
  class="zoomable"
  src="images/example.png"
  width="320"
  align="left"
  alt="示例图片"
/>

html

align="left" 主要会产生图文环绕效果，后面的文字可能绕在图片旁边。它不适合普通的“图片单独占一行”排版，也容易影响后续段落。需要图片单独居中或右对齐时，应使用外层 <p> 或 <div>。

4. `#pic_center` 为什么没有效果#

![图片](images/example.png#pic_center)

markdown

#pic_center 是某些博客平台自定义识别的片段标记，不是 Markdown 标准语法。Astro、GitHub 等渲染器不会自动把它转换成居中样式，所以在本站没有效果。对齐请使用 HTML 或 CSS。

六、两图、三图和相册#

1. Markdown 表格：兼容性最好#

需要图片说明时，表格最直接：

| 安装前 | 安装后 |
| --- | --- |
| ![安装前](images/article/before.png) | ![安装后](images/article/after.png) |
| 修改前的界面 | 修改后的界面 |

markdown

三张图：

| 第一步 | 第二步 | 第三步 |
| --- | --- | --- |
| ![步骤一](images/article/step-01.png) | ![步骤二](images/article/step-02.png) | ![步骤三](images/article/step-03.png) |
| 打开设置 | 修改参数 | 保存结果 |

markdown

适合发布到多个平台、做前后对比和展示操作步骤。图片比例差异很大时，不要为了并列而强行压缩。

2. CSS Grid：本站推荐的多图模板#

本站提供了固定的网格样式，可以直接复制：

<div class="markdown-image-grid markdown-image-grid--2">
  <img class="zoomable" src="images/article/step-01.png" alt="步骤一" />
  <img class="zoomable" src="images/article/step-02.png" alt="步骤二" />
</div>

html

三列：

<div class="markdown-image-grid markdown-image-grid--3">
  <img class="zoomable" src="images/article/step-01.png" alt="步骤一" />
  <img class="zoomable" src="images/article/step-02.png" alt="步骤二" />
  <img class="zoomable" src="images/article/step-03.png" alt="步骤三" />
</div>

html

手机屏幕较窄时，网格会自动变成单列。手写 HTML 图片时要保留 class="zoomable"，这样当前博客的点击放大功能才会生效。

3. 相册模板#

<div class="markdown-image-grid markdown-image-grid--gallery">
  <figure>
    <img class="zoomable" src="images/gallery/photo-01.jpg" alt="照片一" />
    <figcaption>照片一</figcaption>
  </figure>
  <figure>
    <img class="zoomable" src="images/gallery/photo-02.jpg" alt="照片二" />
    <figcaption>照片二</figcaption>
  </figure>
  <figure>
    <img class="zoomable" src="images/gallery/photo-03.jpg" alt="照片三" />
    <figcaption>照片三</figcaption>
  </figure>
</div>

html

相册图片最好使用相近的比例。图片尺寸差异很大时，可以先裁剪，或者改用单图上下排列。

七、图片样式：圆角、阴影和边框#

HTML 的 style 可以添加简单效果：

<p style="text-align: center;">
  <img
    class="zoomable"
    src="images/markdown-image-layout/demo-cover.jpg"
    style="width: 60%; max-width: 100%; border-radius: 10px; box-shadow: 0 0 10px #b9b9b9;"
    alt="带圆角和阴影的 Ubuntu 封面"
  />
</p>

html

常用 CSS 属性：

属性	作用
`width`	设置宽度
`height`	设置高度
`max-width`	限制最大宽度
`height: auto`	保持原始比例
`border-radius`	设置圆角
`box-shadow`	添加阴影
`border`	添加边框

不要给截图随意设置 object-fit: cover，它会裁剪图片内容。只有明确需要统一相册比例时才使用裁剪。

八、表格高级样式#

1. Markdown 表格对齐#

| 名称 | 年龄 | 职业 |
| :--- | :---: | ---: |
| 张三 | 25 | 工程师 |
| 李四 | 30 | 设计师 |

markdown

当前博客会统一给 Markdown 表格添加边框、间距、斑马纹和悬停效果，因此通常不需要在每张表格上重复写 CSS。

2. HTML 表格#

需要自定义表头颜色或精确控制时，可以使用 HTML：

<table style="text-align: center; border-collapse: collapse;" border="1">
  <tr style="background-color: #f2f2f2;">
    <th>模块</th>
    <th>状态</th>
    <th>备注</th>
  </tr>
  <tr>
    <td>登录系统</td>
    <td>✅ 完成</td>
    <td>无异常</td>
  </tr>
  <tr>
    <td>报表中心</td>
    <td>🚧 开发中</td>
    <td>预计本周上线</td>
  </tr>
</table>

html

HTML 表格控制能力更强，但代码更长，跨平台效果也更依赖渲染器。普通数据表优先使用 Markdown 表格。

九、彩色文本和标记#

1. 彩色文本#

Markdown 本身没有颜色语法，HTML 可以实现：

<span style="color: green;">✅ 成功</span>
<span style="color: red;">❌ 失败</span>
<span style="color: orange;">⚠️ 警告</span>

html

效果：✅ 成功、❌ 失败、⚠️ 警告。

2. 高亮文字#

更通用的 HTML 写法是：

<mark>重点内容</mark>

html

效果：重点内容。

有些编辑器支持：

==重点内容==

markdown

但这不是所有 Markdown 渲染器都支持。当前文章中需要稳定显示时，优先使用 <mark>。

十、引用和提示框#

1. 普通引用#

> 这是一段普通引用。
>
> 可以写多行内容。

markdown

效果：

这是一段普通引用。

可以写多行内容。

2. 在引用中使用颜色#

> 💡 <span style="color: #00bfa5;">提示：</span> 先确认图片路径是否正确。
>
> ⚠️ <span style="color: orange;">警告：</span> 不要使用电脑绝对路径。

markdown

效果：

💡 提示：先确认图片路径是否正确。

⚠️ 警告：不要使用电脑绝对路径。

HTML/CSS 可以让提示更醒目，但不建议给每一段普通文字都加颜色。颜色应当表示状态、提醒或重点。

十一、折叠内容#

details 和 summary 适合隐藏较长的补充说明、代码或不需要默认展开的内容：

<details>
  <summary>点击展开详细内容</summary>

  这里是隐藏的内容，可以放文字、图片或代码块。
</details>

html

效果：

点击展开详细内容

这里是隐藏的内容，可以放文字、图片或代码块。

折叠内容属于 HTML，现代浏览器支持良好，但部分导出工具可能会默认展开或忽略交互效果。

十二、Emoji 和图标#

直接输入 Emoji 是最稳定的方式：

🔥 热门功能
💻 开发中
📦 模块封装
📈 数据分析

markdown

效果：

🔥 热门功能
💻 开发中
📦 模块封装
📈 数据分析

GitHub 风格的 Emoji 名称，例如 :rocket:、:warning:，并不是所有 Markdown 渲染器都支持。为了跨平台，建议直接使用 Unicode Emoji。

常用分类可以这样选择：

用途	Emoji 示例
成功	✅ ✔️ ☑️
失败	❌ ✖️ 💥
提示	💡 🤔 🧠
警告	⚠️ ❗ 🚫
技术	⚙️ 🧩 🛠️
进度	🚀 📈 ⏳
文件	📁 📦 📝

十三、组合排版示例#

下面是一段把图片、标题、表格和更新时间组合起来的示例：

<div align="center">
  <h2>📊 项目进度报告</h2>

  <img
    class="zoomable"
    src="images/markdown-image-layout/demo-cover.jpg"
    style="width: 60%; max-width: 100%; border-radius: 8px; box-shadow: 0 0 6px #ccc;"
    alt="项目进度报告示例封面"
  />

  <table style="margin: 1rem auto; text-align: center;" border="1">
    <tr>
      <th>模块</th>
      <th>负责人</th>
      <th>状态</th>
    </tr>
    <tr>
      <td>数据接入</td>
      <td>张三</td>
      <td>✅ 完成</td>
    </tr>
    <tr>
      <td>权限管理</td>
      <td>李四</td>
      <td>🚧 开发中</td>
    </tr>
  </table>

  <p style="color: #666;">更新时间：2026-10-16</p>
</div>

html

实际效果：

📊 项目进度报告

模块	负责人	状态
数据接入	张三	✅ 完成
权限管理	李四	🚧 开发中

更新时间：2026-10-16

十四、当前博客中的图片放大#

本站已经启用了 Medium Zoom。标准 Markdown 图片会自动获得点击放大效果：

![可以点击放大的图片](images/article/example.png)

markdown

手写 HTML 图片时，需要增加 class="zoomable"：

<img
  class="zoomable"
  src="images/article/example.png"
  alt="可以点击放大的图片"
/>

html

如果忘记这个 class，图片仍然可以显示，但不会进入本站的放大功能。

十五、常见问题排查#

表现	常见原因	处理方式
图片空白或裂开	路径错误、文件不存在	从当前 Markdown 文件位置重新检查相对路径
本地正常，网站异常	使用了绝对路径	改成相对路径或公开图床 URL
GitHub 或 PDF 显示失败	文件名包含空格、中文或括号	重命名为小写英文和连字符
`#pic_center` 无效	平台私有标记	改用 HTML/CSS 对齐
`=200x` 无效	当前渲染器不支持该扩展	改用 `<img width="200">`
图片变形	宽高比例不一致	只设置宽度，或使用 `height: auto`
图片超出手机屏幕	没有限制最大宽度	添加 `max-width: 100%`
HTML 图片不能放大	缺少 `zoomable` class	给 `<img>` 增加 `class="zoomable"`
图片模糊	原图分辨率太低或压缩过度	换更清晰的原图，控制图片体积
后面的文字绕在图片旁边	使用了 `align="left"` 或浮动布局	改用外层 `<p>` 控制整行对齐

十六、最终推荐模板#

单图#

![图片说明](images/article/example.png)

markdown

单图 + 宽度 + 居中#

<p style="text-align: center;">
  <img
    class="zoomable"
    src="images/article/example.png"
    style="width: 70%; max-width: 100%; height: auto;"
    alt="图片说明"
  />
</p>

html

两图并列#

<div class="markdown-image-grid markdown-image-grid--2">
  <img class="zoomable" src="images/article/one.png" alt="图片一" />
  <img class="zoomable" src="images/article/two.png" alt="图片二" />
</div>

html

三图并列#

<div class="markdown-image-grid markdown-image-grid--3">
  <img class="zoomable" src="images/article/one.png" alt="图片一" />
  <img class="zoomable" src="images/article/two.png" alt="图片二" />
  <img class="zoomable" src="images/article/three.png" alt="图片三" />
</div>

html

相册#

<div class="markdown-image-grid markdown-image-grid--gallery">
  <figure>
    <img class="zoomable" src="images/article/one.png" alt="图片一" />
    <figcaption>图片一说明</figcaption>
  </figure>
  <figure>
    <img class="zoomable" src="images/article/two.png" alt="图片二" />
    <figcaption>图片二说明</figcaption>
  </figure>
</div>

html

小结#

可以按下面的规则选择写法：

需求	推荐写法
普通图片	Markdown 图片语法
只想快速改宽度	先确认平台是否支持 `=200x`
控制大小和对齐	HTML `<img>` + 外层 `<p>` 或 `<div>`
两图、三图和相册	本站 CSS Grid 模板
需要跨平台发布	Markdown 表格
需要点击放大	Markdown 图片，或 HTML 图片加 `class="zoomable"`
需要提示或补充内容	`<details>`、引用和 `<mark>`

最重要的原则是：图片使用相对路径，文件名保持简单；标准 Markdown 负责内容，HTML/CSS 负责精确排版，平台扩展语法只在确认兼容后使用。

Markdown 写作与高级样式实用教程

前言#

一、Markdown 基础语法#

1. 标题#

2. 强调、删除线和行内代码#

3. 链接#

4. 列表#

5. 引用、分隔线和代码块#

6. 表格#

7. 任务列表#

二、图片文件和路径#

1. 推荐的目录结构#

2. 文件命名建议#

三、最基本的图片写法#

1. 标准 Markdown 图片#

2. 图片说明#

3. 鼠标悬停提示#

四、图片大小和缩放#

1. Markdown 扩展写法：=200x#

2. HTML 设置固定宽度#

3. 同时设置宽度和高度#

五、图片位置和对齐#

1. 居中#

2. 右对齐#

3. align="left" 的区别#

4. #pic_center 为什么没有效果#

六、两图、三图和相册#

1. Markdown 表格：兼容性最好#

2. CSS Grid：本站推荐的多图模板#

3. 相册模板#

七、图片样式：圆角、阴影和边框#

八、表格高级样式#

1. Markdown 表格对齐#

2. HTML 表格#

九、彩色文本和标记#

1. 彩色文本#

2. 高亮文字#

十、引用和提示框#

1. 普通引用#

2. 在引用中使用颜色#

十一、折叠内容#

十二、Emoji 和图标#

十三、组合排版示例#

📊 项目进度报告

十四、当前博客中的图片放大#

十五、常见问题排查#

十六、最终推荐模板#

单图#

单图 + 宽度 + 居中#

两图并列#

三图并列#

相册#

小结#

1. Markdown 扩展写法：`=200x`#

3. `align="left"` 的区别#

4. `#pic_center` 为什么没有效果#