从这里开始

这个站点怎么组织、怎么发布、改哪里。第一篇先当说明书用。

这是一个 Hugo + Stack 主题搭起来的博客骨架。这篇文章的作用是:三个月后你(或者帮你维护的人)回来看,能立刻知道每个文件是干什么的。

目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
blog/
├── config/_default/       # 站点配置,按职责拆成 4 个文件
│   ├── hugo.toml          # 基础:域名、语言、永久链接
│   ├── params.toml        # 主题参数:侧栏、卡片、组件
│   ├── menu.toml          # 导航与社交图标
│   ├── markup.toml        # Markdown 渲染 / 代码高亮
│   └── related.toml       # 相关文章排序权重
├── content/
│   ├── post/              # 文章(每篇一个目录)
│   │   └── start-here/
│   │       └── index.md   # 只放正文;本站不用封面图
│   └── page/              # 关于 / 归档 / 搜索 等固定页
├── assets/
│   ├── scss/custom.scss   # 所有视觉改动只写这里
│   └── img/avatar.png
└── themes/stack/          # git submodule,不要改

写一篇新文章

1
hugo new post/文章目录名/index.md

生成后直接写正文。本站不用封面图,front matter 里不要写 image:——写了但图不存在,主题会把 Featured image of post 标题 这串 alt 文字当内容显示在卡片上,看起来像多了一行标题。

用目录而不是单个 .md 文件,是为了让将来要放的文章配图跟着文章走——迁移、删除、备份都不会留下孤儿图。

图片要不要跟正文同目录

Hugo 的图片处理(缩放、生成 srcset、构建期取主色)只对页面资源生效,也就是和 index.md 同目录的文件。放在 static/ 里的图片会被原样拷贝,既不压缩也不生成多分辨率版本。

正文用图建议还是放同目录。几百张之后,更合理的做法是放到对象存储或图床,Markdown 里直接写完整 URL。

常用命令

1
2
3
hugo server -D          # 本地预览,含草稿
hugo --gc --minify      # 生产构建到 public/
hugo new post/xxx/index.md

构建产物在 public/,已加入 .gitignore。部署时把它同步到服务器即可,不需要在服务器上装任何运行时。

记一笔字数

中文写作时 Hugo 的 .Summary 依赖 hasCJKLanguage = true,已在 hugo.toml 里打开。没开的话,摘要会按空格切词,中文会被当成一个超长单词处理,首页摘要全部失效。

配置项作用当前值
hasCJKLanguage中文分词与字数统计true
pagination.pagerSize每页文章数6
permalinks.post文章 URL 规则/p/:slug/

改配色不要去动 themes/stack,全部写在 assets/scss/custom.scss 里——主题升级时你的改动不会被覆盖。