从零开始使用 MetaBlog
Abstract
这篇文章介绍一个 MetaBlog 站点所需的最小文件结构，以及构建和预览站点时最常用的命令。
Keywords: MetaBlog, 网站构建, 文章元数据
1项目地址
2目录结构
一个 MetaBlog 站点就是一个普通文件夹。最重要的文件包括：
- data/config.toml
网站标题、logo、icon 和分页配置。
- data/articles.toml
需要参与构建的文章列表。
- data/about_page/main.tex
关于页面的 LaTeX 源文档。
- articles/
文章源文件目录。
- asset/
站点级资源，例如 logo 和 favicon。
只有注册在 data/articles.toml 中的文章才会出现在生成的网站中。articles/ 下存在某个文件夹，并不意味着它一定会被构建。
初始化站点
通过golang运行源代码，或使用我们发布的二进制程序，可以在任意空目录初始化网站
| 1 | go run ./cmd/metablog site init -root example -title "MetaBlog Example" |
| 2 | # 使用release的二进制包： |
| 3 | ./metablog_1.0.2_windows_amd64.exe site init -root example -title "MetaBlog Example" |
site init 默认会下载字体文件，并在最后检测 Python、LaTeXML 和 PDF 转换器环境。它只检测并提示安装方式，不会自动安装或修改系统环境。
如果只想先生成目录和配置，可以跳过字体下载和环境检测：
| 1 | go run ./cmd/metablog site init -root example -title "MetaBlog Example" -skip-fonts -skip-env-check |
| 2 | # 使用release的二进制包： |
| 3 | ./metablog_1.0.2_windows_amd64.exe site init -root example -title "MetaBlog Example" -skip-fonts -skip-env-check |
3构建和预览
Github仓库中的 example/文件夹 是一个完整示例站点， 站点名为 MetaBlog Example，包含关于页、自定义组件和多篇展示文章。可以直接从仓库根目录构建或预览：
从仓库根目录构建这个示例：
| 1 | go run ./cmd/metablog site build -root example -out example/out |
| 2 | # 使用release的二进制包： |
| 3 | ./metablog_1.0.2_windows_amd64.exe site build -root example -out example/out |
输出目录是 example/out。如果需要实时预览，可以使用：
| 1 | go run ./cmd/metablog site serve -root example -out example/out -watch |
| 2 | # 使用release的二进制包： |
| 3 | ./metablog_1.0.2_windows_amd64.exe site serve -root example -out example/out -watch |
启用 -watch 后，已注册文章目录、关于页面、站点元数据、站点资源和自定义组件都会被监听。文档变化后，MetaBlog 会增量重建对应页面。
4文章元数据
每篇文章都通过 TOML 配置：
| 1 | [[articles]] |
| 2 | title = "从零开始使用 MetaBlog" |
| 3 | description = "这篇文章介绍一个 MetaBlog 站点的基本结构。" |
| 4 | author = "MetaBlog 示例" |
| 5 | date = "2026-05-16" |
| 6 | category = ["指南", "快速开始"] |
| 7 | tags = ["MetaBlog", "CLI", "网站构建"] |
| 8 | folder = "articles/getting-started-with-metablog" |
| 9 | main_fig = "figs/site-overview.svg" |
| 10 | main_file = "main.tex" |
| 11 | slug = "getting-started-with-metablog" |
description 会显示在首页和文章列表页中。category 是多级分类，tags 中的每个标签都会生成对应的标签列表页。
5分页
这个示例把 home_page_size 设置为 3，并提供 4 篇文章，因此首页可以直接展示分页效果。