5 分钟快速开始 Zensical¶

从零到一，快速搭建你的 Zensical 文档站点

第一步：环境准备¶

检查 Python 版本¶

Zensical 需要 Python 3.10 或更高版本（以 PyPI 当前要求 为准）。首先检查你的 Python 版本：

1
2
3

python3 --version
# 或
python --version

如果版本低于 3.10，请先升级 Python。

创建项目目录¶

选择一个合适的位置创建你的项目目录：

1
2
3

# 创建项目目录
mkdir my-zensical-site
cd my-zensical-site

第二步：安装 Zensical¶

Zensical 是用 Rust 和 Python 编写的，以 Python 包 形式发布。安装方式有三种：pip（推荐）、uv、Docker，与 官方 Get started 一致。使用 pip 或 uv 时强烈推荐先创建 Python 虚拟环境，避免依赖冲突。

使用 pip 安装（推荐）¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 1. 创建虚拟环境
python3 -m venv .venv

# 2. 激活虚拟环境
# 激活后，终端提示符前会显示 (.venv)
source .venv/bin/activate

# 3. 升级 pip（推荐）
pip install --upgrade pip

# 4. 安装 Zensical
pip install zensical

# 5. 验证安装
zensical --version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 1. 创建虚拟环境
python -m venv .venv

# 2. 激活虚拟环境
# 激活后，终端提示符前会显示 (.venv)
.venv\Scripts\activate

# 3. 升级 pip（推荐）
pip install --upgrade pip

# 4. 安装 Zensical
pip install zensical

# 5. 验证安装
zensical --version

使用 uv 安装（开发者推荐）¶

如果你是 Python 开发者，可能已经在使用 uv 作为包管理器：

1
2
3
4
5
6
7
8

# 初始化项目（若目录中尚未有 Python 项目配置）
uv init

# 添加 Zensical（推荐作为开发依赖）
uv add --dev zensical

# 验证安装
uv run zensical --version

使用 Docker 安装¶

若已熟悉 Docker，可直接使用官方镜像，无需在宿主机安装 Python 或虚拟环境：

• 镜像：zensical/zensical（Docker Hub）
• 用法：在项目根目录（含 zensical.toml 或 mkdocs.yml）下运行构建或预览（与 Docker Hub 示例一致）：

1
2
3
4
5
6
7
8

# 拉取镜像（可选）
docker pull zensical/zensical

# 预览（默认等价于 zensical serve）
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs zensical/zensical

# 构建（等价于 zensical build）
docker run --rm -it -v ${PWD}:/docs zensical/zensical build

第三步：创建项目¶

在项目目录中运行以下命令创建新的 Zensical 项目：

1
2
3
4
5
6

# 确保虚拟环境已激活
# 如果还没激活，先执行: source .venv/bin/activate (macOS/Linux)
# 或 .venv\Scripts\activate (Windows)

# 创建新项目
zensical new .

1

zensical new my-site  # 在 my-site 目录创建

检查项目结构¶

创建完成后，检查一下目录结构是否正确：

1
2
3
4
5

# 查看目录结构
tree -a
# 如果没有 tree 命令，可以使用:
# macOS: ls -la
# Windows: dir

应该看到以下结构：

1
2
3
4
5

.
├── docs/
│   ├── index.md            # 网站首页
│   └── markdown.md         # Markdown 示例
└── zensical.toml           # 配置文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 克隆模板项目
git clone https://github.com/Wcowin/Zensical-Chinese-Tutorial.git my-site
cd my-site

# （推荐）创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖（本仓库有额外依赖，如 Markdown 扩展等）
pip install -r requirements.txt

# 启动开发服务器测试
zensical serve

第四步：配置项目¶

打开 zensical.toml 文件，这是 Zensical 的核心配置文件。

基础配置¶

Zensical 提供了许多配置选项，都有合理的默认值。site_name 是唯一必需的设置：

1
2

[project]
site_name = "我的网站"

推荐配置¶

虽然 site_name 就足够了，但强烈建议同时设置以下配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

[project]
# 基本信息（必需）
site_name = "我的网站"

# 网站 URL（强烈推荐！）
# 这是即时导航、即时预览、自定义错误页面的前提
site_url = "https://example.com"

# 网站描述（可选，但推荐）
site_description = "我的 Zensical 站点"

# 作者信息（可选）
site_author = "你的名字"

# 文档目录（默认：docs）
docs_dir = "docs"

# 输出目录（默认：site）
site_dir = "site"

主题配置¶

在父表配置完成后，添加主题配置：

1
2
3
4
5
6

# ... 上面的 [project] 配置 ...

# 主题配置（在父表配置之后）
[project.theme]
variant = "modern"    # 主题变体：modern（现代）或 classic（经典）
language = "zh"       # 界面语言：中文

完整配置示例¶

以下是一个完整的基础配置示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[project]
site_name = "我的网站"
site_url = "https://example.com"
site_description = "我的 Zensical 站点"
site_author = "你的名字"
docs_dir = "docs"
site_dir = "site"

[project.theme]
variant = "modern"
language = "zh"

保存配置文件后，就可以继续下一步了。

第五步：启动开发服务器¶

Zensical 内置了 Web 服务器，可以在编写时实时预览。服务器会在你修改源文件时自动重建网站。

启动服务器¶

在项目目录下运行：

1
2
3
4
5
6

# 确保虚拟环境已激活
# macOS/Linux: source .venv/bin/activate
# Windows: .venv\Scripts\activate

# 启动开发服务器
zensical serve

你会看到类似以下的输出：

1
2

Serving on http://localhost:8000
Build started

访问网站¶

在浏览器中打开 http://localhost:8000 即可看到你的网站。

1

zensical serve --port 8001

第六步：添加第一篇文档页面（可选）¶

Zensical 的内容源文件默认都放在 docs/ 目录下。要“添加一篇文章/页面”，本质上就是新增一个 Markdown 文件（必要时再把它加入导航）。

创建页面文件¶

例如，新建 docs/notes/hello-world.md：

1
2

mkdir -p docs/notes
touch docs/notes/hello-world.md

在 docs/notes/hello-world.md 中写入内容：

1
2
3
4
5
6

# Hello World

这是我的第一篇文档页面！

- 支持 Markdown
- 保存后会自动重建并刷新

保存后，开发服务器会自动刷新。默认情况下（use_directory_urls = true），你可以访问：

• http://localhost:8000/notes/hello-world/

（可选）把页面加入导航¶

如果你希望它出现在左侧目录/顶部导航中，需要在 zensical.toml 的 [project] 里，把文件路径加入 nav。

示例（添加一个新的“笔记”分组）：

1
2
3
4
5
6

nav = [
  # ... 原有导航 ...
  { "笔记" = [
    { "Hello World" = "notes/hello-world.md" },
  ] },
]

第七步：构建网站¶

当你完成编辑后，可以从 Markdown 文件构建静态网站：

1
2
3
4
5

# 构建网站
zensical build

# 或使用清理构建（推荐，清除旧文件）
zensical build --clean

检查构建结果¶

构建完成后，检查 site/ 目录：

1
2
3

# 查看构建结果
ls -la site/
# Windows: dir site

应该看到生成的 HTML 文件：

1
2
3
4
5
6
7

site/
├── index.html
├── notes/
│   └── hello-world/
│       └── index.html
└── assets/
    └── ...

本地预览构建结果（可选）¶

如果你想预览构建后的网站：

1
2
3
4

# 使用 Python 内置服务器预览
cd site
python3 -m http.server 8001
# Windows: python -m http.server 8001

然后在浏览器中访问 http://localhost:8001

完成！🎉¶

恭喜！你已经成功创建了一个 Zensical 站点！

验证项目结构¶

最后，让我们确认一下完整的项目结构：

1
2
3
4
5

# 查看完整目录结构
tree -a
# 如果没有 tree 命令：
# - macOS/Linux: ls -la
# - Windows: dir

应该看到类似这样的结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

.
├── .venv/              # 虚拟环境（如果使用）
├── docs/
│   ├── index.md
│   ├── markdown.md
│   └── notes/
│       └── hello-world.md
├── site/               # 构建输出目录（运行 build 后生成）
├── zensical.toml       # 配置文件
└── .github/            # （可选）如需 GitHub Actions 部署
    └── workflows/
        └── docs.yml

接下来可以做什么？¶

1. 编写更多页面 - 在 docs/ 中添加更多 Markdown 文件
2. 组织内容结构 - 用子目录管理内容（如 docs/notes/、docs/tutorials/）
3. 配置导航 - 在 zensical.toml 中配置 nav 导航菜单
4. 自定义样式 - 创建 docs/stylesheets/extra.css 自定义样式
5. 部署到线上 - 参考 GitHub Pages 部署指南

常用命令速查¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 启动开发服务器
zensical serve

# 启动开发服务器（指定端口）
zensical serve --port 8001

# 构建静态网站
zensical build

# 清理构建（清除旧文件）
zensical build --clean

# 查看帮助
zensical --help

# 查看版本
zensical --version

推荐阅读¶

• 📖 Zensical 博客系统完全指南 - （可选）了解博客相关能力
• ⚙️ 项目配置详解 - 完整的配置选项说明
• 🎨 主题定制指南 - 自定义网站外观
• 🚀 GitHub Pages 部署 - 将网站部署到线上

遇到问题？¶

• 📋 查看 常见问题解答
• 📚 访问 Zensical 官方文档
• 💬 在 GitHub Issues 提问

祝你使用愉快！ 🎉