文章

目录 一、快速开始 二、Front Matter 完全指南 三、Markdown 基础语法 四、PaperMod 主题短代码 五、Hugo 内置短代码 六、本站增强语法 七、写作工具与工作流 八、实战：完整文章示例 九、常见坑与排查 十、速查表 一、快速开始 1.1 三个命令 hugo new content posts/我的新文章.md # 新建文章（自动套用 archetypes/default.md 模板） hugo server -D # 本地预览（-D 表示包含草稿），打开 http://localhost:1313 hugo --gc --minify # 构建发布（产物在 public/ 目录） 1.2 一篇文章的最小结构 --- title: "文章标题" date: 2026-10-07T10:00:00+08:00 draft: false tags: ["标签1", "标签2"] categories: ["分类"] --- 正文从这里开始。 1.3 写作流程建议 hugo new content posts/xxx.md 新建（默认 draft: true） 写内容，浏览器开着 hugo server -D 实时预览 写完把 draft 改为 false hugo --gc --minify 构建，把 public/ 部署到托管平台 二、Front Matter 完全指南 Front matter 是文章头部的 YAML 配置块（--- 包裹）。所有字段都是可选的，不写的字段会使用 hugo.yaml 里的全局默认值。 ...

本站同一份源码部署在多个平台（GitHub Pages / Vercel / Netlify / Cloudflare Pages …）， 但主域名只有一个。本文档说明配置方式。 一、本站采用的方案：主域名统一 hugo.yaml 里 baseURL 填的是主域名： baseURL: "https://blog.646474.xyz/" 所有平台都用这一个值，构建命令不需要任何额外参数。这样做的效果： 内容 实际行为 CSS / JS 资源 用相对路径（/assets/...）→ 每个平台都能正常加载 文章图片 根相对路径（/images/...）→ 同上 canonical 统一指向 https://blog.646474.xyz/... sitemap.xml / rss.xml 统一指向主域名 分享卡片（OG / Twitter） 统一指向主域名 SEO 效果 权重集中在主域名，不存在重复内容问题 其他平台的角色 镜像 / 备用入口（访问正常，但不与主站争夺收录） 这是最省心的多平台方案：配一次，处处可用。 二、各平台配置表 平台 构建命令 输出目录 需要的环境变量 GitHub Pages hugo --gc --minify public 无（本仓库 Actions 已配好，只需 DEPLOY_TOKEN Secret） Vercel hugo --gc --minify public HUGO_VERSION = 0.167.0 Netlify hugo --gc --minify public HUGO_VERSION = 0.167.0 Cloudflare Pages hugo --gc --minify public HUGO_VERSION = 0.167.0 其他平台 hugo --gc --minify public 视平台而定 关键：HUGO_VERSION 必须填 0.167.0，且必须是 extended 版本（PaperMod 用 SCSS，标准版会构建失败）。Cloudflare Pages 默认装的即是 extended；Vercel / Netlify 需要确认。 ...

一、先说结论：工作量评估 项目 说明 文章正文 需要替换标签语法（见第二、三节），每篇约 5~15 分钟 front matter 需要调整字段（见第五节），可脚本批量处理 图片 从 source/img/ 移到 static/images/，路径前缀从 /img/ 改为 /images/ 特有功能 即刻短文、音乐播放器、首页轮播、AI 摘要、置顶卡片 PaperMod 都没有，需要自行实现或放弃 评论系统 需要重新接入（PaperMod 预留了 layouts/_partials/comments.html） 建议：先迁移 3~5 篇代表性文章，跑通流程后再批量处理。 二、新博客不能用的语法（AnZhiYu / Hexo 专有） 以下标签在 Hugo + PaperMod 中不存在，写上去会原样显示成文本（或报错），必须替换： 2.1 Hexo tag 插件（AnZhiYu 全部标签） AnZhiYu 标签 能否使用 替代方案 {% note info %} {% endnote %} ❌ {{< note info >}}…{{< /note >}}（短代码，内容支持 Markdown） {% label 文字 red %} ❌ <mark class="hl red">文字</mark>（本项目已内置样式） {% mermaid %} {% endmermaid %} ❌ ```mermaid 代码块（本项目已配置好） {% katex %} / {% mathjax %} ❌ $$公式$$（单行）或 {{< math >}}…{{< /math >}}（多行） {% tabs %} / {% endtabs %} ❌ <div class="columns">…</div>（静态两栏，本项目已内置）或删除 {% checkbox %} ❌ Markdown 任务列表 - [x] 已完成 {% timeline %} ❌ 有序列表，或自建样式 {% folding %} ❌ {{< collapse "标题" >}}内容{{< /collapse >}} {% links %} ❌ Markdown 列表 + 链接 {% btn %} / {% btns %} / {% cell %} ❌ Markdown 链接或 <a class="..."> {% tip %} ❌ <div class="note primary">…</div> {% span %} / {% u %} / {% emp %} / {% wavy %} / {% del %} / {% kbd %} / {% psw %} ❌ 原生 HTML：<u> <em> <del> <kbd> {% gallery %} ❌ 多张 {{< figure >}} 或用 Markdown 图片 {% hide %} ❌ {{< collapse >}} {% image %} / {% inlineImg %} ❌ {{< figure >}} / Markdown ![]() {% bilibili %} / {% media %} / {% dogeplayer %} ❌ {{< rawhtml >}}<iframe>…{{< /rawhtml >}} {% site %} / {% flink %} / {% iconfont %} / {% Introduction-card %} ❌ 手写 HTML 或用 rawhtml 2.2 其它 Hexo / AnZhiYu 专有写法 写法 说明 <div class="video-container">…</div> + 配套 <style> AnZhiYu 的视频自适应写法 → 改用 {{< youtube ID >}} 或 {{< video src="…" >}} <!-- more --> Hugo 用 ` ...

本文档列出本站支持的全部写作语法，每条都给出「写法」与「实际效果」对照，方便直接照着抄。 提示：右侧目录可快速跳转。 一、快速开始 新建文章（自动套用模板）： hugo new content posts/我的新文章.md 本地预览（写完保存自动刷新）： hugo server -D 推送发布（等价于原来 Hexo 的 hexo push）： ./push.sh # Git Bash push.bat # 或直接双击这个文件 二、Front Matter（文章头部配置） 写法： --- title: "文章标题" date: 2026-10-07T10:00:00+08:00 lastmod: 2026-10-07T10:00:00+08:00 draft: false description: "文章摘要，显示在列表页与搜索结果里" tags: ["标签一", "标签二"] categories: ["随笔"] keywords: ["关键词"] math: true # 开启数学公式 ShowToc: true # 显示目录 cover: image: "/images/cover/x.jpg" alt: "封面描述" caption: "封面说明" --- 说明：所有字段都可选，不写就用 hugo.yaml 里的全局默认值。draft: true 的文章不会发布。 三、文本与结构 3.1 标题 写法： ...

演示 PaperMod 支持的写作语法：提示框、折叠、数学公式、Mermaid 流程图、图片、表格等。