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

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/zolaTerminimal 是 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 经典主题 TerminalRadosław Kozieł / panr 作品的一个fork而非移植在保留原主题 5 套配色、image/figure短代码与完全响应式布局的同时做了大量针对 Zola 的改造。从主题元数据front matter可以确认其关键要求最低 Zola 版本minimum_version 0.11.0实测版本文档标注 Tested with Zola v0.19.2许可证MITHack 字体另有独立的 LICENSE-Hack.md 说明文章后面会提及零 JavaScript主题徽标即注明 JavaScript: none所有交互与样式全部由静态 HTML 编译后的 CSS 完成。需要特别说明的是Zola 各版本之间存在破坏性变更breaking changes文档明确提示较早或较晚的版本可能无法正常工作因此实际使用时建议以当前仓库对应的 Zola 版本为准并留意主题的 release 变更记录。这一特性决定了两类典型适用场景追求极致加载速度的静态博客没有 JS 预处理器、没有第三方 CDN静态资源随站点一同托管强调可访问性与毛坯/粗野主义审美的个人主页所有链接带下划线、内容居中、排版朴素符合 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: OptionString是Config结构体的直接字段解析时要求键位于 TOML 根层级compile_sass同样位于顶层components/config/src/config/mod.rs 中其注释明确是否编译sass目录并把产出的 CSS 写入static文件夹默认值为false。Terminimal 的全部样式来自 Sass因此必须设为true否则站点将没有任何样式。安装完成后主题名称即目录名terminimal与 Zola 官方规则一致themes下的目录名就是配置中的主题名。如果克隆到其他目录名请在theme中对应修改。主题自带的两个短代码image 与 figureTerminimal 针对图片处理提供了两个自定义短代码均可直接在 Markdown 内容中使用需要在templates/shortcodes/下按 Zola 短代码机制注册注意示例中{{/* ... */}}是文档防止被模板引擎提前渲染的写法实际书写时应去掉注释符号。image短代码必填参数只有src可选参数包括alt、positioncenter为默认值另可选left/right与style内联 CSS 样式{{/* image(src/img/hello.png, altHello Friend, positionleft, styleborder-radius: 8px;) */}}figure短代码figure与image用法相同但额外支持带说明文字的 4 个可选参数caption图片说明支持 Markdown 语法caption_position说明文字对齐方式center为默认另可选left/rightcaption_style说明文字的内联样式以及image已有的style、position等参数。示例{{/* figure(srchttp://rustacean.net/assets/rustacean-flat-gesture.png, stylewidth: 25%;, positionright, caption_positionleft, caption**Ferris**, the (unofficial) Rust mascot, caption_stylefont-style: italic;) */}}为文章配置 OpenGraph 社交分享图社交平台抓取链接时依赖 OpenGraph 协议读取meta propertyog: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: HashMapString, 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 themelogo_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 customnbsp;bcopyright/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 源码中其类型为Optionusize且只有大于 0 时才生效components/content/src/front_matter/section.rssort_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 moreenable_post_view_navigation控制文章底部是否显示上一篇/下一篇链接默认truepost_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 sites 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.titlepage_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 namedescription contentMy awesome website/ meta namekeywords contentHacking,Programming,Ranting/ {%/* endblock */%}关键点extends路径形如terminimal/templates/index.html即主题名 templates/前缀通过覆写extra_head这类命名块可在不 fork 主题的前提下注入自定义内容同理也可以覆盖主题的静态资源如 CSS/JS只需在站点static目录放置同名文件。无 JavaScript 设计fork 与原主题的差异Terminimal 相对其前身 TerminalHugo 主题的主要变化既是设计取舍也是性能优势布局与样式调整内容改为居中原为左对齐页眉条纹间距加大分页样式调整尤其是小屏移动端下的表现文章标题下划线由双点线改为虚线所有链接加下划线遵循 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、redimage与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 及以上的提示。快速上手清单安装git clone terminimal 仓库 themes/terminimal或用git submodule addCI 场景更佳配置config.toml顶层设置theme terminimal与compile_sass true定制配色与站标[extra]中设置accent_color、background_color、logo_text、logo_home_link添加菜单与标签配置menu_items数组与taxonomies [{name tags}]开启分页content/_index.md设置paginate_by与sort_by[extra]中调整enable_post_view_navigation与post_view_navigation_prompt完善站点信息设置favicon、page_titles、default_language、author/copyright_html需要扩展时用{% 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考