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"

可配置属性

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"

可配置属性

4. 使用 preset: 引用复杂格式内容

当需要插入复杂内容时，可以使用 preset:：

• 默认仅从 templates/presets/ 目录加载

• 内容会完整替换字段值

示例

content_html: "preset:faq.html"

5. 资源引用

初始数据配置中依据站点字段类型、页面字段类型或动态表单的类型来决定是否需要使用资源

在 site 或 pages 配置中，常见的字段值支持以下几类资源引用方式：

示例

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 文件，按文件名排序。

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: 引用长内容，就能让用户立即体验到模板的最佳效果。