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

Featured

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

一、Zola 模板：目录与优先级

Zola 的模板引擎是 Tera（语法接近 Jinja2 / Liquid）。站点根目录结构：

.
├── config.toml          # 全局配置
├── content/             # Markdown 内容（按 section 组织）
├── templates/           # 站点级模板（优先级高于 theme）
├── static/              # 原样拷贝的静态资源
├── sass/                # 可选，编译为 CSS
└── themes/ametrine/     # 主题（可被 templates/ 同名文件覆盖）

覆盖规则：templates/ 下与主题同路径的文件会完全替换主题模板。例如：

{# templates/article.html — 只改文章页，不动 theme #}
{%% extends "ametrine/templates/article.html" %%}

{%% block content %%}
&#123;&#123; super() &#125;&#125;
{# 追加滚动条、热力图等 #}
{%% endblock %%}

原则：不改 themes/ 内文件，在 templates/ 里 extends + block 扩展。

二、模板类型与 front matter 绑定

模板文件	用途	典型绑定方式
`base.html`	全站骨架（`<html>`、header、sidebar、footer）	被其他模板 extends
`section.html`	Section 索引页（`_index.md`）	section 默认模板
`page.html`	独立 Page	page 默认模板
`article.html`	单篇文章	`page_template = "article.html"`
`article_list.html`	文章列表 + 分页	`template = "article_list.html"`
自定义如 `archive.html`	归档页等特殊布局	`_index.md` 中 `template = "archive.html"`

Section 的 _index.md 示例（参考 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
+++

三、Tera 核心语法

3.1 继承与块（extends / block / super）

{%% extends "ametrine/templates/base.html" %%}

{%% block content %%}
  <main>&#123;&#123; section.content | safe &#125;&#125;</main>
{%% endblock content %%}

在子模板中调用父块内容：super() 过滤器（写作 {{ super() }}）（本站 article.html 即此模式）。

3.2 引入片段（include / import）

{%% 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;

3.3 常用变量（构建时注入）

变量	含义
`config`	`zola.toml` 全文，含 `config.extra.*`
`page`	当前页面（title、date、content、permalink、taxonomies…）
`section`	当前 section（pages 列表、title…）
`lang`	当前语言
`current_url`	当前页面 URL

3.4 常用函数与过滤器

{# 跨 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") %%}

3.5 图片处理（build 时）

主题 base.html 中常见写法：

{%% set blurnail = resize_image(path=page.colocated_path ~ banner, width=4, height=2, op="fill", format="webp") %%}

page.colocated_path 指向与 index.md 同目录，便于 co-located 资源。

四、Shortcode（短代码）

放在 templates/shortcodes/*.html，Markdown 中写作：

{%% shortcode_name(param="value") %%}
内容
{%% end %%}

或自闭合：{%% icon(name="github") %%}

在 Markdown 正文中展示 shortcode 字面量时，用 {%% / %%} 转义，避免被 Zola 当作 shortcode 执行。

查找顺序：站点 templates/shortcodes/ → 主题 themes/ametrine/templates/shortcodes/。

五、Markdown 语法示例

以下示例整理自 daudix.one 的常见写法，并标注 ametrine 支持情况。

5.1 Front matter（TOML）

+++
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 评论
+++

5.2 内部链接

Zola 专用 @/ 前缀，构建时解析为正确 permalink：

详见 [网站重写 Devlog](@/blog/2023-08-13-site-and-blog-devlog/index.md)

脚注式引用：[为什么叫这个名字？](@/03Share_blog/2025-10-04-Zola-build-deploy-circle/index.md)

5.3 标题与目录

## 二级标题        → 自动生成锚点
### 三级标题

[extra] toc = true  → 文章顶部自动生成目录

5.4 文本样式

**粗体**  *斜体*  ~~删除线~~  `行内代码`

> 引用块
> 可以多行

上标脚注引用[^1]，文末定义脚注内容。

[^1]: [Dependency hell](https://en.wikipedia.org/wiki/Dependency_hell)

5.5 术语块（daudix 风格）

 

**SSG：** Static Site Generator，将 Markdown 转为静态 HTML 的构建工具。

5.6 表格

| 页面 | 旧仓库 | 新仓库 |
| ---- | ------ | ------ |
| Home | pages  | website |
| Blog | blog-source | website |

5.7 代码块

支持语法高亮（本站 zola.toml 配置 monokai-pro 主题）：

TOML 配置示例：

[markdown]
smart_punctuation = true
github_alerts = true

HTML 模板示例（Tera 语法，写作时用 {%% / %%} 转义可在正文中展示字面量）：

{%% extends "base.html" %%}
{%% block content %%}&#123;&#123; page.content | safe &#125;&#125;{%% endblock %%}

Shell 命令：

zola build --force
zola serve --drafts

5.8 GitHub Alerts（`github_alerts = true` 时）

> [!NOTE]
> 这是提示框，无需手写 shortcode。

> [!WARNING]
> 警告信息。

> [!TIP]
> 小技巧。

等价的 shortcode 写法（ametrine alert.html）：

{%% alert(title="Note", icon="info", color="note") %%}
自定义图标与颜色的提示块。
{%% end %%}

5.9 图片

普通 Markdown 图片（与 index.md 同目录放 photo.png）：

![Obsidian 附件目录配置](obsidian-attachments.png)

daudix 技巧：URL 锚点控制样式（无需 Kramdown 的 {: .class}）：

![透明背景 PNG](context-menu.png#transparent)
![像素风渲染](sprite.png#pixels)
![无 hover 效果](logo.png#transparent#no-hover)

对应 SCSS 选择器示例：

img[src*="#transparent"] { background: transparent; }
img[src*="#pixels"]       { image-rendering: pixelated; }

Shortcode 图片（更多参数）：

{%% image(url="banner.webp", alt="横幅", full=true, drop_shadow=true) %%}

5.10 ASCII / CRT 艺术字

Section 首页与 daudix blog 首页常用的 crt shortcode：

{%% crt(label="ASCII 插画：左侧卡车，中间房屋，右侧火箭") %%}
         *                 *
  *              _________##
                @\\\\\\\\\##
 *             @@@\\\\\\\\##\
{%% end %%}

渲染为 .crt 样式的 <pre>，带 CRT 扫描线效果。

5.11 嵌入媒体

YouTube（隐私增强域名，需 CSP 允许 youtube-nocookie.com）：

{%% youtube(id="dQw4w9WgXcQ") %%}
{%% youtube(id="abc123", start=30, autoplay=false) %%}

Vimeo / 本地视频 / 音频：

{%% vimeo(id="123456789") %%}

{%% video(url="clip.mp4", controls=true, loop=true, muted=true) %%}

{%% audio(url="podcast.mp3", name="播客片段") %%}

5.12 图标

{%% icon(name="github") %%}
{%% icon(name="terminal", inline=true) %%}

图标来自 Phosphor SVG，主题 icons/phosphor/ 目录。

5.13 Emoji shortcode

当 render_emoji = false 时，可用 shortcode 插入：

{%% emoji(name="🦀") %%}

5.14 本站自定义 shortcode

templates/shortcodes/ 下还有：

Shortcode	用途
`badges`	徽章展示
`polaroid`	宝丽来相框图片
`window`	窗口 UI 框
`masonry`	瀑布流图片墙
`todo`	TODO 列表
`now_playing`	正在播放
`online`	在线状态

用法均为 {%% name(参数) %%}...{%% end %%}，具体参数见对应 html 文件。

六、模板开发注意点清单

不要改 theme：在 templates/ 覆盖或 extends。
safe 过滤器：page.content、| markdown | safe 输出已解析 HTML；纯文本勿加 safe。
Section 路径：get_section(path="03Share_blog/_index.md") 路径相对 content/。
全局变量：{%% set_global x = ... %%} 在 loop 内累加时使用。
CSP：嵌入 iframe / 外部脚本需在 zola.toml 的 [extra.csp] 声明域名。
静态资源：JS/CSS 放 static/，引用 /js/xxx.js；Sass 放 sass/ 由 Zola 编译。
Co-located 资源：图片与 index.md 同目录，构建后 permalink 同路径，便于搬运整文件夹。
分页：paginate_by = 10 + 模板中使用 section.pages 与 paginator partial。
多语言：content/ 下按语言分子目录，配合 i18n/*.toml。
调试：zola build --force 强制重建；zola serve --open 热重载预览。

七、本站实践对照

功能	实现位置
文章页扩展（热力图、滚动条）	`templates/article.html` extends + include partials
归档页 + 年份热力图	`templates/archive.html` + `heatmap_component.html`
自定义列表模板	`templates/article_list.html` / `nanolog_list.html`
全局配置	`zola.toml` → `config.extra.*`
主题变量（颜色）	ametrine `--bg-muted-1`、`--accent-color` 等 CSS 变量

参考

Zola Documentation
Tera Template Engine
daudix.one content — 本文 Markdown 示例主要来源
daudix: Zola vs Jekyll — 目录结构与模板覆盖的详细说明
daudix: My Blog Workflow — front matter 模板与图片工作流

本文即按上述规范编写：toc = true 启用目录，accent_color 设置页面强调色，内部链接使用 @/ 语法。