企业官网建设流程全解析

Zola 主题实践指南：Terminimal 复古极简主题的安装、配置与二次开发

【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zola

Terminimal 是 Zola 生态中一款主打"极简复古"风格的第三方主题，它在无任何 JavaScript 的前提下，通过 Zola 自带的 Sass 预处理能力完成全部样式渲染。本指南以 Terminimal 主题文档 为核心骨架，结合 Zola 源码与官方主题文档，完整讲解该主题的安装流程、image/figure短代码、OpenGraph 配置，以及从配色、菜单、分页到版权、favicon、页面标题的全量[extra]配置项，最后介绍基于命名块（block）的模板扩展方法与无 JavaScript 设计理念。

主题概况与适用场景

Terminimal 是 Zola 主题列表中收录的一页式主题卡片（位于 docs/content/themes/zola-theme-terminimal/index.md），由 Paweł Romanowski 开发，采用 MIT 协议。它是 Hugo 经典主题 Terminal（Radosław Kozieł / panr 作品）的一个fork（而非移植），在保留原主题 5 套配色、image/figure短代码与完全响应式布局的同时，做了大量针对 Zola 的改造。

从主题元数据（front matter）可以确认其关键要求：

• 最低 Zola 版本：minimum_version = "0.11.0"；
• 实测版本：文档标注 "Tested with Zola v0.19.2"；
• 许可证：MIT（Hack 字体另有独立的 LICENSE-Hack.md 说明，文章后面会提及）；
• 零 JavaScript：主题徽标即注明 "JavaScript: none"，所有交互与样式全部由静态 HTML + 编译后的 CSS 完成。

需要特别说明的是，Zola 各版本之间存在破坏性变更（breaking changes），文档明确提示较早或较晚的版本可能无法正常工作，因此实际使用时建议以当前仓库对应的 Zola 版本为准，并留意主题的 release 变更记录。

这一特性决定了两类典型适用场景：

1. 追求极致加载速度的静态博客：没有 JS 预处理器、没有第三方 CDN，静态资源随站点一同托管；
2. 强调可访问性与"毛坯/粗野主义"审美的个人主页：所有链接带下划线、内容居中、排版朴素，符合 Brutalist Web Design 原则。

安装主题：克隆、子模块与配置三步走

Zola 官方的主题安装方式（见 docs/content/documentation/themes/installing-and-using-themes.md）是将其仓库克隆进站点的themes目录。Terminimal 文档提供了两种安装途径：

方式 A：直接克隆

$ git clone https://github.com/pawroman/zola-theme-terminimal.git themes/terminimal

方式 B：作为 Git 子模块引入（推荐用于使用 CI 构建的场景）

$ git submodule add https://github.com/pawroman/zola-theme-terminimal.git themes/terminimal

随后在config.toml中启用主题，并打开 Sass 编译：

theme = "terminimal" # Sass compilation is required compile_sass = true

这里有两个关键点需要结合 Zola 源码理解：

• theme必须写在配置文件顶层，而非某个[xxx]字典内部。在 components/config/src/config/mod.rs 中，theme: Option<String>是Config结构体的直接字段，解析时要求键位于 TOML 根层级；
• compile_sass同样位于顶层，components/config/src/config/mod.rs 中其注释明确：是否编译sass目录并把产出的 CSS 写入static文件夹，默认值为false。Terminimal 的全部样式来自 Sass，因此必须设为true，否则站点将没有任何样式。

安装完成后，主题名称即目录名terminimal（与 Zola 官方规则一致：themes下的目录名就是配置中的主题名）。如果克隆到其他目录名，请在theme中对应修改。

主题自带的两个短代码：image 与 figure

Terminimal 针对图片处理提供了两个自定义短代码，均可直接在 Markdown 内容中使用（需要在templates/shortcodes/下按 Zola 短代码机制注册；注意示例中{{/* ... */}}是文档防止被模板引擎提前渲染的写法，实际书写时应去掉注释符号）。

image短代码

必填参数只有src，可选参数包括alt、position（center为默认值，另可选left/right）与style（内联 CSS 样式）：

{{/* image(src="/img/hello.png", alt="Hello Friend", position="left", style="border-radius: 8px;") */}}

figure短代码

figure与image用法相同，但额外支持带说明文字的 4 个可选参数：

• caption：图片说明，支持 Markdown 语法；
• caption_position：说明文字对齐方式，center为默认，另可选left/right；
• caption_style：说明文字的内联样式；
• 以及image已有的style、position等参数。

示例：

{{/* figure(src="http://rustacean.net/assets/rustacean-flat-gesture.png", style="width: 25%;", position="right", caption_position="left", caption="**Ferris**, the (unofficial) Rust mascot", caption_style="font-style: italic;") */}}

为文章配置 OpenGraph 社交分享图

社交平台抓取链接时依赖 OpenGraph 协议读取<meta property="og:image">。Terminimal 通过 front matter 的extra字段支持两种图片配置：

单篇文章专属图：在文章 front matter 中指定与 Markdown 文件同目录的图片文件名：

[extra] og_image = "colocated_image.png"

站点/栏目级兜底图：为 section 页面以及没有设置og_image的文章提供默认分享图，路径相对于站点根目录（如static目录下的图片）：

[extra] default_og_image = "static/ocean.jpg"

完整配置手册：从配色到页面标题

Terminimal 将几乎所有可定制项收敛到config.toml的[extra]段。Zola 在解析配置时会把extra中的键值对原样透传给模板（components/config/src/config/mod.rs 中extra: HashMap<String, Toml>），因此这些主题自定义项与 Zola 内置配置完全解耦。以下逐项说明。

首页仅显示文章描述

默认情况下，首页文章列表会渲染摘要（summary）。若希望某个帖子在首页只显示其description，在文章 front matter 中设置：

description = "test description" [extra] show_only_description = true

设置后，该帖子首页显示test description而非摘要。

配色：强调色与背景色

强调色（accent）与背景色（background）均可配置，默认均为blue。

[extra] # One of: blue, green, orange, pink, red. # Defaults to blue. # Append -light for light themes, e.g. blue-light # Or append -auto, e.g. blue-auto accent_color = "green" # One of: blue, dark, green, orange, pink, red, light, auto # Enabling dark background will also modify primary font color to be darker. # Defaults to accent color (or, if not accent color specified, to blue). background_color = "dark"

要点：

• 强调色可选blue（默认）、green、orange、pink、red，可追加-light（浅色变体）或-auto（跟随系统深浅色偏好）；
• 背景色在强调色的基础上额外支持dark与light两种独立取值；启用dark背景时，正文主字体颜色会自动变深以保证对比度；
• 背景色未指定时默认跟随强调色（强调色也未指定时回到blue）。

站标文字与链接

[extra] # The logo text - defaults to "Terminimal theme" logo_text = "My blog" # The logo link - defaults to base_url. logo_home_link = "/take/me/away!"

logo_text默认值为 "Terminimal theme"，logo_home_link默认指向base_url。

版权信息：作者名或自定义 HTML

页脚版权默认文本由作者名、当前年份和指向主题的链接构成，可用author定制作者名：

[extra] # Author name: when specified, modifies the default # copyright text. Apart from author, it will # contain current year and a link to the theme. author = "My Name"

若想完全接管版权区，使用copyright_html直接输出 HTML，它会整体替换默认版权文本与作者名：

[extra] # Copyright text in HTML format. If specified, # entirely replaces default copyright and author. copyright_html = "My custom&nbsp;<b>copyright</b>"

静态菜单

菜单是可选的、静态的（所有条目在任何屏幕尺寸下都展示，无折叠按钮，这与零 JS 设计一脉相承），完全由用户配置。只要添加menu_items数组即启用：

[extra] # menu is enabled by adding menu_items (optional) menu_items = [ # each of these is optional, name and url are required # $BASE_URL is going to be substituted by base_url from configuration {name = "blog", url = "$BASE_URL"}, # tags should only be enabled if you have "tags" taxonomy # see documentation below for more details {name = "tags", url = "$BASE_URL/tags"}, {name = "archive", url = "$BASE_URL/archive"}, {name = "about me", url = "$BASE_URL/about"}, # set newtab to true to make the link open in new tab {name = "github", url = "url-to-your-github", newtab = true}, ]

要点：

• 每个条目的name与url必填，其余可选；
• 字符串$BASE_URL会被替换为配置中的base_url；
• 设newtab = true可让链接在新标签页打开；
• 菜单支持"当前 section 高亮"：处于某个栏目时，对应菜单链接会变色标识，这是纯模板层实现的静态效果，无需脚本。

启用标签（tags）分类

主题可选支持标签。在config.toml顶层创建tags分类：

taxonomies = [ {name = "tags"}, ]

启用后 Zola 会生成/tags页面（Zola 内置的 taxonomy 列表/单项模板机制），标签也会出现在archive归档区。注意：仍需手动在menu_items中添加指向/tags的菜单项。

分页：首页分页与文章间导航

分页对文章列表（站点首页）与文章内部（上一篇/下一篇）均提供完整支持，需要两步配置。

第一步：在content/_index.md的 front matter 中开启首页分页：

+++ # number of pages to paginate by paginate_by = 2 # sorting order for pagination sort_by = "date" +++

• paginate_by表示每页文章数；Zola 源码中其类型为Option<usize>，且只有大于 0 时才生效（components/content/src/front_matter/section.rs）；
• sort_by = "date"表示按日期从新到旧排序。Zola 的SortBy枚举（components/content/src/types.rs）还支持update_date、title、title_bytes、weight、slug、permalink与none等多种排序键。

第二步：在config.toml的[extra]中调整主题的分页文案：

[extra] # Whether to show links to earlier and later posts # on each post page (defaults to true). enable_post_view_navigation = true # The text shown at the bottom of a post, # before earlier/later post links. # Defaults to "Thanks for reading! Read other posts?" post_view_navigation_prompt = "Read more"

enable_post_view_navigation控制文章底部是否显示上一篇/下一篇链接（默认true）；post_view_navigation_prompt自定义其上方提示文案，默认 "Thanks for reading! Read other posts?"。

语言代码

Terminimal 不支持国际化/翻译，但可设置站点的 HTML 语言代码：

default_language = "en"

该键是 Zola 配置的顶层字段（components/config/src/config/mod.rs 中default_language默认值为"en"），主题据此渲染<html lang="...">。

Hack 字体子集与全 Unicode

主题默认使用 Hack 字体的混合子集：常规字重使用完整字符集（以便渲染 Unicode 图标与特殊符号），而粗体、斜体等其他字重只使用受限子集。这样能显著减小字体传输体积，但子集可能缺少你需要的某些 Unicode 字符。

需要完整 Unicode 支持时开启：

[extra] # Use full Hack character set, not just a subset. # Switch this to true if you need full unicode support. # Defaults to false. use_full_hack_font = true

默认为false。Hack 字体本身的 WebFont 用法可参考其官方文档（仓库内附有 LICENSE-Hack.md）。

全局 Favicon

主题支持为全站设置统一的 favicon：

# Optional: Global favicon URL and mimetype. # Mimetype defaults to "image/x-icon". # The URL should point at a file located # in your site's "static" directory. favicon = "/favicon.png" favicon_mimetype = "image/png"

注意这两项位于config.toml顶层（非[extra]）：favicon指向static目录中的文件（以/开头），favicon_mimetype可选，默认"image/x-icon"。

页面标题（<title>）渲染策略

主题允许配置<title>的渲染方式：

# Optional: Set how <title> elements are rendered. # Values: # - "main_only" -- only the main title (`config.title`) is rendered. # - "page_only" -- only the page title (if defined) is rendered, # falling back to `config.title` if not defined or empty. # - "combined" -- combine like so: "page_title | main_title", # or if page_title is not defined or empty, fall back to `main_title` # # Note that the main (index) page only has the main title. page_titles = "combined"

取值说明：

• main_only：只输出主标题（config.title）；
• page_only：只输出页面标题，若未定义或为空则回退到主标题；
• combined（推荐）：渲染为页面标题 | 主标题，页面标题缺失时回退为主标题；首页由于没有页面标题，始终只显示主标题。

扩展主题：基于命名块覆盖模板

Terminimal 的每个模板都定义了命名块（named blocks），因此无需修改主题文件即可完成常见定制——这符合 Zola 官方主题定制规范（docs/content/documentation/themes/installing-and-using-themes.md 中 "Customizing a theme" 一节）：任何主题文件都可被站点templates或static目录下的同名文件覆盖，也可以{% extends %}主题模板只重写部分 block。

例如，想向基础模板index.html添加额外的<meta>标签，在站点templates/index.html中写入：

{%/* extends "terminimal/templates/index.html" */%} {%/* block extra_head */%} <meta name="description" content="My awesome website"/> <meta name="keywords" content="Hacking,Programming,Ranting"/> {%/* endblock */%}

关键点：

• extends路径形如"terminimal/templates/index.html"，即主题名 +templates/前缀；
• 通过覆写extra_head这类命名块，可在不 fork 主题的前提下注入自定义内容；
• 同理，也可以覆盖主题的静态资源（如 CSS/JS），只需在站点static目录放置同名文件。

无 JavaScript 设计：fork 与原主题的差异

Terminimal 相对其前身 Terminal（Hugo 主题）的主要变化，既是设计取舍也是性能优势：

布局与样式调整

• 内容改为居中（原为左对齐）；
• 页眉条纹间距加大；
• 分页样式调整，尤其是小屏（移动端）下的表现；
• 文章标题下划线由双点线改为虚线；
• 所有链接加下划线，遵循 Brutalist Web Design Guidelines；
• 页眉字号与页脚细节微调。

工程与依赖

• 绝对零 JavaScript：不需要任何 JS 预处理，Zola 及其 Sass 预处理器是唯一依赖；没有菜单触发器，全部是静态内容，加载极快；
• 不支持 Prism.js 语法高亮：可改用 Zola 内置的语法高亮（需在配置中开启，参见 docs/content/documentation/content/syntax-highlighting.md）；
• 移除所有社交媒体引用（如 Twitter）；
• 移除所有外部 URL 引用（如 Google CDN）：主题静态资源一律随站点本身托管；
• 默认字体改为 Hack；
• 默认配色由橙改为蓝。

新增特性

• 强调色与背景色可自由选择，并新增dark背景；
• 当前 section 菜单链接静态高亮（模板层实现）。

保留特性

• 5 套配色主题：blue（默认）、green、orange、pink、red；
• image与figure短代码；
• 完全响应式布局。

版本管理与许可信息

• 主题从 v1.0.0 起遵循 语义化版本控制；此前通过拉取 master 分支使用。升级前建议查看 release 变更记录，确认是否存在破坏性变更；
• 主题本体以 MIT 协议发布（Copyright © 2019 Paweł Romanowski，原主题 Copyright © 2019 Radosław Kozieł），许可细节见 LICENSE-Hack.md 配套说明；
• 主题卡片页面（docs/content/themes/zola-theme-terminimal/index.md）还注明该主题在 Zola 官方主题列表中的元数据（minimum_version、license、demo、repository等），这些字段由 docs/templates/theme.html 渲染为卡片信息，包括"需要 Zola 版本 X 及以上"的提示。

快速上手清单

1. 安装：git clone <terminimal 仓库> themes/terminimal或用git submodule add（CI 场景更佳）；
2. 配置：config.toml顶层设置theme = "terminimal"与compile_sass = true；
3. 定制配色与站标：[extra]中设置accent_color、background_color、logo_text、logo_home_link；
4. 添加菜单与标签：配置menu_items数组与taxonomies = [{name = "tags"}]；
5. 开启分页：content/_index.md设置paginate_by与sort_by，[extra]中调整enable_post_view_navigation与post_view_navigation_prompt；
6. 完善站点信息：设置favicon、page_titles、default_language、author/copyright_html；
7. 需要扩展时，用{% extends "terminimal/templates/..." %}覆写命名块，而不是直接改动themes目录内的文件（直接修改会导致升级困难且实时预览不生效，参见 docs/content/documentation/themes/installing-and-using-themes.md）。

完成以上步骤后，即可zola build（或开发时zola serve）生成一个零 JavaScript、全静态、加载极快的复古极简站点。

【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zola