站点配置

bookx.yml 保存可随源码同步的站点配置。建议先在工作台“设置”中修改并保存，再重新构建查看结果。本文示例都是配置片段，合并时保留已有字段，不要重复添加同名 YAML 顶层键。

站点地址与子路径

根域名部署：

site:
  title: 我的站点
  description: 记录技术与生活。
  base_url: https://example.com
  base_path: ""
  language: zh-CN
  timezone: Asia/Shanghai

项目子路径部署，例如最终地址为 https://example.github.io/project/：

site:
  base_url: https://example.github.io
  base_path: /project

base_url 保存站点源地址，子路径放在 base_path。构建器统一生成页面、图片、主题资源、搜索和归档 JSON 的地址。不要在 Markdown 中把所有内部链接手工加上 /project，优先使用相对内容链接。

内容与输出目录

content:
  blog: content/blog
  docs: content/docs
media:
  images: media/images
output: dist

这些相对目录以配置文件所在目录为基准。输出目录是生成物，不要拿源码目录当作输出目录，也不要手工修改其中的页面。

列表、分页与归档

blog:
  page_size: 10
  post_navigation: global

page_size 至少为 5。文章前后导航支持 global（全站）、category（同分类）和 off（关闭）。博客列表可以使用全站 order 自定义排序；文档排序规则见进阶使用。

六套内置主题中，两列文章布局使用 page_size；三列固定每页 9 篇，首页最多 9 篇。切回两列会恢复原设置，手机端缩为单列不改变每页数量。

归档独立按创建时间倒序排列，首屏 50 篇，后续每批 50 篇按需加载。同年文章继续合并，年份显示全年总数。全部加载后只保留完成提示并隐藏分页；未完成、失败或无 JavaScript 时保留静态分页入口。

主题与外观

内置主题有 paper、mono、blush、collage、cyber、terminal。Paper 的四种预设为纸白 paper、雾青 mist、夜幕 nocturne、清透 lumen，它们不再是四套独立内置布局。

theme:
  name: paper
  dir: themes
  settings:
    paper:
      preset: mist
      profile_position: left
      post_columns: 2
      radius: 16
      shadow: soft
      opacity: 100
      colors:
        accent: "#4d7778"

设置按主题分别保存，切换不会清除其他主题的配置。颜色使用带引号的六位十六进制值；圆角为 0–40，透明度为 0–100，阴影支持 none、soft、strong。控制台配色只影响工作台，公开站点要在站点主题中调整。

需要自定义布局时阅读bookx主题设计指南。

作者、项目与好友

站点名称与介绍使用 site.title、site.description；作者资料可填写 author、author_bio、author_headline 等字段。Logo、头像、浏览器图标可以在工作台上传。备案号使用可选的 site.icp，为空时隐藏。

项目使用 projects.items，好友使用 links.items，建议通过设置表单维护名称、说明和链接。没有实际项目时不生成项目页；好友需要开启且存在有效条目才展示。没有公开文档合集时也会隐藏文档入口。

SEO 与分享预览

seo:
  enabled: true
  default_image: ""
  twitter_card: summary_large_image

标题和描述复用内容元信息；分享图片优先使用页面封面，再使用 default_image，留空时不会凭空生成封面。开启后输出 Open Graph、Twitter Card 和基础 JSON-LD；canonical 使用配置后的正式地址。twitter_card 支持 summary 和 summary_large_image。

评论使用 giscus 与 GitHub Discussions，默认关闭。在自己的公开评论仓库完成 Discussions 和 giscus App 配置后，通过工作台填入仓库、仓库 ID、分类和分类 ID，再开启评论。

推荐保持 mapping: specific，由内容稳定 ID 关联 Discussion：文章使用 post-<id>，文档使用 doc-<id>。无需为每篇内容维护额外评论标识。theme: auto 根据站点主题确定评论外观；页面可用 comments: false 关闭。

评论必填信息不足时显示配置提示，不会加载不完整的嵌入脚本。工作台的全部内容“本地预览”关闭评论；要检查评论效果，应使用正式构建的“发布预览”。

第三方统计

analytics:
  scripts:
    - src: https://analytics.example.com/script.js
      async: true
      attributes:
        data-website-id: your-site-id

这是可选示例，替换成实际服务提供的 HTTPS 脚本地址后再启用。自定义属性必须以 data- 开头，不支持通过该配置插入任意内联 JavaScript。统计运行在访问者浏览器中，全部内容本地预览不会加载统计。

修改配置后执行 bookx validate。构建报告未知主题、无效值或资源错误时，先根据文件与字段提示修正，再进行发布。

搜索站点内容