文档站维护¶

文档站使用 Zensical 0.0.74，只收录 docs/。MoonBit 代码块由 Pygments 着色，lexer 来自 moonbit-docs v0.10.16 的网站代码，许可证为 Apache-2.0，本地包是 tools/moonbit-lexer。上游没有 PyPI 发行包，也没有 GitHub Release；版本标签是可固定的发布点。shell、C 和 text 继续使用 Pygments 自带 lexer。

构建与预览¶

安装 uv 和 just 后，在仓库根目录运行：

just docs
just docs serve

just docs 用锁定的依赖严格构建，检查站内链接和标题锚点。产物在 .artifacts/docs/site/。just docs serve 在 http://127.0.0.1:8000 预览，并在原始 Markdown 变化后同步到暂存目录。just docs serve 8001 可换端口；端口只接受 1–65535 的整数。

scripts/docs.py 用 PEP 723 固定 Zensical，并把 tools/moonbit-lexer 装进同一个环境，使 Pygments 能按 moonbit 和 mbt 找到 lexer。升级 Zensical 或 lexer 后重新锁定：

uv lock --script scripts/docs.py
just docs

构建前会把 docs/ 复制到 .artifacts/docs/source/。复制时，指向 docs/ 之外仓库文件的相对链接改成 GitHub 上 main 的对应文件，站内链接保持不动。不要手改暂存目录或站点输出。

Cloudflare 托管¶

托管方式与 ZenDev 相同，使用 Cloudflare Workers Static Assets。Worker 名是 moonsmith-docs，配置的站点地址是 https://docs.moonsmith.zrr.dev/。zensical.toml 的 site_url 决定 canonical URL 和 sitemap；wrangler.toml 决定产物目录、域名、目录索引和 404。没有 Worker 脚本。

仓库不保存 Node.js 包。Wrangler 通过 npx 使用固定版本，Zensical 由 scripts/docs.py.lock 锁定。验证配置：

just docs
npx --yes --ignore-scripts wrangler@4.156.0 deploy --dry-run

dry-run 不登录，也不上传。它不能证明域名、TLS 或 Git 集成已经生效。

在 Cloudflare Workers Builds 中连接 zrr1999/moonsmith：

生产部署更新正式域名。非生产分支只上传预览版本。GitHub Actions 只构建并做 dry-run，不部署。凭据放在 Cloudflare 或本机受保护的环境中，不写入仓库。

首次部署会按 routes 创建自定义域名。若该域名已有 DNS 记录，先核对用途。部署后核对首页、一篇含 MoonBit 代码块的页面、搜索，以及不存在路径的 404。