这篇文章记录当前博客从写 Markdown 到网站上线的步骤。以下命令在 Windows PowerShell 中执行，起点是博客根目录：C:\Users\95443\OneDrive\Blog\biribiribird。

1. 创建文章

在 content/posts/ 下新建一个独立文件夹，里面放 index.md。例如这篇文章位于：

1content/posts/tittle-tattle/work-env/blog-writing-publishing/
2└── index.md

从下面的模板开始写，发布前确认 draft: false，并给每篇文章使用不同的 slug：

 1---
 2title: 文章标题
 3date: 2026-09-23
 4draft: false
 5tags: ["标签"]
 6categories: ["分类"]
 7series: ["专栏"]
 8slug: my-post-slug
 9---
10
11正文从这里开始。

slug 决定文章地址，例如 my-post-slug 对应 /posts/my-post-slug/。暂时不想公开时，设为 draft: true；预览草稿时使用下面的 -D 参数。

图片可以放在 index.md 旁边，例如 assets/screenshot.png，然后在正文中写：

1![图片说明](assets/screenshot.png)

2. 编辑 Markdown

标题用 #、##、###，链接写成 [文字](https://example.com)，代码块用三个反引号包住并标明语言。保存后通过本地预览检查效果。

本站开启了单换行显示，因此同一段里直接按回车，网页上也会换行；如果想开始新段落，两段之间留一个空行。

1第一行
2第二行
3
4这是新的一段。

公式会在 Hugo 构建时生成 HTML。行内公式使用单个美元符号包围；行间公式使用双美元符号，并在公式前后留空行：

1这是行内公式：$E=mc^2$。
2
3$$
4E=mc^2
5$$
6
7这里继续写正文。

行间公式内部需要多行排版时，按 LaTeX 语法使用 aligned 等环境与 \\ 换行；不要依靠 Markdown 的普通回车来拆分公式。

3. 本地预览

在博客根目录打开 PowerShell，运行：

1.\hugo.exe server -D

浏览器打开 http://localhost:1313/，查看文章列表和文章页。检查标题、图片、链接、代码块、公式，以及手机宽度下的排版。编辑并保存 index.md 后，Hugo 会自动更新预览；结束时按 Ctrl+C。

-D 会让草稿也出现在本地预览中。准备发布时检查 draft: false，否则正常构建不会输出该文章。

4. 构建并检查发布文件

仍在博客根目录执行：

1.\hugo.exe --minify
2git -C public status --short
3git -C public diff --stat

Hugo 会把网站生成到 public/；这个目录是发布产物，不用于手工写文章。先确认构建没有错误，再查看 public 的变更，尤其是本次文章的 posts/my-post-slug/index.html、图片和站点索引。若 public 里本来就有其他未提交改动，先分清它们的来源再提交。

5. 发布网站

确认 public 中的变更都要发布后，在博客根目录执行：

1git -C public add -A
2git -C public commit -m "Publish blog post"
3git -C public push origin main

这里的 public/ 本身是一个 Git 仓库，远程仓库是 biribiribird/biribiribird.github.io。推送完成后，访问 https://biribiribird.top/posts/my-post-slug/ 核对线上页面；把示例 slug 换成文章自己的 slug。

仓库中也有 upload.bat，但它使用 git push --force。日常发布按上面的命令检查后普通推送更稳妥，尤其不要在未看清 public 变更时直接运行脚本。

每次发布前快速核对

  • index.md 位于 content/posts/ 下，date、slug 和 draft 正确。
  • 本地预览中的图片、链接、公式和换行正常。
  • hugo.exe --minify 构建成功，public 的变更已核对。
  • 推送后打开线上文章地址，再检查一次页面。