给 Zola 博客换上 serene 主题

2026-05-05

本博客的第一篇文章介绍了如何从零搭建 Zola 博客——手写模板、自建样式。但维护一套完整的模板工作量不小。于是我把目光投向了现成主题。

选主题

Zola 官方市场有 120+ 个主题。我的筛选条件：

  • 文档类风格：左侧导航 + 内容区 + 右侧目录
  • 维护活跃：最近一年内有提交
  • Star 数高

我写了个脚本扫了一遍所有主题的 GitHub 数据，按 star 降序取前 10，过滤掉两年以上没更新的。最终选了 serene：

指标值
Star355（Zola 主题最高）
最后提交2026-02-14
类型个人博客 / 文档

Serene 的设计干净、有暗色模式、自带搜索和目录。虽然它不是严格意义上的文档主题，但它的 prose.html 模板可以很好地承载文档内容。

安装主题

Serene 的 GitHub 仓库提供了两种安装方式。先试了 Git 子模块：

git submodule add -b latest https://github.com/isunjn/serene.git themes/serene

但服务器连 GitHub 的速度太慢，clone 超时了。改为手动下载：

curl -sL https://github.com/isunjn/serene/archive/refs/heads/latest.tar.gz -o /tmp/serene.tar.gz
tar xzf /tmp/serene.tar.gz -C /tmp
cp -r /tmp/serene-latest themes/serene

手动下载的好处是不依赖 Git，在任何环境都能装。缺点是后续更新需要手动重复这个过程，而子模块只需 git submodule update --remote。

配置

Serene 自带一个 config.example.toml，复制过来改：

cp themes/serene/config.example.toml zola.toml

然后根据本博客的情况修改：

  1. base_url → https://blog.logfun.xyz
  2. title → LLS Blog
  3. description → 记录技术、编程与生活的点滴
  4. default_language → zh
  5. blog_section_path → /blog（我原来就用这个路径，保持一致）

关键配置项说明：

[extra]
sections = [
  { name = "blog", path = "/blog", is_external = false },
]
blog_section_path = "/blog"

force_theme = false       # false=跟随系统/手动切换
footer_credits = true     # 显示 "Powered by Zola & Serene"

force_theme 如果设为 "light" 或 "dark" 会锁定一个模式，设为 false 则用户可自由切换。

设置首页

Serene 的首页不是自动生成的，需要在 content/_index.md 里配置：

+++
template = "home.html"

[extra]
lang = "zh"

name = "lss6378"
bio = "写代码，写博客，写生活"
avatar = "img/avatar.webp"
links = [
  { name = "GitHub", icon = "github", url = "https://github.com/lss6378" },
]

recent = true
recent_max = 10
+++

avatar = "img/avatar.webp" 指的是 static/img/avatar.webp。如果没有头像文件，主题会显示一个占位框。头像建议用 webp 格式，体积小加载快。

迁移博客内容

原来的内容结构是：

content/
└── blog/
    ├── _index.md
    ├── zola-blog-setup-guide.md
    └── zola-theme-custom-domain.md

Serene 要求博客内容放在 content/blog/ 下，这刚好和我原来的结构一致，不需要移动文件。但需要调整两个地方：

博客分区 _index.md

Serene 的博客模板叫 blog.html，文章页模板叫 post.html：

+++
title = "博客"
description = "技术、编程与生活"
sort_by = "date"
template = "blog.html"
page_template = "post.html"
insert_anchor_links = "right"
generate_feeds = true

[extra]
lang = "zh"
title = "博客"
subtitle = "记录技术与生活"
date_format = "%Y-%m-%d"
toc = true
back_to_top = true
copy = true
+++

文章 front matter

Serene 的文章 front matter 比 Zola 默认多了一些字段。主要是 [extra] 里的配置项：

[extra]
lang = "zh"
toc = true        # 显示目录
comment = false   # 关闭评论
copy = true       # 代码块显示复制按钮

Serene 还支持 featured、math、mermaid、outdate_alert 等。

构建

删掉旧的模板和样式文件，让 serene 接管：

rm -rf templates/ sass/
zola build

第一次构建会编译 serene 的 SCSS，生成 main.css。看到输出行显示 "2 pages, 1 section"，说明一切正常。

打开浏览器访问首页，头像、名称、bio、最近文章列表都正确渲染。暗色模式切换也正常工作。

自定义域名

主题切换不影响域名配置。Caddyfile 不需要任何改动，继续用原来的配置：

blog.logfun.xyz {
    encode zstd gzip
    root * /home/ubuntu/blog/lls_blog/public
    file_server
    tls lss6378@gmail.com
}

唯一要注意的是重新构建后 Caddy 不需要重启——它直接从 public/ 目录读文件。

总结

从自建模板切换到 serene 的整个过程大约 30 分钟：

步骤时间
下载主题2 分钟
配置 zola.toml5 分钟
设置首页5 分钟
迁移内容10 分钟
调整调试8 分钟

Serene 的代码质量很高，CSS 变量体系完善，暗色模式、代码复制、目录导航等都是开箱即用。如果你想给自己的 Zola 博客换个主题，serene 是个很好的起点。

https://blog.logfun.xyz/blog/feed.xml