搜索判断（新增）{% if search.tag or search.keywords %}
解析：overflow-x-auto 实现了溢出部分水平滚动breadcrumb 必须；为面包屑自定义cssbreadcrumb-item 必须；为面包屑自定义cssflex 使“/”和文本在一行（不被挤压）break-keep 使文本在一行（不被挤压）
#### **feedback - 用户反馈表单**
{% form_tag 'feedback' %}
{% endform_tag %}
#### **password - 密码登录**
{% form_tag 'sign_in_with_password' %}
{% endform_tag %}
#### **ssb - Baklib 账号一键登录**
{% form_tag 'sign_in_with_ssb' %}
{% endform_tag %}
#### **sso - 企业 SSO 账号一键登录**
{% form_tag 'sign_in_with_sso' %}
{% endform_tag %}
#### **I18n翻译**
模板设置翻译：
`"t:setings_schema.beian.title"`
页面翻译：
`_("备案号")`
模板翻译：
`{{ 'setings_schema.beian.title' | t : '默认值' }}`
#### **颜色选项卡**
站点主题设置默认添加的颜色选项卡，共6种色卡可定制，如图所示：
在站点设置页面定制好色卡颜色后，可在代码中使用，具体方法：
text-primary
text-primary-lighten
text-primary-darken
text-primary-50
text-primary-600/50
---
URL: https://dev.baklib.cn/install/introduction
Updated: 2024-11-28
## 标题
模板介绍
## 内容
**阅读对象：**Baklib模板开发人员， IT部门前端开发人员
**阅读场景：**1）新开发一个站点模板；2）定制化修改已有站点模板。
### **模板介绍**
Baklib 是一个混合 CMS 系统，系统中的每一个应用站点（包括 CMS、Wiki、Community）的前端界面都是由一个模板驱动的。一个模板构成了一个应用站点的基本构架，后端负责承接知识库内容，前端负责体验界面展示。以下是Baklib模板引擎流程图：
模板引擎流程
你可以把模板理解为启动一个应用站点的初始化库，前端界面都在这个模板库中实现，而且前端模板完全开放，方便用户对前端界面进行任意形式的修改。
* 模板具有固定的文件目录结构。
* 模板语言由开源的Liquid语法实现。
* 后台输出固定的模板变量 API，供Liquid调用。
* 你可以将模板托管在Baklib默认的git仓库中，也可以托管在Github/Gitlab/Gitee等第三方存储库。
### 模板分类
* **公共模板：**系统内置的标准模板，在【工作台】--【市场】中查看。
* **组织模板：**组织从公共模板复制的模板，或者从外部git仓库导入的模板。
🙋
公共模板不可编辑（但可以复制为组织模板），组织模板可以在线编辑并发布。
### 在哪里查看模板？
1. 首先，当我们新安装一个应用站点的时候，会进入【工作台】--【市场】中查看模板列表。 2. 其次，在应用站点创建成功后，可进入【后台管理】--【模板开发】到模板开发界面。 ### --- URL: https://dev.baklib.cn/overview/themes/support-portal Updated: 2024-11-17 ## 标题 CMS: Support Portal ## 内容  **模板类型：**CMS 模板名称： Support Portal **模板介绍：**Support Portal 是一个功能强大、操作简单的在线支持平台，包含知识库、发布日志、FAQ、视频、博客等。 ## 首页主题 该模板预设了三个首页主题风格：List书目风格、Help Center风格、Docs文档风格。 **List书目风格：**首页直接呈现了整个站点的页面层级导航，类似图书目录，简单直接。  **Help Center主题风格：**首页横幅图片背景+大搜索框。  help center主题风格  **Docs风格：** 首页Card版块栏目布局，适合做企业帮助中心、技术文档、客户支持文档。   ## 其他页面预览 内部页面、搜索页、标签页预览效果。      --- URL: https://dev.baklib.cn/overview/themes/guide/fe25 Updated: 2024-11-17 ## 标题 主题安装 ## 内容 ## Guide模板介绍 名称： Guide 概述：小型文档内容管理，可用于构建产品手册、指南、FAQ、Release、Blog等 模板特点： 1. 首页简洁明了，一排到底，没有复杂的层级结构。 2. 提供了卡片列表和文本列表两种页面排版。 3. 搭配Tag标签分类更显得内容丰满。 适合场景： 1. 小规模文档内容管理，注重用户体验。 2. 作为无头CMS内嵌到其他软件内，用于移动端访问效果更优。 不适合场景： 1. 不适用于复杂层级（三级及以上）结构的文档排版 ^ 效果预览： 首页Card主题效果  标签页：  首页List主题效果 搜索页： 详情页效果 ## 视频教程 如何十分钟创建一个Guide模板内容站点 * Guide 模板视频教程制作 ^ ## 创建Guide模板站点 在模板市场中找到“Guide产品指南”的模板，进行应用创建，需要3步完成： 第1步：选择模板  第2步：设置站点 第3步：初始化页面 创建成功后，进入站点管理界面~  前端预览效果如下：  可以说一个基本的Guide CMS网站就创建好了。接下来需要做的事情，就是不定期的在后台新增页面即可。 ## 进阶设置 ### 站点设置 关于如何完善一个CMS网站的设置，包括基本信息设置、域名管理、访问控制、多应用关联、反馈设置以及回收站等功能，这里不再一一讲解，大家可以去参考CMS站点的教程。 接下来重点是要讲解基于本模板的一些特别的设置。 导航到工作台“应用设置--> 界面设置”： 站点基本信息：  品牌相关信息设置：  站点设置主要包括： 1. 站点基本信息 2. 品牌相关信息 3. 页头页脚导航信息 4. 站点主题颜色 当设置好站点信息以后，一个网站的基本骨架就构建完成了。在接下来的事就是讨论如何添加网站的页面。 ### 页面设置 页面设置  预览 页面的设置也相对比较简单。主要是提供标题、摘要、标签、封面图、和内容。 我们可以看到页面设置的前端效果，同时在移动端也会有很好的适配。 ### 子页面 本模板的页面是支持添加子页面的。且子页面的添加可以无限级，但是在前台只显示本页面的子页面一级，一次类推。 后台  前台 ### 标签设置 本模板还支持标签设置管理，站点设置的标签，在添加页面的时候可以为每个页面打标签，前台实现标签分类：  ### 用户反馈管理 在每个页面内容下方放置了页面反馈表单，可以通过后台设置是否启用反馈，是否启用反馈留言：  ### 首页主题更换 本模板预设了两个首页主题。一个是card模式，基于图片封面展示页面列表，这种风格主要突出图文的表达。 另外一种是list模式，直接展示页面的标题摘要列表。 这两种风格各有特点。  ### 其他特殊技巧 该主题可以设置用户反馈、页头、页脚部分是否显示的状态。同时，本模板创建的应用在移动端的展示效果会非常的简洁流畅，也适合于内嵌在应用当中做帮助中心指引。  ## 低代码开发 通过以上的配置和说明，已经满足大部分用户的需求了。 但是如果还需要更进一步的魔改网站界面怎么办呢？ Baklib低代码平台就该出场了。这一部分将直接进入低代码模板开发环节。 模板layout: {% meta_tags %} {{ 'editor.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }} {{ 'css/main.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }} {{ 'javascripts/main.js' | asset_url | script_tag: defer: true, data-turbo-track: 'reload' }} {%# TIPS：在低代码平台开发时，请打开下一行代码注释 %} {% if true %} {{ 'javascripts/cdn.tailwindcss.js' | asset_url | script_tag: data-turbo-track: 'reload' }} {% endif %} {% if site.settings.is_allow_header %} {% render 'header' %} {% endif %}
{{ content_for_layout }}
{% if site.settings.is_allow_footer %}
{% render 'footer' %}
{% endif %}
页面模板和片段：
themes/cms/guide/templates/
index.card.liquid
index.list.liquid
page.liquid
search.liquid
tag.liquid
themes/cms/guide/snippets/
_card.liquid
_feedback_form.liquid
_footer.liquid
_header.liquid
_list.liquid
_page.liquid
_sidebar.liquid
_sub_page_list.liquid
暂时无法在飞书文档外展示此内容
当知道模板和对应的页面板块的关系以后。我们就可以针对性的修改。 不同的部分来完全的定制化每一个方面。
## Guide模板构建的页面参考
---
URL: https://dev.baklib.cn/overview/themes/support-portal/05dd
Updated: 2024-11-17
## 标题
开发指南
## 内容
## Docs 模板介绍
名称： Docs
概述：基于CMS的中型文档内容管理，可用于构建在线帮助中心、文档知识库、技术手册，内置多首页主题
模板特点：
1. 首页具有更多样的布局方式，充当站点地图的引导作用。
2. 支持多层级的树状菜单，让用户在任何时候都不迷路。
3. 强调搜索框和搜索自定义功能。
适合场景：
1. 中等规模文档内容管理，注重用户体验。
2. 作为无头CMS内嵌到其他软件内，用于移动端访问效果更优。
不适合场景：
1. 对知识库内容编辑协同、编排管理要求高，知识内容输出需多版本、多复用的场景，建议采用Wiki模板。
^
效果预览：
首页预览
详情页预览
## 创建Docs应用站点
在应用市场找到“docs文档管理系统”模板，点击安装，一共三个步骤：
第一步：
第二步：
第三步：
创建成功后，文档站点的预览效果如下：
## 站点设置
接下来我们将考虑如何打造这个主题模板，进入“站点设置-->界面设置”
Logo图标：显示在站点页头或页脚
首页背景大图： 搜索框后面的背景图，一般采用虚化的深色图片。
站点描述：即一句话口号
热搜关键词：后台自定义的关键词。这个是Docs模板特殊的设置内容，我们可以看到
## 首页设置
设置好站点内容，并添加相关页面以后，整个站点的展示效果就丰满了，Docs模板提供了3个首页样式：
### [index.help][1]\_center.liquid 首页样式
特点：
1. 首页显示背景大图和搜索栏（自定义热门搜索）
2. 下面展示六个一级栏目及最近4条更新记录
3. 常见问题栏目，按浏览量展示最近10条最新文章
### [index.docs][2].liquid 首页样式
特点：
1. 首页跟内页保持一致展示效果
2. 左侧树状菜单一目了然
3. 右侧图标展示一级栏目和最新热门文章
### index.list.liquid 首页样式
特点：
1. 首页直接通过书目的形式展示知识库所有内容。
^
## 内页设置
内页的展示效果页比较简单清晰，大致分为几个版块：
1. 页头：站点Logo+名称， 右侧自定义导航菜单和暗黑模式切换开关。
2. 左侧：整站内容多层级导航菜单
3. 中间显示文章内容，用户反馈，上一页下一页导航。
4. 右侧将自动提取文章内标题，实现内页导航
5. 底部为页脚，显示品牌信息和自定义导航内容。
## 低代码开发
通过以上的配置和说明，已经满足大部分用户的需求了。 但是如果还需要更进一步的魔改网站界面怎么办呢？ Baklib低代码平台就该出场了。这一部分将直接进入低代码模板开发环节。
模板layout:
{% meta_tags %}
{{ 'editor.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }}
{{ 'css/viewer.min.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }}
{{ 'javascripts/main.js' | asset_url | script_tag: defer: true, data-turbo-track: 'reload' }}
{{ 'css/main.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }}
{%# TIPS：在低代码平台开发时，请打开下一行代码注释 %}
{% if true %} {{ 'javascripts/cdn.tailwindcss.js' | asset_url | script_tag: data-turbo-track: 'reload' }} {% endif %}
{% render 'footer', settings: site.settings %}
### **文件说明**
layout 布局文件是一个标准的 HTML 文件，即包括 <html>、<head>、<body>标签。其中在<head>下引用全局资源文件、定义meta元数据、设置SEO数据、指定站点语言等。
#### content\_for\_layout
`{{ content_for_layout }}` 方法用于替换 `templates` 下的文件内容。您需要在 `` 和 `` HTML 标记之间添加对此方法的引用。
#### render
`render` 方法用于引用 `snippets` 下的文件内容。比如：
{% render 'header', settings: site.settings, page: page %}
表示引用文件: `snippets/_header.liquid`
#### 公共资源
|
---
URL: https://dev.baklib.cn/theme/statics/about
Updated: 2024-07-19
## 标题
about.liquid
## 内容
Boost your productivity.
---
URL: https://dev.baklib.cn/theme/templates/index
Updated: 2024-07-19
## 标题
index.liquid
## 内容
首页模板，文件位置： `docs/templaes/index.liquid`
{% render 'footer', settings: site.settings %}
{% schema %}
{
"name": "首页样式",
"thumb_url": "images/theme/index.png",
"preview_image_urls": [
"images/theme/index-demo1.png",
"images/theme/index-demo2.png"
],
"description": "站点首页",
"sub_page_templates": ["products","blog"]
}
{% endschema %}
---
URL: https://dev.baklib.cn/faqs/a121
Updated: 2024-07-19
## 标题
path 和 url 的区别？
## 内容
比如一篇文章的路径为： `https://help.baklib.cn/my/profile`， 则：
* page.path 返回文章的相对路径： `/my/profile`
* page.url 返回文章的绝对路径： `https://help.baklib.cn/my/profile`
> 一般在模板开发中推荐使用 `page.path`， 如果用 `page.url `可能会导致更换了域名以后，原来引用的地址失效。
---
URL: https://dev.baklib.cn/liquid/basics/introduction
Updated: 2024-07-19
## 标题
介绍(Introduction)
## 内容
**Liquid 使用模板文件**内的[对象][1]、[标签][2]和[过滤器][3]的组合来显示动态内容。
## 对象
**对象**包含 Liquid 在页面上显示的内容。对象和变量用双花括号括起来时显示：`{{`和`}}`。
输入
{{ page.title }}
输出
Introduction
`title`在这种情况下，Liquid 正在渲染对象属性的内容`page`，其中包含文本`Introduction`。
## 标签
**标签**为模板创建逻辑和控制流。花括号百分比分隔符`{%`和`%}`它们包围的文本在呈现模板时不会产生任何可见的输出。这样您就可以分配变量并创建条件或循环，而无需在页面上显示任何 Liquid 逻辑。
输入
{% if user %}
Hello {{ user.name }}!
{% endif %}
输出
Hello Adam!
标签可以分为多种类型：
* [控制流][4]
* [迭代][5]
* [模板][6]
* [变量赋值][7]
您可以在各自的部分中阅读有关每种标签类型的更多信息。
## 筛选器
**过滤器**会改变 Liquid 对象或变量的输出。它们用于双花括号`{{ }}`和[变量赋值][7]中，并以竖线字符分隔`|`。
输入
{{ "/my/fancy/url" | append: ".html" }}
输出
/my/fancy/url.html
一个输出上可以使用多个过滤器，并从左到右应用。
输入
{{ "adam!" | capitalize | prepend: "Hello " }}
输出
Hello Adam!
[1]: https://shopify.github.io/liquid/basics/introduction/#objects
[2]: https://shopify.github.io/liquid/basics/introduction/#tags
[3]: https://shopify.github.io/liquid/basics/introduction/#filters
[4]: https://shopify.github.io/liquid/tags/control-flow/
[5]: https://shopify.github.io/liquid/tags/iteration/
[6]: https://shopify.github.io/liquid/tags/template/
[7]: https://shopify.github.io/liquid/tags/variable/
---
URL: https://dev.baklib.cn/liquid/tags/control-flow
Updated: 2024-07-19
## 标题
控制流(Control flow)
## 内容
控制流标签创建决定 Liquid 代码块是否被执行的条件。
## if
仅当满足特定条件时才执行代码块`true`。
输入
{% if product.title == "Awesome Shoes" %}
These shoes are awesome!
{% endif %}
输出
These shoes are awesome!
## unless
与之相反——仅当**不满足**`if`某个条件时才执行代码块。
输入
{% unless product.title == "Awesome Shoes" %}
These shoes are not awesome.
{% endunless %}
输出
These shoes are not awesome.
这相当于执行以下操作：
{% if product.title != "Awesome Shoes" %}
These shoes are not awesome.
{% endif %}
## elsif / else
`if`在或块内添加更多条件`unless`。
输入
{% if customer.name == "kevin" %}
Hey Kevin!
{% elsif customer.name == "anonymous" %}
Hey Anonymous!
{% else %}
Hi Stranger!
{% endif %}
输出
Hey Anonymous!
## case/when
创建一个 switch 语句，当变量具有指定值时执行特定的代码块。`case`初始化 switch 语句，`when`语句定义各种条件。
一个`when`标签可以接受多个值。当提供多个值时，当变量与标签内的任意值匹配时，就会返回表达式。以逗号分隔列表的形式提供值，或使用运算符分隔它们`or`。
`else`案例末尾的可选语句提供了在没有任何条件满足时执行的代码。
输入
{% assign handle = "cake" %}
{% case handle %}
{% when "cake" %}
This is a cake
{% when "cookie", "biscuit" %}
This is a cookie
{% else %}
This is not a cake nor a cookie
{% endcase %}
输出
This is a cake
---
URL: https://dev.baklib.cn/community/b511
Updated: 2024-10-16
## 标题
变量和方法
## 内容
本教程介绍 Liquid 模板 Community 社区开发中的变量和方法使用。
## **Object（对象）**
|
### **Comment（页面）同cms站点）**
| 
{{ page.author.name }}
### **plugins.feedback （用户反馈配置信息）（同cms站点）**
|
渲染输出
---
URL: https://dev.baklib.cn/liquid/tags
Updated: 2025-01-02
## 标题
标记(Tags)
## 内容
条件判断、循环、变量和注释。
---
URL: https://dev.baklib.cn/guide/forms
Updated: 2024-12-09
## 标题
动态表单
## 内容
用于模版定义动态字段，设计的表单类型，以达到自定义模版变量的目的：
# **表单 type: **`checkbox`
|
{% if page.settings.tags.size > 0 %}
{% endif %}
{% render "feedback_form", page: page %}
{% schema %}
{
"name": "页面",
"description": "页面",
"thumb_url": "images/theme/page.png",
"sub_page_templates": ["page"],
"settings": [
{
"id": "title",
"type": "text",
"label": "标题"
},
{
"id": "content",
"type": "richtext",
"label": "内容"
},
{
"id": "tags",
"type": "tag_picker",
"multiple": true,
"label": "标签"
}
]
}
{% endschema %}
---
URL: https://dev.baklib.cn/faqs/c067
Updated: 2024-11-17
## 标题
如何实现模板的多主题切换？
## 内容
针对同一个模板，首先多主题切换， 则可以通过添加后缀名实现。
比如页面模板 `page.liquid`，新增一个页面的主题样式则可以定义为：`page.channel.liquid`
|-- templates
|-- page.liquid
|-- page.channel.liquid
|-- page.book.liquid
模板设计了多主题以后，在页面编辑中可以可视化切换：
---
URL: https://dev.baklib.cn/community/c925
Updated: 2025-12-04
## 标题
表单示例
## 内容
[https://www.baklib.cn/](https://www.baklib.cn/)
👏
选择的模板 user\_creatable 设置为true表示前端可以创建此种类型的模板，user\_editable设置为true表示前端可以编辑此种类型的模板，user\_deletable设置为true表示前端可以删除此种类型的模板， 未设置的情况下创建编辑修改此种类型的模板页面会抛出错误。
创建编辑时会检查提交的template\_variables模板变量是不是支持修改，例如模板变量里面title、content 需要修改则 \"user\_permitted\_attributes\": \[\"title\", \"content\"\]
#### **page- 页面表单**
1. 创建帖子
{% form_tag 'page' %}
{% endform_tag %}
支持的参数：
2. 编辑帖子
{% form_tag 'edit_page', page %}
{% endform_tag %}/
支持的参数：
3. 删除帖子
{% form_tag 'delete_page' %}
{% endform_tag %}
#### **Feedback- 反馈表单**
1. 添加反馈
{% form_tag 'feedback', page: page %}
{% endform_tag %}
支持的参数：
2. 删除对应表情反馈
{% form_tag 'delete_feedback', page: page, useful_type: site.settings.feedback_useful_type %}
{% endform_tag %}
#### **reply- 页面表单**
//创建评论
{% form_tag 'reply' %}
{% endform_tag %}//删除评论
{% form_tag 'reply', reply, method: 'delete' %}
{% endform_tag %}
支持的参数：
#### richtext\_field\_tag-富文本内容输入框
{% richtext_field_tag 'page[template_variables][content]', content, toolbar: 'full' %}
支持的参数：
---
URL: https://dev.baklib.cn/liquid/tags/comment
Updated: 2025-01-02
## 标题
注释
## 内容
`comment` 标记让你能够在 Liquid 模板中书写的内容不被输出。任何书写在 `comment` 起始与结束标记之间的内容都不会被输出，如果是 Liquid 代码则不会被执行。
输入
Anything you put between {% comment %} and {% endcomment %} tags
is turned into a comment.
输出
Anything you put between tags
is turned into a comment.
---
URL: https://dev.baklib.cn/liquid/basics/3a27
Updated: 2025-01-02
## 标题
操作符
## 内容
Liquid 包含了大量逻辑（logical）和比较操作符（comparison operator）。
## 基本操作符
|
{% form_tag 'search', class: "col-span-7 md:col-start-5 md:col-span-3" %}
{% endform_tag %}
其中，获得自定义搜索结果：
{% paginate_tag search.extends, as: 'extends' %}
{% for extend in extends %}
{{extend.link_text}}
{% endfor %}
{% endpaginate_tag %}
获取自然搜索结果：
{% paginate_tag search.pages, as: 'items' %}
{% for page in items %}
{{ page.link_text | highlight: search.keywords }}
{% else %}
{{ "generic.empty" | t }}
{% endfor %}
{% render 'paginate', paginate: paginate %}
{% endpaginate_tag %}
## 2024-09 更新
高亮块 CSS：
/* Search Result Highlight */
.keyword-highlight-block b{
color: var(--primary);
}
搜索结果中标题的展示：
# 原来的写法：
{{ page.link_text | highlight: search.keywords }}新的写法：{{ page.highlighted_search_title }}
搜索结果中内容的展示：
# 原来的写法：
{{ page.settings.content | strip_html | highlight: search.keywords }}新的写法：{{ page.highlighted_search_content }}
搜索页面的变量 `search` 新增了两个属性：
* `search.extends` - 自定义结果集
* `search.page_number` - 当前分页的页码
因为搜索页面把自定义结果放在了 `search.extends` 里，所以需要单独代码把内容循环显示出来
` 和 `
` 这两个 HTML 标签将其包裹起来。
输入
{% tablerow product in collection.products %}
{{ product.title }}
{% endtablerow %}
输出
## tablerow (parameters)
### cols
定义表格应当有多少列。
输入
{% tablerow product in collection.products cols:2 %}
{{ product.title }}
{% endtablerow %}
输出
#### limit
在执行到指定的脚标（index）之后退出 tablerow 。
{% tablerow product in collection.products cols:2 limit:3 %}
{{ product.title }}
{% endtablerow %}
### offset
在指定的脚标（index）之后开始执行 tablerow 。
{% tablerow product in collection.products cols:2 offset:3 %}
{{ product.title }}
{% endtablerow %}
### range
定义循环执行的范围。可利用数字和变量来定义执行范围。
{% assign num = 4 %}
{% tablerow i in (1..num) %}
{{ i }}
{% endtablerow %}
{% tablerow i in (3..5) %}
{{ i }}
{% endtablerow %}
[1]: https://docs.shopify.com/themes/liquid/objects/for-loops
[2]: https://shopify.github.io/liquid/tags/iteration/#for
[3]: https://liquid.bootcss.com/tags/iteration/#for
---
URL: https://dev.baklib.cn/liquid/basics/1831
Updated: 2025-01-02
## 标题
真值与假值
## 内容
编程时，在条件判断中任何返回 `true` 的都被叫做 **真值（truthy）**。任何返回 `false` 的都被叫做 **假值（falsy）**。所有的对象（object）类型都可以被描述为真值（truthy）或假值（falsy）。
* [Truthy][1]
* [Falsy][2]
* [Summary][3]
## 真值（Truthy）
除了 `nil` 和 `false` 之外的所有值都是真值。
如下例，字符串 “Tobi” 虽不是布尔类型，但是其在条件判断时被当做真值（truthy）：
{% assign tobi = "Tobi" %}
{% if tobi %}
This condition will always be true.
{% endif %}
[字符串（String）][4]，即便是空字符串，也是真值（truthy）。如下例，如果 `settings.fp_heading` 是个空字符串将会输出空 HTML 标签：
输入
{% if settings.fp_heading %}
{% render 'sidebar', site: site %}
---
URL: https://dev.baklib.cn/faqs/9946
Updated: 2024-10-22
## 标题
如何解决页面内容溢出的问题
## 内容
经常我们在添加非常长的链接文字的时候，会出现内容溢出到页面边距的情况。需要在 main.css 中添加样式：
a {
@apply break-all text-wrap;
}
具体 text wrap样式请参考 TailwindCSS 教程： [https://tailwindcss.com/docs/text-wrap][1]
| )`,
lighten: `hsl(var(--theme-color-${name}-hsl-h) var(--theme-color-${name}-hsl-s) calc(var(--theme-color-${name}-hsl-l) + 15%))`,
darken: `hsl(var(--theme-color-${name}-hsl-h) var(--theme-color-${name}-hsl-s) calc(var(--theme-color-${name}-hsl-l) - 15%))`,
...[50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950].reduce((map,lightness) => {
return {
...map,
[lightness]: `hsl(var(--theme-color-${name}-hsl-h) var(--theme-color-${name}-hsl-s) ${100 - lightness/10*0.8}%)`
}
}, {})
}
}
}, {}),
// 错误色永远是红色，饱和度与主色调保持一致
error: {
DEFAULT: `hsl(355 75% var(--theme-color-primary-hsl-l) / )`,
lighten: `hsl(355 75% calc(var(--theme-color-primary-hsl-l) + 15%))`,
darken: `hsl(355 75% calc(var(--theme-color-primary-hsl-l) - 15%))`,
...[50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950].reduce((map,lightness) => {
return {
...map,
[lightness]: `hsl(355 75% ${100 - lightness/10*0.8}%)`
}
}, {})
}
}
},
spacing: {
4.5: "1.125rem",
5.5: "1.375rem",
18: "4.5rem",
},
},
},
plugins: [],
}
```
#### 3.引入Tailwindcss到css文件中
例如：`./src/main.css`
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
@config '../tailwind.config.js'
```
#### 4.在`package.json`中配置css编译路径
```json
"scripts": {
"build": "npm-run-all --parallel build:css build:js",
"build:css": "npx tailwindcss -i ./src/main.css -o ./assets/css/main.css",
......
"dev": "npm-run-all --parallel 'build:css -- --watch' 'build:js -- --watch'"
}
```
#### 5.在`theme.liquid`文件中引入css
```html
{{ 'css/main.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }}
```
## 编译&发布
```bash
yarn build
```
---
URL: https://dev.baklib.cn/liquid/e1712
Updated: 2025-09-12
## 标题
其他
---
URL: https://dev.baklib.cn/liquid/e1712/af15c
Updated: 2026-04-11
## 标题
模板变量 Markdown 输出
## 内容
```
# 模板变量 Markdown 导出配置
本文档面向开发者，说明如何通过模块将页面模板变量导出为 Markdown 格式。
## 功能概述
将页面的模板变量按配置转换为 Markdown 格式。主要应用场景包括：
- LLM 训练数据导出
- 内容备份与迁移
- 文档生成
## 配置方式
### 1. 模板 Schema 配置
在模板 JSON Schema 中，通过添加 `to_markdown: true` 标记需要导出的变量：
```json
{
"id": "content",
"type": "richtext",
"label": "正文内容",
"to_markdown": true
}
```
### 2. 批量配置示例
```json
{
"settings": [
{
"id": "title",
"type": "text",
"label": "标题",
"to_markdown": true
},
{
"id": "summary",
"type": "textarea",
"label": "摘要",
"to_markdown": true
},
{
"id": "body",
"type": "richtext",
"label": "正文",
"to_markdown": true
},
{
"id": "cover_image",
"type": "image_picker",
"label": "封面图",
"to_markdown": true
}
]
}
```
## 支持的字段类型映射
| 类型分类 | 具体类型 | Markdown 输出行为 |
|---------|---------|------------------|
| **富文本类型** (`RICH_TYPES`) | `richtext`, `html` | 通过 `FragmentValue.to_markdown` 转换 |
| **纯文本类型** (`PLAIN_TEXT_TYPES`) | `text`, `textarea`, `paragraph` | 直接输出字符串 |
| **代码类型** (`CODE_TYPES`) | `code` | 包裹为代码块，支持 `language` 指定语法 |
| **选项类型** (`CHOICE_TYPES`) | `select`, `radio`, `checkbox`, `link` | 直接输出值 |
| **简单值类型** (`SIMPLE_VALUE_TYPES`) | `number`, `range`, `date`, `color`, `font_picker`, `color_background` | 直接输出字符串 |
| **资源选择器** (`PICKER_TYPES`) | `image_picker`, `file_picker`, `video_picker`, `dam_picker` | 生成 20 分钟有效期的前端访问地址 |
| **标签选择器** (`TAG_PICKER_TYPE`) | `tag_picker` | 输出标签名称列表 |
## 输出格式
### 标准段落格式
每个启用了 `to_markdown: true` 的变量输出为：
```markdown
## {label}
{转换后的内容}
```
其中 `label` 优先取 `setting["label"]`，否则使用 `id.humanize`。
### 各类型详细输出示例
#### 富文本类型
输入 HTML 内容：
```html
特别注意：
👏
加入以下判断，让暗黑模式首先跟随用户电脑的系统设置：
window.matchMedia('(prefers-color-scheme: dark)').matches
---
URL: https://dev.baklib.cn/liquid/tags/variable
Updated: 2025-01-02
## 标题
变量
## 内容
变量标记（variable tag）用于创建新的 Liquid 变量。
## assign
创建一个新变量。
输入
{% assign my_variable = false %}
{% if my_variable != true %}
This statement is valid.
{% endif %}
输出
This statement is valid.
将变量用 `"` 包裹之后则将其当做字符串对待。
输入
{% assign foo = "bar" %}
{{ foo }}
输出
bar
## capture
将 `capture` 开始与结束标记之间的字符串捕获之后赋值给一个变量。通过 `{% capture %}` 创建的变量都是字符串。
输入
{% capture my_variable %}I am being captured.{% endcapture %}
{{ my_variable }}
输出
I am being captured.
使用 `capture` 时，你还可以利用 `assign` 创建的其他变量创造一个复杂的字符串。
输入
{% assign favorite_food = 'pizza' %}
{% assign age = 35 %}
{% capture about_me %}
I am {{ age }} and my favorite food is {{ favorite_food }}.
{% endcapture %}
{{ about_me }}
输出
I am 35 and my favourite food is pizza.
## increment
创建一个全新的数值变量，并且在后续每次调用时将此变量的值加 1。初始值是 0。
输入
{% increment my_counter %}
{% increment my_counter %}
{% increment my_counter %}
输出
0
1
2
通过 `increment` 标记（tag）创建的变量与通过 `assign` 或 `capture` 创建的变量是相互独立的。
在下面的实例中，名为 “var” 的变量是通过 `assign` 创建的。然后将 `increment` 标记（tag）在相同的变量名上应用了几次。注意，`increment` 标记（tag）不会对 `assign` 创建的变量 “var” 及其值产生任何影响。
输入
{% assign var = 10 %}
{% increment var %}
{% increment var %}
{% increment var %}
{{ var }}
输出
0
1
2
10
## decrement
创建一个全新的数值变量，并且在后续每次调用时将此变量的值减 1。初始值是 -1。
输入
{% decrement variable %}
{% decrement variable %}
{% decrement variable %}
输出
-1
-2
-3
和 [increment][1] 类似，在 `decrement` 之中创建的变量与通过 `assign` 或 `capture` 创建的变量是互相独立的。
[1]: https://liquid.bootcss.com/tags/variable/#increment
---
URL: https://dev.baklib.cn/liquid/basics/6dec
Updated: 2025-01-02
## 标题
控制输出的空白符
## 内容
在 Liquid 模版中，你可以将连字符放在标记（tag）中，例如 `{{-`、`-}}`、`{%-` 和 `-%}`，用于将标记（tag）渲染之后的输出内容的左侧或右侧的空拍符剔除。
通常，即使不输出文本，模版中的任何 Liquid 表达式仍然会在渲染之后输出的 HTML 中包含一个空行：
输入
{% assign my_variable = "tomato" %}
{{ my_variable }}
请注意渲染之后输出的 “tomato” 字符前面包含了一个空行：
输出
tomato
通过为 `assign` 标记（tag）添加连字符，可以将渲染之后所输出的空拍符删除：
输入
{%- assign my_variable = "tomato" -%}
{{ my_variable }}
输出
tomato
如果你不希望任何标记（tag）被渲染之后所输出的内容有任何空白符，只需在所有标记（tag）两侧全部添加连字符即可，例如 (`{%-` 和 `-%}`)：
输入
{% assign username = "John G. Chalmers-Smith" %}
{% if username and username.size > 10 %}
Wow, {{ username }}, you have a long name!
{% else %}
Hello there!
{% endif %}
不做空白符控制的输出
Wow, John G. Chalmers-Smith, you have a long name!
输入
{%- assign username = "John G. Chalmers-Smith" -%}
{%- if username and username.size > 10 -%}
Wow, {{ username }}, you have a long name!
{%- else -%}
Hello there!
{%- endif -%}
带有空白符控制的输出
Wow, John G. Chalmers-Smith, you have a long name!
---
URL: https://dev.baklib.cn/liquid/filters/capitalize
Updated: 2025-01-02
## 标题
capitalize
## 内容
将字符串首字母转为大写。
输入
{{ "title" | capitalize }}
输出
Title
`capitalize` 只把字符串的首字母转为大写，其他字符不受影响：
输入
{{ "my great title" | capitalize }}
输出
My great title
---
URL: https://dev.baklib.cn/faqs
Updated: 2024-08-24
## 标题
常见问题
---
URL: https://dev.baklib.cn/theme/statics
Updated: 2024-07-19
## 标题
statics/
## 内容
该目录用于存放静态页面，并在路由预设了` /s/` 路由。
> 比如当你在该目录添加了一个` about.liquid `文件，则立刻即可在前端通过路由` /s/about `访问。
引用方法：
产品报价
产品报价/基础版
或者：
产品报价
产品报价/基础版
给静态文件添加 TKD：
{% set_meta_title 'about' %}
{% set_meta_description 'some thing about this page' %}
{% set_meta_keywords 'baklib, about as' %}
---
URL: https://dev.baklib.cn/faqs/621d
Updated: 2024-10-22
## 标题
支持多站点域名合为一个域名吗？
## 内容
**回答：** 私有化部署的客户，可以通过服务器端Nginx反向代理来实现多域名融合。
通常情况下，Baklib后台每创建一个站点都会自动分配一个独立的域名， 因此创建两个站点后，分别是两个分开的域名， 如站点A：www.aaa.com, 站点B： www.bbb.com。而通过Nginx反向代理，可以实现比如公司域名为: www.company.com，则：
* A站点路径： www.company.com/aaa
* B站点路径： www.company.com/bbb
见更新日志：
* [v1.2.12][1]
- 支持Nginx反向代理重写URL，实现多站点合并在一个域名下面
[1]: https://gitlab.tanmer.com/baklib/baklib/-/tags/v1.2.12
---
URL: https://dev.baklib.cn/liquid/filters/ceil
Updated: 2025-01-02
## 标题
ceil
## 内容
将一个浮点数向上取整并返回一个最接近的整数。在 ceil 过滤器执行之前 Liquid 会先尝试将输入转换为数字格式。
输入
{{ 1.2 | ceil }}
输出
2
输入
{{ 2.0 | ceil }}
输出
2
输入
{{ 183.357 | ceil }}
输出
184
以下实例所用输入是字符串：
输入
{{ "3.5" | ceil }}
输出
4
---
URL: https://dev.baklib.cn/liquid/tags/4ece
Updated: 2025-04-11
## 标题
页面数据筛选：query
## 内容
> 用于站点 `pages` 的数据过滤
## **1. 支持的功能**
1. 支持筛选页面定义的动态变量数据进行页面过滤
2. 支持通过页面属性进行页面过滤
3. 排序
4. 分页
## **2. 开始使用**
### **2.1 基本语法**
`query` 标签的基本语法：
{% query 结果变量名 from site.pages %}
JSON格式的查询条件
{% endquery %}
### **2.2 JSON 参数中的转义注意事项**
在使用 JSON 格式的查询条件时，特别是对于动态值，使用者需要注意以下几点以确保正确的转义和格式：
1. **字符串转义**：在 JSON 中，字符串需要用双引号包裹，且内部的双引号需要使用反斜杠 `\\` 进行转义。例如：`"title": "这是一个\"示例\"标题"`。
2. **反斜杠转义**：如果字符串中包含反斜杠 `\\`，需要进行双重转义，即使用 `\\\\`。例如：`"path": "C:\\\\Users\\\\Example"`。
3. **特殊字符**：注意转义特殊字符，如换行符 `\\n`、制表符 `\\t` 等。
4. **避免语法错误**：确保 JSON 的结构正确，所有的键值对用逗号分隔，最后一个键值对后不应有逗号。
5. **使用工具**：建议使用 JSON 格式化工具或库来自动处理转义和格式化，以减少手动错误。
通过注意这些细节，可以确保在使用 JSON 格式的查询条件时，动态值能够被正确解析和处理。
### **2.3 示例**
{% query faq_pages from site.pages %}
{
"where": {
"template_name_eq": "page",
"settings.var_name_matches": params.any_string,
"settings.description_start": "帮助"
},
"order_by": ["-created_at"],
"limit": 10,
"offset": 0
}
{% endquery %}
{% for page in faq_pages %}
{{ page.title }}
{% endfor %}
## **3. 参数说明**
### 3.1 `where`
* 用于指定查询条件，支持页面属性和动态变量的筛选。
* 支持复杂的逻辑组合，如 `and` 和 `or`。
#### **示例**
"where": {
"属性名_操作符": 值,
"settings.变量名_操作符": 值,
"settings.模版文件完整路径:变量名_操作符": 值, // 指定检索使用某模版创建的页面中动态变量的数据
"and": {
// 嵌套的AND条件
},
"or": {
// 嵌套的OR条件
}
}
"where": {
"template_name_eq": "product",
"or": {
"name_start": "文章标题",
"settings.description_cont": "智能设备"
}
}
### 3.2 `order_by`
* 用于指定结果的排序规则。
* 格式为：`["字段名", ...]`。
#### 排序方向
* **升序（默认）**：直接使用字段名，如 `"created_at"`
* **降序**：在字段名前加 `-` 前缀，如 `"-created_at"`
#### **支持的排序字段**
* `created_at`: 创建时间
* `visits_count`: 访问次数
* `edited_at`: 编辑时间
* `published_at`: 发布时间
#### **示例**
"order_by": ["-visits_count", "created_at"]
### 3.3 分页 `limit` 和 `offset`
* 用于指定结果的分页
^
"limit": 10,
"offset": 20
#### **示例**
在模板中实现分页示例：
{% assign page_size = 10 %}
{% assign current_page = params.page | default: 1 | floor %}
{% assign offset = page_size | times: current_page | minus: page_size %}
{% query paginated_results from site.pages %}
{
"where": { "template_name_eq": "article" },
"limit": {{ page_size }},
"offset": {{ offset }},
"order_by": ["-created_at"]
}
{% endquery %}
## **4. where - 页面动态变量**
### **4.1 动态变量筛选逻辑**
1. **字段格式**：字段名由 `模板名:变量名_操作符` 构成（如：`description_start`, \'templates/index.list.liquid:description\_start\'）。
2. **数据类型限制操作符**：每个字段根据数据类型限制支持的操作符。
3. **支持 AND / OR 组合查询**：可组合多条件查询。
4. **模糊模版匹配**：若未指定模板路径，将查询所有模板下匹配变量并使用 `OR` 合并查询。
5. **可筛选字段**：必须在页面 schema 的 settings 中标注 `queryable: true` 才支持该字段筛选。
### **4.2 设置模板可用于筛选的动态变量**
在模板文件的 `settings_schema` 中添加 `queryable: true`：
{% schema %}
{
"name": "Help Center",
"settings": [
{
"id": "description",
"type": "textarea",
"label": "描述",
"queryable": true
}
]
}
{% endschema %}
### **4.3 动态变量数据类型**
| {{ page.link_text }}
{% endfor %}
{% endsearch %}
## **2. 参数说明**
|
---
URL: https://dev.baklib.cn/liquid/filters/concat
Updated: 2025-01-02
## 标题
concat
## 内容
Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays.
Input
{% assign fruits = "apples, oranges, peaches" | split: ", " %}
{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
{% assign everything = fruits | concat: vegetables %}
{% for item in everything %}
- {{ item }}
{% endfor %}
Output
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
You can string together `concat` filters to join more than two arrays:
Input
{% assign furniture = "chairs, tables, shelves" | split: ", " %}
{% assign everything = fruits | concat: vegetables | concat: furniture %}
{% for item in everything %}
- {{ item }}
{% endfor %}
Output
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
- chairs
- tables
- shelves
---
URL: https://dev.baklib.cn/api
Updated: 2026-02-03
---
URL: https://dev.baklib.cn/liquid/tags/270d6
Updated: 2025-08-29
## 标题
weixin_share_tag
## 内容
```
## 微信分享：`weixin_share_tag`
## 1. 概述
`weixin_share_tag` 是布局专用的 Liquid 标签，用于在站点页面中接入微信相关能力：
- **微信内置浏览器**：注入微信 JS-SDK 配置，并设置「发送给朋友」「分享到朋友圈」的标题、描述、链接与图片。
- **微信小程序 `web-view` 内嵌站点 H5**：自动通过 **postMessage** 向小程序推送当前页的分享元数据，便于小程序在「转发给好友」等场景下与站点内容保持一致。
分享文案与配图**不由标签手写**，而是由系统根据当前页面与站点的 SEO / Meta 信息自动汇总（见第 6 节）。
---
## 2. 模板中的用法
### 2.1 使用位置
- 仅在 **布局文件**（如 `layouts/theme.liquid`）中使用，一般放在 `` 中。
### 2.2 引入脚本
标签依赖主题共享脚本中的微信能力（含 `window.baklibWhenWxReady` 等）。在布局中引入其一即可：
```liquid
{{ 'baklib/shared/main.js' | asset_url | script_tag: data-turbo-track: 'reload' }}
```
或仅引入微信模块：
```liquid
{{ 'baklib/shared/weixin.js' | asset_url | script_tag: data-turbo-track: 'reload' }}
```
### 2.3 配置标签
- 标签配置（请直接复制进模板布局文件head标签中，一般无需修改调整）
```liquid
{% weixin_share_tag
app_id: site.settings.weixin_app_id,
app_secret: site.settings.weixin_app_secret,
access_token_url: site.settings.weixin_access_token_url,
debug: site.settings.weixin_debug,
enabled: site.settings.weixin_enabled
%}
```
- 参数说明：
| 属性 | 说明 |
|------|------|
| `app_id` | 微信公众平台 AppID；启用分享且需服务端签名时必填。 |
| `app_secret` | 微信公众平台 AppSecret；同上。 |
| `access_token_url` | 可选。自定义 access_token 获取地址；不填则使用默认逻辑。 |
| `debug` | 可选。为真时，签名失败或 JSSDK 错误等情况下可通过弹窗 / 控制台辅助排查（仅建议在配置阶段开启）。 |
| `enabled` | 可选。为假时标签不输出任何内容。 |
---
## 3. 主题后台配置（`settings_schema.json`）
建议在 `config/settings_schema.json` 中增加设置项，供站点在后台填写微信参数，模板通过 `site.settings.*` 引用。使用与配置（一般无需修改，直接写入config/settings_schema.json中）：
```json
{
"name": "t:schema.settings.weixin_share.title",
"settings": [
{
"id": "weixin_app_id",
"type": "text",
"label": "开发者ID(AppID)",
"info": "微信公众号/设置与开发/开发接口管理中获取"
},
{
"id": "weixin_app_secret",
"type": "text",
"label": "开发者密码(AppSecret)",
"info": ""
},
{
"id": "weixin_access_token_url",
"type": "text",
"label": "Access Token URL（可选）",
"info": "一般留空；仅在使用自定义 token 端点时填写"
},
{
"id": "weixin_enabled",
"type": "checkbox",
"label": "是否启用微信分享",
"default": false,
"info": "提供站点页面微信分享的能力1. 请在微信公众号中配置 IP 白名单（ip: ${service_ip}），配置后将有一段时间的生效延迟。2. 检查是否开启微信分享权限，微信公众号/设置与开发/开发接口管理: 网页服务/分享接口。3. 分享链接是否为卡片：从卡片形式进入分享卡片形式，链接形式进入分享链接形式；网页初始链接分享可由公司的服务号中或收藏后进行卡片分享（此规则为微信分享限制）。"
},
{
"id": "weixin_debug",
"type": "checkbox",
"label": "是否开启 debug 提示",
"default": false,
"info": "请仅在配置阶段开启此选项；开启后在访问前端站点时若未正确配置微信分享将自动提示错误信息"
}
]
}
```
---
## 4. 微信公众平台配置说明
### 4.1 AppID 与 AppSecret
登录 [微信公众平台](https://mp.weixin.qq.com/)，进入 **开发 > 基本配置**，可查看 AppID、AppSecret。
**说明：** 使用网页分享等相关接口通常需要 **已认证的服务号**（以微信官方文档为准）。
### 4.2 IP 白名单
- ip配置至 微信公众平台 → 开发 > 基本配置 ip白名单中
- 具体 IP地址可在站点配置中微信分享配置中获取
- 白名单配置保存后，通常需要等待 几小时左右 才会生效
### 4.3 分享接口权限
在 **设置与开发 > 接口权限** 中确认已开通 **网页服务 / 分享接口** 等所需能力。
---
## 5. 分享效果与展示形态
### 5.1 卡片与链接形态
- **卡片分享**：用户从公众号菜单、收藏等入口进入页面后再分享，通常展示带标题、描述、缩略图的卡片。
- **链接分享**：用户直接打开或复制链接进入时，分享形态可能仅为链接，属微信客户端规则，与标签配置无关。
---
## 6. 分享内容来源（Meta）
以下内容由系统自动从页面与站点 Meta 等信息推导，用于 H5 JSSDK 与小程序 postMessage **共用同一套数据**：
| 项目 | 说明 |
|------|------|
| 标题 | 页面 title 与站点名称等组合（与实现一致） |
| 描述 | 页面 description，可回退到站点首页等 |
| 链接 | 当前页面 URL |
| 图片 | 页面 icon / `image_src` 等，可回退站点 favicon 或系统默认 logo |
请通过页面 SEO、站点 favicon 等保证上述信息准确。
---
## 7. 小程序集成站点后的分享数据对接
当小程序通过 **`web-view` 加载站点 H5**，且站点布局中已启用 `weixin_share_tag`（`enabled` 为真、微信公众平台参数配置正确）时，页面脚本会在 **小程序环境** 下调用 `wx.miniProgram.postMessage`，把当前页的分享元数据发给小程序。若希望在「转发给好友」等场景下与 H5 当前页标题、封面、链接一致，小程序需要监听 `web-view` 消息、缓存最近一次有效数据，并在 `onShareAppMessage`（以及你方其它分享入口）里组装返回值。
### 7.1 `postMessage` 的数据结构
- data 数据
H5 侧调用形式为：`wx.miniProgram.postMessage({ data: <对象> })`。本标签传入的 **`data` 为单个对象**（不是数组），结构如下。
| 字段 | 类型 | 说明 |
|------|------|------|
| `__baklib_mp_bridge__` | 布尔 | 固定为 `true`，用于与其它 `postMessage` 区分。 |
| `event` | 字符串 | 固定为 `"weixin.share_meta"`，表示分享元数据。 |
| `timestamp` | 数字 | 发送时的毫秒时间戳。 |
| `payload` | 对象 | 分享业务字段。 |
- payload 数据
| 字段 | 含义 |
|------|------|
| `title` | 分享标题 |
| `desc` | 摘要描述 |
| `link` | 当前 H5 页完整 URL，用于回访站点对应页面 |
| `imgUrl` | 分享配图 URL |
- 示例：
```json
{
"__baklib_mp_bridge__": true,
"version": "1.0",
"event": "weixin.share_meta",
"timestamp": 1710000000000,
"payload": {
"title": "文章标题 - 站点名称",
"desc": "页面摘要",
"link": "https://example.com/path/to/page",
"imgUrl": "https://example.com/share.png"
}
}
```
微信文档中，`web-view` 的 **`message` 事件里 `detail.data` 为数组**：其中每个元素对应一次（或一批）`postMessage` 的 `data`。解析时需遍历 `data`，找到 `event === "weixin.share_meta"` 且 `payload` 为对象的项再使用。
### 7.2 小程序侧接入方式
1. 在承载站点的 **`web-view` 上绑定消息回调**（例如微信小程序的 `bindmessage`，或使用你所用框架提供的等价 API）。
2. 在回调中读取 **`detail.data`**（数组），遍历每一项；可优先判断 `__baklib_mp_bridge__ === true`、`version === "1.0"`、`event === "weixin.share_meta"`，再读取 `payload`。
3. 将 `payload` 中的 `title`、`desc`、`link`、`imgUrl` **写入本页或全局可访问的状态**（如页面 data、store 等），供分享时使用。若你方分享 API 使用 `url`、`imageUrl` 等字段名，可在这一步做字段映射。
4. 在 **`onShareAppMessage`** 中读取上述缓存，设置小程序分享的 `title`、`imageUrl`，并通过 **`path` / `query` 等把你方打开 `web-view` 所需的参数带上**（常见做法是把 `link` 编码进 query，打开 `web-view` 时再解码为站点 URL），保证好友点开分享卡片后仍能进入当前 H5 页面对应地址。
具体 API 名称以微信官方文档及你所用小程序框架为准；上述步骤描述的是通用接入顺序。
### 7.3 注意事项
- **送达时机**：`postMessage` 的数据往往在用户进行**分享、复制链接、返回**等操作时才会被送到小程序逻辑层，而不是页面每次渲染立即送达。不要假设首屏加载完成时一定已收到最新消息；分享时应尽量使用**最近一次成功解析**的 `payload`，并接受短窗口内信息与当前页不完全同步的可能。
- **多次发送**：用户在站点内跳转时，每一页若都带有本标签，可能多次 `postMessage`。小程序侧宜**每次收到 `weixin.share_meta` 就更新缓存**，以当前页为准。
- **字段名**：业务层若只识别 `url`、`imageUrl`，须自行与 `link`、`imgUrl` 对齐，避免封面或回访链接为空。
- **站点与小程序配置**：`web-view` 加载的站点域名需在小程序后台配置为**业务域名**；站点本身须 **HTTPS**，且微信侧能力（如合法校验）需满足官方要求，否则 H5 无法正常执行到 `postMessage`。
---
## 8. 常见问题（FAQ）
**为什么看不到分享按钮？**
分享入口由微信客户端提供；标签只负责配置分享内容或向小程序上报元数据。
**分享信息不正确？**
检查页面 Meta（title、description、image 相关）及站点 favicon 等。
**报错「不在 IP 白名单内」？**
在公众平台核对服务器出口 IP 与白名单一致，并等待生效。
**为什么分享形态有时只有链接？**
见第 5.1 节，属微信展示规则。
**如何调试 H5 签名与 JSSDK？**
开启 `debug: true`，根据弹窗或控制台输出排查。
```
---
URL: https://dev.baklib.cn/faqs/9e19
Updated: 2024-12-09
## 标题
如何获得页面的Version 版本信息
## 内容
`page.versions `变量可获得当前页面的所有版本信息。
如：主页面地址为：` /get-start ` 则版本的路径格式为： `/get-start?version=v2.0.0`
{% assign version_count = page.versions | size %}
{% if version_count > 0 %}
```
**Turbo Stream 操作类型**：
- `append` - 在目标元素内部末尾追加内容
- `prepend` - 在目标元素内部开头插入内容
- `replace` - 替换目标元素的整个内容
- `update` - 更新目标元素的 innerHTML
- `remove` - 移除目标元素
- `before` - 在目标元素之前插入内容
- `after` - 在目标元素之后插入内容
**多操作示例**：
```liquid
{% response_type "turbo_stream" %}
{% layout none %}
{%# 移除旧元素 %}
{%# 追加新元素 %}
{% render 'list_item', item: new_item %}
```
### 2. 返回 JSON 格式
用于创建 API 接口端点，返回结构化数据。
```liquid
{% response_type "json" %}
{% layout none %}
{
"status": "success",
"message": "操作成功",
"data": {
"id": 123,
"name": "示例"
}
}
```
**动态 JSON 示例**：
```liquid
{% response_type "json" %}
{% layout none %}
{
"articles": [
{% for article in articles %}
{
"id": {{ article.id }},
"title": {{ article.title | json }},
"created_at": {{ article.created_at | date: "%Y-%m-%d" | json }}
}{% unless forloop.last %},{% endunless %}
{% endfor %}
]
}
```
### 3. 返回 XML 格式
用于返回 XML 格式的数据。
```liquid
{% response_type "xml" %}
{% layout none %}
success
数据已更新
- 内容1
- 内容2
```
### 4. 使用默认 HTML 格式
如果不设置 `response_type`，或者设置为 `html`，模板会以 HTML 格式返回。
```liquid
{% response_type "html" %}
{% render 'comment_form', comment: comment, errors: errors %}
{%# 如果成功，追加新评论 %}
{% if comment.persisted? %}
{% render 'comment', comment: comment %}
{% endif %}
```
### 场景 2：API JSON 响应
在静态模板中创建 API 接口端点。
```liquid
{% response_type "json" %}
{% layout none %}
{
"articles": [
{% for article in articles %}
{
"id": {{ article.id }},
"title": {{ article.title | json }},
"excerpt": {{ article.excerpt | json }},
"created_at": {{ article.created_at | date: "%Y-%m-%d" | json }}
}{% unless forloop.last %},{% endunless %}
{% endfor %}
],
"total": {{ articles.size }}
}
```
### 场景 3：错误响应
结合 `response_status` 返回错误信息。
```liquid
{% response_status 422 %}
{% response_type "json" %}
{% layout none %}
{
"status": "error",
"message": "验证失败",
"errors": {
"email": ["邮箱格式不正确"],
"password": ["密码长度至少8位"]
}
}
```
## 注意事项
1. **类型验证**：只接受 `html`、`turbo_stream`、`json`、`xml` 四个值，其他值会被忽略，使用默认的 HTML 格式
2. **必须配合 layout none**：当使用非 HTML 格式时，通常需要配合 `{% layout none %}` 禁用布局，避免布局的 HTML 结构（如 ``、``、`` 等标签）污染响应内容
3. **优先级**：布局（layout）中设置的 `response_type` 会覆盖模板中的设置，因此建议在模板中设置响应类型，而不是在布局中
4. **标签顺序**：将 `response_type` 标签放在模板的最前面，确保在渲染过程中正确设置响应类型
5. **内容格式**：确保响应内容符合指定的格式要求（如有效的 JSON、XML 或 Turbo Stream），否则可能导致解析错误
## 常见错误
### 错误 1：忘记禁用布局
```liquid
{%# ❌ 错误示例 %}
{% response_type "json" %}
{
"status": "success"
}
```
**问题**：响应会被布局的 HTML 结构包装，导致 JSON 解析失败。
**解决**：
```liquid
{%# ✅ 正确示例 %}
{% response_type "json" %}
{% layout none %}
{
"status": "success"
}
```
### 错误 2：响应类型拼写错误
```liquid
{%# ❌ 错误示例 %}
{% response_type "turbo-stream" %}
```
**问题**：类型值不匹配，会被忽略，使用默认的 HTML 格式。
**解决**：
```liquid
{%# ✅ 正确示例 %}
{% response_type "turbo_stream" %}
```
### 错误 3：在布局中设置响应类型
```liquid
{%# ❌ 不推荐的做法 %}
{%# 在模板中 %}
{% response_type "json" %}
{% layout "custom" %}
{% response_type "html" %}
```
**问题**：布局中的设置会覆盖模板中的设置，可能导致意外的响应格式。
**建议**：响应类型应该在模板中设置，而不是在布局中。
## 最佳实践
1. **始终配合 layout none**：当使用非 HTML 响应类型时，始终配合 `{% layout none %}` 禁用布局
2. **标签顺序**：将 `response_type` 和 `layout` 标签放在模板的最前面
3. **类型验证**：确保响应类型值拼写正确，使用下划线而不是连字符（`turbo_stream` 而不是 `turbo-stream`）
4. **内容格式**：确保响应内容符合指定的格式要求（如有效的 JSON、XML 或 Turbo Stream）
5. **测试验证**：在浏览器开发者工具中检查响应的 Content-Type 和内容格式，确保符合预期
6. **错误处理**：对于 API 响应，结合 `response_status` 返回适当的状态码
## 总结
`response_type` 标签是控制模板响应格式的关键标签，支持 HTML、Turbo Stream、JSON、XML 四种格式。当使用非 HTML 格式时，必须配合 `{% layout none %}` 禁用布局，以确保响应内容的格式正确。正确使用此标签可以实现丰富的交互效果，如无刷新页面更新、API 接口、流式响应等。
```
---
URL: https://dev.baklib.cn/faqs/b682
Updated: 2024-12-27
## 标题
如何更新模板代码 git 仓库？
## 内容
### 步骤：
在站点的“应用设置”--“界面展示”中，组织模板。点击“进入模板开发”。
在模板开发界面，点击导航中的“组织模板”，找到对应的模板，点“拉取”。
* 如果远程git 仓库代码更新了，需要同步至组织模版中，则点“拉取”。
* 如果当前组织模板由在线修改了后，希望同步到远程git 仓库， 则点“推送”，将当前的修改推送到远端 git 仓库。
---
URL: https://dev.baklib.cn/liquid/filters/default
Updated: 2025-01-02
## 标题
default
## 内容
指定一个默认值，以防预期的值不存在。如果左侧的值为 `nil`、`false` 或空，`default` 将输出此默认值。
如下实例中，`product_price` 并未被定义，因此将输出默认值。
输入
{{ product_price | default: 2.99 }}
输出
2.99
如下实例中，`product_price` 已被定义，不再输出默认值。
输入
{% assign product_price = 4.99 %}
{{ product_price | default: 2.99 }}
输出
4.99
如下实例中，`product_price` 的值为空，因此将输出默认值。
输入
{% assign product_price = "" %}
{{ product_price | default: 2.99 }}
输出
2.99
---
URL: https://dev.baklib.cn/theme/99342
Updated: 2025-09-22
## 标题
seeds/
## 内容
`seeds/` 机制可以帮助你在创建站点时，自动生成默认的配置和页面内容。通过定义 `yml` / `json` 等格式文件，在通过模板创建站点时可以快速为用户提供一个带有基础结构和示例数据的站点。
## 1. 基本目录结构
位于主题的 seeds 目录中：
```
```
templates/
├── assets/ # 模板内置静态资源
├── seeds/ # 初始化数据定义（核心）
│ ├── 001_site.yml # 站点配置
│ ├── 002_pages.yml # 页面结构
│ └── xxx.yml # 其他初始化文件
└── presets/ # 可选，用于存放大段 HTML/Markdown
├── hero_content.html
└── faq.md
```
```
## 2. 文件命名规则
* **允许**：任意 `*.json` 、`*.yml` 或 `*.yaml` 文件，执行时会按文件名排序。
* **注意**：文件名只是顺序标记，真正的解析逻辑取决于文件内容的 **顶级 key**。
## 3. 文件内容格式
### 3.1 `site` 配置
用于设置站点级别的属性、动态表单(config/settings\_schema.json:settings)配置
#### 示例（YAML）
site:
language: 'zh-TW'
settings:
logo_url: "images/hero.jpeg"
contact_info: "联系人信息xxxxx"
header_bg_color: "#000000"
header_text_color: "#cccccc"
footer_bg_color: "#cccccc"
footer_description: "footer 描述信息"
copyright: "© xxx公司"
footer_nav_links: "preset:footer_nav_links2.html"
#### 可配置属性
|
{{ "search.result.t1" | t }} {% if search.tag %} {{ search.tag.name }} {% endif %} {% if search.keywords %} {{ search.keywords }} {% endif %} {{ "search.result.t2" | t }}
{% endif %} #### **Breadcrumb** 用户可以通过 `page.breadcrumb` 输出的 JSON 数组，自己循环生成，如： `themes/cms/test/snippets/_breadcrumb.liquid` {% comment %} @params breadcrumb array of objects with keys: link_text: string path: string {% endcomment %}#引用: page.liquid {% render 'breadcrumb', breadcrumb: page.breadcrumb %}#实现： snippets/_breadcrumb.liquid # 前端最佳实践一个优秀的面包屑导航需要满足：1）移动端不会因为面包屑太长而被挤压；超出的部分可自动水平滚动；2）文本不会因为被挤压而截断。前端生成的代码：1. 首先，当我们新安装一个应用站点的时候，会进入【工作台】--【市场】中查看模板列表。 2. 其次，在应用站点创建成功后，可进入【后台管理】--【模板开发】到模板开发界面。 ### --- URL: https://dev.baklib.cn/overview/themes/support-portal Updated: 2024-11-17 ## 标题 CMS: Support Portal ## 内容  **模板类型：**CMS 模板名称： Support Portal **模板介绍：**Support Portal 是一个功能强大、操作简单的在线支持平台，包含知识库、发布日志、FAQ、视频、博客等。 ## 首页主题 该模板预设了三个首页主题风格：List书目风格、Help Center风格、Docs文档风格。 **List书目风格：**首页直接呈现了整个站点的页面层级导航，类似图书目录，简单直接。  **Help Center主题风格：**首页横幅图片背景+大搜索框。  help center主题风格  **Docs风格：** 首页Card版块栏目布局，适合做企业帮助中心、技术文档、客户支持文档。   ## 其他页面预览 内部页面、搜索页、标签页预览效果。      --- URL: https://dev.baklib.cn/overview/themes/guide/fe25 Updated: 2024-11-17 ## 标题 主题安装 ## 内容 ## Guide模板介绍 名称： Guide 概述：小型文档内容管理，可用于构建产品手册、指南、FAQ、Release、Blog等 模板特点： 1. 首页简洁明了，一排到底，没有复杂的层级结构。 2. 提供了卡片列表和文本列表两种页面排版。 3. 搭配Tag标签分类更显得内容丰满。 适合场景： 1. 小规模文档内容管理，注重用户体验。 2. 作为无头CMS内嵌到其他软件内，用于移动端访问效果更优。 不适合场景： 1. 不适用于复杂层级（三级及以上）结构的文档排版 ^ 效果预览： 首页Card主题效果  标签页：  首页List主题效果 搜索页： 详情页效果 ## 视频教程 如何十分钟创建一个Guide模板内容站点 * Guide 模板视频教程制作 ^ ## 创建Guide模板站点 在模板市场中找到“Guide产品指南”的模板，进行应用创建，需要3步完成： 第1步：选择模板  第2步：设置站点 第3步：初始化页面 创建成功后，进入站点管理界面~  前端预览效果如下：  可以说一个基本的Guide CMS网站就创建好了。接下来需要做的事情，就是不定期的在后台新增页面即可。 ## 进阶设置 ### 站点设置 关于如何完善一个CMS网站的设置，包括基本信息设置、域名管理、访问控制、多应用关联、反馈设置以及回收站等功能，这里不再一一讲解，大家可以去参考CMS站点的教程。 接下来重点是要讲解基于本模板的一些特别的设置。 导航到工作台“应用设置--> 界面设置”： 站点基本信息：  品牌相关信息设置：  站点设置主要包括： 1. 站点基本信息 2. 品牌相关信息 3. 页头页脚导航信息 4. 站点主题颜色 当设置好站点信息以后，一个网站的基本骨架就构建完成了。在接下来的事就是讨论如何添加网站的页面。 ### 页面设置 页面设置  预览 页面的设置也相对比较简单。主要是提供标题、摘要、标签、封面图、和内容。 我们可以看到页面设置的前端效果，同时在移动端也会有很好的适配。 ### 子页面 本模板的页面是支持添加子页面的。且子页面的添加可以无限级，但是在前台只显示本页面的子页面一级，一次类推。 后台  前台 ### 标签设置 本模板还支持标签设置管理，站点设置的标签，在添加页面的时候可以为每个页面打标签，前台实现标签分类：  ### 用户反馈管理 在每个页面内容下方放置了页面反馈表单，可以通过后台设置是否启用反馈，是否启用反馈留言：  ### 首页主题更换 本模板预设了两个首页主题。一个是card模式，基于图片封面展示页面列表，这种风格主要突出图文的表达。 另外一种是list模式，直接展示页面的标题摘要列表。 这两种风格各有特点。  ### 其他特殊技巧 该主题可以设置用户反馈、页头、页脚部分是否显示的状态。同时，本模板创建的应用在移动端的展示效果会非常的简洁流畅，也适合于内嵌在应用当中做帮助中心指引。  ## 低代码开发 通过以上的配置和说明，已经满足大部分用户的需求了。 但是如果还需要更进一步的魔改网站界面怎么办呢？ Baklib低代码平台就该出场了。这一部分将直接进入低代码模板开发环节。 模板layout: {% meta_tags %} {{ 'editor.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }} {{ 'css/main.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }} {{ 'javascripts/main.js' | asset_url | script_tag: defer: true, data-turbo-track: 'reload' }} {%# TIPS：在低代码平台开发时，请打开下一行代码注释 %} {% if true %} {{ 'javascripts/cdn.tailwindcss.js' | asset_url | script_tag: data-turbo-track: 'reload' }} {% endif %} {% if site.settings.is_allow_header %} {% render 'header' %} {% endif %}
{% render 'header', settings: site.settings %}
{{ content_for_layout }}
页面模板和片段：
themes/cms/docs/snippets
_breadcrumb.liquid
_collapse_pages.liquid
_empty.liquid
_feedback_form.liquid
_footer.liquid
_header.liquid
_sidebar.liquid
_tree.liquid
themes/cms/docs/templates
index.docs.liquid
index.help_center.liquid
index.liquid
nav_tree.liquid
page.liquid
search.liquid
详情页面的布局解析如下图所示：
暂时无法在飞书文档外展示此内容
[1]: http://index.help
[2]: http://index.docs
---
URL: https://dev.baklib.cn/install
Updated: 2024-11-28
## 标题
启动指南
## 内容
了解 Baklib 模板介绍，需要准备的软件和技能，以及随时跟踪了解模板引擎更新日志。
---
URL: https://dev.baklib.cn/theme/config/settings-schema
Updated: 2024-07-19
## 标题
settings_schema.json
## 内容
## 文件内容
[
{
"name": "theme_info",
"theme_name": "daisy_wiki",
"theme_label": "t:theme_label",
"theme_version": "1.0.0",
"theme_scope": "wiki",
"theme_author": "Baklib",
"theme_description": "t:theme_description",
"theme_documentation_url": "https://help.baklib.cn/themes/daisy-wiki",
"theme_support_url": "https://help.baklib.cn/themes/daisy-wiki/settings",
"theme_thumb_url": "images/theme/thumb.png",
"theme_preview_images": [
"images/theme/index.png",
"images/theme/index-documentation.png",
"images/theme/index-portal.png",
"images/theme/page-channel.png",
"images/theme/page.png"
],
"theme_languages": [
{
"name": "中文简体",
"value": "zh-CN"
},
{
"name": "English",
"value": "en-US"
},
{
"name": "Germany",
"value": "de"
},
{
"name": "France",
"value": "fr"
}
],
"recommendations": {
"color_schemas": {
"fashion": {
"name": "时尚",
"colors": {
"--theme-color-primary": "#0d9488",
"--theme-color-secondary": "#ea580c",
"--theme-color-accent": "#AAAAAA",
"--theme-color-info": "#2196F3",
"--theme-color-success": "#4CAF50",
"--theme-color-warning": "#FFC107"
}
},
"old_school": {
"name": "复古",
"colors": {
"--theme-color-primary": "#9C27B0",
"--theme-color-secondary": "#673AB7",
"--theme-color-accent": "#AAAAAA",
"--theme-color-info": "#418CC8",
"--theme-color-success": "#29B52F",
"--theme-color-warning": "#FFC107"
}
}
}
}
},
{
"name": "t:settings_schema.generic.name",
"settings": [
{
"id": "is_allow_published_at",
"type": "checkbox",
"label": "文章内是否展示发布日期",
"default": true
},
{
"id": "is_allow_author",
"type": "checkbox",
"label": "文章内是否展示作者",
"default": true
}
]
},
{
"name": "t:settings_schema.generic.head_title",
"settings": [
{
"id": "head_html",
"type": "html",
"label": "t:settings_schema.generic.settings.head_html.label",
"info": "t:settings_schema.generic.settings.head_html.info",
"rows": 10,
"placeholder": "t:settings_schema.generic.settings.head_html.placeholder"
}
]
}
]
## 文件说明
文件内容为 JSON 格式，存储多个配置数组，每个配置必须包含 `name` 属性，表示配置的类型。
## 配置 name 为 \"theme\_info\" 表示主题模版信息
theme\_info 为特殊配置，每个 settings\_schema.json 必须有且唯一存在。支持的属性如下：
| 属性名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| name | 是 | 字符串 | 此属性的值必须是theme_info，不能为其他值，表示此配置段为主题模版信息。 |
| theme_name | 是 | 字符串 | 主题模版的名称标识。只允许字母、数字、下划线的组合，如： help_center |
| theme_label | 否 | 字符串 | 主题模版的显示名称，如：帮助中心。 |
| theme_version | 是 | 字符串 | 主题模版的版本号，格式遵循 1.0.0 标准，用户使用模版时，可选择指定版本的模版。 |
| theme_scope | 是 | 字符串 | 主题模板的类型。只允许填写：community、cms、wiki |
| theme_author | 是 | 字符串 | 模版开发者 |
| theme_description | 是 | 字符串 | 描述 |
| theme_documentation_url | 否 | 字符串 | 文档地址 |
| theme_support_url | 否 | 字符串 | 技术支持地址 |
| theme_thumb_url | 是 | 字符串 | 缩略图地址 |
| theme_preview_images | 是 | 字符串数组 | 预览图，数组 |
| theme_languages | 否 | 字符串数组 | 多语言支持，填写数组，如['en', 'zh-CN', 'ja']表示支持英语、简体中文、日语。允许填写的值参考下表“多语言支持名单” |
| color_schemas | 否 | 哈希值 | 默认主题颜色配置 |
| theme_syntax_version | 是 | 字符串 | v2。不建议添加v1或不添加此值。 |
| miniprogram | 否 | 布尔 | true: 在使用此模板的站点后台中开启小程序下载、配置功能；请在模板适配小程序展示与功能后开启此选项 |
## 配置 name 为其它值表示站点配置项
| 属性名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| name | 是 | 字符串 | 此属性的值必填，不能是theme_info，此名称会展示在站点管理后台 |
| settings | 是 | 哈希数组 | 在此定义站点的动态配置项，会展示在站点管理后台。模板代码中可通过 site.settings 获取站点配置的值 |
| settings[x].id | 是 | 字符串 | 配置项的标识，如logo_url，模版代码中可通过 site.settings.logo_url 获取值 |
| settings[x].type | 是 | 字符串 | 配置项的类型，支持的配置类型参考下表“Setting支持的类型” |
| settings[x].label | 是 | 字符串 | 配置项的显示名称 |
| settings[x].info | 否 | 字符串 | 配置项的描述信息 |
| settings[x].default | 否 | | |
| settings[x].placeholder | 否 | | 输入框的提示文字 |
## 附录
### 多语言支持名单
# 中文
'zh-CN' => '中国大陆简体'
'zh-TW' => '台湾繁体'
'zh-HK' => '香港繁体'
'zh-MO' => '澳门繁体'
'zh-SG' => '新加坡简体'
# 英语
'en' => '通用英语'
'en-US' => '英语 (美国)'
'en-GB' => '英语 (英国)'
'en-AU' => '英语 (澳大利亚)'
'en-CA' => '英语 (加拿大)'
'en-NZ' => '英语 (新西兰)'
'en-IE' => '英语 (爱尔兰)'
# 葡萄牙语
'pt' => '通用葡萄牙语'
'pt-BR' => '葡萄牙语 (巴西)'
'pt-PT' => '葡萄牙语 (葡萄牙)'
# 西班牙语
'es' => '通用西班牙语'
'es-ES' => '西班牙语 (西班牙)'
'es-MX' => '西班牙语 (墨西哥)'
'es-AR' => '西班牙语 (阿根廷)'
# 法语
'fr' => '通用法语'
'fr-FR' => '法语 (法国)'
'fr-CA' => '法语 (加拿大)'
'fr-BE' => '法语 (比利时)'
'fr-CH' => '法语 (瑞士)'
# 德语
'de' => '通用德语'
'de-DE' => '德语 (德国)'
'de-AT' => '德语 (奥地利)'
'de-CH' => '德语 (瑞士)'
# 其他主要语言
'ja' => '日语'
'ko' => '韩语'
'vi' => '越南语'
'th' => '泰语'
'id' => '印尼语'
'ms' => '马来语'
'ar' => '阿拉伯语'
'hi' => '印地语'
'bn' => '孟加拉语'
'ru' => '俄语'
'tr' => '土耳其语'
### Setting支持的类型
| 类型 | 名称 |
| --- | --- |
| header | 段落标题 |
| paragraph | 段落描述 |
| text | 单行文字输入框 |
| number | 数字输入框 |
| range | 数字范围 |
| textarea | 多行文字输入框 |
| richtext | 富文本输入框 |
| html | HTML 源代码输入框 |
| liquid | Liquid 源代码输入框 |
| link | 链接输入框 |
| checkbox | 复选框 |
| radio | 单选项 |
| select | 下拉选择框 |
| color | 颜色选择器 |
| color_background | 背景颜色选择器 |
| date | 日期选择器 |
| font_picker | 字体选择器 |
| image_picker | 图片选择器 |
| video_picker | 视频选择器 |
| type 值 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| checkbox | True/False | false | |
| color_background | 颜色值 | | 背景颜色选择器，可以生成渐变色。颜色值在模板中的使用方法： <!-- 方法 1 --> <div style="height: 32px; background-image: {{ site.settings.banner_bg_color }}"></div> <!-- 方法 2 --> <div style="height: 32px; background-image: linear-gradient({{ site.settings.banner_bg_color.degree }}deg, {{ site.settings.banner_bg_color.from }}, {{ site.settings.banner_bg_color.to }}"></div>
{% render 'header', settings: site.settings, page: page %}
{% render 'sidebar', settings: site.settings, page: page %}
{{ content_for_layout }}
文件路径
|是否必须
|类型
|说明
|使用方式
| | --- | --- | --- | --- | --- | |baklib/shared/editor.css
|⚙️ 可选（如模版中需要使用富文本编辑器）
|样式 (CSS)
|富文本编辑器输出样式文件，使用 TailwindCSS 构建，控制编辑器基础样式（如段落、标题、列表、代码块等）。
baklib/shared/main.css
|✅ 必须
|样式 (CSS)
|全局共享样式文件，提供 bkt- 前缀的 TailwindCSS 公共组件与颜色系统，避免污染外部 CSS 命名空间。
在模板主布局中加载：{{ 'baklib/shared/main.css' \| asset_url \| stylesheet_tag: data-turbo-track: 'reload' }}
baklib/shared/editor.js
|⚙️ 可选（如模版中需要使用富文本编辑器）
|脚本 (JS)
|编辑器核心逻辑脚本，包含富文本编辑、组件注册、事件绑定等。
| | |baklib/shared/main.js
|✅ 必须
|脚本 (JS)
|全局前端逻辑js入口文件，自动导入全站通用模块：
• turbo — 启用 Turbo Drive/Frame 支持
• stimulus — 初始化 Stimulus 控制器
• ai_search_completion — 启用 AI 搜索建议（stimulus controller）
• expandable_content — 处理可展开内容交互（stimulus controller）
• responsive_attr — 响应式属性调整逻辑（stimulus controller）
在模板主布局中加载：{{ 'baklib/shared/main.js' \| asset_url \| script_tag: data-turbo-track: 'reload' }}
baklib/shared/ai_search_completion.js
|⚙️ 可选（仅在开启 AI 搜索建议时需要）
|脚本 (JS)
|提供 AI 搜索功能，用于站内搜索输入框或 AI 助手模块。默认由baklib/shared/main.js导入
baklib/shared/stimulus.js
|⚙️ 可选（如页面需要使用 Stimulus js）
|脚本 (JS)
|启用 Stimulus 控制器的初始化入口，负责连接 data-controller 标记的组件。默认由baklib/shared/main.js导入
baklib/shared/turbo.js
|⚙️ 可选（如页面需要使用 Turbo Frames / Turbo Streams）
|脚本 (JS)
|用于支持 Turbo Drive、Turbo Frames 和 Streams 的前端导航与局部更新。默认由baklib/shared/main.js导入
模版中使用turbo时请勿多次导入子模块，统一使用同一个模块实例，否则可能导致未知冲突问题，可能造成页面turbo导航混乱等问题；baklib/shared/main.js 和 baklib/shared/turbo.js 勿同时使用，默认挂载至window.Turbo
| --- URL: https://dev.baklib.cn/theme/locales/en-json Updated: 2024-07-19 ## 标题 en.json ## 内容 { "theme_label": "Daisy Wiki", "theme_description": "The web framework for content-driven website based on DaisyUI.", "generic": { "menu": "Menu", "theme": "Theme", "close": "Close", "back": "Back", "search": "Search", "popular_search": "Popular Search", "search_result": "related searching result", "index": "Home", "articles": "articles", "read_more": "read more", "404": "404 not found", "403": "403 No access permission", "empty": "content is empty", "sub_page_list": "Sub Pages", "copyright": "All rights reserved", "published_at": "Published at", "prev_page": "previous page", "next_page": "next page", "hot_pages": "Hot visit articles", "recent_pages": "Recent articles", "tags": "Tags" }, "placeholders": { "search": "Searching..", "input_password": "Please input your password" }, "buttons": { "submit": "Submit", "login": "Login", "sso_login": "SSO Login", "baklib_login": "Baklib Account Login" }, "prompts": { "page_restricted": "This page can only be accessed with authentication" }, "feedback": { "title": "Submit Feedback", "input_placeholder": "Please input feedback" } } --- URL: https://dev.baklib.cn/theme/snippets/header Updated: 2024-07-19 ## 标题 _header.liquid ## 内容 {% assign screen_width = site.settings.screen_width.value | default: 'max-w-screen-xl' %}
{% # 搜索栏 %}
{% form_tag 'search', class: 'w-11/12 md:w-1/2 absolute top-5 z-20 left-1/2 -translate-x-1/2' %}
{% endform_tag %}
Deploy faster
Everything you need to deploy your app
Quis tellus eget adipiscing convallis sit sit eget aliquet quis. Suspendisse eget egestas a elementum pulvinar et feugiat blandit at. In mi viverra elit nunc.
-
Push to deploy
- Morbi viverra dui mi arcu sed. Tellus semper adipiscing suspendisse semper morbi. Odio urna massa nunc massa.
-
SSL certificates
- Sit quis amet rutrum tellus ullamcorper ultricies libero dolor eget. Sem sodales gravida quam turpis enim lacus amet.
-
Simple queues
- Quisque est vel vulputate cursus. Risus proin diam nunc commodo. Lobortis auctor congue commodo diam neque.
-
Advanced security
- Arcu egestas dolor vel iaculis in ipsum mauris. Tincidunt mattis aliquet hac quis. Id hac maecenas ac donec pharetra eget.
Boost your productivity.
Start using our app today.
Incididunt sint fugiat pariatur cupidatat consectetur sit cillum anim id veniam aliqua proident excepteur commodo do ea.
模板页面 HTML
类型名称
|解释
| | --- | --- | |site
|当前cms站点信息
| |page
|页面的详细信息
| |tag
|标签
| |author
|作者
| |comment
|评论
| |current_user
|当前登录用户
| |plugins.feedback
|用户反馈插件
| ### **site（当前站点）（同cms站点）** |属性/方法
|类型
|解释
|示例
| | --- | --- | --- | --- | |name
|string
|站点名称
|开心农场
| |favicon_url
|string
|站点图标
|<url>
| |time_zone
|string
|站点时区
|Beijiang
| ### **page（页面）（同cms站点）** |属性/方法
|类型
|使用方法
|返回值
|说明
| | --- | --- | --- | --- | --- | |id
|string
| |9g5hkd
|页面的ID唯一标识
| |slug
|string
|page.slug
|guide
|页面path/url的唯一标识
| |link_text
|string
|page.link_text
|操作教程
|页面标题
|属性/方法
|类型
|使用方法
|返回值
|说明
| | --- | --- | --- | --- | --- | |id
|string
|comment.id
|9g5hkd
|评论的ID唯一标识
| |body
|string
|comment.body
|guide
|评论的内容
| |created_at
|datetime
|comment.created_at
| |评论创建时间
{ page.created_at \| time_ago }} {{ page.created_at \| date: "%Y-%m-%d" }}
| |author
|author
|comment.author
| |评论作者
| |reply_to_user
|author
|comment.reply_to_user
| |回复内容作者
| |target
|page
|comment.target
| |评论主题
| |parent
|comment
|comment.parent
| |回复的评论
| |root
|comment
|comment.root
| |评论所属一级评论
| |replies
|comment[]
|comment.replies
| |评论回复集合
| ### **current\_user（当前登录用户）同cms站点）** |uid
|string
|current_user.uid
|10001
|用户的ID唯一标识
| | --- | --- | --- | --- | --- | |name
|string
|current_user.name
|张三
|用户名称
| |image
|string
|current_user.image
|http://site-5zw8rxj1.free.lvh.me:3000/-/avatars/ey…CJ9fQ==--f3bb19439273b4e1f05ffbdbd9ce7108485c7f75
|用户头像地址
| |member_id
|integer
|current_user.member_id
| |用户成员的ID唯一标识
| |profile_url
|string
|current_user.profile_url
|http://tanmer.lvh.me:3000/my/profile
|个人中心链接
| |pages
|page[]
|current_user.pages
| |当前用户创建的页面集合
| ### **tag（标签）同cms站点）** |属性/方法
|类型
|解释
|示例
| | --- | --- | --- | --- | |path
|string
|标签页面的路径
|/-/tags/AxdEf
| |name
|string
|名称
|测试标签
| |color
|string
|字体颜色
|#42445A
| |bg_color
|string
|背景颜色
|#42445A
| |color_hls
|string
|颜色计算
|background-color: hsl({{ tag.color_hls[0] }}, {{ tag.color_hls[1] }}%, 90%);
| |pages_count
|integer
|含有该标签的页面数量
|<待开放>
| |pages
|page[]
|含有该标签的页面列表
| | 页面的标签通过在 `settings` 中动态定义，通过 `page.settings.tags` 方法调用。 {% schema %} { "settings": [ { "id": "tags", "type": "tag_picker", "multiple": true, "label": "标签" } ] } {% schemaend %} * 页面中的调用示例： ^ {% for tag in page.settings.tags %} {{ tag.name }} {% endfor %} site.tags 则返回当前站点的 Tag 标签集合-
{% for tag in site.tags %}
- {{ tag.name }} {% endfor %}
属性/方法
|类型
|解释
|示例
| | --- | --- | --- | --- | |name
|string
|作者名称
|张三
| |avatar_url
|string
|作者头像
| | 操作示例： {% assign avatar_url = 'images/icons/icon.svg' | asset_url %}属性/方法
|类型
|解释
|示例
| | --- | --- | --- | --- | |helpful_types
|Array(JSON)
|用户可选择的表情列表
|plugins.feedback.helpful_types
| |helpful_types[0].emoji
|string
|表情符
|😊
| |helpful_types[0].label
|string
|表情符对应的意思
|有用
| |helpful_label
|string
|提示用户选择表情
|您的反馈是对我们的产品极其重要
| |message_enabled
|boolean
|是否启用反馈留言
| | |message_required
|boolean
|当开启反馈留言，反馈留言是否必填
| | |login_required
|boolean
|反馈是否必须登录
| | ## **Filter（函数）** |名称
|解释
| | --- | --- | |order_by
|排序
| #### **order\_by** 对`page`列表进行排序，排序规则： |参数
|解释
| | --- | --- | |created_at
|按照创建时间排列
| |edited_at
|按照修改时间排列
| |visits_count
|按照访问量排列
| > ***在参数前添加***`-`，代表倒序排列 示例： {% assign tag_pages = tag.pages | order_by: '-created_at' %} |名称
|解释
| | --- | --- | |where
|筛选
| #### **where** 对`page`列表进行筛选，筛选参数 |参数
|解释
| | --- | --- | |template_name
|模板名称
| 示例： {% assign pages = search.pages | where: 'template_name', 'post' %} |名称
|解释
| | --- | --- | |feedback_count
|反馈数量
| |feedback_type_count(page, useful_type)
|某个反馈类型的反馈数量
| #### **feedback\_count、feedback\_type\_count** 获取`page`的反馈数量 示例： {{ page | feedback_type_count: '😊' }} //😊表情的反馈数量 {{ page | feedback_count }} //页面总反馈数 |roots
|一级评论
| #### **roots** `comment`列表一级评论 示例： {{ post.comments | roots | size }} --- URL: https://dev.baklib.cn/liquid/filters/abs Updated: 2025-01-02 ## 标题 abs ## 内容 返回一个数字的绝对值。 输入 {{ -17 | abs }} 输出 17 输入 {{ 4 | abs }} 输出 4 如果组成字符串的各个字符全是数字，`abs` 也能够对此字符串求绝对值。 输入 {{ "-19.86" | abs }} 输出 19.86 --- URL: https://dev.baklib.cn/api/55c38 Updated: 2025-08-05 ## 标题 📢 接口更新声明 · 2025 年 8 月 5日 ## 内容 ``` --- 为提升接口一致性与功能完备性，`Baklib` 已对页面内容相关接口做出以下更新： --- ### 🔁 1. 页面详情查询接口区分 `id` 与 `full_path` * **通过 ID 查询页面详情（保留原接口）** `GET /v1/sites/{site_id}/pages/{page_id}` * **通过 full\_path 查询页面详情（新接口，之前通过/v1/sites/{site_id}/pages/{page_id}传递full_path查询废弃）** `GET /v1/sites/{site_id}/pages/by_path/{full_path}` ⚠️ `full_path` 需进行 URL 编码（如 `encodeURIComponent`）以避免路由冲突。 --- ### ✏️ 2. 页面草稿查询接口新增 * **通过 ID 获取草稿内容：** `GET /v1/sites/{site_id}/pages/{page_id}/draft` * **通过 full\_path 获取草稿内容：** `GET /v1/sites/{site_id}/pages/by_path/{full_path}/draft` --- ### 🕓 3. 页面版本内容接口新增 #### ✅ 支持通过 ID 与 full\_path 两种路径访问页面版本信息： | 操作 | 通过 page\_id 路径 | 通过 full\_path 路径 | | ------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | 获取版本列表 | `GET /v1/sites/{site_id}/pages/{page_id}/versions` | `GET /v1/sites/{site_id}/pages/by_path/{full_path}/versions` | | 获取单个版本 | `GET /v1/sites/{site_id}/pages/{page_id}/versions/{version_id}` | `GET /v1/sites/{site_id}/pages/by_path/{full_path}/versions/{version_id}` | | 创建版本 | `POST /v1/sites/{site_id}/pages/{page_id}/versions` | `POST /v1/sites/{site_id}/pages/by_path/{full_path}/versions` | | 更新版本 | `PUT /v1/sites/{site_id}/pages/{page_id}/versions/{version_id}` | `PUT /v1/sites/{site_id}/pages/by_path/{full_path}/versions/{version_id}` | | 删除版本 | `DELETE /v1/sites/{site_id}/pages/{page_id}/versions/{version_id}` | `DELETE /v1/sites/{site_id}/pages/by_path/{full_path}/versions/{version_id}` | > ⚠️ 所有通过 full\_path 查询的接口都要求将full_path转义编码。 --- ### 🗑 4. 页面列表默认不返回已删除数据 * **获取页面列表（默认仅返回未删除页面）：** `GET /v1/sites/{site_id}/pages` * **如需获取回收站中的已删除页面，请传入参数：** `GET /v1/sites/{site_id}/pages?deleted=true` --- ### ✅ 总结更新内容一览 | 功能模块 | 说明/变更 | | -------- | ------------------------------------------------------------- | | 页面详情查询 | 区分 ID 与 full\_path 查询方式，full\_path 新增专用路径 | | 页面草稿接口 | 新增通过 ID 或 full\_path 获取草稿内容的接口 | | 页面版本接口 | **新增完整的版本内容 CRUD 接口**，支持通过 ID 与 full\_path 路径访问 | | 页面列表行为调整 | 默认不返回删除页面，如需获取回收站数据请添加 `deleted=true` 查询参数 | | URL 编码提醒 | 所有涉及 full\_path 的接口必须对路径进行 URL 编码（如使用 `encodeURIComponent()`） | --- 如对更新内容有任何疑问，请联系技术支持。建议所有接入方及时适配新的接口路径，并根据需要对 `full_path` 做 URL 编码处理，确保兼容性与稳定性。 --- ``` --- URL: https://dev.baklib.cn/liquid/e1712/8bb8d Updated: 2025-09-12 ## 标题 动态表单 - setting 默认值引用 ## 内容 当在settings配置中需要为默认值添加复杂的值时，可通过使用 `preset:`关键字引用 presets 目录下的文件 ##### **示例**： 模版根目录添加presets文件夹，并添加 footer_nav_links.html 文件 - snippets - footer_nav_links.html - styles - templates # setting 默认值引用 footer_nav_links.html 的内容作为默认值 { "id": "footer_nav_links", "type": "code", "language": "html", "label": "t:schema.settings.footer.nav_links.label", "info": "t:schema.settings.footer.nav_links.info", "default": "preset:footer_nav_links.html" } --- URL: https://dev.baklib.cn/theme Updated: 2024-11-28 ## 标题 目录结构 ## 内容 主题模板决定了用户站点的布局、功能和样式。模板主题是使用`Liquid`以及`HTML`，`CSS`，`JavaScript`和`JSON`构建的，使用这些语言，开发人员可以创建客户想要的任何外观。同时提供了多种工具和最佳实践来加速开发过程。 > ***作为开发人员，您可以为特定客户构建自定义主题模板以满足客户的需求，或构建要在模板商店中销售的模板。*** ## **概述** 主题模板决定了用户站点的布局、功能和样式。主题代码需要按照主题的标准目录结构组织，同时还包括配套资源，如`images`，`stylesheets`和`scripts`。 ## **文件资源** 主题文件分为以下一般类别： * 标记和功能 - 这些文件控制主题的布局和功能。他们使用Liquid生成站点页面的HTML标记。 * 配套资源 - 这些文件是主题中其他文件调用或使用的资产、脚本或本地化文件。 * 配置文件 - 这些文件使用JSON存储配置数据，用户可以通过主题编辑器进行自定义设置。 ## **目录结构** 模板固定的目录结构： . ├── assets └── images └── css └── javascripts └── ... ├── config └── settings_schema.json ├── layout └── theme.liquid ├── locales ├── src ├── snippets └── templates ## **目录介绍** 一个名为 `docs` 的模板的目录结构如下所示：`themes/cms/docs/` | |一级目录
|二级目录
|备注
| | --- | --- | --- | --- | | |assets/
| | | | | |css/
|存放从 src 中编译后的 css 文件
| | | |javascripts/
|存放从 src 中编译后的 js 文件
| | | |images/
|存放本地引用的资源
| | |config/
| | | | | |settings_schema.json
|存放模板的配置信息
| | |layout/
| | | | | |theme.liquid
|模板框架布局文件，其他模板文件都
| | |locales/
| |多语言版本翻译文件
| | |src/
| |原始 css/js 资源文件
| | |snippets/
| |存放模板页面片段
| | |statics/
| |存放静态模板文件
| | |templates/
| |存放模板文件，必须有一个 index.liquid
.gitignore
| |git 忽略文件
| | |package-lock.json
| |js 库打包文件
| | |package.json
| |js 库打包文件
| | |README.md
| |模板教程
| | |tailwind.config.js
| |TailwindCss 框架引用文件
| | |yarn.lock
| |yarn 打包文件
| --- URL: https://dev.baklib.cn/theme/assets Updated: 2024-07-19 ## 标题 assets/ ## 内容 资源文件目录，存放 css 、javascript、图片、字体等文件，通过 `asset_url` 方法生成可访问的 URL。 ## 示例 ### 插入 css 文件 把网站样式文件存放在 `assets/stylesheets/application.css` {{ 'stylesheets/application.css' | asset_url | stylesheet_tag: data-turbo-track: 'reload' }} 渲染输出 ### 插入 javascript 文件 把 javascript 文件存放在 `assets/javascripts/application.js` {{ 'javascripts/application.js' | asset_url | script_tag: defer: true, data-turbo-track: 'reload' }} 渲染输出 ### 显示图片 把图片存放`assets/images/welcome.png`
渲染输出
---
URL: https://dev.baklib.cn/liquid/tags
Updated: 2025-01-02
## 标题
标记(Tags)
## 内容
条件判断、循环、变量和注释。
---
URL: https://dev.baklib.cn/guide/forms
Updated: 2024-12-09
## 标题
动态表单
## 内容
用于模版定义动态字段，设计的表单类型，以达到自定义模版变量的目的：
# **表单 type: **`checkbox`
| Param
|Description
|Input
| | --- | --- | --- | |Type
|—
|checkbox
| |Label
|—
| | |Default
|—
|0 1 false true
| |Info
|—
| | **前端变量值** 类型：TrueClass true **前端变量显示** \{\{page.settings.foo}} `true` **示例：** 表单代码： { "id": "recommend_to_index", "type": "checkbox", "label": "推荐到首页展示", "default": true } --- 表单预览：  # **表单 type: **`color` |Param
|Description
|Input
| | --- | --- | --- | |Type
|—
|color
| |Label
|—
| | |Default
|—
|#00AA00
| |Colors
|—
|#FF0000\|#00FF00\|#0000FF
| |Info
|—
| | **前端变量值** 类型：String **前端变量显示** \{\{ page.settings.text\_color }} `#00AA00` **示例：** 代码： { "id": "text_color", "type": "color", "label": "Hero 文字颜色" } --- 预览：  # **表单 type: **`color_background` |Param
|Description
|Input
| | --- | --- | --- | |Id
|—
|bg_color
| |Label
|—
| | |Info
|—
| | |Default
|—
|{"from":"#0F69E8","to":"#1C0597"}
| |Colors
|—
|rgba(244, 67, 54, 1)\|rgba(233, 30, 99, 1)
| **前端变量值** 类型：DynamicForm::ColorBackgroundComponent::Value **前端变量显示** \{\{page.settings.bg\_color}} `linear-gradient(90deg, #0F69E8, #1C0597)` \{\{page.settings.bg\_color.to}} `#1C0597` \{\{page.settings.bg\_color.degree}} `90` \{\{page.settings.bg\_color.from}} `#0F69E8` **示例：** 代码： { "id": "banner_background", "label": "Hero 背景色", "type": "color_background" } --- 预览：  # **表单 type: **`date` |Param
|Description
|Input
| | --- | --- | --- | |Type
|—
|date
| |Label
|—
|foo
| |Default
|—
|2024-01-28
| |Info
|—
|这是一个日期选择器
| **前端变量值** 类型：Date "2024-01-28" **前端变量显示** \{\{page.settings.foo}} `2024-01-28` **示例：** 代码： { "id": "start_at", "type": "date", "label": "开始时间", "default": "2025-01-01" } --- 预览：  # **表单 type: **`font_picker` |Param
|Description
|Input
| | --- | --- | --- | |Type
|—
|font_picker
| |Label
|—
| | |Default
|—
|arial
| |Fonts
|—
|["system-ui", "arial"]
| |Info
|—
|选择一个字体
| **前端变量值** 类型：String "arial" **前端变量显示** \{\{page.settings.font\_name}} `arial` **示例：** 代码： { "id": "font", "type": "font_picker", "label": "字体", "default": "Arial" } --- 预览： # **表单 type: **`header` 动态表单分类标题，用于分组表单字段。 > \* 没有前端变量 |Param
|Description
|Input
| | --- | --- | --- | |Content
|—
| | **示例：** 代码： { "type": "header", "content": "分组 1" } --- 预览：  # **表单 type: **`paragraph` 这是一段文字介绍，用于动态表单的说明文字, 支持安全的 **HTML** 标签，自动过滤 script 标签。 > \* 没有前端变量 |Param
|Description
|Input
| | --- | --- | --- | |Content
|—
| | **示例：** 代码： { "type": "paragraph", "content": "paragraph" } --- 预览：  # **表单 type: **`html` |Param
|Description
|Input
| | --- | --- | --- | |Id
|—
|google_ads
| |Label
|—
|谷歌广告代码
| |Default
|—
| | |Info
|—
|粘贴谷歌广告 HTML 代码
| **前端变量值** 类型：ActiveSupport::SafeBuffer "这是蓝色粗体字" **前端变量显示** \{\{page.settings.google\_ads}} `这是蓝色粗体字` **示例：** 代码： { "id": "third_party_video_url", "type": "html", "label": "Youtube或其他视频地址", "info": "" } } }, "page": { "name": "Page", "description": "Document content page", "settings": { "description":{ "label": "Description" }, "content":{ "label": "Content", "info": "Synchronized from data source, cannot be edited" }, "icon": { "label": "ICON", "info": "1:1 ratio is recommended" }, "tags":{ "label": "Tags" } } } } } --- URL: https://dev.baklib.cn/theme/snippets/breadcrumb Updated: 2024-07-19 ## 标题 _breadcrumb.liquid ## 内容 {% comment %} @params breadcrumb array of objects with keys: link_text: string path: string {% endcomment %} --- URL: https://dev.baklib.cn/theme/templates/page Updated: 2024-07-19 ## 标题 page.liquid ## 内容 页面模板，位于 `templates/page.liquid`{{ page.settings.title }}
{{ page.settings.content }}
{{ "generic.tags" | t }}
{% for tag in page.settings.tags %} {{ tag.name }} {% endfor %}属性/方法 | 类型 | 解释 | |
|---|---|---|---|
page[parent_full_path] | string | 父页面full_path，可以指定创建页面的父级 | |
page[name] | string | 页面名称 | |
page[template_name] | string | 页面模板名称 | |
page[template_style] | string | 页面模板风格， 同一个模板页面可以有不同风格并切换，例如index.doc.liquid index.list.liquid, 页面使用模板template_name.template_style | |
page[published] | string | true false页面发布状态 | |
page[template_variables] | string | 模板变量 | |
page[template_variables][title] | string | { "id": "title", "type": "text", "placeholder": "", "label": "标题", "info": "显示在正文上方的文章标题" } ， 模板setting里可以设置的变量 | |
page[template_variables][content] | html | { "id": "content", "type": "richtext", "label": "问题内容" } | |
return_template_name | 修改成功返回页面，默认跳转详情页 | ||
属性/方法 | 类型 | 解释 | |
|---|---|---|---|
page[published] | string | true false页面发布状态 | |
page[template_variables] | string | 模板变量 | |
page[template_variables][title] | string | { "id": "title", "type": "text", "placeholder": "", "label": "标题", "info": "显示在正文上方的文章标题" } ， 模板setting里可以设置的变量 | |
page[template_variables][content] | richtext | { "id": "content", "type": "richtext", "label": "问题内容" } | |
return_template_name | 修改成功返回页面，默认跳转详情页 | ||
属性/方法 | 类型 | 解释 | |
|---|---|---|---|
feedback[useful_type] | string | 😊 😞， 反馈表情 | |
feedback[message] | string | 反馈具体信息 | |
属性/方法 | 类型 | 解释 | |
|---|---|---|---|
target_full_path | string | 评论页面full_path | |
reply[published] | string | true, false评论发布状态 | |
reply[root_id] | string | 一级评论id | |
reply[parent_id] | string | 回复评论id | |
reply[body] | richtext | 回复内容 | |
return_template_name | string | 修改成功返回处理页面 | |
属性/方法 | 类型 | 解释 | |
|---|---|---|---|
name | string | 输入框name，page[template_variables][content] | |
content | richtext | 编辑器内容，content | |
toolbar | string | 工具栏，例如toolbar、simple | |
==
相等
| | --- | --- | |!=
不相等
| |>
大于
| |<
小于
| |>=
大于或等于
| |<=
小于或等于
| |or
逻辑或
| |and
逻辑与
| 例如： {% if product.title == "Awesome Shoes" %} These shoes are awesome! {% endif %} 可以在一个标记（tag）中使用多个操作符： {% if product.type == "Shirt" or product.type == "Shoes" %} This is a shirt or a pair of shoes. {% endif %} ## contains（包含） `contains` 用于检查在一个字符串中是否存在某个子串。 {% if product.title contains 'Pack' %} This product's title contains the word Pack. {% endif %} `contains` 还可以用于检查一个字符串数组中是否存在某个字符串。 {% if product.tags contains 'Hello' %} This product has been tagged with 'Hello'. {% endif %} `contains` 只能用于搜索字符串。你不能将其用于从一个对象数组中检查是否存在某个对象。 --- URL: https://dev.baklib.cn/liquid/filters/append Updated: 2025-01-02 ## 标题 append ## 内容 将两个字符串拼接起来并返回拼接之后的值。 输入 {{ "/my/fancy/url" | append: ".html" }} 输出 /my/fancy/url.html `append` 同样能够作用于变量： 输入 {% assign filename = "/index.html" %} {{ "website.com" | append: filename }} 输出 website.com/index.html --- URL: https://dev.baklib.cn/api/b59c2 Updated: 2025-08-12 ## 标题 📢 接口更新声明 · 2025 年 8 月 12日 ## 内容 ``` --- ### API 更新文档 — `GET /api/v1/sites/:site_id/pages` #### 变更内容 ##### 1. 新增参数 `full_path_in` * **说明**：支持批量查询多个页面数据，不超过 50 个 `full_path`。 * **格式**：多个路径以逗号分隔，如 `/page1,/page1/page3,/page2` * **示例**： ``` GET /api/v1/sites/123/pages?full_path_in=/page1,/page1/page3,/page2 ``` ##### 2. 新增参数 `fields[pages]` * **说明**：指定返回的页面字段，支持多字段和嵌套字段。列表和详情可用 * **格式**：字段用逗号分隔，如 `full_path, slug ,settings.thumb_url,template_variables.title`。需要settings或者template_variables的字段需要同时传递include_details为true * **示例**： ``` GET /api/v1/sites/123/pages?fields[pages]=name,full_path,slug ``` --- ##### 3. 新增缓存支持 * **说明**： * 新增通过添加请求头 `FROM_CACHE: y` 使用缓存功能。 * 若请求携带此请求头且缓存存在，则直接返回缓存结果，无需重新计算。 * 缓存 key 由当前用户和请求参数组成，确保不同用户和请求参数独立缓存。 * **使用示例**： ```bash curl -H "FROM_CACHE: y" http://your.api/v1/sites/123/pages?full_path_in=/page1 ``` --- ##### 4. 新增 Webhook 支持 * **用途**：知识库设置，站点设置，文章内容变更时推送通知。 * **事件示例**： * `site_pages_events` * `site_settings_events` * **示例负载**： ```json { "site_id":462, "name":"【官网】探码科技", "hook_time":1754994215516, "event_name":"site_pages_events", "pages_updated_at":"2025-08-12T18:23:35.514+08:00" } { "site_id":462, "name":"【官网】探码科技", "hook_time":1754994929529, "event_name":"site_settings_events", "settings_updated_at":"2025-08-12T18:35:29.521+08:00" } ``` --- ##### 5. 修复 * **验证码自动失效**： * 验证码错误输入超过 5 次后，验证码自动失效，需重新获取。 * **翻页重复问题**： * 修复接口分页返回时，存在页面重复的 Bug，保证每页数据唯一且正确。 ``` --- URL: https://dev.baklib.cn/liquid/e1712/246f4 Updated: 2025-09-12 ## 标题 动态表单 - select、radio input 数据引用 ## 内容 当select表单需要使用其他页面的用户输入值作为当前 表达的候选值时，可以通过使用 `choices_from`key 引用其他数据源作为候选值。 使用时原 `choices` 参数改为 `choices_from`。以下为 choices\_from 可选值： 1. `$self.[setting_key]` 从当前页面获取动态表单的值，作为 choices 数据 2. `$index.[setting_key]` 从首页页面获取动态表单的值，作为 choices 数据 3. `$parent.[setting_key]` 从当前页面的上级获取动态表单的值，作为 choices 数据 4. `$site.[setting_key]` 从站点(settings\_schema.json)获取动态表单的值，作为 choices 数据 5. `$site_user_group` 从站点用户组获取数据 被引用的数据返回值必须为 数组 或 textarea input 的输出值 ##### **示例**： # $self.[setting_key] { "id": "keywords", "type": "radio", "choices_from": "$self.keywords_options" "label": "关键词", "info": "从当前页面指定的关键词中选择" } # $index.[setting_key] { "id": "keywords", "type": "radio", "choices_from": "$index.keywords_options" "label": "关键词", "info": "从首页页面指定的关键词中选择" } # $parent.[setting_key] { "id": "keywords", "type": "radio", "choices_from": "$parent.keywords_options" "label": "关键词", "info": "从当前页面的上级指定的关键词中选择" } # $site.[setting_key] { "id": "city", "type": "radio", "choices_from": "$site.cities", "label": "所在城市" "info": "从首页设置城市选择" } # $site_user_group { "id": "user_group_ids", "type": "select", "choices_from": "$site_user_group", "multiple": true, "label": "用户组" } # --- URL: https://dev.baklib.cn/liquid/filters Updated: 2025-01-02 ## 标题 函数(Filters) ## 内容 函数包含abs, append, at\_least, at\_most, capitalize, ceil, compact等一些具体的实用方法，具体教程见：
[https://liquid.bootcss.com/filters/abs/][1]
[1]: https://liquid.bootcss.com/filters/abs/
---
URL: https://dev.baklib.cn/overview/themes/site
Updated: 2024-11-28
## 标题
CMS: Portal 主题模板
## 内容
**模板类型：**CMS
**模板名称：** Portal
**应用场景：**CMS内容管理，可用于构建门户、官网，网站托管；内置首页、关于我们、博客资讯、产品及服务等模板。
👏
由于企业的官网门户没有标准设计，本主题模板只是一个样例展示，企业可以通过低代码完全按照自身的设计定制企业门户官网效果。
## 首页主题风格
首页主题风格有多种形式，可以支持轮播、大图展示、播放视频等。
移动端也做了很好的优化和自适应。
一个完整的首页截图预览：
## 其他页面预览
用于展示产品的产品列表页
用于撰写分栏内容的栏目页：
用于展示图文并茂的博客文章
另外风格的博客栏目效果预览
更多的模板风格，可直接参考我们推出的UI组件库： [https://www.uibak.com/][1]
[1]: https://www.uibak.com/
---
URL: https://dev.baklib.cn/overview/marketing
Updated: 2024-11-28
## 标题
模板市场
## 内容
> 进入【工作台】--【市场】。
模板市场是所有公开可见的模板展示平台，你可以在这里选择任意一个模板作为下一个项目的开始。
市场中的模板来源：公共模板和组织模板。
模板的分类：CMS 网站应用，Wiki知识库应用，Community社区应用，以及其他。下面做详细介绍。
模板市场
### CMS 模板
CMS （内容管理系统）站点，用于创建一站式的网站门户，基于模板添加各种类型的动态网页和静态网页。
适用场景：需要高度个性化定制展示界面的网站，比如企业官网、品牌门户。
参考：
* [CMS 系统介绍][1]。
* [5分钟创建一个CMS站点][2]。
* CMS 系统对比： [Baklib VS WordPress][3]。
### Wiki 模板
Wiki站点为内容和展示分离的新型 CMS 系统，内容存放在【知识库】中，站点负责模板界面的展示。所以要创建一个 Wiki站点的前提是需要在【知识库】中准备一个知识库用于提供数据源。
参考：
* [Wiki 系统介绍][4]
* [5 分钟创建一个 Wiki 知识库站点][5]
* Wiki 系统对比： [Baklib VS Docusaurus][6]
### Community 模板
Community 用于创建可与用户交互的社区论坛站点，支持前端用户认证（独立的注册登录界面），发布信息/评论等互动功能。
参考：
* [5 分钟创建一个 Community 社区站点][7]
* [Community 社区站点前端体验流程][8]
###
[1]: https://www.baklib.cn/s/cms/
[2]: https://help.baklib.cn/get-started/install-cms-site/
[3]: https://www.baklib.cn/vs/wordpress/
[4]: https://www.baklib.cn/s/kb/
[5]: https://help.baklib.cn/get-started/install-kb-site/
[6]: https://www.baklib.cn/vs/docusaurus/
[7]: https://help.baklib.cn/get-started/install-community/
[8]: https://help.baklib.cn/sites/community/
---
URL: https://dev.baklib.cn/theme/layout
Updated: 2024-07-19
## 标题
layout/
## 内容
布局是主题的基础，通过该主题渲染所有模板。
默认的布局名称为 `theme.liquid` 。templates 目录中的模板文件将默认引用该布局文件。
**特别说明**
在 templates/\*.liquid 模版中，如果期望使用其它特殊布局（非 theme.liquid），就可以用 `layout`申明，比如期望用 print 布局显示页面打印的样式
...
layout/print.liquid
templates/page-pdf.liquid
{% layout 'print' %}
在 templates/\*.liquid 模版中，如果不期望使用 layout 布局，就可以用 `none` 表示：
{% layout none %}
---
URL: https://dev.baklib.cn/theme/locales/zh-cn-json
Updated: 2024-07-19
## 标题
zh-CN.json
## 内容
{
"theme_label": "Daisy Wiki",
"theme_description": "基于DaisyUI构建的内容驱动型知识库门户。",
"generic": {
"menu": "菜单",
"theme": "主题",
"close": "关闭",
"back": "返回",
"search": "搜索",
"popular_search": "热门搜索",
"search_result": "搜索结果",
"index": "首页",
"articles": "篇文章",
"read_more": "阅读更多",
"404": "404 页面找不到",
"403": "403 无访问权限",
"empty": "内容为空",
"sub_page_list": "子页面列表",
"prev_page": "上一页",
"next_page": "下一页",
"copyright": "版权所有",
"published_at": "发布于",
"hot_pages": "热门话题",
"recent_pages": "最近文章",
"tags": "标签"
},
"placeholders": {
"search": "在站内搜索",
"input_password": "输入密码"
},
"buttons": {
"submit": "提交",
"login": "登录",
"sso_login": "SSO 登录",
"baklib_login": "Baklib 账号登录"
},
"prompts": {
"page_restricted": "本页面需要认证才可以被访问"
},
"feedback": {
"title": "提交反馈",
"input_placeholder": "请输入反馈内容"
}
}
---
URL: https://dev.baklib.cn/theme/snippets/feedback-form
Updated: 2024-07-19
## 标题
_feedback_form.liquid
## 内容
https://liquid.bootcss.com/filters/abs/
{% form_tag 'feedback', page: page %}
{% endform_tag %}
---
URL: https://dev.baklib.cn/theme/templates/search
Updated: 2024-07-19
## 标题
search.liquid
## 内容
搜索结果页模板，位于： templaes/search.liquid
主要是考虑在有搜索结果的情况下，如果遍历显示结果页面列表。通用的代码：
{{ site.plugins.feedback.useful_label }}
{% if site.plugins.feedback.message_enabled %}
{%# 反馈内容 %}
{% if site.plugins.feedback.message_enabled %}
{% if site.plugins.feedback.message_required %}
{% for useful_type in site.plugins.feedback.useful_types %}
{% endfor %}
{% else %}
{% for useful_type in site.plugins.feedback.useful_types %}
{% endfor %}
{% endif %}
* 反馈内容
{% endif %}
{%# 提交按钮 %}
{% endif %}
{% if search.tag or search.keywords %}
{{ 'generic.search' | t }} {% if search.tag %} {{ search.tag.name }} {% endif %} {% if search.keywords %} {{ search.keywords }} {% endif %}
{% endif %}
{% if search.keywords or search.tag %}
{% paginate_tag search.pages, as: 'items', per: 15 %}
{% for page in items %}
{% else %} {% assign message = "empty.name" | t %} {% render 'empty', message: message %} {% endfor %}
{{ page.highlighted_search_title }}
{# page.settings.content | strip_html | highlight: search.keywords } {{ page.highlighted_search_content }}
{% render 'breadcrumb', breadcrumb: page.breadcrumb %}
{% else %} {% assign message = "empty.name" | t %} {% render 'empty', message: message %} {% endfor %}
{% render 'paginate', paginate: paginate %}
{% endpaginate_tag %}
{% else %}
{{ "search.please_enter_keywords" | t }}
{% endif %}
{% if search.page_number == 1 %}
{% for link in search.extends %}
---
URL: https://dev.baklib.cn/guide
Updated: 2024-12-09
## 标题
开发指南
---
URL: https://dev.baklib.cn/faqs/11b1
Updated: 2024-10-16
## 标题
判断页面是否是首页或静态页
## 内容
首页的slug 为空
{% if page.slug == "" %}
这是首页
{% endif %}
`statics/ `下的静态页面 slug 为 nil
{% if page.slug == nil %}
这是statics下的静态页
{% endif %}
以下判断是否为 `templates `下的模板页
{% if page.slug == "" or page.slug == nil %}
是首页 和 statics/ 下面的静态页面
{% else %}
是模板页
{% endif }
---
URL: https://dev.baklib.cn/install/steps
Updated: 2025-01-13
## 标题
模板开发 Step by Step
## 内容
本指南提供了在特定平台内开发和实施自定义模板的分步指南。指南提供了有关如何浏览平台模板开发界面、复制模板、管理版本、修改静态和动态内容以及将自定义模板集成到平台前端的清晰说明。通过遵循本指南，用户可以有效地定制平台的外观和功能以满足他们的特定需求。
[模板开发教程指南][1]
## Intro 引导教程
[https://www.guidejar.com/embed/b3e9059c-d91c-41c1-956d-feb56d4720cb?type=1&controls=on](https://www.guidejar.com/embed/b3e9059c-d91c-41c1-956d-feb56d4720cb?type=1&controls=on)
## Step by Step 教程
**1.**进入的需要定制模板的站点管理界面
**2.**点击左侧边栏“模板开发”
**3.**Click on \"修改模板\"
**4.**首次登录模板开发界面，会看到 \"当前模板不可编辑，点击复制模板版本（main）至当前组织\"，直接点击复制。
**5.**复制模板到当前组织，并设置一个版本号：dev1.0
**6.**可以看到组织模板中，增加了一个\"dev1.0\"的版本
**7.**再次进入站点“应用设置”--“界面展示”设置中 选择使用组织模板
**8.**选择当前模板的版本号
**9.**版本号确定为刚才设置的“dev1.0”，点击“确定”
**10.**Click on \"进入模板开发\"
**11.**确定已经进入了当前模板的“dev1.0”版本界面
**12.**在 /statics 目录下添加静态页面
**13.**添加一个“hello.liquid”静态文件
**14.编辑文件内容**
在文件中输入“Hello World”，点击右上角的“保存”
**15.预览**
在网站前端输入地址“/s/hello”即可访问静态页面
**16.编辑动态模板页面**
在“/templates”目录下修改动态模板页面， 比如修改首页
**17.编辑器代码**
在这里可以任意添加和修改 index.liquid 的代码，这将影响到首页的展示效果。 例如这里将 Hero 行注释掉，点击“保存”
**18.前台预览修改**
前台查看效果，注释代码前预览：
**19.刷新界面**
刷新页面，发现 Hero 部分消失了（因为后台代码已注释），表面修改的模板中前端生效了。
## **FAQs**
#### 如果我在尝试编辑模板时遇到错误怎么办？
如果您在编辑模板时遇到问题，请尝试刷新页面。如果问题仍然存在，请检查您的互联网连接或尝试再次登录。查看您最近所做的更改以识别代码中任何潜在的冲突或错误也很有帮助。
#### 我如何知道我对模板所做的更改是否反映在网站上？
保存更改后，您可以访问网站的前端以查看结果。刷新页面以确保显示最新修改。如果看不到更改，请确保您已正确保存模板并且已清除浏览器的缓存。
#### 访问和编辑模板的先决条件是什么？
您需要在 Baklib 平台上拥有一个帐户，并可以访问拥有您要修改的模板的特定组织。此外，您还需要了解基本的 Web 开发概念，包括文件结构、流动语法和 HTML。
#### 为什么我需要将模板复制到我的组织？
将模板复制到您的组织后，您可以进行自定义修改，而不会影响原始模板或使用它的其他组织。这可确保您的更改是独立的，不会影响共享模板结构。
#### 如何访问和使用模板中的静态文件？
静态文件（如 CSS、JavaScript 或图像）存储在模板的 `/statics` 目录中。您可以在网站的前端使用它们的相对路径访问它们，例如，`/s/hello` 表示 `/statics` 目录中名为 `hello.liquid` 的文件。
[1]: https://dev.baklib.cn/
---
URL: https://dev.baklib.cn/liquid/tags/iteration
Updated: 2025-01-02
## 标题
迭代／循环
## 内容
迭代（或循环）标记（iteration tag）用于重复运行一段代码。
## for
重复运行一段代码。`for` 循环中所能够使用的属性请参考 [forloop (object)][1]。
输入
{% for product in collection.products %}
{{ product.title }}
{% endfor %}
输出
hat shirt pants
### break
循环过程中若干遇到 `break` 标记（tag）即停止循环。
输入
{% for i in (1..5) %}
{% if i == 4 %}
{% break %}
{% else %}
{{ i }}
{% endif %}
{% endfor %}
输出
1 2 3
### continue
循环过程中若遇到 `continue` 标记（tag）则跳出当前循环。
输入
{% for i in (1..5) %}
{% if i == 4 %}
{% continue %}
{% else %}
{{ i }}
{% endif %}
{% endfor %}
输出
1 2 3 5
## for (parameters)
### limit
限定循环执行的次数。
输入
{% for item in array limit:2 %}
{{ item }}
{% endfor %}
输出
1 2
### offset
从指定索引号开始执行循环。
输入
{% for item in array offset:2 %}
{{ item }}
{% endfor %}
输出
3 4 5 6
### range
定义循环执行的范围。可利用数字或变量来定义此执行范围。
输入
{% for i in (3..5) %}
{{ i }}
{% endfor %}
{% assign num = 4 %}
{% for i in (1..num) %}
{{ i }}
{% endfor %}
输出
3 4 5
1 2 3 4
### reversed
反转循环的执行顺序。注意和 `reverse` 过滤器（filter）的拼写是不同的。
输入
{% for item in array reversed %}
{{ item }}
{% endfor %}
输出
6 5 4 3 2 1
## forloop (object)
Information about a parent `for`[ loop][2].
{
"first": true,
"index": 1,
"index0": 0,
"last": false,
"length": 4,
"rindex": 3
}
### Use the `forloop` object
Input
{% assign smoothie_flavors = "orange, strawberry, banana" | split: ", " %}
{% for flavor in smoothie_flavors -%}
{%- if forloop.length > 0 -%}
{{ flavor }}{% unless forloop.last %}-{% endunless -%}
{%- endif -%}
{% endfor %}
Output
orange-strawberry-banana
### forloop (properties)
|
{{ link.link_text }}
{% endfor %}
{% endif %}
{% paginate_tag search.pages, as: 'pages', per: 10 %}
{% for page in pages %}
{% else %}
{{ link.url }}
{{ "search.no_results" | t: 'No results found' }}
{% endfor %}
{% render 'paginate', paginate: paginate %}
{% endpaginate_tag %}
Property
|Description
|Returns
| | --- | --- | --- | |length
The total number of iterations in the loop.
|number
parentloop
The parent forloop object. If the current for loop isn’t nested inside another for loop, then nil is returned.
forloop
index
The 1-based index of the current iteration.
|number
index0
The 0-based index of the current iteration.
|number
rindex
The 1-based index of the current iteration, in reverse order.
|number
rindex0
The 0-based index of the current iteration, in reverse order.
|number
first
Returns true if the current iteration is the first. Returns false if not.
boolean
last
Returns true if the current iteration is the last. Returns false if not.
boolean
| Cool Shirt | Alien Poster | Batman Poster | Bullseye Shirt | Another Classic Vinyl | Awesome Jeans |
| Cool Shirt | Alien Poster |
| Batman Poster | Bullseye Shirt |
| Another Classic Vinyl | Awesome Jeans |
{{ settings.fp_heading }}
{% endif %} 输出 ## 假值（Falsy） 在 Liquid 中，`nil` 和 `false` 是假值。 ## 总结 下表总结了在 Liquid 中什么是真值什么是假值。 ||
真值（truthy）
|假值（falsy）
| | --- | --- | --- | |true
|•
|| |
false
||
•
| |nil
||
•
| |string
|•
|| |
empty string
|•
|| |
0
|•
|| |
integer
|•
|| |
float
|•
|| |
array
|•
|| |
empty array
|•
|| |
page
|•
|| |
EmptyDrop
|•
|| [1]: https://liquid.bootcss.com/basics/truthy-and-falsy/#truthy [2]: https://liquid.bootcss.com/basics/truthy-and-falsy/#falsy [3]: https://liquid.bootcss.com/basics/truthy-and-falsy/#summary [4]: https://liquid.bootcss.com/basics/types/#string --- URL: https://dev.baklib.cn/liquid/filters/at-least Updated: 2025-01-02 ## 标题 at_least ## 内容 将数字限制在最小值。 输入 {{ 4 | at_least: 5 }} 输出 5 输入 {{ 4 | at_least: 3 }} 输出 4 --- URL: https://dev.baklib.cn/guide/git Updated: 2025-01-13 ## 标题 通过 git 安装模板 ## 内容 进入【管理】--【组织模板】，在组织模板中，选择 git 安装外部模板： > Baklib 的 git 仓库托管在: > > > gitee: [https://gitee.com/organizations/baklib/projects][1] > > > github: [https://github.com/tanmer][2]  安装完组织模板以后，进入【市场】选择【组织模板】即可找到，点击并安装应用。  [1]: https://gitee.com/organizations/baklib/projects [2]: https://github.com/tanmer --- URL: https://dev.baklib.cn/api/3d3bb Updated: 2025-08-18 ## 标题 📢 接口更新声明 · 2025 年 8 月 18日 ## 内容 ``` ### API 更新文档 — `GET /api/v1/sites/:site_id/pages` #### 变更内容 ### 1. `full_path_in` 参数 * 当 **未传递其他排序参数**（`sort_by`）时，查询结果将 **按照传入的 `full_path_in` 顺序返回**。 * 示例： ```json ?full_path_in=a/b/c, a/d/e ``` 返回结果的顺序将与传入的 `full_path_in` 顺序一致。 --- ### 2. 新增排序参数：`sort_by=position_tree` * 新增支持 **目录结构顺序** 排序。 * 使用方式： ``` ?sort_by=position_tree ``` * **排序规则** 1. 页面顺序由 **父页面链路（祖先路径 + 自身 position）** 决定； 2. 父页面在前 → 其子页面一定整体排在前面； 3. 同一父页面下，子页面按自身 `position` 排序； 4. 保证树形目录结构的完整性。 #### 示例 目录结构（含 position）： ``` A (pos=1) ├─ A1 (pos=2) └─ A2 (pos=3) B (pos=2) ├─ B1 (pos=1) │ ├─ B1a (pos=1) │ └─ B1b (pos=2) └─ B2 (pos=2) ``` 排序结果： ``` A, A1, A2, B, B1, B1a, B1b, B2 ``` 解释： * 虽然 **B1 (pos=1)** 小于 **A1 (pos=2)**，但由于 `B` 在 `A` 后面，B1 也必须排在 A 之后； * B1a / B1b 的排序，受制于父页面 B1 的顺序。 --- ### 3. 全文检索（`keywords` 参数）说明 * 当使用 `keywords` 参数进行全文检索时： * **不再执行 `full_path_in` 排序或 `position_tree` 排序**。 * 查询结果只会按照 **搜索相关度（pg\_rank 值）** 排序，确保最相关的结果优先。 --- ### 4. API 缓存说明 #### HTTP Header参数 * **`FROM_CACHE`** * 用于开启缓存，并设置缓存的唯一标识。 * 如果不设置，API 将不启用缓存。 * 修改这个值，即可刷新缓存，旧的缓存依然存在，过期自动清除。 * **`FROM_CACHE_TTL`** * 设置 API 缓存过期时间（单位：秒）。 * 默认值为 **7200 秒（2 小时）**。 * API 缓存时间是 `FROM_CACHE_TTL + 10分钟` 。 --- #### 使用示例 ```bash # 开启缓存，并设置缓存唯一标识 FROM_CACHE=version20250818 # 设置 API 缓存过期时间为 300 秒（默认 7200 秒） FROM_CACHE_TTL=300 ``` 返回的内容过期时间为： ``` FROM_CACHE_TTL + 600 秒 # 示例：300 + 600 = 900 秒 ``` --- #### 清除缓存 通过修改 `FROM_CACHE` 的值即可刷新缓存，例如： ```bash # 原先 FROM_CACHE=version20250818 # 刷新缓存 FROM_CACHE=version20250819 ``` #### 4.1 缓存命中信息（响应 Header） 仅在 **`sites/:id/pages` 接口** 且开启缓存时，响应中会返回以下两个 Header： * `X-Baklib-Cache` → `MISS` 或 `HIT` * `Age` → 缓存存在时间（单位：秒） 示例： ```http X-Baklib-Cache: HIT Age: 120 ``` 说明：该请求命中缓存，缓存已存在 **120 秒**。 ### 5 资源 URL 过期时间控制（请求 Header） * **`DAM_URL_TTL`**：资源 URL 的生存时间（秒），**最高优先级**。 * **`DAM_URL_TTL_DELAY_AFTER_CACHE`**：资源 URL 在**缓存过期后**的额外生存时间（秒）。 * **`DAM_URL_TTL_DELAY_AFTER_CACHE`** 依赖 **`FROM_CACHE_TTL`**，只有在设置了 `FROM_CACHE_TTL` 的情况下才会生效。 #### 5.1 过期时间优先级与计算 资源 URL 的最终过期时间按以下优先级确定： 1. 若设置 **`DAM_URL_TTL`**： ``` URL 过期时间 = DAM_URL_TTL ``` 2. 否则，若同时设置 **`FROM_CACHE_TTL`** 和 **`DAM_URL_TTL_DELAY_AFTER_CACHE`**： ``` URL 过期时间 = FROM_CACHE_TTL + DAM_URL_TTL_DELAY_AFTER_CACHE ``` 3. 否则，若仅设置 **`FROM_CACHE_TTL`**： ``` URL 过期时间 = FROM_CACHE_TTL + 600（10 分钟） ``` 4. 仅开启缓存，未设置其他参数： ``` URL 过期时间 = 默认FROM_CACHE_TTL(2小时) + 600（10 分钟） ``` #### 5.2 使用示例 ```bash # 直接指定 URL 过期时间为 1800 秒（最高优先级） DAM_URL_TTL=1800 # 缓存 300 秒，缓存过期后希望 URL 额外存活 600 秒 FROM_CACHE_TTL=300 DAM_URL_TTL_DELAY_AFTER_CACHE=600 # 实际 URL 过期时间 = 300 + 600 = 900 秒 ``` ``` --- URL: https://dev.baklib.cn/liquid/e1712/5a64b Updated: 2026-03-02 ## 标题 批量创建页面功能配置指南 ## 内容 ``` ## 概述 批量创建页面功能允许模板定义一个专门的界面，让用户能够批量导入/创建页面。这个功能通过在模板的 `schema` 中配置 `batch_create_url` 来实现。 使站点在管理端中可以按需提供批量创建页面的功能。 ## 工作流程 ### 系统交互流程 ``` 1. 用户在页面管理界面中点击"批量创建"按钮 ↓ 2. 系统获取该页面的模板及其子模板信息 ↓ 3. 如果子模板的 schema 中配置了 batch_create_url，则显示批量创建选项 ↓ 4. 用户点击某个模板的批量创建选项 ↓ 5. 系统生成包含认证信息的 batch_create_url 并在 iframe 中打开 ↓ 6. 用户在 iframe 中进行批量导入操作 ↓ 7. iframe 中的页面通过 API 调用创建页面 ``` ## 配置步骤 ### 1. 在模板 Schema 中添加 `batch_create_url` 在你的 `.liquid` 模板文件中，在 `{% schema %}` 部分添加 `batch_create_url` 配置： ```liquid {% schema %} { "name": "页面模板名称", "description": "页面模板描述", "batch_create_url": "https://your-import-service.com/batch_import", // 或者 "/s/batch_import"（模版中静态地址） "settings": [ // ... 其他模板设置 ] } {% endschema %} ``` ### 2. `batch_create_url` 的两种形式 #### 2.1 绝对 URL（推荐用于外部服务） ```json { "batch_create_url": "https://external-service.com/batch_import" } ``` 绝对 URL 使用完整的 http/https 地址。系统会自动追加以下查询参数： - `token`: 用户的临时 API token（JWT 格式） - `site_id`: 当前站点 ID - `full_path`: 父页面的完整路径 - `template_name`: 模板名称 - `template_style`: 模板风格 **示例生成的 URL：** ``` https://external-service.com/batch_import? token=JWT+eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3NzAyOTY1NTh9... &site_id=34 &full_path=%2F80ec12 &template_name=page &template_style=style ``` #### 2.2 相对路径 URL（建议页面构建在模版中静态页面中） ```json { "batch_create_url": "/s/batch_import" } ``` 相对路径会被转换为完整的站点门户 URL。系统会使用站点的门户地址作为基础 URL，并追加相同的查询参数。 **示例生成的 URL：** ``` http://site-demo.baklib.localhost:3000/s/batch_import? token=JWT+eyJhbGciOiJIUzI1NiJ9... &site_id=34 &full_path=%2Fparent &template_name=page &template_style=style ``` ### 3. 完整的模板配置示例 ```liquid {% # 模板的 HTML/Liquid 内容 %} {% schema %} { "name": "数据批量导入页面", "description": "支持批量创建页面的模板", "thumb_url": "images/theme/batch_import_page.png", "batch_create_url": "https://api.example.com/pages/batch_import", "settings": [ { "id": "title", "type": "text", "label": "页面标题" }, { "id": "description", "type": "richtext", "label": "页面描述" }, { "id": "enable_batch_import", "type": "checkbox", "label": "启用批量导入", "default": true } ] } {% endschema %} ``` ## 在批量创建 iframe 中的操作 ### 接收的查询参数 当 iframe 中的页面加载时，会收到以下查询参数： | 参数 | 说明 | 示例 | |------|------|------| | `token` | JWT 格式的 API 认证 token | `JWT eyJhbGciOiJIUzI1NiJ9...` | | `site_id` | 站点的数字 ID | `34` | | `full_path` | 父页面的完整路径（URL 编码） | `%2F80ec12` | | `template_name` | 模板名称 | `page` | | `template_style` | 模板风格 | `style` | ### 调用 API 创建页面 iframe 中的页面可以通过以下 Baklib API 创建新页面： > baklib api接口文档： https://dev.baklib.cn/api#/paths/sites-site_id--pages/post ## 最佳实践 ### 1. 选择合适的 URL 类型 - **外部服务**：使用绝对 URL（完整的 http/https 地址） - **站点内部**：使用相对路径（以 `/` 开头） ### 2. 安全考虑 - 传递给 iframe 的 `token` 是临时 API token，有过期时间限制 - 确保你的批量创建服务在安全的 HTTPS 连接上运行 - 验证 `site_id` 和 `full_path` 参数的有效性 ### 3. 用户体验 - 在模板中明确说明支持批量创建功能 - 在 `batch_create_url` 指向的页面中提供清晰的导入说明 - 实现进度提示和错误处理 ### 4. 模板命名规范 - `template_name`: 模板的基础名称（如 `page`, `article`） - `template_style`: 模板的风格变体（如 `default`, `dark`, `compact`） ## 故障排查 ### 问题：批量创建选项不显示 **可能原因：** - 模板的 schema 中没有配置 `batch_create_url` - `batch_create_url` 值为空或 `null` - 子模板没有正确关联到父模板 **解决方案：** 1. 检查模板文件中的 `schema` 部分 2. 确保 `batch_create_url` 有有效的值 3. 验证模板的 `sub_page_templates` 配置 ### 问题：iframe 加载失败 **可能原因：** - URL 解析错误 - 网络不可达 - CORS 跨域问题 **解决方案：** 1. 检查浏览器控制台的错误信息 2. 验证 URL 是否正确生成 3. 确保批量创建服务正在运行 4. 检查是否配置了适当的 CORS 头 ### 问题：无法创建页面 **可能原因：** - API token 已过期 - 用户权限不足 - API 参数格式错误 **解决方案：** 1. 刷新页面重新获取 token 2. 检查用户是否有页面创建权限 3. 验证 API 请求体格式是否正确 ``` --- URL: https://dev.baklib.cn/overview Updated: 2024-11-28 ## 标题 模板设置 ## 内容 本章节介绍 Baklib 模板开发的入口界面，如何应用到站点中，如何进入低代码编辑器。 --- URL: https://dev.baklib.cn/overview/themes/wiki Updated: 2024-11-17 ## 标题 Wiki: Wiki 主题模板 ## 内容  **模板类型：**wiki **模板名称：** Wiki知识库系统 **应用场景：**用于大型可复用的文档内容管理，基于KB知识库，构建Wiki、Documentation、Help Center等站点。 ## 首页主题风格 首页主题风格有多种形式，可以支持轮播、大图展示、播放视频等。  首页预览  help center 风格  list 风格 ## 页面风格 页面详情主要包含侧边栏导航和页面主体内容本身。  网站的页面预览效果：   完整的页面截图  更换主题颜色预览效果。 --- URL: https://dev.baklib.cn/overview/themes Updated: 2024-07-19 ## 标题 公共模板 ## 内容 公共模板是系统自带的模板样例，这些模板覆盖了不同场景的使用体验，用户可以通过公共模板快速匹配业务需求，以启动相关项目。 --- URL: https://dev.baklib.cn/theme/locales Updated: 2024-07-19 ## 标题 locales/ ## 内容 翻译文件是`json`类型，其中包含一组在整个主题中使用的文本字符串的翻译 客户除了可以编辑在整个主题中重复的单词和短语之外，还允许将站点内容设置翻译成国际商家和客户的多种语言。 ### 定义： { "hello": "你好", } ### 调用： # {{ 'hello' | t }} # {{ 'hello' | t: '你好' }} 默认值： 你好 # {{ 'hello' | t: '你好', locale: 'de' }} 默认值： 你好, 语言：德语, 翻译：Hallo # {{ 'hello' | t, locale: 'de' }} 语言：德语, 翻译：Hallo --- URL: https://dev.baklib.cn/theme/locales/zh-cn-schema-json Updated: 2024-07-19 ## 标题 zh-CN.schema.json ## 内容 { "settings_schema": { "generic": { "name": "站点基本信息设置", "help_center_index_description": "功能丰富的产品知识库样式", "list_index_description": "首页目录列表样式", "header_name": "页头页尾导航菜单", "head_title": "Head HTML 配置", "settings": { "hero_image_url": { "label": "首页背景大图", "info": "用于部分主题首页的背景横幅，建议1900*600px的深色图片" }, "title": { "label": "站点标题" }, "description": { "label": "站点描述" }, "hot_tags": { "label": "热搜关键词（请用英文逗号「,」分隔）" }, "copyright_info": { "label": "备案/版权信息", "default": "蜀ICP备15035023号" }, "company_name": { "label": "公司名称", "default": "Baklib.cn" }, "header_menu_html": { "label": "Header页头导航菜单", "info": "支持HTML标签和TailwindCss样式代码" }, "footer_menu_html": { "label": "Footer页尾导航菜单", "info": "支持HTML标签和TailwindCss样式代码" }, "head_html": { "label": "Head Meta HTML代码", "info": "这部分内容会植入到站点的标签内，请使用标准的 HTML 格式", "placeholder": "" } } }, "page": { "name": "页面", "description": "文档内容页面", "settings": { "description":{ "label": "页面描述" }, "content":{ "label": "内容", "info": "同步自数据源，不可编辑" }, "icon": { "label": "页面图标", "info": "用于显示页面图标，建议1:1比例" }, "tags":{ "label": "标签" } } } } } --- URL: https://dev.baklib.cn/theme/snippets/footer Updated: 2024-07-19 ## 标题 _footer.liquid ## 内容 {% assign screen_width = site.settings.screen_width.value | default: 'max-w-screen-xl' %} --- URL: https://dev.baklib.cn/theme/templates/tag Updated: 2024-07-19 ## 标题 tag.liquid ## 内容 标签页模板，位于： `templaes/tag.liquid` 通常标签页模板主要是将指定的某个标签下的所有页面展示出来，该页面会传人一个变量： `tag `，通过遍历 `tag.pages` 获得标签下所有页面。 通用代码如下：
# {{ tag.name }}
-
{% paginate_tag tag.pages, as: 'pages' %}
{% render "collapse_pages", pages: pages, tag_name: tag.name %}
{% render 'paginate', paginate: paginate %}
{% endpaginate_tag %}
Class
|Properties
| | --- | --- | |text-wrap
|text-wrap: wrap;
| |text-nowrap
|text-wrap: nowrap;
| |text-balance
|text-wrap: balance;
| |text-pretty
|text-wrap: pretty;
| [1]: https://tailwindcss.com/docs/text-wrap --- URL: https://dev.baklib.cn/liquid/tags/raw Updated: 2025-01-02 ## 标题 原始内容 ## 内容 `raw` 标记临时禁止处理其所包围的代码。如果输出的内容与 Liquid 模板语言有冲突时（例如 Mustache、Handlebars 模板语言）可以避免冲突。 输入 {% raw %} In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not. {% endraw %} 输出 In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not. --- URL: https://dev.baklib.cn/liquid/basics/e2a2 Updated: 2025-01-02 ## 标题 数据类型 ## 内容 Liquid 对象的类型可以是以下五种： * [String][1] * [Number][2] * [Boolean][3] * [Nil][4] * [Array][5] 你可以通过 [assign][6] 或 [capture][7] 标记来初始化 Liquid 变量。 ## String（字符串） 将变量的值包裹在单引号或双引号之中就声明了一个字符串： {% assign my_string = "Hello World!" %} ## Number（数字） 数字类型包括浮点数和整数： {% assign my_int = 25 %} {% assign my_float = 39.756 %} ## Boolean（布尔） Booleans 类型只能是 `true` 或 `false`。布尔值千万不能加引号，否则就成为字符串了。 {% assign foo = true %} {% assign bar = false %} ## Nil（空） Nil 是一个特殊的空值，当 Liquid 代码没有可输出的结果时将返回 Nil。他并**不是**由 “nil” 这个三个字符组成的字符串。 在 `if` 条件判断和其他 Liquid 标记（tag）判断语句中，Nil [被当做 false][8] 。 下例中，如果 user 不存在（也就是 `user` 返回 `nil`），Liquid 不输出问候语： {% if user %} Hello {{ user.name }}! {% endif %} 如果 Liquid 标记（tag）或输出返回的是 `nil`，页面上将不会有任何内容。 输入 The current user is {{ user.name }} 输出 The current user is ## Array（数组） 数组能够存储一组任意类型的变量。 ### 访问数组中的项 通过 [迭代标记（iteration tag）][9] 可以访问数组中的所有项。 输入 {% for user in site.users %} {{ user }} {% endfor %} 输出 Tobi Laura Tetsuro Adam ### 访问数组中的特定项 利用方括号 `[` `]` 能够访问数组中的特定项。数组的索引从 0 开始。 输入 {{ site.users[0] }} {{ site.users[1] }} {{ site.users[3] }} 输出 Tobi Laura Adam ### 初始化数组 你无法只通过 Liquid 语法初始化一个数组。 然而，你可以利用 [split][10] 过滤器将一个字符串分割为一个子字符串数组。 [1]: https://liquid.bootcss.com/basics/types/#string [2]: https://liquid.bootcss.com/basics/types/#number [3]: https://liquid.bootcss.com/basics/types/#boolean [4]: https://liquid.bootcss.com/basics/types/#nil [5]: https://liquid.bootcss.com/basics/types/#array [6]: https://liquid.bootcss.com/tags/variable/#assign [7]: https://liquid.bootcss.com/tags/variable/#capture [8]: https://liquid.bootcss.com/basics/truthy-and-falsy [9]: https://liquid.bootcss.com/tags/iteration [10]: https://liquid.bootcss.com/filters/split --- URL: https://dev.baklib.cn/liquid/filters/at-most Updated: 2025-01-02 ## 标题 at_most ## 内容 将数字限制在最大值。 输入 {{ 4 | at_most: 5 }} 输出 4 输入 {{ 4 | at_most: 3 }} 输出 3 --- URL: https://dev.baklib.cn/install/init Updated: 2025-01-13 ## 标题 初始化资源 ## 内容 ## 开发 ```bash npm run dev ``` ### 安装配置TailwindCSS [TailwindCSS官网](https://www.tailwindcss.cn/docs/installation) #### 1.安装Tailwindcss 通过`npm`安装`tailwindcss`，然后创建`tailwind.config.js`配置文件 ```bash npm add -D tailwindcss npx tailwindcss init ``` #### 2.配置模板文件的路径和自定义样式 ```javascript /** @type {import('tailwindcss').Config} */ module.exports = { content: ["./templates/**/*.liquid", "./snippets/**/*.liquid", "./layout/**/*.liquid", "./statics/**/*.liquid"], darkMode: 'class', theme: { extend: { colors: () => { return { slate: { 150: "#E9EEF5" }, ...["primary", "secondary", "accent", "info", "success", "warning"].reduce((map, name) => { return { ...map, [name]: { DEFAULT: `hsl(var(--theme-color-${name}) /这是一段加粗的文本。
``` 输出： ```markdown ## 正文 这是一段**加粗**的文本。 ``` #### 代码类型 Schema 配置： ```json { "id": "script", "type": "code", "label": "脚本代码", "language": "javascript", "to_markdown": true } ``` 输出： ```markdown ## 脚本代码 ```javascript const x = 1; ``` ``` #### 图片选择器 输出 Markdown 图片语法： ```markdown ## 封面图  ``` #### 文件/视频选择器 仅输出 URL 字符串（无 Markdown 包裹）： ``` ## 附件 https://portal.example.com/signed-url?expires=... ``` #### 标签选择器 根据标签 IID 输出名称列表： ```markdown ## 标签 技术, 文档, 教程 ``` ## 资源链接有效期配置 资源选择器生成的 URL 有效期默认为 20 分钟，可通过修改常量调整： ```ruby # app/models/page/to_markdown.rb PORTAL_URL_EXPIRES_IN = 20.minutes ``` ``` --- URL: https://dev.baklib.cn/liquid Updated: 2024-11-28 ## 标题 Liquid 语法 ## 内容 Baklib 的主题模板是通过 Liquid 模板语言开发的，在熟悉主题模板开发之前，需要了解 Liquid 基本语法。 👏 Liquid 是由 Shopify 创建并用 Ruby 编写的开源模板语言。它是 Shopify（全球最大的独立电商平台） 主题的支柱，用于在店面加载动态内容。 Liquid 自 2006 年起就在 Shopify 投入生产，现在也被许多其他托管 Web 应用程序使用。 **教程：** [https://shopify.github.io/liquid/][1] > ***请直接参考官方教程，若没有特殊说明，Baklib 遵循 Liquid 官方教程版本同步。*** [1]: https://shopify.github.io/liquid/ --- URL: https://dev.baklib.cn/overview/themes/daisy-wiki Updated: 2024-11-17 ## 标题 Wiki: Daisy Wiki ## 内容  **模板类型：**wiki **模板名称：** Daisy Wiki **应用场景：**内置基于 DaisyUI 构建的多风格主题、内容驱动型知识库门户。用于大型可复用的文档内容管理，基于KB知识库，构建Wiki、Documentation、Help Center等站点。 ## 首页主题风格 首页主题风格支持 12 种个性化切换。  主题切换  help center 风格首页 ## 页面风格 页面详情主要包含侧边栏导航和页面主体内容本身。 栏目页面：  详情页面：  得益于 Daisy UI 的丰富组件库，可以自定义构建各种效果的页面块布局。  --- URL: https://dev.baklib.cn/theme/snippets Updated: 2024-07-19 ## 标题 snippets/ ## 内容 snippets 目录中包含自定义的可重用模板片段，比如页头、页脚、面包屑、导航、广告等页面片段。 ### **定义** 创建一个文件： snippets/\_footer.liquid ### **调用** 用 `render` 方法在 `layouts/`和`templates/`的模板文件中引用文件： {% render 'footer' %} 下面是一些常见的页面片段： --- URL: https://dev.baklib.cn/theme/templates/robots Updated: 2024-07-19 ## 标题 robots.txt.liquid ## 内容 模板 `robots.txt.liquid` 呈现 `robots.txt` 托管在 `/robots.txt` URL 上的文件。 该文件 `robots.txt` 告诉搜索引擎哪些页面可以或不能在网站上抓取。它包含执行此操作的规则组，每个组有三个主要组件： * 用户代理，用于记录规则组应用于哪个爬网程序。例如， `adsbot-google` . * 规则本身，用于记录爬网程序可以访问或无法访问的特定 URL。 * 可选的站点地图网址。 `baklib`默认情况下会生成一个 `robots.txt` 文件，该文件适用于大多数站点，因此默认情况下此模板不包含在任何主题中。 通用代码： User-Agent: * Disallow: --- URL: https://dev.baklib.cn/faqs/31b7 Updated: 2024-11-28 ## 标题 如何添加暗黑模式: Dark mode ## 内容 Baklib 的模板都默认带有暗黑模式，暗黑模式的实现方法如下。 在 src/main.js 中： import ThemeController from "./theme_controller" const application = Application.start() window.Stimulus = application application.register('theme', ThemeController) 在theme\_contrller.js中： import { Controller } from "@hotwired/stimulus"; //自动跟随系统： window.matchMedia('(prefers-color-scheme: dark)').matches export default class extends Controller { static targets = ["checkbox"]; connect() { const dark = localStorage.getItem("dark-mode"); if (dark && dark == 'true' || window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.classList.add("dark"); this.checkboxTarget.checked = true; } else { document.documentElement.classList.remove("dark"); this.checkboxTarget.checked = false; } } toggle() { const checkbox = this.checkboxTarget; const isDarkMode = checkbox.checked; if (isDarkMode) { document.documentElement.classList.add("dark"); localStorage.setItem("dark-mode", true); } else { document.documentElement.classList.remove("dark"); localStorage.setItem("dark-mode", false); } } } 接下来在网页中添加 light/dark 的切换开关：settings_type（表单类型）
|数据类型
| | --- | --- | |checkbox
|boolean
| |color, color_background, font_picker, image_picker, link, radio, select, tag_picker, text, video_picker
|multiple = true ? array : string
| |date
|date
| |html, richtext, textarea
|text
| |number, range
|float
| ## **5. where - 页面属性** ### **5.1 页面属性筛选逻辑** 1. **字段格式**：字段名由 `属性名_操作符` 构成（如：`visits_count_gt`, \'created\_at\_lteq\'）。 2. **数据类型限制操作符**：每个字段根据数据类型限制支持的操作符。 3. **支持 AND / OR 组合查询**：可组合多条件查询。 4. **可筛选字段**：仅下面列出的字段支持筛选。 ### **5.2 可用作筛选的页面属性** 页面属性是指页面自身的属性，可用于筛选。支持的页面属性包括： |属性名
|说明
|数据类型
| | --- | --- | --- | |name
|页面名称（计算后实际展示的值）
|string
| |visits_count
|访问次数
|integer
| |full_path
|完整路径
|string
| |template_name
|模板名称
|string
| |template_style
|模板样式
|string
| |updated_at
|页面更新时间
|datetime
| |created_at
|页面创建时间
|datetime
| ## **6. 筛选操作符表及其解释** ``` | 操作符 | 含义 | 适用类型 | 例如 | |--------|------|----------|------| | `eq` | 等于 | 所有类型 | `"name_eq": "产品"` | | `not_eq` | 不等于 | 所有类型 | `"name_not_eq": "产品"` | | `lt` | 小于 | 数值、日期 | `"visits_count_lt": 100` | | `gt` | 大于 | 数值、日期 | `"visits_count_gt": 100` | | `lteq` | 小于等于 | 数值、日期 | `"created_at_lteq": "2023-01-01"` | | `gteq` | 大于等于 | 数值、日期 | `"created_at_gteq": "2023-01-01"` | | `cont` | 包含(区分大小写) | 字符串 | `"title_cont": "关键词"` | | `i_cont` | 包含(忽略大小写) | 字符串 | `"title_i_cont": "关键词"` | | `not_cont` | 不包含(区分大小写) | 字符串 | `"title_not_cont": "关键词"` | | `not_i_cont` | 不包含(忽略大小写) | 字符串 | `"title_not_i_cont": "关键词"` | | `start` | 以...开头 | 字符串 | `"name_start": "产品"` | | `not_start` | 不以...开头 | 字符串 | `"name_not_start": "产品"` | | `end` | 以...结尾 | 字符串 | `"name_end": "产品"` | | `not_end` | 不以...结尾 | 字符串 | `"name_not_end": "产品"` | | `matches` | 正则匹配 | 字符串 | `"name_matches": "^产品.*"` | | `does_not_match` | 正则不匹配 | 字符串 | `"name_does_not_match": "^产品.*"` | | `matches_any` | 任意正则匹配 | 字符串 | `"name_matches_any": ["^产品.*", ".*服务$"]` | | `matches_all` | 所有正则匹配 | 字符串 | `"name_matches_all": ["^产品.*", ".*服务$"]` | | `does_not_match_any` | 任意正则不匹配 | 字符串 | `"name_does_not_match_any": ["^产品.*", ".*服务$"]` | | `does_not_match_all` | 所有正则不匹配 | 字符串 | `"name_does_not_match_all": ["^产品.*", ".*服务$"]` | | `in` | 在集合中 | 字符串 | `"name_in": ["产品1", "产品2"]` | | `not_in` | 不在集合中 | 字符串 | `"name_not_in": ["产品1", "产品2"]` | | `start_any` | 任意以...开头 | 字符串 | `"name_start_any": ["产品", "服务"]` | | `start_all` | 所有以...开头 | 字符串 | `"name_start_all": ["产品", "服务"]` | | `not_start_any` | 任意不以...开头 | 字符串 | `"name_not_start_any": ["产品", "服务"]` | | `not_start_all` | 所有不以...开头 | 字符串 | `"name_not_start_all": ["产品", "服务"]` | | `end_any` | 任意以...结尾 | 字符串 | `"name_end_any": ["产品", "服务"]` | | `end_all` | 所有以...结尾 | 字符串 | `"name_end_all": ["产品", "服务"]` | | `not_end_any` | 任意不以...结尾 | 字符串 | `"name_not_end_any": ["产品", "服务"]` | | `not_end_all` | 所有不以...结尾 | 字符串 | `"name_not_end_all": ["产品", "服务"]` | | `cont_any` | 任意包含(区分大小写) | 字符串 | `"name_cont_any": ["产品", "服务"]` | | `cont_all` | 所有包含(区分大小写) | 字符串 | `"name_cont_all": ["产品", "服务"]` | | `not_cont_any` | 任意不包含(区分大小写) | 字符串 | `"name_not_cont_any": ["产品", "服务"]` | | `not_cont_all` | 所有不包含(区分大小写) | 字符串 | `"name_not_cont_all": ["产品", "服务"]` | | `i_cont_any` | 任意包含(忽略大小写) | 字符串 | `"name_i_cont_any": ["产品", "服务"]` | | `i_cont_all` | 所有包含(忽略大小写) | 字符串 | `"name_i_cont_all": ["产品", "服务"]` | | `not_i_cont_any` | 任意不包含(忽略大小写) | 字符串 | `"name_not_i_cont_any": ["产品", "服务"]` | | `not_i_cont_all` | 所有不包含(忽略大小写) | 字符串 | `"name_not_i_cont_all": ["产品", "服务"]` | | `true` | 为真 | 布尔值 | `"is_active_true": true` | | `false` | 为假 | 布尔值 | `"is_active_false": false` | | `array_cont_all` | 包含所有指定值 | 数组 | `"array_cont_all": ["热门", "促销"]` | | `not_array_cont_all` | 不包含所有指定值 | 数组 | `"not_array_cont_all": ["热门", "促销"]` | | `array_cont_any` | 包含任一指定值 | 数组 | `"array_cont_any": ["热门", "促销"]` | | `not_array_cont_any` | 不包含任一指定值 | 数组 | `"not_array_cont_any": ["热门", "促销"]` | | `array_equals` | 数组完全相等 | 数组 | `"array_equals": ["热门", "促销"]` | | `not_array_equals` | 数组不完全相等 | 数组 | `"not_array_equals": ["热门", "促销"]` | ``` ### **7. 数据类型可允许的操作符** |数据类型
|支持的操作符
| | --- | --- | |boolean
|true, false, eq
string
|eq not_eq matches does_not_match matches_any matches_all does_not_match_any does_not_match_all in not_in start not_start start_any start_all not_start_any not_start_all end not_end end_any end_all not_end_any not_end_all cont cont_any cont_all not_cont not_cont_any not_cont_all i_cont i_cont_any i_cont_all not_i_cont not_i_cont_any not_i_cont_all
text
|i_cont cont not_i_cont not_cont eq not_eq start not_start end not_end
date / datetime
|eq, not_eq, lt, gt, lteq, gteq
float / integer
|eq, not_eq, lt, gt, lteq, gteq
array
|array_cont_all, not_array_cont_all, array_cont_any, not_array_cont_any, array_equals, not_array_equals
参数名
|描述
|类型
|默认值
|示例
| | --- | --- | --- | --- | --- | |collection_name
|要搜索的pages数据集合
|PagesDrop
| |site.pages 站点下所有页面进行检索
page.children 当前页面下的仅下级页面
page.pages 当前页面下的全部页面
keywords
|搜索关键词
|字符串或变量
| | | |by_user
|标记是否为用户检索，若为true将自动记录用户检索记录与统计数据
Boolean
|true
| | ## **3. 搜索结果可用属性** 在 `{% search ... %}` 和 `{% endsearch %}` 包裹的内容中，可通过 `search` 对象获取以下参数： * `search.pages` 搜索结果页面集合，可用于遍历。 * `search.keywords` 本次搜索的关键词。 * `search.extends` 额外扩展信息（如有）。 ## **4. 直达跳转（自动处理）** 如果搜索结果为直达，会自动跳转到目标页面。 > 由站点页面管理，搜索记录/自定义搜索结果 中配置 #### ## **5. 设置模板可用于分词检索的动态变量** 在模板文件的 settings\_schema 中添加 searchable: true {% schema %} { "name": "Help Center", "settings": [ { "id": "description_en", "type": "textarea", "label": "英文描述", "searchable": true # 开启后，创建的页面中填写此值的，在前端可直接分词搜索 } ] } {% endschema %} ## **6. 示例** - 目标：在某栏目页面中实现筛选、搜索功能 - 可筛选页面动态字段（由模版settings中自行开启）： tags (array[tag])、 category(string)) - 可搜索页面内容：页面标题、内容等, 由url中获取params 提供的关键词进行搜索 - 实现方案：通过query tag + search tag，共同处理 - 页面模版中：templates/articles_channel.liquid {% query pages1 from site.pages %} { "where": { "tags_array_cont_any": ["faq", "help"] "category_eq": "会议" } } {% endquery %} {% search pages1, keywords: params[:q] %}-
{% for page in search.pages %}
- {{ page.link_text }} {% endfor %}
{{ page.highlighted_search_title }}
{{ page.highlighted_search_content }}
- 当前版本 {% for version_page in page.versions %}
- {{ version_page.name }} {% endfor %}
更新后的内容
{% render 'updated_content', data: data %}
页面标题
页面内容
``` ## 实际应用场景 ### 场景 1：Turbo Stream 表单提交 表单提交后，使用 Turbo Stream 更新页面内容，显示验证错误或成功消息。 ```liquid {% response_type "turbo_stream" %} {% layout none %} {%# 替换表单，显示验证错误 %}字段
|说明
|是否必填
|示例
| | --- | --- | --- | --- | |language
站点语言(由模板config/settings_schema.json 中 theme_languages 的配置值提供可用值，从中选择一项)
|否
|'zh-CN', 'en', 'zh-TW'
time_zone
时区
|否
|Beijing
favicon
网站图标
|否
|资源地址；模板内images/下的图片或远程可访问的图片地址
| |settings
settings_schema 动态表单配置，依据 config/settings_schema.json中settings 提供的可配置项进行设置
否
| | ### 3.2 `pages` 页面结构 用于初始创建站点页面，支持多层级子页面创建。 #### 示例（YAML） pages: title: "首页" slug: "index" template_name: "page" settings: hero_image_url: "images/home-banner.png" search_hot_keywords: "安装\n使用指南\nFAQ" children: - name: "product_index-1" template_name: "product_index" settings: textarea: "----描述" icon: "images/logo.svg" thumb_image_url: "https://example.com/thumb.png" content_html: "preset:footer_nav_links2.html" - name: "product_index-2" slug: "test2" template_name: "product_index" settings: textarea: "----描述2" icon: "images/logo.svg" thumb_image_url: "https://example.com/thumb2.png" content_html: "preset:footer_nav_links2.html" #### 可配置属性 |字段
|说明
|是否必填
|示例
| | --- | --- | --- | --- | |name
页面标题
|必填
|"product_index-1"
slug
页面路径
|否
|"index", "guide"
template_name
页面模板名称
|必填
|"page", "product_index"
template_style
页面头图
| |当需要使用页面模板类似格式为templates/index.preview.liquid 时，此项填写 preview
settings
由当前页面指定的页面模板中schema.settings来配置；以schema.settings的id为key，值为value的形式
值的数据类型请根据动态表单的类型
children
下级页面的数据（数组格式）
| | | ## 4. 使用 `preset:` 引用复杂格式内容 当需要插入复杂内容时，可以使用 `preset:`： * 默认仅从 `templates/presets/` 目录加载 * 内容会完整替换字段值 #### 示例 content_html: "preset:faq.html" ## 5. 资源引用 初始数据配置中依据站点字段类型、页面字段类型或动态表单的类型来决定是否需要使用资源 在 `site` 或 `pages` 配置中，常见的字段值支持以下几类资源引用方式： |类型
|格式
|示例
|说明
| | --- | --- | --- | --- | |模板内置图片
|"images/..."
"images/logo.png"
引用模板 assets/ 目录下的文件
远程资源
|"http://..." 或 "https://..."
"https://example.com/banner.png"
使用外部 URL
| |预设内容
|"preset:..."
"preset:faq.md"
引用 templates/presets/ 下的文件内容，适合长文本/富文本