这篇文章既是一份发文教程，也是一份 Markdown 渲染回归样例。以后升级 Hugo、PaperMod 或自定义样式后，可以打开本页快速检查标题、列表、引用、表格、链接、图片、代码块等元素是否仍然正常。

一、创建一篇新文章

登录服务器并进入博客目录：

ssh ubuntu@yuning.wang
cd /home/ubuntu/blog

用 Hugo 创建一个 Page Bundle：

hugo new posts/my-new-post/index.md

命令会生成：

content/posts/my-new-post/
└── index.md

文章图片也可以放进这个目录：

content/posts/my-new-post/
├── index.md
├── cover.png
└── architecture.png

二、填写文章信息

新文件会自动带有 Front Matter：

---
title: "My New Post"
date: 2026-07-18T21:45:00+08:00
categories:
  - 技术笔记
draft: true
---

需要手动确认的字段只有：

  1. title：文章标题。
  2. categories：文章分类；新分类无需提前创建。
  3. draft：写作时保持 true，发布时改成 false。

作者会自动使用全局笔名“云兮”，阅读时间与字数也由 Hugo 自动计算，不需要逐篇填写。

三、控制首页摘要

把首页需要展示的摘要写在 <!--more--> 之前：

这部分会显示在首页。

<!--more-->

这部分只在文章详情页显示。

四、预览与发布

预览包含草稿的站点：

cd /home/ubuntu/blog
hugo server -D --bind 0.0.0.0 --port 8888

确认无误后，把文章改成：

draft: false

生成正式静态文件：

hugo --minify

正式站点由 Nginx 直接读取 /home/ubuntu/blog/public，构建成功后新文章即可生效。

五、Markdown 渲染回归

以下内容用于检查常见语法。

5.1 文本样式

普通正文、粗体文字、斜体文字、删除线、inline code。

这是一个站内归档链接，这是一个外部链接。

5.2 无序列表

  • 一级项目 A
  • 一级项目 B
    • 二级项目 B.1
    • 二级项目 B.2
      • 三级项目 B.2.1
  • 一级项目 C

5.3 有序列表

  1. 创建文章。
  2. 编写正文。
  3. 本地预览。
  4. 构建发布。

5.4 任务列表

  • 标题能够显示
  • 代码能够高亮
  • 表格能够对齐
  • 写下一篇真正的新文章

5.5 引用

写作不是把已经想明白的内容抄下来。

很多时候，我们正是在写作中把事情想明白。

5.6 表格

能力是否自动说明
作者是默认使用“云兮”
日期是hugo new 自动生成
字数是Hugo 构建时统计
阅读时间是根据正文自动估算
分类否在 Front Matter 中选择

5.7 分隔线

上方正文。

下方正文。

5.8 Shell 代码

set -e
cd /home/ubuntu/blog
hugo --minify

5.9 Python 代码

from pathlib import Path

posts = Path("content/posts")
for article in posts.glob("*/index.md"):
    print(article)

5.10 JavaScript 代码

const articles = document.querySelectorAll('.article-row');
console.log(`共有 ${articles.length} 篇文章`);

5.11 JSON 与 YAML

{
  "title": "示例文章",
  "author": "云兮",
  "draft": false
}

title: 示例文章
categories:
  - 技术笔记
draft: false

5.12 普通文本与长行

[INFO] Hugo build completed successfully
[INFO] Static files are ready to be served by Nginx

下面这行用于检查代码块横向滚动，而不是把整个页面撑宽：

curl -fsSL "https://yuning.wang/posts/how-to-write-a-new-post/?source=markdown-render-regression&viewport=mobile" -H "Accept: text/html"

六、图片写法

将图片放进文章目录后，使用相对路径：

![图片说明](architecture.png)

如果图片尚未准备好，不要提交一个失效路径。发布前应检查图片请求返回 200。

七、发布前检查清单

  • title 是最终标题。
  • categories 分类正确。
  • draft 已改为 false。
  • 摘要位于 <!--more--> 前。
  • 代码块都标注了语言。
  • 图片路径可以访问。
  • 桌面端和移动端没有横向溢出。
  • hugo --minify 构建成功。

完成这些步骤后，一篇新文章就发布完成了。