Zola 模板开发要点与 Markdown 语法速查

2026-06-21T00:00:00+00:00

本文分两部分：Zola 模板的核心机制（结合 Zola 官方文档</a> 与本站实践），以及参考 daudix.one/content</a> 整理的 Markdown / Shortcode 写法示例。本站使用 ametrine</a> 主题（源自 Duckquill 系），示例均可在本仓库直接复现。

一、Zola 模板：目录与优先级</h2>
Zola 的模板引擎是 Tera（语法接近 Jinja2 / Liquid）。站点根目录结构：
. ├── config.toml # 全局配置 ├── content/ # Markdown 内容（按 section 组织） ├── templates/ # 站点级模板（优先级高于 theme） ├── static/ # 原样拷贝的静态资源 ├── sass/ # 可选，编译为 CSS └── themes/ametrine/ # 主题（可被 templates/ 同名文件覆盖）</code></pre> 覆盖规则：templates/</code> 下与主题同路径的文件会完全替换主题模板。例如： {# templates/article.html — 只改文章页，不动 theme #} {%% extends "ametrine/templates/article.html" %%} {%% block content %%} &#123;&#123; super() &#125;&#125; {# 追加滚动条、热力图等 #} {%% endblock %%}</code></pre> 原则：不改 themes/</code> 内文件，在 templates/</code> 里 extends + block 扩展。 </blockquote> 二、模板类型与 front matter 绑定</h2> 模板文件</th> 用途</th> 典型绑定方式</th></tr></thead> base.html</code></td> 全站骨架（<html></code>、header、sidebar、footer）</td> 被其他模板 extends</td></tr> section.html</code></td> Section 索引页（_index.md</code>）</td> section 默认模板</td></tr> page.html</code></td> 独立 Page</td> page 默认模板</td></tr> article.html</code></td> 单篇文章</td> page_template = "article.html"</code></td></tr> article_list.html</code></td> 文章列表 + 分页</td> template = "article_list.html"</code></td></tr> 自定义如 archive.html</code></td> 归档页等特殊布局</td> _index.md</code> 中 template = "archive.html"</code></td></tr> </tbody></table> Section 的 _index.md</code> 示例（参考 daudix 的 blog/_index.md）： +++ title = "效率-工作流" sort_by = "date" template = "article_list.html" # 列表页模板 page_template = "article.html" # 该 section 下每篇文章的模板 paginate_by = 10 generate_feeds = true [extra] no_header = true # 传给模板，控制是否渲染 h1 +++</code></pre> 三、Tera 核心语法</h2> 3.1 继承与块（extends / block / super）</h3> {%% extends "ametrine/templates/base.html" %%} {%% block content %%} <main>&#123;&#123; section.content | safe &#125;&#125;</main> {%% endblock content %%}</code></pre> 在子模板中调用父块内容：super()</code> 过滤器（写作 {{ super() }}</code>）（本站 article.html</code> 即此模式）。 3.2 引入片段（include / import）</h3> {%% include "partials/heatmap_component.html" %%} {%% import "macros/macros.html" as macros %%} &#123;&#123; macros::translate(key="skip_to_content", default="Skip", language_strings=language_strings) &#125;&#125;</code></pre>3.3 常用变量（构建时注入）</h3> 变量</th> 含义</th></tr></thead> config</code></td> zola.toml</code> 全文，含 config.extra.*</code></td></tr> page</code></td> 当前页面（title、date、content、permalink、taxonomies…）</td></tr> section</code></td> 当前 section（pages 列表、title…）</td></tr> lang</code></td> 当前语言</td></tr> current_url</code></td> 当前页面 URL</td></tr> </tbody></table> 3.4 常用函数与过滤器</h3> {# 跨 section 拉取文章 — archive.html 中的用法 #} {%% set sec = get_section(path="03Share_blog/_index.md") %%} {%% set posts = sec.pages | sort(attribute="date") | reverse %%} {# 加载外部数据 #} {%% set strings = load_data(path="i18n/en.toml") %%} {# 过滤器链 #} &#123;&#123; page.date | date(format="%Y-%m-%d") &#125;&#125; &#123;&#123; heat_data | json_encode() | safe &#125;&#125; {%% for year, posts in all_posts | group_by(attribute="year") %%}</code></pre>3.5 图片处理（build 时）</h3> 主题 base.html</code> 中常见写法： {%% set blurnail = resize_image(path=page.colocated_path ~ banner, width=4, height=2, op="fill", format="webp") %%}</code></pre> page.colocated_path</code> 指向与 index.md</code> 同目录，便于 co-located 资源。 四、Shortcode（短代码）</h2> 放在 templates/shortcodes/*.html</code>，Markdown 中写作： {%% shortcode_name(param="value") %%} 内容 {%% end %%}</code></pre> 或自闭合：{%% icon(name="github") %%}</code> 在 Markdown 正文中展示 shortcode 字面量时，用 {%%</code> / %%}</code> 转义，避免被 Zola 当作 shortcode 执行。 </blockquote> 查找顺序：站点 templates/shortcodes/</code> → 主题 themes/ametrine/templates/shortcodes/</code>。 五、Markdown 语法示例</h2> 以下示例整理自 daudix.one</a> 的常见写法，并标注 ametrine 支持情况。 5.1 Front matter（TOML）</h3> +++ title = "文章标题" description = "摘要，用于列表卡片与 SEO" date = 2026-06-22 updated = 2026-06-22 draft = true # 草稿，需 zola build --drafts [taxonomies] tags = ["Zola", "Devlog"] categories = ["Featured"] [extra] toc = true # 目录 accent_color = ["hsl(254 44% 55%)", "hsl(290 20% 71%)"] # 浅色/深色强调色 banner = "banner.webp" # 与 index.md 同目录的横幅图 [extra.fediverse] host = "vmst.io" user = "username" id = "113295812044964246" # 启用 Fediverse 评论 +++</code></pre>5.2 内部链接</h3> Zola 专用 @/</code> 前缀，构建时解析为正确 permalink： 详见 [网站重写 Devlog](@/blog/2023-08-13-site-and-blog-devlog/index.md) 脚注式引用：[为什么叫这个名字？](@/03Share_blog/2025-10-04-Zola-build-deploy-circle/index.md)</code></pre>5.3 标题与目录</h3> ## 二级标题 → 自动生成锚点 ### 三级标题 [extra] toc = true → 文章顶部自动生成目录</code></pre>5.4 文本样式</h3> **粗体** *斜体* ~~删除线~~ `行内代码` > 引用块 > 可以多行 上标脚注引用[^1]，文末定义脚注内容。 [^1]: [Dependency hell](https://en.wikipedia.org/wiki/Dependency_hell)</code></pre>5.5 术语块（daudix 风格）</h3> **SSG：** Static Site Generator，将 Markdown 转为静态 HTML 的构建工具。 </code></pre>5.6 表格</h3> | 页面 | 旧仓库 | 新仓库 | | ---- | ------ | ------ | | Home | pages | website | | Blog | blog-source | website |</code></pre>5.7 代码块</h3> 支持语法高亮（本站 zola.toml</code> 配置 monokai-pro 主题）： TOML 配置示例： [markdown] smart_punctuation = true github_alerts = true</code></pre> HTML 模板示例（Tera 语法，写作时用 {%%</code> / %%}</code> 转义可在正文中展示字面量）： {%% extends "base.html" %%} {%% block content %%}&#123;&#123; page.content | safe &#125;&#125;{%% endblock %%}</code></pre> Shell 命令： zola build --force zola serve --drafts</code></pre>5.8 GitHub Alerts（github_alerts = true</code> 时）</h3> > [!NOTE] > 这是提示框，无需手写 shortcode。 > [!WARNING] > 警告信息。 > [!TIP] > 小技巧。</code></pre> 等价的 shortcode 写法（ametrine alert.html</code>）： {%% alert(title="Note", icon="info", color="note") %%} 自定义图标与颜色的提示块。 {%% end %%}</code></pre>5.9 图片</h3> 普通 Markdown 图片（与 index.md</code> 同目录放 photo.png</code>）： ![Obsidian 附件目录配置](obsidian-attachments.png)</code></pre> daudix 技巧：URL 锚点控制样式（无需 Kramdown 的 {: .class}</code>）： ![透明背景 PNG](context-menu.png#transparent) ![像素风渲染](sprite.png#pixels) ![无 hover 效果](logo.png#transparent#no-hover)</code></pre> 对应 SCSS 选择器示例： img[src*="#transparent"] { background: transparent; } img[src*="#pixels"] { image-rendering: pixelated; }</code></pre> Shortcode 图片（更多参数）： {%% image(url="banner.webp", alt="横幅", full=true, drop_shadow=true) %%}</code></pre>5.10 ASCII / CRT 艺术字</h3> Section 首页与 daudix blog 首页常用的 crt</code> shortcode： {%% crt(label="ASCII 插画：左侧卡车，中间房屋，右侧火箭") %%} * * * _________## @\\\\\\\\\## * @@@\\\\\\\\##\ {%% end %%}</code></pre> 渲染为 .crt</code> 样式的 <pre></code>，带 CRT 扫描线效果。 5.11 嵌入媒体</h3> YouTube（隐私增强域名，需 CSP 允许 youtube-nocookie.com</code>）： {%% youtube(id="dQw4w9WgXcQ") %%} {%% youtube(id="abc123", start=30, autoplay=false) %%}</code></pre> Vimeo / 本地视频 / 音频： {%% vimeo(id="123456789") %%} {%% video(url="clip.mp4", controls=true, loop=true, muted=true) %%} {%% audio(url="podcast.mp3", name="播客片段") %%}</code></pre>5.12 图标</h3> {%% icon(name="github") %%} {%% icon(name="terminal", inline=true) %%}</code></pre> 图标来自 Phosphor SVG，主题 icons/phosphor/</code> 目录。 5.13 Emoji shortcode</h3> 当 render_emoji = false</code> 时，可用 shortcode 插入： {%% emoji(name="🦀") %%}</code></pre>5.14 本站自定义 shortcode</h3> templates/shortcodes/</code> 下还有： Shortcode</th> 用途</th></tr></thead> badges</code></td> 徽章展示</td></tr> polaroid</code></td> 宝丽来相框图片</td></tr> window</code></td> 窗口 UI 框</td></tr> masonry</code></td> 瀑布流图片墙</td></tr> todo</code></td> TODO 列表</td></tr> now_playing</code></td> 正在播放</td></tr> online</code></td> 在线状态</td></tr> </tbody></table> 用法均为 {%% name(参数) %%}...{%% end %%}</code>，具体参数见对应 html 文件。 六、模板开发注意点清单</h2> 不要改 theme：在 templates/</code> 覆盖或 extends。</li> safe</code> 过滤器：page.content</code>、| markdown | safe</code> 输出已解析 HTML；纯文本勿加 safe。</li> Section 路径：get_section(path="03Share_blog/_index.md")</code> 路径相对 content/</code>。</li> 全局变量：{%% set_global x = ... %%}</code> 在 loop 内累加时使用。</li> CSP：嵌入 iframe / 外部脚本需在 zola.toml</code> 的 [extra.csp]</code> 声明域名。</li> 静态资源：JS/CSS 放 static/</code>，引用 /js/xxx.js</code>；Sass 放 sass/</code> 由 Zola 编译。</li> Co-located 资源：图片与 index.md</code> 同目录，构建后 permalink 同路径，便于搬运整文件夹。</li> 分页：paginate_by = 10</code> + 模板中使用 section.pages</code> 与 paginator partial。</li> 多语言：content/</code> 下按语言分子目录，配合 i18n/*.toml</code>。</li> 调试：zola build --force</code> 强制重建；zola serve --open</code> 热重载预览。</li> </ol> 七、本站实践对照</h2> 功能</th> 实现位置</th></tr></thead> 文章页扩展（热力图、滚动条）</td> templates/article.html</code> extends + include partials</td></tr> 归档页 + 年份热力图</td> templates/archive.html</code> + heatmap_component.html</code></td></tr> 自定义列表模板</td> templates/article_list.html</code> / nanolog_list.html</code></td></tr> 全局配置</td> zola.toml</code> → config.extra.*</code></td></tr> 主题变量（颜色）</td> ametrine --bg-muted-1</code>、--accent-color</code> 等 CSS 变量</td></tr> </tbody></table> 参考</h2> Zola Documentation</a></li> Tera Template Engine</a></li> daudix.one content</a> — 本文 Markdown 示例主要来源</li> daudix: Zola vs Jekyll</a> — 目录结构与模板覆盖的详细说明</li> daudix: My Blog Workflow</a> — front matter 模板与图片工作流</li> </ul> 本文即按上述规范编写：toc = true</code> 启用目录，accent_color</code> 设置页面强调色，内部链接使用 @/</code> 语法。

Rocky‘s Blog - Template

Zola 模板开发要点与 Markdown 语法速查

三、Tera 核心语法</h2>

五、Markdown 语法示例</h2>
以下示例整理自 daudix.one</a> 的常见写法，并标注 ametrine 支持情况。</p>

Rocky‘s Blog - Template

Zola 模板开发要点与 Markdown 语法速查

三、Tera 核心语法</h2>

五、Markdown 语法示例</h2> 以下示例整理自 daudix.one</a> 的常见写法，并标注 ametrine 支持情况。</p>

五、Markdown 语法示例</h2>
以下示例整理自 daudix.one</a> 的常见写法，并标注 ametrine 支持情况。</p>