模板开发与 Liquid

概述

Baklib 站点前台由 Liquid 模板 渲染：布局、栏目、动态表单、多语言等均在主题目录中维护。客户管理员在 应用设置 → 界面展示 中选模板、改颜色与导航即可满足多数需求；深度定制（新布局、新字段、自定义逻辑）则进入模板开发。

本篇说明从「选模板」到「本地 dev」的路径，并指向官方模板库与 CLI；Liquid 全量语法不在此重复，请配合 baklib-theme-dev 技能与模板中心文档。

操作步骤

步骤一：在后台选择与管理模板

进入目标应用 应用设置 → 界面展示。
在模板列表中选择官方或组织内模板；可配置首页布局、主题色、导航等（因模板而异）。
安装后逐项配置见 模板中心（创建应用时的外链文档），不在本操作手册逐页扩写。

深度定制前，先确认是否可用现有模板 + 设置项满足需求，见界面与品牌设置。

预期结果：前台可用所选模板访问；轻量调整无需改代码。

步骤二：了解模板来源与目录结构

官方模板库：github.com/baklib-templates — CMS、Wiki、社区等示例与主题 Git 仓库
主题目录约定：Liquid 在 templates/、statics/ 等路径；settings_schema.json 定义后台可配置项；部分模板含 {% schema %} 块
低代码入门（概念）：旧站 Liquid 低代码仍可作为概念参考；细节以模板库与 baklib-theme-dev 为准

预期结果：知道从哪克隆/拉取官方主题作为起点。

步骤三：用 CLI 拉取主题并本地预览

需已安装并配置 CLI 教程：

# 查看可选模板
baklib theme list
baklib theme show cms/guide

# 拉取到本地
baklib theme pull cms/guide --out ./cms--guide --yes

# 进入目录启动开发服
cd cms--guide
baklib theme dev

在管理面板中选择站点、开启 同步模版到预览，保存文件后即可在浏览器查看服务端渲染结果。

新建骨架：

baklib theme init cms vcard

预期结果：本地修改 Liquid 可热更新预览，HTML 与线上一致由 Baklib preview_render 生成。

步骤四：安装 baklib-theme-dev 技能

在 AI 辅助改模板时，安装社区技能以避免 Liquid / schema / 表单标签用法错误：

npx skills add baklib-tools/skills --skill baklib-theme-dev
# 或
baklib skill install --skill baklib-theme-dev -g

技能覆盖：settings_schema.json、模板 {% schema %}、多语言 locales、site.settings / page.settings、form_tag / form_field_tag、静态页、seeds 等；深度参考见技能内 references/。

预期结果：AI 改模板时遵循 Baklib 模板约定。

步骤五：发布与协作

预览上传：baklib theme push（单次同步到预览缓存）
版本与 Git：组织内模板通常对应 Git 仓库；与平台分支对齐可用 baklib theme pull … --use-git-branch
成员权限：模板修改需相应应用/组织权限；与成员与权限管理一致

生产发布流程以组织规范与 Baklib 后台「模板 / 主题」管理为准（具体按钮与审批以界面为准）。

预期结果：主题变更可追踪、可回滚，并经测试后上线。

常见问题

Q：改模板必须会用 CLI 吗？
A：不是。仅换官方模板、调设置项可全程在后台完成；改 Liquid 源码 才需要 CLI 或 Git 工作流。

Q：Wiki 与 CMS 模板一样吗？
A：应用类型不同，主题 scope 与目录结构不同（如 cms/、wiki/）；用 theme list 查看可选范围。

Q：动态表单字段怎么写？
A：见 baklib-theme-dev 中 form_tag 文档；站点页 DAM 图片字段在 API/MCP 侧常用 signed_id + purpose=dynamic_form，见 MCP 教程。

概述