# 富文本写作：图片、链接与代码 图片与图注、链接与锚点、代码高亮与复制，以及文章资源管理。 本篇属于 [Markdown 语法手册](/collections/markdown/)。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。 ## 图文排版示例：星空下的一页笔记 {#image-story} 写完一段文字，有时可以留一张图，让读者稍作停顿。下面使用本站星空头像的 WebP 展示版，展示正文、较大图片和图注组合后的实际效果。 {{< image src="/images/avatars/avatar-starfield-dark.webp" alt="深蓝星空中，白色终端提示符与绿色光标居于中央" caption="连接点303 · 把想法写进星空里" width="640" linked=true >}} 星点散落在深蓝色的背景上，中央的提示符像是一段尚未写完的命令。写作也可以从这里开始：先留下一个问题，再慢慢补上观察、尝试与答案。 **图片负责呈现氛围，正文负责补充信息。** 图注可以交代图片内容或来源；替代文本则应描述画面，方便图片加载失败或使用读屏时理解。 ### 复制这段图文源码 ```markdown 写完一段文字，有时可以留一张图，让读者稍作停顿。 {{}} 星点散落在深蓝色的背景上，中央的提示符像是一段尚未写完的命令。 ``` 这里的 `width="640"` 控制桌面展示宽度，手机上由主题响应式样式缩小；不指定高度，以保留原图比例。点击图片可放大查看，图注会沿用本站的深浅色次要文字色。WebP 展示版位于 `static/images/avatars/`，PNG 原图保留在其 `originals/` 子目录，无需修改或复制到 `public/`。 ## Markdown 图片 ```markdown ![连接点303终端图标](/favicon.svg "连接点303的标记") ``` ![连接点303终端图标](/favicon.svg "连接点303的标记") 方括号中是替代文本，便于读屏和加载失败时理解内容；引号中是标题。`static/favicon.svg` 在生成站点中对应 `/favicon.svg`，URL 不应包含 `static/`。 ## 带图注的 image 短代码 ```text {{}} ``` {{< image src="/images/avatars/avatar-starfield-dark.webp" alt="深色星空中的头像" caption="连接点303 · 星空头像" width="320" linked=true >}} | 参数 | 说明 | | --- | --- | | `src` | 图片路径；支持页面资源、assets 资源和静态资源 | | `alt` | 描述图片内容，避免只写“图片” | | `caption` | 图注，支持 Markdown | | `width` / `height` | 显示尺寸，可仅指定宽度保留比例 | | `linked` | 是否包裹原图链接 | | `loading` | 默认 `lazy`；首屏必要图片可用 `eager` | | `optimise` | 是否启用主题图片优化 | 本页 front matter 使用 `lightgallery: true`。带标题或图注的图片可在画廊中查看；小屏幕宽度由主题响应式样式约束。 ## 普通链接与页内锚点 ```markdown [回到合集](/collections/markdown/) [查看本页资源建议](#资源放在哪里) ``` [回到合集](/collections/markdown/) · [查看本页资源建议](#资源放在哪里) 内部链接优先使用稳定路径；文件改名后需要同步检查链接。 ## link 短代码与卡片 ```text {{}} ``` {{< 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` 则显示行内链接。外部站点需要网络访问。 ## 资源放在哪里 ```text 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/` 是生成结果，不应直接编辑。 ## 图片只展示，不打开原图 ```text {{}} ``` {{< image src="/favicon.svg" alt="连接点303终端标记" width="64" height="64" linked=false optimise=false >}} `linked=false` 适合小图标，避免为装饰性图片提供没有必要的放大操作。`optimise=false` 明确关闭图片优化；SVG 本身是矢量图，不需要栅格化缩放。 ## 使用明确的锚点 自动生成的中文标题锚点方便阅读，但标题改名后地址也可能改变。需要长期引用的章节可以指定英文 ID。 ```markdown ### 图片验收清单 {#image-review} - 图片有明确的替代文本。 - 手机屏幕上没有横向溢出。 [跳到图片验收清单](#image-review) ``` ### 图片验收清单 {#image-review} - 图片有明确的替代文本。 - 手机屏幕上没有横向溢出。 [跳到图片验收清单](#image-review) 同一页面内 ID 必须唯一。标题属性由本站继承的 Goldmark 配置支持，不应把这类扩展写法视作所有 Markdown 编辑器都支持的语法。 ## 用内部链接串起学习路径 ```text {{}} ``` {{< link href="/wiki/markdown-basics/" content="从基础排版开始" title="回到基础章节" >}} 对不需要特殊样式的链接，普通 Markdown 往往更简洁。短代码适合需要卡片、下载属性或图标等额外参数的场景；不要为了使用短代码而重写所有普通链接。 ## 图片与链接的检查顺序 1. 先确认原始文件存在，且文件名大小写一致。 2. 看浏览器最终请求的路径，不要只看编辑器里的预览。 3. 区分页面相对路径和站点根路径；page bundle 图片通常使用相对路径。 4. 检查有无过大的图片，优先缩小源图或使用主题图片优化。 5. 在深色背景下检查透明图片、黑色文字图片是否仍然清晰。 6. 点击内部链接和锚点，确认跳到的是预期位置。 本站字标使用原始 PNG，图标使用 SVG；这两类文件可以共存。SVG 更适合线条图形，照片和复杂纹理更适合 WebP、JPEG 或 PNG，不必为了统一格式而强行转换。 ## 代码块与复制 下面是 Markdown 源码，外层使用四个反引号，从而容纳里面的三个反引号。 ````markdown ```go {title="hello.go" hl_lines=[3]} package main func main() { println("你好，连接点303") } ``` ```` 实际效果： ```go {title="hello.go" hl_lines=[3]} package main func main() { println("你好，连接点303") } ``` `go` 选择语法高亮语言，`title` 设置标题，`hl_lines` 指定高亮行（从 1 开始）。主题默认提供复制按钮。这里使用 v1 的块属性，旧版 `data-*` 属性不再作为写法示范。 ## 代码高亮行与起始行号 ````markdown ```toml {title="hugo.toml 摘录" linenostart=20 hl_lines=[2,3]} [params] collection_list = true collection_navigation = true ``` ```` ```toml {title="hugo.toml 摘录" linenostart=20 hl_lines=[2,3]} [params] collection_list = true collection_navigation = true ``` `linenostart=20` 改变显示的起始行号；`hl_lines` 仍按此代码片段从 1 开始计数，所以高亮的是显示编号 21、22 的两行。代码标题应说明片段来自哪里，不要让读者误以为这是完整配置。 ## 用 diff 展示前后改动 ````markdown ```diff {title="草稿状态调整"} -draft: true +draft: false title: 我的第一篇笔记 ``` ```` ```diff {title="草稿状态调整"} -draft: true +draft: false title: 我的第一篇笔记 ``` 行首 `-` 表示删除，`+` 表示新增，空格表示上下文。这种代码块适合解释修改，不适合直接复制为配置文件；读者需要去掉 diff 标记后再使用。 ## 多语言代码片段 同一个概念可用不同语法表达。语言名控制高亮，不会执行代码。 ````markdown ```json {title="article.json"} { "title": "连接点303笔记", "draft": false, "tags": ["Markdown", "写作"] } ``` ```` ```json {title="article.json"} { "title": "连接点303笔记", "draft": false, "tags": ["Markdown", "写作"] } ``` ````markdown ```yaml {title="同一份数据的 YAML 表达"} title: 连接点303笔记 draft: false tags: - Markdown - 写作 ``` ```` ```yaml {title="同一份数据的 YAML 表达"} title: 连接点303笔记 draft: false tags: - Markdown - 写作 ``` JSON 要求双引号和严格的逗号分隔；YAML 用缩进表达结构。文章里可以并列展示它们，方便比较，但不能把两种语法混写到同一个配置文件。 ## 不需要高亮的输出 日志、目录树和终端输出可标记为 `text`，避免被误判成程序语言。 ````markdown ```text {title="示例构建摘要"} Pages: 47 Warnings: 0 Errors: 0 ``` ```` ```text {title="示例构建摘要"} Pages: 47 Warnings: 0 Errors: 0 ``` 这里是为了展示排版而写的示例摘要，不是实时构建结果。教程应清楚区分“输入命令”和“输出结果”，以免读者把日志也复制到终端执行。 ## 行内反引号与代码围栏 ```markdown 用 `` `name` `` 展示包含反引号的行内代码。 ``` 用 `` `name` `` 展示包含反引号的行内代码。 如果正文需要展示三个反引号组成的代码围栏，外层就用四个反引号；需要展示四个时，外层再多一个。源码与渲染效果分开写，比在代码块里叠加复杂转义更容易维护。 --- > 作者: [yuehei](/authors/yuehei/) > URL: https://33.ax/wiki/images-and-links/