Baklib 文档中心

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"

可配置属性

字段
说明
是否必填
示例
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
  1. 由当前页面指定的页面模板中schema.settings来配置；以schema.settings的id为key，值为value的形式
  2.  值的数据类型请根据动态表单的类型
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/ 下的文件内容，适合长文本/富文本

示例

site:
  settings:
    logo_url: "images/logo.png"               # 模板内置资源
    hero_image: "https://cdn.example.com/bg"  # 远程图片
    footer_nav_links: "preset:footer_nav_links.html" # 外部文件引用

5. 执行逻辑

Seeds 的执行遵循以下规则：
  1. 扫描目录：读取 seeds/ 下所有 .yml 、.json文件，按文件名排序。
  2. 解析文件：
    • 顶级 key 为 site → 更新站点配置
    • 顶级 key 为 pages → 递归创建页面
    • 其他 key → 忽略
  3. 处理 preset：如果字段值以 preset: 开头 → 替换为 presets/ 中的文件内容。
  4. 处理资源：
    • "images/... → 转换为 assets/ 目录下路径,
    • "http(s)://..." → 原样保留
    • 资源在通过以上两种方式引用后，创建站点时将自动上传至组织资源库中
  5. 幂等性：
    • 相同层级、相同 slug 的页面已存在 → 跳过
    • 不存在 → 新建

6. 使用场景

  1. 站点初始化：新建站点时，一键生成首页、导航、示例内容。
  2. 模板演示：展示主题时，加载完整的示例数据，而不是空白页面。

7. 开发者最佳实践

* 始终用编号前缀保证执行顺序（如 001_site.json → 002_pages.yml）。
* 页面复杂的内容尽量用 preset: 引用，例如动态表单的值需要html，富文本等，避免在json、yml中格式、编码等问题。
* 页面数据避免重复的 slug，否则会被跳过。
* 勿重复写pages、site 多套初始数据

总结：

Seeds 是模板开发中的关键机制，可以帮助你在站点初始化时，快速提供完整的结构和内容。只需在 seeds/ 文件夹中编写好 site 和 pages 定义，再配合 preset: 引用长内容，就能让用户立即体验到模板的最佳效果。
搜索范围 目录结构
搜索全站