使用文档

TemplateMaker 使用文档

基于 Scriban 的强大模板渲染引擎，快速构建和管理您的网站模板

版本 1.0.0 • 更新于 2025年11月

快速开始

只需几个简单步骤，即可开始使用 TemplateMaker 创建和管理您的模板

1

查看模板列表

列出所有可用的模板及其详细信息

dotnet run template list
2

渲染模板

将模板和数据结合，生成静态 HTML 页面

dotnet run render A1002
3

预览效果

启动本地服务器，实时预览渲染结果

dotnet run preview A1002

核心功能

强大的命令行工具，提供完整的模板管理和渲染能力

模板管理

查看、创建和管理模板的基本信息

dotnet run template list
dotnet run template info 001

页面渲染

使用 Scriban 引擎渲染模板页面

dotnet run render 001
dotnet run render 001 --page home

实时预览

启动本地服务器进行实时预览

dotnet run preview 001
dotnet run preview 001 --port 8080

远程获取

从远程服务器下载模板到本地

dotnet run fetch MyTemplate
dotnet run fetch MyTemplate --with-resources

发布上传

将本地模板发布到远程服务器

dotnet run publish 001
dotnet run publish 001 --name CustomName

资源构建

自动运行 npm build 构建前端资源，将 site.css/site.js 编译为 site.min.css/site.min.js

自动检测 package.json
自动执行 npm install 和 npm run build
生成 site.min.css 和 site.min.js

命令参考

所有可用命令的详细说明和使用示例

template list

列出所有可用的模板

查询

语法：

dotnet run template list

示例：

$ dotnet run template list
显示所有模板的 ID、名称、版本和描述

template info

查看指定模板的详细信息，包括所有页面配置

查询

语法：

dotnet run template info

参数：

模板的唯一标识符，如 001、A1002 等

示例：

$ dotnet run template info 001
查看模板 001 的详细信息和所有页面列表

render

渲染模板页面，生成静态 HTML 文件。渲染前自动执行 npm build

核心

语法：

dotnet run render [--page ]

参数：

要渲染的模板 ID
--page 可选，指定要渲染的页面 ID。不指定则渲染所有页面

示例：

$ dotnet run render A1002
渲染模板 A1002 的所有页面
$ dotnet run render A1002 --page index
仅渲染模板 A1002 的 index 页面

preview

启动本地 Web 服务器，预览已渲染的模板页面

开发

语法：

dotnet run preview [--port ]

参数：

要预览的模板 ID
--port 可选，指定服务器端口，默认为 1688

示例：

$ dotnet run preview A1002
在默认端口 1688 预览模板 A1002
$ dotnet run preview A1002 --port 8080
在端口 8080 预览模板 A1002

fetch

从远程服务器获取模板到本地

远程

语法：

dotnet run fetch [--dir ] [--with-resources]

参数：

远程模板的名称
--dir 可选，指定保存模板的本地目录
--with-resources 可选，同时下载模板相关的资源文件

示例：

$ dotnet run fetch MyTemplate
从远程获取名为 MyTemplate 的模板
$ dotnet run fetch MyTemplate --dir ./templates/custom
获取模板并保存到指定目录
$ dotnet run fetch MyTemplate --with-resources
获取模板及其所有资源文件

publish

将本地模板发布到远程服务器

远程

语法：

dotnet run publish [--name ] [--no-resources]

参数：

要发布的本地模板 ID
--name 可选，指定发布到远程的模板名称
--no-resources 可选，不上传资源文件，仅上传模板文件

示例：

$ dotnet run publish 001
发布模板 001 到远程服务器
$ dotnet run publish 001 --name CustomTemplate
以自定义名称发布模板
$ dotnet run publish 001 --no-resources
仅发布模板文件，不包含资源

模板结构

了解模板的目录结构和配置文件格式

目录结构 

templates/
└── 001/                    # 模板目录 (模板 ID)
    ├── template.json       # 模板配置文件 (必需)
    ├── package.json        # npm 包配置
    ├── tailwind.config.js  # Tailwind 配置
    ├── pages/              # 页面目录
    │   ├── index.sbn       # 页面模板文件
    │   ├── index.data.json # 页面数据文件
    │   └── ...
    ├── components/         # 组件目录
    │   ├── layout/         # 布局组件 (header, footer, navigation)
    │   │   ├── header.sbn
    │   │   ├── footer.sbn
    │   │   ├── navigation.sbn
    │   │   ├── globalStyles.sbn
    │   │   └── globalScripts.sbn
    │   └── custom/         # 自定义组件 (业务组件)
    │       ├── hero.sbn
    │       └── cta.sbn
    ├── css/                # 样式文件
    │   ├── site.css        # 源文件
    │   └── site.min.css    # 编译后的文件
    ├── js/                 # JavaScript 文件
    │   ├── site.js         # 源文件
    │   └── site.min.js     # 编译后的文件
    └── images/             # 图片资源
        └── ...
template.json 定义模板基本信息和所有页面配置
pages/ 存放所有页面的 .sbn 模板和 .data.json 数据文件
components/layout/ 布局组件，如 header、footer、navigation、全局样式和脚本
components/custom/ 自定义业务组件，可在页面中通过 include 引入复用
css/js/images/ 静态资源文件。site.css/site.js 为源文件，npm build 编译后生成 site.min.css/site.min.js

template.json 配置 

{
  "templateName": "我的模板",
  "description": "模板描述",
  "version": "1.0.0",
  "templateType": "business-website",
  "author": "Your Name",
  "pages": [
    {
      "pageId": "index",
      "pageName": "首页",
      "description": "网站首页",
      "templateFile": "index.sbn",
      "dataFile": "index.data.json",
      "outputFile": "index.html",
      "pageType": "home"
    }
  ]
}

配置说明

每个模板必须包含 template.json 配置文件，定义模板的基本信息和所有页面配置。

Layout 组件说明

系统预定义的布局组件，名称固定，用于构建页面的基础结构

重要提示

Layout 组件的名称是系统预定义的，不可自定义。所有 layout 组件都是可选的，存在则渲染，不存在则跳过。

所有布局组件由渲染引擎自动引入，无需在模板中手动调用。系统会自动检测 components/layout/ 目录下的组件文件并插入到页面的正确位置。

所有 layout 组件文件必须放在 components/layout/ 目录下。

页面结构盒模型

<html> 完整HTML文档
<head> 不可见区域
<title>, <meta>, ...
HeadTop
可选
head标签内的上方区域
GlobalStyles
自动插入 · 可选
<link rel="stylesheet" href="css/styles.css">
<style>/* 全局样式 */</style>
💡 CSS样式链接、内联样式
HeadBottom
可选
head标签内的下方区域
</head>
<body> 浏览器可见区域
BodyTop
自动渲染 · 可选
页面顶部追踪代码、全局通知等（存在则渲染）
Header 头部区域
自动引入 · 可选
TopHeader - 顶部横幅（body中的最顶部）
Header 主要内容（body中的头部区域）
注意：HeadTop和HeadBottom位于<head>标签内，非Header组件内部
Navigation
自动引入 · 可选
主导航菜单、Logo、搜索框
页面主要内容区域
你的页面模板内容 (.sbn 文件主体)
Custom 组件使用示例：
→ 英雄区
→ 功能特性
→

准备好体验下一代建站系统了吗？

加入数千家企业的行列，让AI助力您的网站建设
免费试用，无需信用卡

立即免费开始 联系销售团队

已有超过 5,000+ 用户选择 AiCms.dev

行动召唤
💡 自定义组件来自 components/custom/ 目录
Footer 页脚
自动引入 · 可选
版权信息、友情链接、社交媒体
BodyBottom
自动渲染 · 可选
返回顶部按钮、浮动元素等（存在则渲染）
GlobalScripts
自动插入 · 可选
<script src="..."></script>
<script>...</script>
💡 JavaScript库、分析代码
</body>
</html>

不可见区域

<head> - 页面元数据
GlobalStyles

浏览器可见区域

Header / Navigation
主要内容
Footer

自动渲染

GlobalStyles
BodyTop / BodyBottom
GlobalScripts

Header (页面头部)

header • TopHeader / Header

页面头部组件。TopHeader为body中最顶部的独立区域（如顶部通知条），Header为页面主要头部区域（如Logo、菜单等）。注意：HeadTop和HeadBottom是位于head标签内的独立组件，不属于Header组件

使用方式：
渲染引擎自动引入，无需手动调用

Navigation (导航栏)

navigation • Navigation

网站的主导航菜单，通常包含网站的主要页面链接和菜单项

使用方式：
渲染引擎自动引入，无需手动调用

Footer (页脚)

footer • Footer

页面底部的页脚组件，通常包含版权信息、链接、联系方式等

使用方式：
渲染引擎自动引入，无需手动调用

HeadTop (头部上方)

headTop • HeadTop

位于 标签内部的上方区域，用于插入额外的meta标签、预加载资源等，在GlobalStyles之前加载

使用方式：
渲染引擎自动引入，无需手动调用

HeadBottom (头部下方)

headBottom • HeadBottom

位于 标签内部的下方区域，用于插入额外的脚本、样式等，在GlobalStyles之后加载

使用方式：
渲染引擎自动引入，无需手动调用

GlobalStyles (全局样式)

globalStyles • GlobalStyles

全局CSS样式引用，会被自动插入到 HTML 标签中

使用方式：
渲染引擎自动引入，无需手动调用

GlobalScripts (全局脚本)

globalScripts • GlobalScripts

全局JavaScript脚本引用，会被自动插入到 HTML 底部

使用方式：
渲染引擎自动引入，无需手动调用

BodyTop (主体顶部)

bodyTop • BodyTop

页面主体内容区域的顶部，位于 标签开始之后

使用方式：
渲染引擎自动引入，无需手动调用

BodyBottom (主体底部)

bodyBottom • BodyBottom

页面主体内容区域的底部，位于 标签结束之前

使用方式：
渲染引擎自动引入，无需手动调用

Layout 组件的渲染顺序

1
HeadTop - 在 <head> 标签内部上方（可选）
2
GlobalStyles - 在 <head> 中自动插入全局样式
3
HeadBottom - 在 <head> 标签内部下方（可选）
4
BodyTop - 主体内容顶部，<body> 开始之后（自动渲染）
5
TopHeader - body中的顶部条区域（自动引入）
6
Header - body中的页面头部区域（自动引入）
7
Navigation - 导航菜单（自动引入）
8
页面内容 - 你的页面主要内容
9
Footer - 页面页脚（自动引入）
10
BodyBottom - 主体内容底部（自动渲染）
11
GlobalScripts - 在 </body> 前自动插入全局脚本

Scriban 模板语法

使用强大的 Scriban 模板引擎构建动态页面

{{ 变量输出

使用双大括号输出变量值

基本输出
{{ title }}
输出: 显示 title 变量的值
对象属性
{{ user.name }}
输出: 访问对象的属性

~ 空白控制

使用波浪号控制输出的空白字符

去除前后空白
{{~ include 'header' ~}}
输出: 去除 include 前后的换行和空格

for 循环遍历

使用 for 循环遍历数组或列表

遍历数组
{{~ for item in items ~}}
{{ item.name }}
{{~ end ~}}
输出: 遍历 items 数组并输出每个元素
带索引
{{~ for item in items ~}} {{ for.index }}: {{ item }} {{~ end ~}}
输出: 使用 for.index 获取当前索引

if 条件判断

使用 if/else 进行条件判断

简单判断
{{~ if user.isAdmin ~}}
管理员
{{~ end ~}}
输出: 当条件为真时显示内容
if-else
{{~ if count > 0 ~}} 有数据 {{~ else ~}} 无数据 {{~ end ~}}
输出: 根据条件显示不同内容

inc 包含组件

使用 include 引入其他模板或组件

包含布局组件
{{~ include 'layout/header' ~}}
输出: 引入 header 布局组件（header、footer、navigation等）
包含自定义组件
{{~ include 'heroSection' ~}}
输出: 引入自定义业务组件（来自 components/custom/ 目录）

| 管道操作符

使用管道对值进行转换和格式化

大小写转换
{{ title | upcase }}
输出: 将文本转换为大写
数组操作
{{ items | array.size }}
输出: 获取数组长度

更多 Scriban 语法

Scriban 支持更多高级功能，包括管道操作符、内置函数、自定义函数等。

查看完整 Scriban 文档

最佳实践

遵循这些建议，创建高质量、易维护的模板

组件化开发

将可复用的界面元素封装为独立组件，提高代码复用率

  • layout组件：存放header、footer、navigation等布局组件
  • custom组件：存放业务相关的可复用组件
  • 通过 include 引入组件实现复用

数据分离

将数据与模板分离，便于内容管理和多语言支持

  • 使用 .data.json 文件存储页面数据
  • 模板中只处理展示逻辑，数据从外部传入
  • 便于实现内容的动态更新和多语言版本

命名规范

遵循统一的文件和变量命名规范，提升项目可维护性

  • 页面文件: pageId.sbn 和 pageId.data.json
  • 组件文件: 使用小驼峰命名，如 heroSection.sbn
  • 变量名使用有意义的英文单词

性能优化

优化模板结构和资源加载，提升页面渲染速度

  • 避免深层嵌套的 for 循环
  • 合理使用空白控制符 ~ 减少输出体积
  • 使用 Tailwind 等工具进行 CSS 优化

错误处理

添加适当的错误处理和默认值，提高模板健壮性

  • 检查变量是否存在: {{~ if items ~}}
  • 提供默认值: {{ title ?? '默认标题' }}
  • 使用 try-catch 处理可能的错误

版本控制

使用 Git 管理模板版本，记录每次修改

  • 为每个重要版本打 tag
  • 在 template.json 中维护版本号
  • 记录清晰的 commit message

常见问题

快速找到常见问题的解答

如何创建一个新的模板？

在 templates 目录下创建新文件夹（使用唯一 ID 作为文件夹名），然后创建 template.json 配置文件和页面文件。参考现有模板的结构进行创建。

templates/ └── myTemplate001/ ├── template.json └── pages/ ├── index.sbn └── index.data.json

渲染时出现错误怎么办？

系统会显示详细的错误信息，包括错误的组件名称、类型和具体错误内容。同时会生成包含错误信息的 HTML 文件便于调试。检查模板语法、变量名称和数据文件是否正确。

如何使用自定义组件？

系统区分两种组件：layout组件（header/footer/navigation等布局组件）和custom组件（业务组件）。自定义组件放在 components/custom/ 目录下，布局组件放在 components/layout/ 目录下。

# 引入布局组件 {{~ include 'layout/header' ~}} # 引入自定义组件 {{~ include 'heroSection' ~}}

如何配置 Tailwind CSS？

在模板目录下创建 tailwind.config.js 和 package.json 文件，配置 Tailwind。运行 render 命令时会自动执行 npm build 构建样式文件，生成 site.min.css。

渲染后的文件保存在哪里？

渲染后的 HTML 文件和静态资源会保存在对应模板目录下的 output 目录中。css 和 js 目录中的 site.min.css 和 site.min.js 会被自动复制到输出目录。

templates/001/output/ ├── index.html ├── css/ │ └── site.min.css └── js/ └── site.min.js

如何实现多语言支持？

为每种语言创建独立的 .data.json 文件（如 index.en.data.json、index.zh.data.json），然后在渲染时指定使用哪个数据文件。

相关资源

探索更多文档和工具，充分利用 TemplateMaker

Scriban 官方文档

查看完整的 Scriban 模板引擎语法和 API 文档

查看详情

Tailwind CSS 文档

学习如何使用 Tailwind CSS 构建现代化的响应式界面

查看详情

示例模板库

浏览和下载预制的模板示例，快速开始您的项目

查看详情
查看示例模板 获取技术支持