# 文章模板与写作发布流程


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

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

<!--more-->

## 内容文件放在哪里

本站按[官方内容组织说明](https://fixit.lruihao.cn/zh-cn/docs/content-management/introduction/#contents-organization)整理目录。日常文章放在 `content/posts/`，Wiki 知识文档放在 `content/wiki/`，关于和链接等独立页面放在 `content/`；不要编辑构建生成的 `public/`。

```text
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，地址就不会随之变化。其他内容仍可使用简短英文和连字符命名。

### 单文件文章与文章包

| 写法 | 适用情况 | 默认访问地址 |
| --- | --- | --- |
| `content/posts/my-note.md` | 主要是文字，图片不多 | `/posts/my-note/` |
| `content/posts/my-note/index.md` | 图片、附件与文章一起维护 | `/posts/my-note/` |
| `content/posts/_index.md` | 描述文章列表，不是独立文章 | `/posts/` |
| `content/wiki/markdown/my-note.md` | Wiki 知识文档 | `/wiki/my-note/` |
| `content/about.md` | 独立页面 | `/about/` |

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

新建纯文字文章：

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

新建带图文章：

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

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

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

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

<!--more-->

## 正文

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

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

### 本地资源路径怎么写

| 实际位置 | 引用示例 | 用途 |
| --- | --- | --- |
| `content/posts/my-note/diagram.png` | `diagram.png` | 本文独有的图片，随文章包管理 |
| `assets/images/shared.png` | `/images/shared.png` | 多篇文章共享、可交给 Hugo 处理的资源 |
| `static/badge/fixit-logo.svg` | `/badge/fixit-logo.svg` | 原样输出的文件 |

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

图片语法、图注和代码高亮详见[富文本写作](/wiki/images-and-links/)。

### 目录、栏目与合集的区别

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

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

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

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

```yaml
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`：

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

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

## 最小文章头部

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

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

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

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

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

开始前需要准备：

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

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

开始前需要准备：

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

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

## 一份可复制的短文骨架

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

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

## 当时的情况

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

## 我做了什么

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

## 得到的结论

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

## 后续可以尝试

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

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

## 常见问题速查

| 现象 | 常见原因 | 调整方式 |
| --- | --- | --- |
| 标题显示成普通文字 | `#` 后没有空格 | 写成 `## 标题` |
| 两段连成一段 | 段落之间没有空行 | 空一行再写下一段 |
| 子列表跑出父列表 | 缩进不足或混用制表符 | 使用空格，对齐正文列 |
| 星号没有按预期显示 | 被识别成强调语法 | 写成 `\*` |
| 文章没有出现在首页 | 草稿状态或未来日期 | 检查 `draft`、`date` 和预览参数 |

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

## 选择哪种结构

| 要表达的内容 | 推荐结构 | 原因 |
| --- | --- | --- |
| 两个版本的差别 | diff 代码块 | 改动位置一眼可见 |
| 多个参数的含义 | 简短表格 | 便于按列比较 |
| 有顺序的操作 | 有序列表 | 明确先后依赖 |
| 发布前的检查 | 任务清单 | 完成标准清楚 |
| 次要背景和来源 | 脚注 | 保持主线连贯 |
| 多套可选方案 | 标签页 | 避免连续堆叠大段内容 |

可以用[折叠与标签页](/wiki/fixit-shortcodes/#标签页-tabs--tab)组织这些内容，让长文章既能连续阅读，也能快速查找。

## 常用文章元数据

| 字段 | 用途 | 建议 |
| --- | --- | --- |
| `title` | 页面标题 | 明确说明文章要解决的问题 |
| `description` | 页面描述 | 用一句完整的话概括价值 |
| `date` | 发布日期与排序依据 | 带时区，避免时间含糊 |
| `lastmod` | 最近更新时间 | 有实质更新时维护 |
| `draft` | 是否草稿 | 发布前检查是否为 `false` |
| `tags` | 交叉检索 | 少量稳定关键词 |
| `categories` | 内容归类 | 使用清晰的分类名 |
| `collections` | 连续阅读的合集 | 本手册使用 `Markdown 语法` |
| `aliases` | 旧地址跳转 | 改 URL 时保留必要旧路径 |

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

## 本地预览与生产构建

```sh {title="包含草稿的本地预览"}
./scripts/hugo.sh server --bind 127.0.0.1 --port 1313 --disableFastRender -D
```

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

```sh
lsof -nP -iTCP:1313 -sTCP:LISTEN
```

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

```sh {title="生产构建"}
./scripts/hugo.sh --environment production --gc --minify --cleanDestinationDir
```

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

## 可以复用的发布检查清单

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

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

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


---

> 作者: [yuehei](/authors/yuehei/)  
> URL: https://33.ax/wiki/writing-workflow/