Back to Details

baklib-theme-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Baklib 模板开发

Baklib Template Development

Baklib 站点前台使用 Liquid 模板（与 Shopify 模板体系相近）。模板作者通过 对象（变量）、指令（控制逻辑，官方称 Tag）、过滤器（转换输出）组合页面。
Baklib's site frontend uses Liquid templates (similar to Shopify's template system). Template authors build pages by combining objects (variables), directives (control logic, officially called Tags), and filters (transform output).

术语

Terminology

术语含义
对象在 
{{ }}
中输出的变量或属性，如 
{{ site.name }}
指令在 
{% %}
中控制流程；本文称「指令」以免与站点内容「标签」混淆
过滤器在 
{{ }}
内用 
|
连接，如 
{{ site.pages | order_by: "-published_at" }}
TermDefinition
ObjectVariables or properties output in 
{{ }}
, e.g., 
{{ site.name }}
DirectiveControl flow in 
{% %}
; referred to as "directive" here to avoid confusion with site content "tags"
FilterConnected with 
|
inside 
{{ }}
, e.g., 
{{ site.pages | order_by: "-published_at" }}

工作流（按需阅读）

Workflow (Read as Needed)

场景文档
在产品仓库中新建 
themes/[scope]/[name]/
并生成最小文件		create-theme-scaffold.md
复刻参考网站（分析、适配、分期落地、质检；多步须先确认）website-cloning-workflow.md
ScenarioDocument
Create 
themes/[scope]/[name]/
in the product repository and generate minimal files		create-theme-scaffold.md
Clone Reference Website (analysis, adaptation, phased implementation, quality inspection; multiple steps require prior confirmation)website-cloning-workflow.md

文档索引（
references/
）

Document Index (
references/
)

按需打开下列文件获取完整表格与示例：
文件内容
directory-and-naming.md主题目录、
templates
/
layout
/
snippets
/
statics
/
assets
/
config
/
locales
/
src
与文件命名
liquid-tags.md页面模板与布局中的自定义指令、
render
、
form_tag
、
track_event
、
paginate_tag
、
query
、
search
等
shared-snippets-source.md
{% render '@shared/…' %}
三枚内置片段与仓库 
themes/shared/snippets/_*.liquid
原文一致，便于复制改写
objects-and-drops.md全局变量、按场景传入的变量、
site
/ 
page
/ 
tag
/ 
search
/ 
paginate
等对象
filters.md产品提供的自定义过滤器（含站点扩展）
limits-and-security.md主题名规则、分页上限、
strict_filters
、反向代理与路径前缀
seeds-and-migrations.md
seeds/
初始化数据与 
migrations/
主题迁移
Open the following files as needed for complete tables and examples:
FileContent
directory-and-naming.mdTheme directory, naming conventions for 
templates
/
layout
/
snippets
/
statics
/
assets
/
config
/
locales
/
src
and files
liquid-tags.mdCustom directives in page templates and layouts, 
render
, 
form_tag
, 
track_event
, 
paginate_tag
, 
query
, 
search
, etc.
shared-snippets-source.mdThe three built-in snippets in 
{% render '@shared/…' %}
are identical to the original files in the repository's 
themes/shared/snippets/_*.liquid
, making them easy to copy and modify
objects-and-drops.mdGlobal variables, scenario-specific variables, and objects like 
site
/ 
page
/ 
tag
/ 
search
/ 
paginate
filters.mdCustom filters provided by the product (including site extensions)
limits-and-security.mdTheme name rules, pagination limits, 
strict_filters
, reverse proxy and path prefix
seeds-and-migrations.md
seeds/
initialization data and 
migrations/
theme migrations

能力边界

Scope

  • 说明对象：面向在 Baklib 站点主题中编写 Liquid 的开发者；不描述 Baklib 应用后台或 Rails 实现细节。
  • 与标准 Liquid 的关系：除下列自定义能力外，可使用 Liquid 标准语法与内置过滤器。
  • 版本差异：具体站点是否开启登录、搜索、反馈、AI 等功能以租户配置为准；模板中应对空值做判断（如 
    {% if current_user %}
    ）。
  • Target Audience: For developers writing Liquid for Baklib site themes; does not cover details of Baklib's application backend or Rails implementation.
  • Relationship with Standard Liquid: Except for the following custom capabilities, you can use standard Liquid syntax and built-in filters.
  • Version Differences: Whether functions like login, search, feedback, and AI are enabled for a specific site depends on tenant configuration; templates should handle null values (e.g., 
    {% if current_user %}
    ).

快速示例

Quick Example

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