Zolarwind 主题实战指南在 Zola 中构建 GDPR 友好的 Tailwind CSS 博客【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zolaZolarwind 是一个以 Zola 静态站点生成器为核心的博客主题内置 Tailwind CSS、KaTeX 数学公式渲染、Mermaid 图表、本地化与客户端搜索能力且默认不发起任何第三方请求。本文以该主题的官方文档为主体结合 Zola 源码中的配置解析与渲染机制完整讲解从安装、配置、内容创作到主题集成的全流程帮助你用它在几分钟内搭建一个无 Cookie、无需同意横幅、自带暗色模式与搜索功能的现代化博客。主题概览开箱即用的功能清单Zolarwind 针对「想要 Tailwind 风格 UI、图表与公式渲染、且在意隐私合规」的博客场景设计核心功能如下GDPR 洁净默认无第三方请求、无 Cookie、无跟踪。所有 JS/CSS 均自托管因此默认的 Zolarwind 站点无需同意横幅consent banner。Tailwind CSS使用 Tailwind 构建布局与 UI。Mermaid 集成从文本渲染图表。KaTeX 集成在文章中渲染数学公式。本地化支持主题字符串存放在语言资源文件中选择需要的语言即可若语言未覆盖可自行创建资源文件补充翻译。暗色/亮色模式内置切换按钮并在用户切换后于会话期内持久化偏好仅存于sessionStorage。客户端搜索基于 Zola 的搜索索引与 MiniSearch 的本地搜索页。系列Series支持通过 taxonomy 将文章分组为系列并在系列文章底部提供有序导航。Artalk 评论可选集成自托管 Artalk 服务器详见主题内docs/artalk.md。主题截图见 screenshot.png展示了该主题在博客首页的视觉效果。版本要求与兼容性说明主题文档明确给出了一条重要的版本约束自 2026-08-07 发布的 Zola v0.23.2 起Giallo 暗色/亮色主题 CSS 的生成恢复正常该主题依赖此能力才能正常工作。本主题不兼容 Zola v0.23.1 及更早版本。因此在选用 Zolarwind 前请确认本机 Zola 版本不低于 v0.23.2。这一点与 Zola 源码中的双主题dual-theme高亮机制直接相关在 markup.rs 中当同时配置light_theme与dark_theme时Zola 会调用registry.generate_dual_css生成giallo-light.css与giallo-dark.css两个文件暗色模式依赖这一配对输出才能正确工作。环境准备Prerequisites使用 Zolarwind 所需的软件Git版本控制必备。Node.js可选仅在需要修改css/main.css并重新生成 CSS 时才需要。主题自带预编译 CSS没有 Node.js 也能完整运行。Zola静态站点生成器这是构建 Zolarwind 站点的唯一绝对必要条件版本需 ≥ v0.23.2。安装两种路径方式一独立使用快速开始将本仓库直接作为新博客的基底git clone https://github.com/thomasweitzel/zolarwind.git cd zolarwind zola serve随后在浏览器打开zola serve输出的链接即可预览。之后按需修改zola.toml中的base_url等配置。方式二作为主题集成若已有 Zola 站点想将 Zolarwind 放入themes/目录可参考本文「集成主题文件夹」一节推荐使用仓库内置的自动化脚本。配置详解zola.tomlzola.toml控制站点全部定制项。以下按主题文档的划分逐项说明。基础配置Basic Configuration配置项作用base_url站点构建目标 URL例如https://example.org需改为自己的域名。它是 Zola 唯一必需的顶层配置见 mod.rs。compile_sass是否自动编译sass目录中的 Sass 文件。本主题设为false因为主题使用预编译 Tailwind CSS无需 Sass 编译。default_language站点默认语言配置中为英语en当前i18n目录已提供德语de。Zola 默认值为en见 mod.rs。theme站点使用的主题名。配置中该行默认被注释表示主题文件直接取自templates目录独立模式若将主题移动到themes/zolarwind则填写zolarwind。build_search_index设为true时为default_language构建搜索索引。本主题开启。generate_feeds是否自动生成 Atom 订阅文件atom.xml本主题开启。Zola 默认值为false见 mod.rs。taxonomies站点的分类系统数组。此处定义了tags启用 feed与series禁用 feed分页限制均为 6。feed与paginate_by字段的默认行为可参见 taxonomies.rs。Markdown 高亮配置light_theme与dark_theme亮/暗模式下代码高亮主题。Zola 会在构建输出中生成giallo-light.css与giallo-dark.css模板同时加载两者主题切换按钮负责启用对应样式表。想让两种模式同风格将两者设为同一主题即可。Zolarwind 要求两个值都必须设置因为高亮文件在渲染 Markdown 内容的模板文章/页面中被加载若在其他模板中直接加入代码块也需要自行引入高亮文件。此约束与源码中(None, Some(light), Some(dark))分支的校验逻辑一致见 markup.rs。error_on_missing_language当要高亮的语言不存在时如何处理。设为true会让构建报错为false时 Zola 会回退为纯文本渲染源码见 markup.rs 的fallback_to_plain逻辑。style高亮输出方式可选class或inline本主题使用class枚举定义见 markup.rs。extra_grammars额外 TextMate 语法文件JSON 格式数组用于补充 Zola/Giallo 未内置的语言。主题自带上游 Caddyfile 语法作为可运行示例syntaxes/caddyfile.tmLanguage.json其 MIT 许可证位于syntaxes/caddyfile.LICENSE。源码中这些语法文件会通过registry.add_grammar_from_path加载并链接见 markup.rs。Extra 配置[extra]自定义变量[extra]存放模板可访问的自定义变量title必需站点标题示例为 Zolarwind.。path_language_resources必需语言资源文件所在目录独立模式下为i18n/移动主题后改为themes/zolarwind/i18n/。generator可选声明生成站点的工具例如Zola v0.22.1。favicon_svg可选站点 SVG favicon 路径示例指向/img/yin-yang.svg。copyright可选版权声明模板含{year}占位符会在每次zola build时替换为当前年份。site_description可选显示在站点横幅上的简短描述。quote可选由引言与作者组成的结构示例引用自 Yoda。menu_pages可选主导航菜单项数组每项含title与url。footer_pages可选页脚展示的页面数组每项含title与url。social_links可选社交链接数组每项含名称、启用布尔值、URL 与 SVG 图标。toc可选当页面 front matter 未设置extra.toc时页内目录TOC的默认开关缺省为false。toc_levels可选页内目录默认标题层级范围缺省为{ min 2, max 3 }合法范围是1..6且min必须 max越界值会被钳制。displaymode.sun与displaymode.moon可选暗/亮切换按钮使用的内联 SVG 图标。两者都定义才渲染切换按钮缺任一个则不渲染。子路径 base_url 支持主题可安全运行在子路径下如https://example.org/blog/前提是所有内部链接与资源都通过 Zola 的get_url辅助函数解析。因此模板中对 CSS、JS、图片和菜单链接统一使用get_url。zola.toml中的内部链接也应保持根相对如/pages/about/以便 Zola 可靠地拼接base_url前缀。该辅助函数在 files.rs 中实现负责把路径解析为带base_url前缀的最终 URL。若新增或调整模板避免硬编码href/...或src/...始终优先使用{{/* get_url(path/img/example.jpg) */}}子路径本地测试zola serve始终挂载在/不会模拟子路径行为。要在本地验证子路径可构建到子目录再从该目录提供静态服务zola build --base-url http://127.0.0.1:1111/demo/zolarwind -o public/demo/zolarwind python -m http.server --directory public 1111python -m http.server只是示例静态文件服务器任何能服务public/的服务器如 Apache、Nginx、static-web-server都可用。随后在浏览器打开服务器输出的链接即可。内容创作Front Matter 与 Markdown 组件文章结构约定博客文章content/blog下的 Markdown 文件每篇独占一个文件夹可将图片、视频等资源与文章放在一起。每篇文章关联一张展示图首页卡片与详情页共用未在extra.image提供图片时主题使用默认图。示例 Front Matter可将其复制到新文章如content/blog/perception-vs-math/index.md date 2026-02-05 title Intuition vs. mathematical facts description Examine the reliability of tests using probability trees and Bayes theorem. authors [Jane Doe] [taxonomies] tags [math, statistics] [extra] math true diagram true image banner.jpg 字段说明date文章日期如2026-02-05。title文章标题如Intuition vs. mathematical facts。description文章描述用作博客首页的摘要。authors可选作者数组如[Jane Doe]。可为空但为空时 feedatom.xml中首位作者将显示为Unknown。taxonomies可选支持tags与series。标签展示于文章与标签索引页系列展示于系列页及系列文章底部的系列导航。extra.mathfalse默认或true。为true时文章启用 KaTeX 公式渲染。行内公式用$...$由于 Markdown 会先处理反斜杠需要 KaTeX 收到\%百分号时应写作\\%。展示型公式使用 KaTeX 组件且组件体内不要写$$定界符{%/* katex */%} a^2 b^2 {%/* /katex */%}extra.diagramfalse默认或true。控制是否加载渲染 Mermaid 图表所需的 JavaScript为true时文章支持通过diagram组件渲染图表。extra.tocfalse默认或true。启用该文章/页面的页内目录省略时使用全局extra.toc默认值。为保证目录一致正文标题建议从##开始并仅按升序嵌套##→###→####→#####→######。extra.toc_levels可选页内目录标题层级范围的单页覆盖省略时使用全局extra.toc_levels默认值超出1..6的值会被钳制。extra.image可选文章配图省略时使用默认图展示于博客首页与文章详情页。Markdown 组件短代码Zolarwind 提供面向 Markdown 的组件存放于主题的templates/shortcodes/。按需使用而非作为排版工具完整参数与示例见主题内docs/shortcodes.mdkatex渲染展示型 KaTeX 公式。diagram从围栏文本块渲染 Mermaid 图表。image渲染带题注、可选亮/暗变体的本地图片。audio_simple主题卡片风格的原生audio播放器。audio使用捆绑 JS 控制的自定义音频播放器。系列Series有序的文章分组Zolarwind 通过 Zola taxonomy 实现系列系列文章底部会出现系列导航。配置步骤在zola.toml中启用 taxonomytaxonomies [ { name tags, paginate_by 6, feed true }, { name series, paginate_by 6, feed false }, ]系列 feed 的消费频率低于文章/标签 feed默认关闭以保持输出精简若希望订阅者跟踪系列页可自行开启。将文章归入系列[taxonomies] series [my-series]可选排序在文章 front matter 中设置extra.series_order省略时系列列表按文章日期排序。系列索引页位于/series/与/series/name/。注意若没有任何文章使用seriestaxonomyZola 不会生成/series/访问将 404——这与 Zola 对未使用 taxonomy 不渲染页面的行为一致。搜索本地客户端搜索主题自带本地、客户端搜索页数据源是 Zola 构建的搜索索引Elasticlunr 输出与 MiniSearch。Zola 默认的索引格式即为elasticlunr_javascript见 search.rs。配置步骤在zola.toml中开启搜索索引build_search_index true创建使用搜索模板的页面如content/pages/search.md。若content/pages/_index.md使用sort_by date则该页需要date或weight以免被忽略。可选设置extra.results_per_page控制分页大小、extra.pagination_window控制当前页两侧显示的页码数 date 2026-01-14 title Search template search.html [extra] results_per_page 5 pagination_window 2 页头出现搜索图标并链接到/pages/search/。注意仅当build_search_index true时才会渲染搜索图标。在其他 Zola 站点中使用本主题时需要在那个站点仓库中自行添加content/pages/search.md——Zola 不会加载主题的content/目录。搜索索引只针对当前default_language构建。若开启build_search_index却未创建content/pages/search.md搜索链接将 404。本地化单语言构建的语言资源设想页面上的文字Published on July 04, 2023; 1,234 words。若博客是德语的你希望显示为Veröffentlicht am 04. Juli 2023; 1.234 Wörter——不仅文案要翻译日期与数字格式也不同且单数形式1 word/1 Wort应被正确使用。该主题负责处理这一切。本地化步骤在zola.toml中通过default_language选择语言。当前i18n目录已提供英语en与德语de资源若语言未覆盖可新建资源文件以en.toml为模板使用正确语言代码命名如eo.toml对应世界语。主题仅支持从左到右ltr阅读的语言。主题会自动以所选语言展示全部主题级字符串。你提供的内容应与该语言匹配——这属于你的职责主题不会翻译你的正文。该主题把default_language当作构建期开关每次构建只针对单一语言环境不面向 Zola 的单次构建多语言输出。若需自定义日期格式可参考 chrono 的 strftime 规范符说明。集成主题文件夹两种方案该仓库默认是一个独立 Zola 站点。要把 Zolarwind 作为主题集成进已有网站有两条路径。方案一自动化集成推荐仓库提供辅助脚本integrate-theme-folder.sh可自动完成文件移动与配置更新已在 Linux/Bash 上测试。注意只应在 Zolarwind 的全新检出副本上运行因为它会就地移动并编辑文件。./integrate-theme-folder.sh方案二手动集成适用于偏好手动移动文件或使用非 Linux 系统的场景将相关主题文件移动到themes/zolarwind目录其余文件保留在根目录若根目录已有自己的同名文件需要与主题文件合并并相应调整根目录的zola.toml与package.json。大多数extra.*设置是可选的除title与path_language_resources但省略后相关 UI 元素不会渲染菜单、页脚链接、社交图标或主题切换按钮。若启用搜索请在站点仓库中添加content/pages/search.md主题的content/不会被 Zola 加载。独立模式下主题位于根目录的目录结构/ ├── css ├── i18n ├── static │ ├── css │ ├── img │ └── js ├── syntaxes ├── templates └── theme.toml创建themes/zolarwind目录并移动主题专属文件后站点根目录保留的内容与移动后的结构如下/ ├── static │ └── css ├── syntaxes └── themes └── zolarwind ├── css ├── i18n ├── static │ ├── img │ └── js ├── templates └── theme.toml要点说明syntaxes目录留在原位若想移动它必须同步调整zola.toml中的extra_grammars条目。static/css是特例其中存放生成的 Tailwind 文件generated.css保留在原位置。Zola 无论是否使用主题都会服务站点自己的static/目录。该文件由css/main.cssCSS 生成的输入生成。giallo-light.css与giallo-dark.css是 Zola 依据高亮主题配置在构建输出中生成的并非需要随集成移动的源文件。CSS 生成可由package.json中的脚本触发。只有当你修改了主题模板文件或在内容文件中直接使用了新的 Tailwind CSS 类时才需要调整并运行package.json中的脚本。由于源文件css/main.css已移至themes/zolarwind/css/main.css需相应调整脚本。独立站点的脚本片段scripts: { css:build: npx tailwindcss -i ./css/main.css -o ./static/css/generated.css --minify, css:watch: npx tailwindcss -i ./css/main.css -o ./static/css/generated.css --watch, server: zola serve }改为指向主题内的输入文件scripts: { css:build: npx tailwindcss -i ./themes/zolarwind/css/main.css -o ./static/css/generated.css --minify, css:watch: npx tailwindcss -i ./themes/zolarwind/css/main.css -o ./static/css/generated.css --watch, server: zola serve }同时需在zola.toml中声明主题并调整语言资源路径# The site theme to use theme zolarwind # ... # Path to the language resource files [extra] path_language_resources themes/zolarwind/i18n/开发自定义 CSS 与热更新定制 CSS 时编辑templates与css目录中的文件并确保static/css/generated.css保持最新。该文件由css/main.css与通过自动内容检测识别的文件共同生成。主题使用自定义调色板neutral、primary、ok、warn、fail替代 Tailwind 默认颜色。在模板或内容中新增类后需重新构建 CSS 以包含生成的调色板类。若某源文件默认未被扫描到可在css/main.css中用source指令添加source ../node_modules/my-company/ui-lib;文件变更后运行package.json中的css:build脚本。这需要 Node.js 与package.json中的依赖通过npm install安装。运行npm run css:watch可监听文件变化并自动触发 CSS 生成确保static/css/generated.css始终最新。建议开启两个终端一个运行 Zola 服务器zola serve另一个运行 CSS 监听脚本npm run css:watch。文件修改后浏览器会自动加载更新后的 CSS。隐私GDPR 合规设计主题不设置 Cookie也不从第三方站点加载资源。暗/亮模式偏好仅在用户显式切换后存入sessionStorage。KaTeX、Mermaid 与 MiniSearch 都捆绑在static/中可从自有域名提供并按已知版本固定。若改为从 CDN 加载需考虑以下 GDPR 影响第三方请求与数据隐私加载 CDN 资源会向 CDN 服务器发起第三方请求服务器可能记录你的 IP、User-Agent 及其他请求元数据。GDPR 下 IP 地址可能被视为个人数据。自托管可减少第三方数据传输。Cookie许多 CDN 会出于分析或性能优化设置 Cookie并可能跨站跟踪用户。自托管让你掌控 Cookie确保合规。同意Consent若 CDN 设置 Cookie 或收集数据加载前可能需要明确的用户同意这会复杂化体验并可能损害拒绝用户下的性能自托管可绕开此问题。透明与可控自托管让你确切知道所用库的版本确保无改动或意外行为CDN 存在库被篡改并波及其他站点的风险。欧盟外数据传输CDN 服务器位于欧盟之外时可能涉及数据出境合规要求自托管可确保数据不离开所在区域。补充说明Markdown 排版实现主题不使用tailwindcss/typography来排版 Markdown 文件而是在css/main.css中通过apply实现。apply是 Tailwind CSS 指令可将多个工具类组合进自定义 CSS 类中用于 Markdown 内容排版。该方式对视觉结果有更强的控制力但需要手动编写样式并复刻 typography 插件已提供的常见排版模式。贡献与许可证欢迎提交 PR 改进或新增功能尤其期待更多翻译。可查看i18n目录了解已有与缺失的语言以en.toml为模板提交新翻译。主题采用 MIT 许可证详情见其 LICENSE 文件。第三方声明HeroiconsMIT、KaTeXMIT、MermaidMIT、MiniSearchMIT、mhchemApache 2.0、Unsplash 图片Unsplash License。关键文件速查Zolarwind 主题官方文档本文依据的原始文档含完整功能清单与配置说明。主题截图主题实际渲染效果。markup.rsZola 语法高亮配置的解析与giallo-*.css生成逻辑。taxonomies.rstaxonomy 的feed、paginate_by等字段定义。mod.rsbase_url、default_language、build_search_index、generate_feeds、compile_sass等顶层配置的解析。search.rs搜索索引格式与内容包含策略。files.rsget_url辅助函数实现是子路径部署的关键。【免费下载链接】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），仅供参考 Zolarwind 主题实战指南：在 Zola 中构建 GDPR 友好的 Tailwind CSS 博客
Zolarwind 主题实战指南在 Zola 中构建 GDPR 友好的 Tailwind CSS 博客【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zolaZolarwind 是一个以 Zola 静态站点生成器为核心的博客主题内置 Tailwind CSS、KaTeX 数学公式渲染、Mermaid 图表、本地化与客户端搜索能力且默认不发起任何第三方请求。本文以该主题的官方文档为主体结合 Zola 源码中的配置解析与渲染机制完整讲解从安装、配置、内容创作到主题集成的全流程帮助你用它在几分钟内搭建一个无 Cookie、无需同意横幅、自带暗色模式与搜索功能的现代化博客。主题概览开箱即用的功能清单Zolarwind 针对「想要 Tailwind 风格 UI、图表与公式渲染、且在意隐私合规」的博客场景设计核心功能如下GDPR 洁净默认无第三方请求、无 Cookie、无跟踪。所有 JS/CSS 均自托管因此默认的 Zolarwind 站点无需同意横幅consent banner。Tailwind CSS使用 Tailwind 构建布局与 UI。Mermaid 集成从文本渲染图表。KaTeX 集成在文章中渲染数学公式。本地化支持主题字符串存放在语言资源文件中选择需要的语言即可若语言未覆盖可自行创建资源文件补充翻译。暗色/亮色模式内置切换按钮并在用户切换后于会话期内持久化偏好仅存于sessionStorage。客户端搜索基于 Zola 的搜索索引与 MiniSearch 的本地搜索页。系列Series支持通过 taxonomy 将文章分组为系列并在系列文章底部提供有序导航。Artalk 评论可选集成自托管 Artalk 服务器详见主题内docs/artalk.md。主题截图见 screenshot.png展示了该主题在博客首页的视觉效果。版本要求与兼容性说明主题文档明确给出了一条重要的版本约束自 2026-08-07 发布的 Zola v0.23.2 起Giallo 暗色/亮色主题 CSS 的生成恢复正常该主题依赖此能力才能正常工作。本主题不兼容 Zola v0.23.1 及更早版本。因此在选用 Zolarwind 前请确认本机 Zola 版本不低于 v0.23.2。这一点与 Zola 源码中的双主题dual-theme高亮机制直接相关在 markup.rs 中当同时配置light_theme与dark_theme时Zola 会调用registry.generate_dual_css生成giallo-light.css与giallo-dark.css两个文件暗色模式依赖这一配对输出才能正确工作。环境准备Prerequisites使用 Zolarwind 所需的软件Git版本控制必备。Node.js可选仅在需要修改css/main.css并重新生成 CSS 时才需要。主题自带预编译 CSS没有 Node.js 也能完整运行。Zola静态站点生成器这是构建 Zolarwind 站点的唯一绝对必要条件版本需 ≥ v0.23.2。安装两种路径方式一独立使用快速开始将本仓库直接作为新博客的基底git clone https://github.com/thomasweitzel/zolarwind.git cd zolarwind zola serve随后在浏览器打开zola serve输出的链接即可预览。之后按需修改zola.toml中的base_url等配置。方式二作为主题集成若已有 Zola 站点想将 Zolarwind 放入themes/目录可参考本文「集成主题文件夹」一节推荐使用仓库内置的自动化脚本。配置详解zola.tomlzola.toml控制站点全部定制项。以下按主题文档的划分逐项说明。基础配置Basic Configuration配置项作用base_url站点构建目标 URL例如https://example.org需改为自己的域名。它是 Zola 唯一必需的顶层配置见 mod.rs。compile_sass是否自动编译sass目录中的 Sass 文件。本主题设为false因为主题使用预编译 Tailwind CSS无需 Sass 编译。default_language站点默认语言配置中为英语en当前i18n目录已提供德语de。Zola 默认值为en见 mod.rs。theme站点使用的主题名。配置中该行默认被注释表示主题文件直接取自templates目录独立模式若将主题移动到themes/zolarwind则填写zolarwind。build_search_index设为true时为default_language构建搜索索引。本主题开启。generate_feeds是否自动生成 Atom 订阅文件atom.xml本主题开启。Zola 默认值为false见 mod.rs。taxonomies站点的分类系统数组。此处定义了tags启用 feed与series禁用 feed分页限制均为 6。feed与paginate_by字段的默认行为可参见 taxonomies.rs。Markdown 高亮配置light_theme与dark_theme亮/暗模式下代码高亮主题。Zola 会在构建输出中生成giallo-light.css与giallo-dark.css模板同时加载两者主题切换按钮负责启用对应样式表。想让两种模式同风格将两者设为同一主题即可。Zolarwind 要求两个值都必须设置因为高亮文件在渲染 Markdown 内容的模板文章/页面中被加载若在其他模板中直接加入代码块也需要自行引入高亮文件。此约束与源码中(None, Some(light), Some(dark))分支的校验逻辑一致见 markup.rs。error_on_missing_language当要高亮的语言不存在时如何处理。设为true会让构建报错为false时 Zola 会回退为纯文本渲染源码见 markup.rs 的fallback_to_plain逻辑。style高亮输出方式可选class或inline本主题使用class枚举定义见 markup.rs。extra_grammars额外 TextMate 语法文件JSON 格式数组用于补充 Zola/Giallo 未内置的语言。主题自带上游 Caddyfile 语法作为可运行示例syntaxes/caddyfile.tmLanguage.json其 MIT 许可证位于syntaxes/caddyfile.LICENSE。源码中这些语法文件会通过registry.add_grammar_from_path加载并链接见 markup.rs。Extra 配置[extra]自定义变量[extra]存放模板可访问的自定义变量title必需站点标题示例为 Zolarwind.。path_language_resources必需语言资源文件所在目录独立模式下为i18n/移动主题后改为themes/zolarwind/i18n/。generator可选声明生成站点的工具例如Zola v0.22.1。favicon_svg可选站点 SVG favicon 路径示例指向/img/yin-yang.svg。copyright可选版权声明模板含{year}占位符会在每次zola build时替换为当前年份。site_description可选显示在站点横幅上的简短描述。quote可选由引言与作者组成的结构示例引用自 Yoda。menu_pages可选主导航菜单项数组每项含title与url。footer_pages可选页脚展示的页面数组每项含title与url。social_links可选社交链接数组每项含名称、启用布尔值、URL 与 SVG 图标。toc可选当页面 front matter 未设置extra.toc时页内目录TOC的默认开关缺省为false。toc_levels可选页内目录默认标题层级范围缺省为{ min 2, max 3 }合法范围是1..6且min必须 max越界值会被钳制。displaymode.sun与displaymode.moon可选暗/亮切换按钮使用的内联 SVG 图标。两者都定义才渲染切换按钮缺任一个则不渲染。子路径 base_url 支持主题可安全运行在子路径下如https://example.org/blog/前提是所有内部链接与资源都通过 Zola 的get_url辅助函数解析。因此模板中对 CSS、JS、图片和菜单链接统一使用get_url。zola.toml中的内部链接也应保持根相对如/pages/about/以便 Zola 可靠地拼接base_url前缀。该辅助函数在 files.rs 中实现负责把路径解析为带base_url前缀的最终 URL。若新增或调整模板避免硬编码href/...或src/...始终优先使用{{/* get_url(path/img/example.jpg) */}}子路径本地测试zola serve始终挂载在/不会模拟子路径行为。要在本地验证子路径可构建到子目录再从该目录提供静态服务zola build --base-url http://127.0.0.1:1111/demo/zolarwind -o public/demo/zolarwind python -m http.server --directory public 1111python -m http.server只是示例静态文件服务器任何能服务public/的服务器如 Apache、Nginx、static-web-server都可用。随后在浏览器打开服务器输出的链接即可。内容创作Front Matter 与 Markdown 组件文章结构约定博客文章content/blog下的 Markdown 文件每篇独占一个文件夹可将图片、视频等资源与文章放在一起。每篇文章关联一张展示图首页卡片与详情页共用未在extra.image提供图片时主题使用默认图。示例 Front Matter可将其复制到新文章如content/blog/perception-vs-math/index.md date 2026-02-05 title Intuition vs. mathematical facts description Examine the reliability of tests using probability trees and Bayes theorem. authors [Jane Doe] [taxonomies] tags [math, statistics] [extra] math true diagram true image banner.jpg 字段说明date文章日期如2026-02-05。title文章标题如Intuition vs. mathematical facts。description文章描述用作博客首页的摘要。authors可选作者数组如[Jane Doe]。可为空但为空时 feedatom.xml中首位作者将显示为Unknown。taxonomies可选支持tags与series。标签展示于文章与标签索引页系列展示于系列页及系列文章底部的系列导航。extra.mathfalse默认或true。为true时文章启用 KaTeX 公式渲染。行内公式用$...$由于 Markdown 会先处理反斜杠需要 KaTeX 收到\%百分号时应写作\\%。展示型公式使用 KaTeX 组件且组件体内不要写$$定界符{%/* katex */%} a^2 b^2 {%/* /katex */%}extra.diagramfalse默认或true。控制是否加载渲染 Mermaid 图表所需的 JavaScript为true时文章支持通过diagram组件渲染图表。extra.tocfalse默认或true。启用该文章/页面的页内目录省略时使用全局extra.toc默认值。为保证目录一致正文标题建议从##开始并仅按升序嵌套##→###→####→#####→######。extra.toc_levels可选页内目录标题层级范围的单页覆盖省略时使用全局extra.toc_levels默认值超出1..6的值会被钳制。extra.image可选文章配图省略时使用默认图展示于博客首页与文章详情页。Markdown 组件短代码Zolarwind 提供面向 Markdown 的组件存放于主题的templates/shortcodes/。按需使用而非作为排版工具完整参数与示例见主题内docs/shortcodes.mdkatex渲染展示型 KaTeX 公式。diagram从围栏文本块渲染 Mermaid 图表。image渲染带题注、可选亮/暗变体的本地图片。audio_simple主题卡片风格的原生audio播放器。audio使用捆绑 JS 控制的自定义音频播放器。系列Series有序的文章分组Zolarwind 通过 Zola taxonomy 实现系列系列文章底部会出现系列导航。配置步骤在zola.toml中启用 taxonomytaxonomies [ { name tags, paginate_by 6, feed true }, { name series, paginate_by 6, feed false }, ]系列 feed 的消费频率低于文章/标签 feed默认关闭以保持输出精简若希望订阅者跟踪系列页可自行开启。将文章归入系列[taxonomies] series [my-series]可选排序在文章 front matter 中设置extra.series_order省略时系列列表按文章日期排序。系列索引页位于/series/与/series/name/。注意若没有任何文章使用seriestaxonomyZola 不会生成/series/访问将 404——这与 Zola 对未使用 taxonomy 不渲染页面的行为一致。搜索本地客户端搜索主题自带本地、客户端搜索页数据源是 Zola 构建的搜索索引Elasticlunr 输出与 MiniSearch。Zola 默认的索引格式即为elasticlunr_javascript见 search.rs。配置步骤在zola.toml中开启搜索索引build_search_index true创建使用搜索模板的页面如content/pages/search.md。若content/pages/_index.md使用sort_by date则该页需要date或weight以免被忽略。可选设置extra.results_per_page控制分页大小、extra.pagination_window控制当前页两侧显示的页码数 date 2026-01-14 title Search template search.html [extra] results_per_page 5 pagination_window 2 页头出现搜索图标并链接到/pages/search/。注意仅当build_search_index true时才会渲染搜索图标。在其他 Zola 站点中使用本主题时需要在那个站点仓库中自行添加content/pages/search.md——Zola 不会加载主题的content/目录。搜索索引只针对当前default_language构建。若开启build_search_index却未创建content/pages/search.md搜索链接将 404。本地化单语言构建的语言资源设想页面上的文字Published on July 04, 2023; 1,234 words。若博客是德语的你希望显示为Veröffentlicht am 04. Juli 2023; 1.234 Wörter——不仅文案要翻译日期与数字格式也不同且单数形式1 word/1 Wort应被正确使用。该主题负责处理这一切。本地化步骤在zola.toml中通过default_language选择语言。当前i18n目录已提供英语en与德语de资源若语言未覆盖可新建资源文件以en.toml为模板使用正确语言代码命名如eo.toml对应世界语。主题仅支持从左到右ltr阅读的语言。主题会自动以所选语言展示全部主题级字符串。你提供的内容应与该语言匹配——这属于你的职责主题不会翻译你的正文。该主题把default_language当作构建期开关每次构建只针对单一语言环境不面向 Zola 的单次构建多语言输出。若需自定义日期格式可参考 chrono 的 strftime 规范符说明。集成主题文件夹两种方案该仓库默认是一个独立 Zola 站点。要把 Zolarwind 作为主题集成进已有网站有两条路径。方案一自动化集成推荐仓库提供辅助脚本integrate-theme-folder.sh可自动完成文件移动与配置更新已在 Linux/Bash 上测试。注意只应在 Zolarwind 的全新检出副本上运行因为它会就地移动并编辑文件。./integrate-theme-folder.sh方案二手动集成适用于偏好手动移动文件或使用非 Linux 系统的场景将相关主题文件移动到themes/zolarwind目录其余文件保留在根目录若根目录已有自己的同名文件需要与主题文件合并并相应调整根目录的zola.toml与package.json。大多数extra.*设置是可选的除title与path_language_resources但省略后相关 UI 元素不会渲染菜单、页脚链接、社交图标或主题切换按钮。若启用搜索请在站点仓库中添加content/pages/search.md主题的content/不会被 Zola 加载。独立模式下主题位于根目录的目录结构/ ├── css ├── i18n ├── static │ ├── css │ ├── img │ └── js ├── syntaxes ├── templates └── theme.toml创建themes/zolarwind目录并移动主题专属文件后站点根目录保留的内容与移动后的结构如下/ ├── static │ └── css ├── syntaxes └── themes └── zolarwind ├── css ├── i18n ├── static │ ├── img │ └── js ├── templates └── theme.toml要点说明syntaxes目录留在原位若想移动它必须同步调整zola.toml中的extra_grammars条目。static/css是特例其中存放生成的 Tailwind 文件generated.css保留在原位置。Zola 无论是否使用主题都会服务站点自己的static/目录。该文件由css/main.cssCSS 生成的输入生成。giallo-light.css与giallo-dark.css是 Zola 依据高亮主题配置在构建输出中生成的并非需要随集成移动的源文件。CSS 生成可由package.json中的脚本触发。只有当你修改了主题模板文件或在内容文件中直接使用了新的 Tailwind CSS 类时才需要调整并运行package.json中的脚本。由于源文件css/main.css已移至themes/zolarwind/css/main.css需相应调整脚本。独立站点的脚本片段scripts: { css:build: npx tailwindcss -i ./css/main.css -o ./static/css/generated.css --minify, css:watch: npx tailwindcss -i ./css/main.css -o ./static/css/generated.css --watch, server: zola serve }改为指向主题内的输入文件scripts: { css:build: npx tailwindcss -i ./themes/zolarwind/css/main.css -o ./static/css/generated.css --minify, css:watch: npx tailwindcss -i ./themes/zolarwind/css/main.css -o ./static/css/generated.css --watch, server: zola serve }同时需在zola.toml中声明主题并调整语言资源路径# The site theme to use theme zolarwind # ... # Path to the language resource files [extra] path_language_resources themes/zolarwind/i18n/开发自定义 CSS 与热更新定制 CSS 时编辑templates与css目录中的文件并确保static/css/generated.css保持最新。该文件由css/main.css与通过自动内容检测识别的文件共同生成。主题使用自定义调色板neutral、primary、ok、warn、fail替代 Tailwind 默认颜色。在模板或内容中新增类后需重新构建 CSS 以包含生成的调色板类。若某源文件默认未被扫描到可在css/main.css中用source指令添加source ../node_modules/my-company/ui-lib;文件变更后运行package.json中的css:build脚本。这需要 Node.js 与package.json中的依赖通过npm install安装。运行npm run css:watch可监听文件变化并自动触发 CSS 生成确保static/css/generated.css始终最新。建议开启两个终端一个运行 Zola 服务器zola serve另一个运行 CSS 监听脚本npm run css:watch。文件修改后浏览器会自动加载更新后的 CSS。隐私GDPR 合规设计主题不设置 Cookie也不从第三方站点加载资源。暗/亮模式偏好仅在用户显式切换后存入sessionStorage。KaTeX、Mermaid 与 MiniSearch 都捆绑在static/中可从自有域名提供并按已知版本固定。若改为从 CDN 加载需考虑以下 GDPR 影响第三方请求与数据隐私加载 CDN 资源会向 CDN 服务器发起第三方请求服务器可能记录你的 IP、User-Agent 及其他请求元数据。GDPR 下 IP 地址可能被视为个人数据。自托管可减少第三方数据传输。Cookie许多 CDN 会出于分析或性能优化设置 Cookie并可能跨站跟踪用户。自托管让你掌控 Cookie确保合规。同意Consent若 CDN 设置 Cookie 或收集数据加载前可能需要明确的用户同意这会复杂化体验并可能损害拒绝用户下的性能自托管可绕开此问题。透明与可控自托管让你确切知道所用库的版本确保无改动或意外行为CDN 存在库被篡改并波及其他站点的风险。欧盟外数据传输CDN 服务器位于欧盟之外时可能涉及数据出境合规要求自托管可确保数据不离开所在区域。补充说明Markdown 排版实现主题不使用tailwindcss/typography来排版 Markdown 文件而是在css/main.css中通过apply实现。apply是 Tailwind CSS 指令可将多个工具类组合进自定义 CSS 类中用于 Markdown 内容排版。该方式对视觉结果有更强的控制力但需要手动编写样式并复刻 typography 插件已提供的常见排版模式。贡献与许可证欢迎提交 PR 改进或新增功能尤其期待更多翻译。可查看i18n目录了解已有与缺失的语言以en.toml为模板提交新翻译。主题采用 MIT 许可证详情见其 LICENSE 文件。第三方声明HeroiconsMIT、KaTeXMIT、MermaidMIT、MiniSearchMIT、mhchemApache 2.0、Unsplash 图片Unsplash License。关键文件速查Zolarwind 主题官方文档本文依据的原始文档含完整功能清单与配置说明。主题截图主题实际渲染效果。markup.rsZola 语法高亮配置的解析与giallo-*.css生成逻辑。taxonomies.rstaxonomy 的feed、paginate_by等字段定义。mod.rsbase_url、default_language、build_search_index、generate_feeds、compile_sass等顶层配置的解析。search.rs搜索索引格式与内容包含策略。files.rsget_url辅助函数实现是子路径部署的关键。【免费下载链接】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），仅供参考