baklib-theme-dev

name

baklib-theme-dev

description

Baklib 站点主题（模板）开发：Liquid 目录与命名、`config/settings_schema.json` 与模板 `{% schema %}`、多语言 `locales`、对象与指令/过滤器、静态页 URL、seeds 与迁移；站点表单 `form_tag`/`form_field_tag` 全量说明见 references/forms.md。并含「新建主题脚手架」「参考站复刻工作流」、本地 `baklib theme dev` 预览，以及 CLI 初始化 manifest（template.json，见 references/theme-init-template-manifest.md）。新建或迭代主题起步模版、写 template.json、theme init/apply 时必读该文档；完成主题开发后应把过程沉淀进 manifest 的 developmentNotes/workflow。页面预览参数用 `baklib theme preview set`（theme-preview-page-config.md），勿让用户手填面板。在用户编写 .liquid、配置 schema、新建模板、复刻参考站或排查模板与变量时使用；详规见 references/。

Baklib 模板开发

Baklib 站点前台使用 Liquid 模板（与 Shopify 模板体系相近）。模板作者通过 对象（变量）、指令（控制逻辑，官方称 Tag）、过滤器（转换输出）组合页面。

术语

术语	含义
对象	在 {{ }} 中输出的变量或属性，如 {{ site.name }}
指令	在 {% %} 中控制流程；本文称「指令」以免与站点内容「标签」混淆
过滤器	在 {{ }} 内用 | 连接，如 {{ site.pages | order_by: "-published_at" }}

本地预览：改页面模版 / 页面参数（AI 必读）

需要为指定 path 切换 Liquid 模版或写入 template_variables（对应模板 {% schema %} / page.settings）以查看效果时：

1. 确认用户已运行 baklib theme dev，且在 /!admin 已选站点、已开启「同步模版到预览」。
2. 使用 baklib theme preview set --path <path> --template <name> --vars '<json>'（或 --vars-file、 --merge-vars）；不要让用户在管理面板里逐字段手填演示内容。
3. 用 baklib theme preview url --path <path> 或浏览器 MCP 打开预览 URL 验证。

命令说明、HTTP API 与前置条件见 theme-preview-page-config.md。

工作流（按需阅读）

场景	文档
在产品仓库中新建 themes/[scope]/[name]/ 并生成最小文件	create-theme-scaffold.md
复刻参考网站（分析、适配、分期落地、质检；多步须先确认）	website-cloning-workflow.md
baklib theme dev 下按 path 切换模版 / 填页面参数（AI 用 CLI，勿手填面板）	theme-preview-page-config.md
编写 / 维护 template.json 起步模版（theme init / theme apply；沉淀开发过程）	theme-init-template-manifest.md

起步模版 manifest（AI 必读）

主题工程化起步不靠改 CLI，而靠维护 template.json（安装技能、MCP、片段、骨架文件，并在 manifest 内记录 developmentNotes / workflow 供下一项目复用）。

• 新建：baklib theme init <scope> <name> --template <id> 或 --template ../path/to/template.json
• 已有目录：baklib theme apply --template …
• 格式与字段：theme-init-template-manifest.md

文档索引（references/）

按需打开下列文件获取完整表格与示例：

文件	内容
directory-and-naming.md	主题目录、templates/layout/snippets/statics/assets/config/locales/src 与文件命名
settings-schema.md	config/settings_schema.json：theme_info、分组、track_events、字段 type 与属性
template-schema.md	模板底部 {% schema %} JSON：页面变量、子模板、user_*、queryable 等
locales-and-i18n.md	locales/*.json / *.schema.json、theme_syntax_version v1/v2、t: 与 ${lang}
settings-in-liquid.md	site.settings / page.settings 在 Liquid 中的读取与默认值
forms.md	form_tag（11 种）与 form_field_tag（6 种）逐表单说明
query-and-search.md	{% query %}（JSON where / order_by）与 {% search %}（关键词、search 对象）
liquid-tags.md	其余自定义指令、render、track_event、paginate_tag 等（query / search 摘要链至上文）
page-as-api.md	{% response_type %}：JSON / XML / Markdown 与 request 格式判断（页面作 API）
site-mounts.md	站点聚合：主域路径挂载子站、script_name、site.sites
shared-snippets-source.md	{% render '@shared/…' %} 内置片段与产品仓库 themes/shared/snippets/_*.liquid 原文一致
objects-and-drops.md	全局变量、按场景传入的变量、site / page / tag / search / paginate 等对象
filters.md	产品提供的自定义过滤器（含站点扩展）
static-pages-and-urls.md	statics、script_name、勿写死 /s/
limits-and-security.md	主题名规则、分页上限、strict_filters、事件追踪
seeds-and-migrations.md	seeds/ 初始化数据与 migrations/ 主题迁移
to-markdown-export.md	模板字段 to_markdown 导出说明
faq.md	常见问题
theme-preview-page-config.md	baklib theme preview：按 path 设模版名与 template_variables、查询/清除、预览 URL
theme-init-template-manifest.md	template.json manifest：theme init / theme apply、字段说明、developmentNotes 沉淀

能力边界

• 说明对象：面向在 Baklib 站点主题中编写 Liquid 与 JSON schema 的开发者；不描述 Baklib 应用后台或服务器实现细节。
• 与标准 Liquid 的关系：除自定义能力外，可使用 Liquid 标准语法与内置过滤器。
• 版本差异：具体站点是否开启登录、搜索、反馈、AI 等功能以租户配置为准；模板中应对空值做判断（如 {% if current_user %}）。

快速示例

{% layout "theme" %}
<h1>{{ site.name }}</h1>
<p>{{ site.settings.company_name }}</p>
{% for p in site.pages | limit: 5 %}
  <a href="{{ p.path }}">{{ p.link_text }}</a>
{% endfor %}