creating-zola-static-sites

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Zola Static Sites

使用Zola构建静态站点

Single-binary static site generator. Built-in Sass, image processing, Tera templating.

单二进制文件的静态站点生成器，内置Sass、图像处理和Tera模板功能。

Quick Start

快速开始

New Project:
- [ ] zola init my-site && cd my-site
- [ ] Edit config.toml: set base_url
- [ ] IF using theme: skip next step (theme provides templates)
- [ ] IF no theme: copy templates from skill assets/
- [ ] zola serve → http://127.0.0.1:1111 loads
- [ ] zola check → exit code 0

新项目创建步骤：
- [ ] 执行zola init my-site && cd my-site
- [ ] 编辑config.toml：设置base_url
- [ ] 若使用主题：跳过下一步（主题已提供模板）
- [ ] 若不使用主题：从技能assets/目录复制模板
- [ ] 执行zola serve → 访问http://127.0.0.1:1111即可加载站点
- [ ] 执行zola check → 退出码为0

Commands

命令说明

Command	Purpose	Verify Success
`zola init`	Create project	`ls config.toml` exists
`zola serve`	Dev server :1111	Browser loads site
`zola build`	Output to public/	`ls public/index.html` exists
`zola check`	Validate links	Exit 0, no errors printed

命令	用途	验证成功方式
`zola init`	创建项目	检查config.toml文件是否存在
`zola serve`	启动开发服务器，端口1111	浏览器可正常加载站点
`zola build`	将站点输出至public/目录	检查public/index.html文件是否存在
`zola check`	验证链接有效性	退出码为0，无错误信息输出

Core: Sections vs Pages

核心概念：栏目与页面的区别

_
prefix = section (listing); no prefix = page (content):

Filename	Type	Template	Example URL
`_index.md`	section	section.html	`/blog/` (listing)
`index.md`	page	page.html	`/about/` (with assets)
`post.md`	page	page.html	`/blog/post/`

content/
├── _index.md        # section: /
├── about.md         # page: /about/
└── blog/
    ├── _index.md    # section: /blog/
    └── post.md      # page: /blog/post/

前缀
_
表示栏目（列表页）；无前缀表示页面（详情页）：

文件名	类型	模板文件	示例URL
`_index.md`	栏目	section.html	`/blog/` （列表页）
`index.md`	页面	page.html	`/about/` （含资源文件）
`post.md`	页面	page.html	`/blog/post/`

content/
├── _index.md        # 栏目：站点根目录/
├── about.md         # 页面：/about/
└── blog/
    ├── _index.md    # 栏目：/blog/
    └── post.md      # 页面：/blog/post/

Frontmatter

前置元数据

section (

_index.md

toml

+++
title = "Blog"
sort_by = "date"        # date|title|weight|none
paginate_by = 10
+++

page (

*.md

toml

+++
title = "My Post"
date = 2024-01-15       # NO QUOTES or sorting breaks
[taxonomies]
tags = ["rust"]
+++

栏目（
_index.md
）：

toml

+++
title = "博客"
sort_by = "date"        # 排序方式：date|title|weight|none
paginate_by = 10
+++

页面（
*.md
）：

toml

+++
title = "我的文章"
date = 2024-01-15       # 请勿加引号，否则会导致排序失效
[taxonomies]
tags = ["rust"]
+++

Internal Links

内部链接

Build-validated with

@/

prefix:

markdown

[About](@/about.md)
[Blog](@/blog/_index.md)

使用

@/

前缀可在构建时验证链接有效性：

markdown

[关于我们](@/about.md)
[博客](@/blog/_index.md)

Workflows

工作流

Create Blog

创建博客

Blog Setup:
- [ ] Create content/blog/_index.md with sort_by="date"
- [ ] Create post: content/blog/2024-01-15-hello.md
- [ ] IF multilingual: add blog/_index.fr.md per language
- [ ] zola serve → /blog/ shows listing (empty if no posts yet)
- [ ] zola serve → /blog/hello/ shows post
- [ ] IF pagination: add more posts than paginate_by to test
- [ ] zola check → passes

博客搭建步骤：
- [ ] 创建content/blog/_index.md文件，设置sort_by="date"
- [ ] 创建文章：content/blog/2024-01-15-hello.md
- [ ] 若为多语言站点：为每种语言添加blog/_index.fr.md文件
- [ ] 执行zola serve → 访问/blog/可查看文章列表（若无文章则显示为空）
- [ ] 执行zola serve → 访问/blog/hello/可查看文章详情
- [ ] 若启用分页：添加超过paginate_by数量的文章进行测试
- [ ] 执行zola check → 验证通过

Add Taxonomies

添加分类管理

Taxonomy Setup:
- [ ] config.toml: taxonomies = [{name = "tags", feed = true}]
- [ ] Page frontmatter: [taxonomies] tags = ["value"]
- [ ] IF need categories: add {name = "categories"} to array
- [ ] IF term has spaces: use slugified URL (/tags/my-tag/)
- [ ] zola serve → /tags/ lists tags
- [ ] zola serve → /tags/rust/ shows posts

分类设置步骤：
- [ ] 在config.toml中添加：taxonomies = [{name = "tags", feed = true}]
- [ ] 在页面前置元数据中添加：[taxonomies] tags = ["value"]
- [ ] 若需要分类栏目：在数组中添加{name = "categories"}
- [ ] 若分类名称含空格：使用URL友好的slug格式（如/tags/my-tag/）
- [ ] 执行zola serve → 访问/tags/可查看所有分类
- [ ] 执行zola serve → 访问/tags/rust/可查看该分类下的文章

Deploy

部署站点

Production Deploy:
- [ ] zola check → passes (use --skip-external-links if slow)
- [ ] zola build → no errors
- [ ] ls public/index.html → exists
- [ ] IF feeds enabled: ls public/atom.xml → exists

生产环境部署步骤：
- [ ] 执行zola check → 验证通过（若速度慢可添加--skip-external-links参数跳过外部链接检查）
- [ ] 执行zola build → 无错误信息输出
- [ ] 检查public/index.html文件是否存在
- [ ] 若启用订阅源：检查public/atom.xml文件是否存在

Reference Files

参考文件

Task	Reference	Load When User Asks About
Config	config-reference.md	Feeds, taxonomies, highlighting, search, link checker
Templates	tera-templates.md	Filters, loops, variables, macros, shortcodes
Content	content-organization.md	_index.md vs index.md, frontmatter, multilingual
Deploy	deployment-guides.md	Netlify, Cloudflare, GitHub Actions, Vercel, Firebase
Hybrid	astro-integration.md	Zola+Astro, Firebase export, shared navigation

任务	参考文档	适用场景（用户询问以下内容时加载）
配置	config-reference.md	订阅源、分类管理、语法高亮、搜索功能、链接检查器
模板	tera-templates.md	过滤器、循环、变量、宏、短代码
内容管理	content-organization.md	_index.md与index.md的区别、前置元数据、多语言站点
部署	deployment-guides.md	Netlify、Cloudflare、GitHub Actions、Vercel、Firebase部署
混合架构	astro-integration.md	Zola+Astro集成、Firebase导出、导航栏共享

Assets

资源文件

Copy from skill

assets/

directory:

Asset	Use For
`templates/base.html`	Base layout
`templates/section.html`	Listings with pagination
`templates/page.html`	Articles with TOC
`templates/404.html`	Error page
`templates/shortcodes/`	youtube.html, figure.html
`config-templates/blog.toml`	Blog preset
`config-templates/docs.toml`	Docs preset

从技能assets/目录复制以下资源：

资源文件	用途
`templates/base.html`	基础布局模板
`templates/section.html`	带分页功能的列表页模板
`templates/page.html`	含目录的文章详情页模板
`templates/404.html`	404错误页面模板
`templates/shortcodes/`	包含youtube.html、figure.html等短代码模板
`config-templates/blog.toml`	博客站点配置预设
`config-templates/docs.toml`	文档站点配置预设

Common Mistakes

常见错误

Wrong	Right	Why
`date = "2024-01-15"`	`date = 2024-01-15`	Quoted dates are strings, break sorting
`[About](about.md)`	`[About](@/about.md)`	Missing @/ means no build validation
`index.md` in blog/	`_index.md` in blog/	Without `_` it's a page, not a section
`templates/blog.html`	`templates/section.html`	Zola looks for section.html by default

错误做法	正确做法	原因
`date = "2024-01-15"`	`date = 2024-01-15`	带引号的日期会被识别为字符串，导致排序失效
`[About](about.md)`	`[About](@/about.md)`	缺少@/前缀会导致构建时无法验证链接有效性
在blog/目录下使用index.md	在blog/目录下使用_index.md	不带 `_` 前缀的文件会被识别为页面，而非栏目
使用 `templates/blog.html` 作为模板	使用 `templates/section.html` 作为模板	Zola默认查找section.html作为栏目模板

Troubleshooting

问题排查

Error	Fix	Verify
Template not found	Check spelling; ensure templates/ exists	`ls templates/*.html` shows files
Dates not sorting	Use `date = 2024-01-15` (no quotes)	Posts appear in date order
Broken @/ links	Path from content/, include .md extension	`zola check` passes
Slow check	Skip external: `zola check --skip-external-links`	Completes in <10s

Debug:

{{ __tera_context }}

in template shows all variables.

Verbose:

RUST_LOG=zola=info zola build

错误提示	解决方法	验证方式
模板未找到	检查模板文件名拼写；确保templates/目录存在	执行ls templates/*.html可查看所有模板文件
日期排序失效	使用 `date = 2024-01-15` 格式（不加引号）	文章按日期顺序正常显示
@/链接失效	路径需基于content/目录，且包含.md扩展名	执行zola check验证通过
zola check执行缓慢	添加--skip-external-links参数跳过外部链接检查	10秒内完成检查

调试技巧： 在模板中添加

{{ __tera_context }}

可查看所有可用变量。

详细日志： 执行

RUST_LOG=zola=info zola build

查看详细构建日志。

When Not to Use

不适用场景

Other SSGs: Hugo, Jekyll, Eleventy use different syntax
General Markdown: Questions without Zola context
Pure Astro: Projects without Zola integration

其他SSG工具： Hugo、Jekyll、Eleventy使用不同的语法规则
通用Markdown问题： 无Zola相关上下文的Markdown问题
纯Astro项目： 未集成Zola的Astro项目