Gitl.cn云建站 SaaS🧩 公共标签（通用辅助标签）
最后更新：2026-10-02
📊 公共标签能力总览
以下能力在所有前台模板均可使用，按使用频率从高到低排列。
| 能力 | 用法 | 说明 |
|---|---|---|
| 模板局部复用 | {{template "header.html" .}} | 用 Go 命名模板复用公共片段（见「模板嵌套」） |
| 时间格式化 | {{.CreatedAt | formatDate "Y-m-d"}} | 支持 Y-m-d / Y/m/d / Y年m月d日（仅日期） |
| 内容截取 | {{.Summary | truncate 50}} | 按字符（rune）截取，中文友好，超出补 ... |
| 原样输出 HTML | {{.Content | safeHTML}} | 富文本字段默认转义，标记为安全 HTML 后原样渲染 |
| 数值运算 | {{add .CurrentPage 1}} | 整数相加，用于序号、偏移 |
| JSON/多值拆分 | {{range splitJSON .Images}} | 多图、tags 等多值字段解析为可遍历切片 |
| 自定义片段 | {{.FooterNotice}} | 后台「模板内容片段」以同名全局变量注入 |
| 面包屑 | .ParentCategory / .CategoryName | 栏目页自带父级与当前栏目数据 |
| 当前网址 | {{.SiteDomain}} / {{.URL}} | 站点域名 / 内容详情链接（{{.URL}} 的形态由后台「配置参数 → URL规则」决定，详见下方「由后台配置参数控制的输出」） |
| 站点地图与 SEO 文件 | /sitemap.xml、/llms.txt 等 | 运行时自动生成，大数据自动分片 |
| 图片显示尺寸 | CSS 控制 | 原图不变，显示尺寸由 CSS 决定 |
🔧 公共模板函数
以下函数任何前台模板均可调用，语法为 {{管道 | 函数 参数}} 或 {{函数 参数}}。
🕒 formatDate — 时间格式化
| format 取值 | 输出示例 | 说明 |
|---|---|---|
Y-m-d | 2026-08-19 | 默认，横线分隔 |
Y/m/d | 2026/08/19 | 斜杠分隔 |
Y年m月d日 | 2026年08月19日 | 中文格式 |
<time>{{.CreatedAt | formatDate "Y-m-d"}}</time>
<!-- 列表条目 → -->
{{range .Posts}}
<span>{{.CreatedAt | formatDate "Y年m月d日"}}</span>
{{end}}⚠️ 仅处理日期部分；字段为空 / 非字符串 / 长度不足时返回空（nil 安全，不会 500）。若字符串长度足够但不匹配上述三种格式，则原样返回该字符串（同样不会 500）。需要「时分秒」请用 .CreatedAt 原样输出。
✂️ truncate — 内容截取（中文友好）
按字符数（rune）截取，避免中英文长度不一；超出在末尾补 ...。
{{.Summary | truncate 50}}
<!-- 产品简介截取 30 字 -->
<p>{{.Product.Description | truncate 30}}</p>🧱 safeHTML — 原样输出 HTML
字段里若含 HTML（如后台富文本），默认会被转义；用 safeHTML 可原样渲染（标记为安全 HTML 后输出）。
<div class="rich">{{.Content | safeHTML}}</div>📐 add — 数值相加
整数相加，可用于序号、偏移等。
<span>第 {{add .CurrentPage 1}} 页</span>🔣 splitJSON — JSON/多值数组转列表
把数据库里的 JSON 数组字符串（如多图 .Images）解析为可 range 的切片；非 JSON 时按行拆分。
{{range splitJSON .Images}}
<img src="{{.}}" alt="">
{{end}}🧩 模板嵌套（局部复用）
Gitl.cn CMS 使用 Go 命名模板做公共片段复用：把公共片段写成 {{define "名字"}}…{{end}}，在需要处用 {{template "名字" .}} 引入，. 为传入的数据根。
<!-- header.html 顶部 -->
{{template "header.html" .}}
<!-- 页脚 -->
{{template "footer.html" .}}
<!-- 内置图标片段（default 模板已定义）-->
<div class="icon">{{template "icon-arrow-right"}}</div>提示：templates/<tpl_path>/ 下的 header.html、footer.html 等即为可被任意页面引入的公共局部。
🌐 全局变量（任意页面可直接读）
除各章节字段外，以下变量在前台模板可用。注意：CanonicalURL / PageJSONLD / BreadcrumbJSONLD 仅在详情页 / 栏目页注入（首页、列表页、搜索页为空），其余为全站可用。
| 变量 | 含义 |
|---|---|
{{.SiteDomain}} | 站点域名（含协议，如 https://www.gitl.cn） |
{{.SiteTitle}} / {{.SiteSubtitle}} | 站点标题 / 副标题 |
{{.SitePrefix}} | 多语言路径前缀（默认站为空，英文站为 /en） |
{{.SiteHomeURL}} / {{.SiteContactURL}} / {{.SiteAboutURL}} | 首页 / 联系我们 / 关于我们 链接 |
{{.CompanyName}} / {{.CompanyPhone}} / {{.CompanyEmail}} … | 公司信息（详见「公司信息」章节） |
{{.Navigations}} / {{.TopCategories}} / {{.ProductCategories}} | 导航菜单 / 顶级栏目 / 产品栏目 |
{{.CurrentYear}} | 当前年份（页脚版权常用） |
{{.LangSwitcher}} | 多语言切换数据（多站点时） |
{{.CanonicalURL}} | 当前页绝对规范地址（详情页 / 栏目页可用；首页、列表页为空） |
{{.OGLocale}} | Open Graph 语言区域（如 zh_CN / en_US / ja_JP），用于 og:locale NEW |
{{.OGImage}} | Open Graph 分享图（绝对 URL，系统自动补全域名；无正文图时用站点默认图）NEW |
{{.PageJSONLD}} | 详情页结构化数据（Product / Article，已是 safeHTML；仅详情页有）NEW |
{{.BreadcrumbJSONLD}} | 面包屑结构化数据（BreadcrumbList，已是 safeHTML；仅栏目页 / 详情页有）NEW |
<a href="{{.SiteDomain}}">{{.SiteTitle}}</a>
<p>© {{.CurrentYear}} {{.CompanyName}}</p>
<a href="{{.SiteContactURL}}">联系我们</a>📈 SEO 头部标签（canonical / hreflang / OG / JSON-LD）
以下为生产模板实际使用的 SEO 头部写法，可直接套用到自己的 header.html / footer.html。所有变量均由 Go 后台自动注入，无需手写 URL。
🔗 <head> 中的 canonical / hreflang / OG
<!-- canonical：绝对地址，自动带站点前缀（/en 等） -->
<link rel="canonical" href="{{.CanonicalURL}}">
<!-- hreflang：多语言互链（仅多站点时非空） -->
{{range .HrefLangs}}<link rel="alternate" hreflang="{{.Lang}}" href="{{.Href}}">
{{end}}
<!-- Open Graph -->
<meta property="og:type" content="website">
<meta property="og:url" content="{{.CanonicalURL}}">
<meta property="og:locale" content="{{.OGLocale}}">
<meta property="og:image" content="{{.OGImage}}">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">说明：{{.CanonicalURL}} 已是绝对地址且自动包含多语言前缀；{{.OGLocale}} 输出 zh_CN / en_US 等；{{.OGImage}} 已是绝对 URL（后台「站点 OG 图」或默认占位图），不要再拼域名。
🧱 详情页结构化数据（footer 的 </body> 之前输出）
<!-- 放在 footer.html 的 </body> 之前 -->
{{if .PageJSONLD}}{{.PageJSONLD}}{{end}}
{{if .BreadcrumbJSONLD}}{{.BreadcrumbJSONLD}}{{end}}{{.PageJSONLD}} 在文章 / 产品 / 案例 / 单页详情页自动生成 Product 或 Article 类型 JSON-LD；{{.BreadcrumbJSONLD}} 生成 BreadcrumbList。两者已是 safeHTML，直接输出即可，不要再加 safeHTML，也不要手动包 <script>（系统已含 <script type="application/ld+json"> 包裹）。
🍞 面包屑
栏目页自带 .ParentCategory（父级，可能为 nil）与 .CategoryName（当前），自行拼接即可。
{{if .ParentCategory}}<a href="{{.ParentCategory.Link}}">{{.ParentCategory.Name}}</a> / {{end}}{{.CategoryName}}🏷️ 自定义片段标签（后台「模板内容片段」）
在后台「模板内容片段」中定义的片段，会以同名全局变量注入所有前台模板，直接 {{.片段名}} 输出（已是 safeHTML）。
<!-- 后台定义了名为 "FooterNotice" 的片段 -->
<div class="notice">{{.FooterNotice}}</div>🗺️ 站点地图与 SEO 文件
Gitl.cn CMS 在运行时动态生成以下地址，直接访问即实时地图（大数据站点会自动拆分为多个分片）：
| 地址 | 说明 |
|---|---|
/sitemap.xml | 站点地图索引（自动指向各分片 /sitemap-part-N.xml） |
/robots.txt | 爬虫协议，自动包含 sitemap 地址 |
/llms.txt · /.well-known/llms.txt | 给 AI 看的站点说明 |
/llms-full.txt · /.well-known/llms-full.txt | 全量正文（大数据自动分片为 llms-full-N.txt） |
⚙️ 由后台「配置参数」控制的输出（URL规则 / 标题样式）
后台「配置参数」里的 URL规则 与 标题样式 两个 tab 会直接改写前台渲染结果。模板开发者无需写任何分支逻辑——系统已经把正确的值注入到 {{.URL}} 与 {{.PageTitle}}，直接用即可；这里列出规则只是让你知道「为什么链接长这样」。
🔗 URL规则（影响 {{.URL}}）
| 设置项 | 可选值 | 对前台的影响 |
|---|---|---|
url_detail_suffix 详情页后缀 | 空（默认）/ .html / .htm | 详情链接是否带后缀，如 /news/13 vs /news/13.html |
url_detail_name 详情页命名 | id（默认）/ slug（别名） | 链接用编号还是别名，如 /news/13 vs /news/my-post（jobs 表无别名，固定用 ID；自定义模型固定 /m/<code>/<id>） |
url_page_style 列表分页形式 | path（默认）/ query | 分页链接用路径式 /news/index2.html 还是查询式 /news?page=2（路径式是静态站必需） |
✅ 模板约定：列表 / 首页 / 栏目里每条内容的 {{.URL}} 已按上述规则拼好（含站点前缀与后缀），一律原样用 {{.URL}}，不要手写 /news/{{.ID}}。改了 URL规则后，动态页即时生效，已生成的静态站需重新生成才会落地为新的链接文件。
🏷️ 标题样式（影响 {{.PageTitle}}）
| 设置项 | 可选值 | 对前台的影响 |
|---|---|---|
seo_title_sep 分隔符 | 默认 - （可改 _ / | / · 等） | 站点名与内容标题之间的连接符 |
seo_title_order 顺序 | title_first（默认）/ site_first / title_only | 详情页 <title> 是「内容 - 站点」还是「站点 - 内容」或仅内容 |
seo_home_title 首页标题模板 | 默认 {site} - {subtitle} | 首页 <title>，可用 {site} / {subtitle} 占位 |
seo_desc_len 自动摘要长度 | 默认 160（20–500） | 未手动填摘要时，{{.Summary}} / 列表 summary 的默认截取字符数 |
✅ 模板约定：详情页 / 首页的 <title> 统一用 {{.PageTitle}}（系统按标题样式拼好），不要再手写 {{.SiteTitle}} - {{.News.Title}}；SEO 标题若想用内容级覆盖，可通过 {{.News.SEOTitle}} 等字段自行判断。