KnowSphere 主题脚手架参考

以已有 Halo 主题为基础增量集成。Halo 的原生主题路由、插件 API 和 Halo UC 控制台路由属于不同系统；创建某个 HTML 文件不会自动注册 /uc/orders 等地址。

建议目录

my-theme/
├── theme.yaml
├── settings.yaml
├── templates/
│   ├── index.html
│   ├── post.html
│   ├── page.html
│   ├── modules/
│   │   ├── layout.html
│   │   └── knowsphere-membership.html
│   └── custom/
│       └── membership.html
└── assets/
    └── knowsphere.css

自定义会员页

在 theme.yaml 的现有 spec.customTemplates.page 中增加条目，不覆盖主题其他设置：

spec:
  requires: ">=2.26.0"
  customTemplates:
    page:
      - name: 会员套餐
        description: 展示 KnowSphere 会员套餐
        file: custom/membership.html

在 Halo 后台创建自定义页面、选择该模板，再使用实际页面 permalink 配置导航。若主题需要接入插件约定的 /membership 或 /columns/... 路径，先确认安装包已注册对应主题路由和要求的模板名称；不能仅靠这个自定义模板示例推导出路由存在。

<!doctype html>
<html lang="zh-CN" xmlns:th="https://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>会员套餐</title></head>
<body>
  <main>
    <h1>会员套餐</h1>
    <th:block th:if="${pluginFinder.available('know-sphere') or pluginFinder.available('know-sphere-pro')}">
      <section th:with="plans=${knowSphereFinder.listMembershipPlans().collectList().block()}">
        <p th:if="${#lists.isEmpty(plans)}">暂无套餐</p>
        <article th:each="plan : ${plans}">
          <h2 th:text="${plan.title}"></h2>
          <p th:text="${plan.description}"></p>
          <span th:text="${plan.price}"></span><span>元</span>
        </article>
      </section>
    </th:block>
  </main>
</body>
</html>

这是展示模板，购买交互请接入实际用户中心建单接口和插件支付组件，不在模板中伪造支付成功。

原生文章页

保留原主题布局和文章变量，用 th:utext="${post.content.content}" 输出已经过插件过滤的正文。不要用摘要、快照或后端原始内容替换它。共用片段通过 th:replace 复用，避免每个页面重复资源与评论组件。

设置

主题集成开关、配色和导航路径放在 settings.yaml，模板读取 theme.config。新设置使用 Halo 支持的 FormKit 表单类型；数组使用 array，不引入已弃用的 repeater。

参考 Halo 官方主题配置 和 页面指南。