富文本写作：图片、链接与代码

图片与图注、链接与锚点、代码高亮与复制，以及文章资源管理。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

图文排版示例：星空下的一页笔记

写完一段文字，有时可以留一张图，让读者稍作停顿。下面使用本站星空头像的 WebP 展示版，展示正文、较大图片和图注组合后的实际效果。

星点散落在深蓝色的背景上，中央的提示符像是一段尚未写完的命令。写作也可以从这里开始：先留下一个问题，再慢慢补上观察、尝试与答案。

图片负责呈现氛围，正文负责补充信息。 图注可以交代图片内容或来源；替代文本则应描述画面，方便图片加载失败或使用读屏时理解。

复制这段图文源码

1
2
3
4
5

写完一段文字，有时可以留一张图，让读者稍作停顿。

{{< image src="/images/avatars/avatar-starfield-dark.webp" alt="深蓝星空中，白色终端提示符与绿色光标居于中央" caption="连接点303 · 把想法写进星空里" width="640" linked=true >}}

星点散落在深蓝色的背景上，中央的提示符像是一段尚未写完的命令。

这里的 width="640" 控制桌面展示宽度，手机上由主题响应式样式缩小；不指定高度，以保留原图比例。点击图片可放大查看，图注会沿用本站的深浅色次要文字色。WebP 展示版位于 static/images/avatars/，PNG 原图保留在其 originals/ 子目录，无需修改或复制到 public/。

Markdown 图片

1

![连接点303终端图标](/favicon.svg "连接点303的标记")

方括号中是替代文本，便于读屏和加载失败时理解内容；引号中是标题。static/favicon.svg 在生成站点中对应 /favicon.svg，URL 不应包含 static/。

带图注的 image 短代码

1

{{< image src="/images/avatars/avatar-starfield-dark.webp" alt="深色星空中的头像" caption="连接点303 · 星空头像" width="320" linked=true >}}

本页 front matter 使用 lightgallery: true。带标题或图注的图片可在画廊中查看；小屏幕宽度由主题响应式样式约束。

普通链接与页内锚点

1
2

[回到合集](/collections/markdown/)
[查看本页资源建议](#资源放在哪里)

回到合集 · 查看本页资源建议

内部链接优先使用稳定路径；文件改名后需要同步检查链接。

link 短代码与卡片

1

{{< link href="https://fixit.lruihao.cn/" content="主题官方文档" title="前往官方文档" card=true card-icon="fa-solid fa-book" >}}

href 指定目标，content 指定链接文字，title 提供悬浮提示，card=true 使用卡片布局。card-icon 指定 Font Awesome 图标，避免自动请求外部 favicon。省略 card 则显示行内链接。外部站点需要网络访问。

资源放在哪里

1
2
3
4
5
6
7

content/posts/a-trip/
├── index.md
└── coast.jpg

static/images/avatars/avatar-starfield-dark.webp
static/brand-wordmark.png
static/favicon.svg

文章专属图片推荐与 index.md 组成 leaf bundle，正文写 ![海岸](coast.jpg)。需要 Hugo 图片处理的公共资源放 assets/；需要原样发布的文件放 static/。public/ 是生成结果，不应直接编辑。

图片只展示，不打开原图

1

{{< image src="/favicon.svg" alt="连接点303终端标记" width="64" height="64" linked=false optimise=false >}}

linked=false 适合小图标，避免为装饰性图片提供没有必要的放大操作。optimise=false 明确关闭图片优化；SVG 本身是矢量图，不需要栅格化缩放。

使用明确的锚点

自动生成的中文标题锚点方便阅读，但标题改名后地址也可能改变。需要长期引用的章节可以指定英文 ID。

1
2
3
4
5
6

### 图片验收清单 {#image-review}

- 图片有明确的替代文本。
- 手机屏幕上没有横向溢出。

[跳到图片验收清单](#image-review)

图片验收清单

• 图片有明确的替代文本。
• 手机屏幕上没有横向溢出。

跳到图片验收清单

同一页面内 ID 必须唯一。标题属性由本站继承的 Goldmark 配置支持，不应把这类扩展写法视作所有 Markdown 编辑器都支持的语法。

用内部链接串起学习路径

1

{{< link href="/wiki/markdown-basics/" content="从基础排版开始" title="回到基础章节" >}}

对不需要特殊样式的链接，普通 Markdown 往往更简洁。短代码适合需要卡片、下载属性或图标等额外参数的场景；不要为了使用短代码而重写所有普通链接。

图片与链接的检查顺序

1. 先确认原始文件存在，且文件名大小写一致。
2. 看浏览器最终请求的路径，不要只看编辑器里的预览。
3. 区分页面相对路径和站点根路径；page bundle 图片通常使用相对路径。
4. 检查有无过大的图片，优先缩小源图或使用主题图片优化。
5. 在深色背景下检查透明图片、黑色文字图片是否仍然清晰。
6. 点击内部链接和锚点，确认跳到的是预期位置。

本站字标使用原始 PNG，图标使用 SVG；这两类文件可以共存。SVG 更适合线条图形，照片和复杂纹理更适合 WebP、JPEG 或 PNG，不必为了统一格式而强行转换。

代码块与复制

下面是 Markdown 源码，外层使用四个反引号，从而容纳里面的三个反引号。

1
2
3
4
5
6
7

```go {title="hello.go" hl_lines=[3]}
package main

func main() {
    println("你好，连接点303")
}
```

实际效果：

1
2
3
4
5

package main

func main() {
    println("你好，连接点303")
}

go 选择语法高亮语言，title 设置标题，hl_lines 指定高亮行（从 1 开始）。主题默认提供复制按钮。这里使用 v1 的块属性，旧版 data-* 属性不再作为写法示范。

代码高亮行与起始行号

1
2
3
4
5

```toml {title="hugo.toml 摘录" linenostart=20 hl_lines=[2,3]}
[params]
collection_list = true
collection_navigation = true
```

20
21
22

[params]
collection_list = true
collection_navigation = true

linenostart=20 改变显示的起始行号；hl_lines 仍按此代码片段从 1 开始计数，所以高亮的是显示编号 21、22 的两行。代码标题应说明片段来自哪里，不要让读者误以为这是完整配置。

用 diff 展示前后改动

1
2
3
4
5

```diff {title="草稿状态调整"}
-draft: true
+draft: false
 title: 我的第一篇笔记
```

1
2
3

-draft: true
+draft: false
 title: 我的第一篇笔记

行首 - 表示删除，+ 表示新增，空格表示上下文。这种代码块适合解释修改，不适合直接复制为配置文件；读者需要去掉 diff 标记后再使用。

多语言代码片段

同一个概念可用不同语法表达。语言名控制高亮，不会执行代码。

1
2
3
4
5
6
7

```json {title="article.json"}
{
  "title": "连接点303笔记",
  "draft": false,
  "tags": ["Markdown", "写作"]
}
```

1
2
3
4
5
6
7

```yaml {title="同一份数据的 YAML 表达"}
title: 连接点303笔记
draft: false
tags:
  - Markdown
  - 写作
```

1
2
3
4
5

title: 连接点303笔记
draft: false
tags:
  - Markdown
  - 写作

JSON 要求双引号和严格的逗号分隔；YAML 用缩进表达结构。文章里可以并列展示它们，方便比较，但不能把两种语法混写到同一个配置文件。

不需要高亮的输出

日志、目录树和终端输出可标记为 text，避免被误判成程序语言。

1
2
3
4
5

```text {title="示例构建摘要"}
Pages: 47
Warnings: 0
Errors: 0
```

1
2
3

Pages: 47
Warnings: 0
Errors: 0

这里是为了展示排版而写的示例摘要，不是实时构建结果。教程应清楚区分“输入命令”和“输出结果”，以免读者把日志也复制到终端执行。

行内反引号与代码围栏

1

用 `` `name` `` 展示包含反引号的行内代码。

用 `name` 展示包含反引号的行内代码。

如果正文需要展示三个反引号组成的代码围栏，外层就用四个反引号；需要展示四个时，外层再多一个。源码与渲染效果分开写，比在代码块里叠加复杂转义更容易维护。