BookX 使用手册

BookX 把带 YAML Front Matter 的 Markdown 编译成纯静态站点，同一个工作区可以同时管理博客和多个文档合集。内容保存在普通文件中，发布后的站点不需要数据库、Go 进程或在线管理后台。

从哪里开始

工作区里保存什么

my-site/
├── bookx.yml          # 站点配置，可随源码同步
├── content/blog/     # 博客 Markdown
├── content/docs/     # 文档合集与真实目录树
├── media/images/     # 共用图片库
├── themes/           # 可选的自定义主题
├── dist/             # 正式构建产物
└── .bookx/           # 本地设置、缓存与全部内容预览

修改内容、配置或主题后重新构建，变更才会进入正式预览和发布文件。不要直接编辑 dist/，下一次构建会重新生成它。

第一次启动

使用发行包中的命令行程序，可以先创建工作区再打开管理页面：

bookx init --title "我的站点" ./my-site
bookx studio --workspace ./my-site

打开终端提供的本地地址开始写作。使用源码仓库时，可以先运行 go run ./cmd/bookx validate 和 go run ./cmd/bookx build，再用 go run ./cmd/bookx serve 预览；Go 版本以仓库 go.mod 为准。

日常使用顺序

1. 在工作台创建或打开工作区，编辑文章与文档。
2. 检查保存状态，确认稳定 id、标题、日期与可见性。
3. 点击“构建站点”，通过“发布预览”检查准备公开的内容。
4. 需要查看草稿、私有或仅本地内容时，使用“构建全部”与“本地预览”。
5. 按需同步源码，再发布站点；同步和发布是独立操作。

需要记住的约定

• id 是永久身份，修改标题或整理目录时保留它；不要复制一篇文章后继续使用原 ID。
• 文档层级来自实际目录，不再维护一套独立父子关系。
• private 控制公开构建，不会让已进入 Git 的源码消失；仅本地目录另有同步保护。
• BookX 没有独立备份系统，源码应通过你已有的 Git 或文件备份方式保存。

本手册描述当前实现，示例中的站点名、域名、仓库和服务器地址需要替换成自己的值。