从一个空目录到能跑起来的博客,中间踩的坑都记在这儿。

为什么用 Hugo

静态站点没有数据库、没有后台,写完 Markdown 提交仓库就完事。构建一次通常不到一秒,改完立刻能看到效果,写东西的时候不会被工具打断。

备注

主题支持 GitHub 原生风格的提示块,> [!NOTE]、> [!TIP]、> [!WARNING] 都可以直接用。

怎么写一篇新文章

在项目根目录执行:

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

生成的草稿默认 draft: true,本地预览加 -D 就能看到,正式构建时会被忽略。

文章开头的 Front Matter 常用字段:

---
title: 标题
date: 2026-11-12
draft: false
categories: ["技术"]
tags: ["Hugo", "Markdown"]
summary: 列表页显示的摘要,留空会自动截取正文
pin: 1          # 置顶,正整数,越小越靠前
ShowToc: true   # 是否显示目录
cover:
  image: cover.jpg   # 同目录下的封面图
  alt: 封面
---

几个小约定

字段作用
pin首页置顶,数字越小越前
summary列表摘要,不写则自动截断
cover.image封面图,和文章放同一目录即可

文章里的图片放在 posts/文章名/ 目录下,用相对路径引用就行,主题会自动做灯箱和尺寸优化。

建议

搜索用的是 Pagefind,构建后跑一次索引脚本才能搜到内容,具体命令见项目根目录的 README。

先写到这,接下来慢慢填内容。