博客编写与发布指南（Thus.Live）
从创建第一篇 Markdown 草稿开始，了解日期目录、文章信息、多标签、图片和发布检查。
本文目录
Thus.Live 的文章保存在 content/posts/。每篇文章是一份 Markdown 文件，日期由所在目录决定；博文列表、标签、时间轴和搜索会在构建时生成。
本文介绍写作流程，正文格式与代码展示请参考 Markdown 写作与代码展示。
这篇文章也适合作为上手指南，所以我把它也放进了 Thus.Live 项目，作为示例文章。第一次使用模板时，可以跟着走一遍，从创建文章到预览发布，先把流程熟悉起来。
创建第一篇草稿
在项目根目录执行：
npm run new:post -- my-first-post --title "我的第一篇文章" --date 2026-09-17把 my-first-post 换成文章文件名，把日期换成自己的发布日期。建议使用简短的小写英文和连字符；支持中文、数字和下划线，不支持空格、点号或多层路径。
命令会创建 content/posts/2026/09/17/my-first-post.md，并设置 draft: true。它不会覆盖已有文件。省略 --date 时，按 Asia/Shanghai 时区取当天日期。
也可以手工建立 Markdown 文件，遵循相同的目录规则。
日期目录与文章地址
简单文章可以直接放在日期目录中：
content/posts/
└── 2026/09/17/
├── my-first-post.md
└── assets/
└── example.webp图片较多时，可以让每篇文章独占一个文件夹：
content/posts/
└── 2026/09/17/
└── my-first-post/
├── index.md
└── assets/
└── example.webp两种组织方式都支持。第一种地址为 /posts/2026/09/17/my-first-post，第二种为 /posts/2026/09/17/my-first-post/。同一个日期下请选择其中一种，不能同时创建两者。
年份用四位数字，月份和日期用两位数字。移动日期目录或修改文件名会改变链接；已经发布的文章如需改地址，应在部署平台配置旧地址重定向。
填写文章信息
文件开头两个 --- 之间的内容称为 frontmatter，用来描述文章信息：
---
title: 我的第一篇文章
description: 介绍这篇文章解决的问题，或最值得读者了解的内容。
tags: [写作, 学习笔记]
draft: true
---| 字段 | 如何填写 |
|---|---|
title | 文章标题；推荐在这里填写，省略时尝试读取正文的一级标题 |
description | 列表与搜索中的摘要；省略时从正文提取 |
tags | 字符串数组，一篇文章可以有多个标签 |
draft | true 为草稿，false 或省略表示发布 |
updated | 可选，实际修改日期，例如 2026-09-18，不能早于发布日期 |
order | 可选整数，控制所有文章列表、时间轴、文章导航和 RSS 中同一天文章的顺序；越大越靠前，默认 0，相同值按文章 URL 排序。搜索匹配度相同时也遵循此规则。例如先写的填写 order: 1，后写的填写 order: 2，后写的显示在前 |
date | 通常省略；填写时必须与日期目录一致 |
draft 使用布尔值，不要写成字符串 "true"。标题中含有冒号等 YAML 特殊字符时，可以用双引号包住整个标题。
标签会自动生成页面，无需手工登记。相同话题应保持相同拼写，避免 Vue 和 vue 这类生成同一地址的标签同时出现。文章的阅读时间会根据正文自动估算。
作者为全站统一配置：修改根目录 site.profile.json 的 author，即可同步更新博文列表、正文和搜索结果；无需在每篇文章添加作者字段。
组织正文
文章页面会自动展示 frontmatter 中的标题。正文建议从二级标题 ## 开始，二、三级标题会进入文章目录。
## 这次想记录什么
先用一小段话说明背景和结论。
### 一个具体示例
```typescript
const message = 'Hello, writing!'
console.log(message)
```
## 小结
整理要点，并写下还需要继续探索的问题。每篇文章尽量围绕一个主题，摘要说明读者能获得什么，代码标记对应语言。表格、脚注、公式、Mermaid、代码分组和 Emoji 的具体写法见 Markdown 指南。
添加图片与链接
将图片放在文章附近的 assets/ 目录中，然后使用相对路径：
两种目录结构中的相对路径都从当前 Markdown 文件所在目录开始计算。图片会随构建一起处理。站点共用的头像等资源放在 content/public/，引用时使用 /avatar.webp 这类路径。
文章之间也可以使用相对链接：
[Markdown 写作与代码展示](./markdown-guide)这个示例适用于两篇文章同处 2026/09/22/ 目录的情况。移动文件后需要同步调整相对路径。发布前确认图片实际存在，并为图片填写有意义的替代文字。
预览与发布
项目首次使用时安装依赖，然后启动开发服务器：
npm ci
npm run dev访问终端给出的本地地址，默认是 http://127.0.0.1:5173。
草稿如何预览
当前站点在开发和构建环境中都会排除 draft: true 的文章。要预览正文，请在本地暂时改为 draft: false 并重启开发服务器；尚未准备发布时，检查完成后改回 true。
新增、删除、移动文章或切换草稿状态后，重启开发服务器以刷新动态路由。已存在文章的正文修改可以热更新。
准备发布时，将 draft 改为 false，运行：
npm run build
npm run check:output
npm run preview构建会校验日期、标签和文章信息；输出检查会检查生成页面中的本地链接和资源路径。静态预览默认为 http://127.0.0.1:4173，重新构建后应重启预览进程。
确认标题、摘要、多标签、图片和代码在手机与桌面布局下都正常，再发布构建结果：使用 Vercel 时提交到已连接的部署分支触发构建；使用 Nginx 时更新服务器上的完整 dist/ 内容。完整部署配置见项目根目录 README。
更新与整理
- 修改文章后，可以添加或更新
updated，保留原来的发布日期目录。 - 删除文章时，清理其他文章中指向它的链接；确认图片没有被其他文章使用后再删除。
- 标签、搜索和时间轴由内容自动生成，重新构建后会一起更新。
- 日期目录用于归档，不是定时发布功能；未来日期且
draft: false的文章也会参与构建。 - 草稿不会生成文章页面和搜索索引；
content/public/会原样发布，不要用它存放草稿附件中的私密资料。
先写下一篇简短而完整的记录，再逐步调整自己的写作习惯。这两份指南可以保留作参考，也可以在熟悉流程后替换为自己的内容。