文章模板与写作发布流程

元数据、草稿、摘要、文章模板、本地预览与发布检查。

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

内容文件放在哪里

本站按官方内容组织说明整理目录。日常文章放在 content/posts/，Wiki 知识文档放在 content/wiki/，关于和链接等独立页面放在 content/；不要编辑构建生成的 public/。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

content/
├── about.md                         # 关于页
├── links.md                         # 链接页，layout: friends
├── posts/
│   ├── _index.md                     # 文章列表的标题和说明
│   └── my-note/                      # 带资源的文章包（新文章示例）
│       ├── index.md                 # 文章正文
│       ├── cover.webp               # 本文封面
│       └── diagram.png              # 本文插图
├── wiki/
│   ├── _index.md                    # 普通页面使用独立 wiki 类型
│   └── markdown/
│       └── Markdown 基础与扩展语法.md # slug: markdown-basics；URL 不变
└── collections/
    └── markdown-语法/_index.md       # 合集介绍与固定地址
assets/images/                       # 多篇文章共用、可处理的图片
static/badge/                        # 原样发布的徽章
data/friends.yml                    # 链接页面的数据

my-note/ 是目录示例，不是已发布的文章。本站 Markdown 手册使用文章标题作为文件名，并在 Front Matter 中设置固定英文 slug，例如 Markdown 基础与扩展语法.md 设置 slug: markdown-basics，访问地址仍为 /wiki/markdown-basics/。以后修改文件名或标题时保留 slug，地址就不会随之变化。其他内容仍可使用简短英文和连字符命名。

单文件文章与文章包

index.md 表示叶子页面包，适合一篇文章和它的资源；_index.md 表示分支或列表页，适合栏目与合集。不要为了给文章加图片，把 index.md 写成 _index.md，也不要同时创建同名的单文件文章和文章包。

新建纯文字文章：

1

./scripts/hugo.sh new content posts/my-note.md

新建带图文章：

1

./scripts/hugo.sh new content posts/my-note/index.md

把图片复制到 content/posts/my-note/ 后，用相对文件名引用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
title: 我的图文笔记
date: 2026-10-14T09:00:00+08:00
draft: true
authors: [yuehei]
description: 记录一次图文写作的过程。
featured_image: cover.webp
tags: [笔记]
---

这里写一段可独立阅读的首页摘要。

<!--more-->

## 正文

![流程示意图](diagram.png)

先放好示例中引用的两张图片，再预览。本站首页将封面显示为标题上方的宽幅图片；无封面的文章不必设置 featured_image。

本地资源路径怎么写

主题资源解析会先找页面资源，再找 assets，最后使用静态路径。引用时不要写成 /static/badge/... 或 /assets/images/...；这两个目录名不是发布后的 URL 前缀。尽量避免在多个位置存放同名资源，以免命中意外的文件。

图片语法、图注和代码高亮详见富文本写作。

目录、栏目与合集的区别

• 文件目录决定内容组织和默认 URL；本站 mainSections = ['posts', 'wiki'] 控制首页主要文章来源。
• categories 和 tags 在文章、Wiki 及后续其他栏目之间共享；分类表示较宽泛的主题，标签表示具体工具、对象或问题，不要求移动文件。
• collections 用来组织连续阅读的内容；本站手册名称为 Markdown 语法。
• manual_part 是本站手册目录使用的自定义分组字段，不是所有文章都需要填写。

分类按需填写，不要求每篇都有；标签使用少量稳定关键词。同一主题跨栏目使用相同名称，例如 Hugo 文章和 Hugo 部署 Wiki 都可使用 categories: ['技术']、tags: [Hugo]，不另建“Wiki 技术”或“文章技术”。分类和标签页会聚合来自不同栏目的关联内容。

Wiki 不再作为分类名称。“收录于 Wiki”始终指向 Wiki 栏目并保留彩色图标，有合集时继续显示合集；即使 Wiki 文档填写了主题分类，也不在这一行追加分类。普通文章仍显示分类。新增栏目是否进入首页、全站归档及订阅，需另行配置，不由分类或标签决定。

新增手册文章时，可填写：

1
2

collections: ['Markdown 语法']
manual_part: '富文本写作'

当前分组为“基础排版、富文本写作、组件、数学与图表、写作流程”。如果创建新的分组名称，还要同步更新 layouts/manual.html，否则它不会出现在本站自定义的合集目录里。文章顺序由日期升序决定，不需要给标题加数字编号。

本站 content/wiki/_index.md 通过 cascade 为普通页面统一设置 type: wiki 和 url: /wiki/:slugorcontentbasename/，阅读模板通过挂载复用 FixIt 的原生实现，新增 Wiki 文档无需重复填写，也不再自动赋予 Wiki 分类。target.kind: page 避免把栏目列表页当成文章。知识文档使用 /wiki/.../ 地址；日常写作继续使用 content/posts/。合集仍由 collections 字段关联，不由文件目录自动决定。 markdown/ 仅用于文件整理，不设置 _index.md，因此面包屑直接显示“Wiki → 文章标题”，Wiki 下所有普通文章 URL 使用 /wiki/文章名/，省略中间目录，不添加 aliases。

迁移文章时，在 Front Matter 的 aliases 中保留旧 URL，并更新正文内链。Twikoo 默认按 URL 路径关联评论，旧地址跳转不会自动迁移评论；若原文章已有评论，应同时处理评论数据或单独保留其评论路径。

独立页面与链接列表

普通独立页面可使用 layout: page；本站关于页已经采用这种方式。链接页使用内置的 layout: friends 和 friend_scheme: domino，实际链接维护在 data/friends.yml：

1
2
3
4
5

- nickname: 网站名称
  url: https://example.com/
  avatar: /images/site-avatar.png
  description: 一句话说明这个网站。
  weight: 10

头像需要先保存到对应位置；也可省略 avatar 使用默认图标。权重越大越靠前。添加链接不需要安装项目组件，也不需要 GitHub 仓库或访问令牌。

最小文章头部

1
2
3
4
5
6
7
8

---
title: 我的第一篇笔记
date: 2026-10-01T09:00:00+08:00
draft: false
authors: [yuehei]
tags: [笔记]
collections: ['Markdown 语法']
---

draft: true 只在带 -D 的预览中出现；description 可提供文章摘要。合集文章依日期升序排列，请给每篇安排明确的日期。

给长文章写一个有用的开头

技术文章的开头可以回答三个问题：读者遇到了什么、这篇文章解决到什么程度、需要什么前置条件。下面是一段可改写的示范：

1
2
3
4
5
6
7
8

我想把零散的笔记整理成一个可以持续更新的博客。
这篇文章记录从新建 Markdown 文件到本地预览的最短流程。

开始前需要准备：

- 一个已能运行的 Hugo 项目。
- 支持 UTF-8 的文本编辑器。
- 十分钟可以专心写作的时间。

我想把零散的笔记整理成一个可以持续更新的博客。 这篇文章记录从新建 Markdown 文件到本地预览的最短流程。

开始前需要准备：

• 一个已能运行的 Hugo 项目。
• 支持 UTF-8 的文本编辑器。
• 十分钟可以专心写作的时间。

本站使用显式摘要分隔标记控制首页摘录，见本页源文件中的 <!--more-->。它是写在正文中的 Hugo 摘要标记，不应放入文章头部。首页摘要应能独立说明文章主题，而不是只剩下“前言”两个字。

一份可复制的短文骨架

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

---
title: 一次小改动的记录
date: 2026-10-13T09:00:00+08:00
draft: true
authors: [yuehei]
description: 记录问题、尝试与结论。
tags: [笔记]
---

用两三句话交代这次遇到的问题。

## 当时的情况

写下触发条件、期望结果和实际结果。

## 我做了什么

1. 先确认最容易验证的事实。
2. 每次只改变一个条件。
3. 保存有价值的观察结果。

## 得到的结论

区分已经验证的结论与仍然需要观察的部分。

## 后续可以尝试

- [ ] 补充另一个使用场景。
- [ ] 一周后回看这次判断。

这是完整文件模板，不应直接追加到已有正文里。创建新文件后，先检查标题和日期，发布前再设置 draft: false。日期晚于构建时间的文章也可能不出现在普通构建中。

常见问题速查

练习：用这一篇介绍的语法写一则周记，包含两个二级标题、一个列表、一处引用和一个内部链接。参照基础与扩展语法，再为它增加任务清单和脚注。

选择哪种结构

可以用折叠与标签页组织这些内容，让长文章既能连续阅读，也能快速查找。

常用文章元数据

文章拆分或合并时，最容易遗漏的是旧链接和合集归属。标题可自由调整，已经分享过的 URL 应尽量稳定；需要改路径时，为旧地址添加别名。

本地预览与生产构建

1

./scripts/hugo.sh server --bind 127.0.0.1 --port 1313 --disableFastRender -D

预览服务启动后，在另一终端确认实际监听地址：

1

lsof -nP -iTCP:1313 -sTCP:LISTEN

应看到 127.0.0.1:1313。这表示服务只对本机开放。浏览器访问本地地址检查文章，完成后使用 Ctrl+C 停止服务。

1

./scripts/hugo.sh --environment production --gc --minify --cleanDestinationDir

生产构建生成 public/，不等于上传或部署。本站的 Hugo 包装脚本只负责找到本地 Dart Sass 并设置缓存目录，底层仍直接调用 Hugo。

可以复用的发布检查清单

1
2
3
4
5
6
7
8

- [ ] 标题、摘要和发布日期正确
- [ ] draft 已改为 false
- [ ] 合集名称与已有文章一致
- [ ] 每个代码片段都说明了输入和结果
- [ ] 演示短代码没有在源码区意外执行
- [ ] 图片、内部链接和锚点可访问
- [ ] 桌面、手机和深色模式正常
- [ ] 生产构建通过

• 标题、摘要和发布日期正确
• draft 已改为 false
• 合集名称与已有文章一致
• 每个代码片段都说明了输入和结果
• 演示短代码没有在源码区意外执行
• 图片、内部链接和锚点可访问
• 桌面、手机和深色模式正常
• 生产构建通过

这里的清单是供每篇新文章复用的模板，不表示本手册的实时验收状态。