博客编写与发布指南

Thus.Live 的文章保存在 content/posts/。每篇文章是一份 Markdown 文件，日期由所在目录决定；博文列表、标签、时间轴和搜索会在构建时生成。

本文介绍写作流程，正文格式与代码展示请参考 Markdown 写作与代码展示。

创建第一篇草稿 ​

在项目根目录执行：

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
---

draft 使用布尔值，不要写成字符串 "true"。标题中含有冒号等 YAML 特殊字符时，可以用双引号包住整个标题。

标签会自动生成页面，无需手工登记。相同话题应保持相同拼写，避免 Vue 和 vue 这类生成同一地址的标签同时出现。文章的阅读时间会根据正文自动估算。

作者为全站统一配置：修改根目录 site.profile.json 的 author，即可同步更新博文列表、正文和搜索结果；无需在每篇文章添加作者字段。

组织正文 ​

文章页面会自动展示 frontmatter 中的标题。正文建议从二级标题 ## 开始，二、三级标题会进入文章目录。

## 这次想记录什么

先用一小段话说明背景和结论。

### 一个具体示例

```typescript
const message = 'Hello, writing!'
console.log(message)
```

## 小结

整理要点，并写下还需要继续探索的问题。

每篇文章尽量围绕一个主题，摘要说明读者能获得什么，代码标记对应语言。表格、脚注、公式、Mermaid、代码分组和 Emoji 的具体写法见 Markdown 指南。

添加图片与链接 ​

将图片放在文章附近的 assets/ 目录中，然后使用相对路径：

![解释图片内容，而不是仅写“图片”](./assets/example.webp)

两种目录结构中的相对路径都从当前 Markdown 文件所在目录开始计算。图片会随构建一起处理。站点共用的头像等资源放在 content/public/，引用时使用 /avatar.webp 这类路径。

文章之间也可以使用相对链接：

[Markdown 写作与代码展示](../16/markdown-guide)

这个示例适用于本文的 2026/09/17/ 位置。移动文件后需要同步调整相对路径。发布前确认图片实际存在，并为图片填写有意义的替代文字。

预览与发布 ​

项目首次使用时安装依赖，然后启动开发服务器：

npm ci
npm run dev

访问终端给出的本地地址，默认是 http://127.0.0.1:5173。

新增、删除、移动文章或切换草稿状态后，重启开发服务器以刷新动态路由。已存在文章的正文修改可以热更新。

准备发布时，将 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/ 会原样发布，不要用它存放草稿附件中的私密资料。

先写下一篇简短而完整的记录，再逐步调整自己的写作习惯。这两份指南可以保留作参考，也可以在熟悉流程后替换为自己的内容。