Zola 结构化数据从 0 到 1：给页面注入 JSON-LD 标记-育师

Zola 结构化数据从 0 到 1：给页面注入 JSON-LD 标记

🔥【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zola

搜索结果里，同主题的两篇文章摆在一起：一条带作者、发布日期和缩略图，另一条只有一行标题。点击率的差距从这里开始。Zola 结构化数据这块没有内置功能，但它的 Tera 模板能力足够你在<head>里输出一段 JSON-LD 标记，让搜索引擎识别出页面是文章、产品还是活动。

读完这一篇，你能做到：

文章页输出合法的 Article 类型 JSON-LD，字段全部取自页面变量
首页、产品页、事件页按 section 自动切换标记类型
用zola serve在本地验证输出，上线前把常见报错清零

30 秒速览

目标	改哪里	验证方式
文章页输出 Article 标记	`page.html`的`<head>`	构建后检查输出 JSON 是否合法
首页输出 WebSite 标记	`index.html`的`<head>`	Rich Results Test 粘贴线上 URL
多类型自动切换	拆成 partials，主模板 include	`zola serve`逐页检查

一句话概括：不动 Zola 配置，只改模板，就能让每类页面带上对应的 Schema.org 实体。

原理极简说明

Schema.org 是一套实体词汇表，JSON-LD 是它的嵌入载体。把一段 JSON 放进<script type="application/ld+json">，爬虫解析后即可判断页面"是什么"。常用类型：

Article：博客文章、新闻，核心是标题、作者、日期
WebSite：站点首页，可挂站内搜索动作
Product：商品页，核心是名称、图片与报价
Event：活动页，必须有开始/结束时间与地点
Organization：组织或机构介绍页，含 logo 与联系方式

从 0 到 1：第一个 JSON-LD 落地

本节只做文章详情页，其余场景下一节讲切换思路。

找到文章实际渲染的模板。默认是templates/page.html，可参考 test_site/templates/；若某 section 有覆盖模板，则改对应文件。
在<head>内、</title>之后插入脚本标签。位置不影响解析，放头部方便调试。
构建后查看public目录下的 HTML，确认 JSON 可被解析。

<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "Article", "headline": "{{ page.title }}", "description": "{{ page.description | default(value=config.description) }}", "datePublished": "{{ page.date | date(format="%Y-%m-%d") }}", "author": { "@type": "Person", "name": "{{ page.extra.author | default(value=config.extra.author) }}" }, "publisher": { "@type": "Organization", "name": "{{ config.title }}", "logo": "{{ get_url(path=config.extra.logo) }}" }, "mainEntityOfPage": "{{ current_url }}" } </script>

每个变量的来源，逐一说明：

page.title：front matter 的title，缺失时回退到文件名
page.description：front matter 的description；default过滤器在缺省值取自config.description
page.date：文章日期，取 front matter 的date或带日期前缀的文件名
page.extra.author/config.extra.author：分别来自 front matter 的extra段与config.toml的[extra]
current_url：Zola 渲染时注入的当前页绝对地址
get_url()：把config.extra.logo解析为基于base_url的绝对路径，实现见 files.rs

全部可用变量的清单，见 docs/content/documentation/templates/overview.md。

多场景适配

切换的本质只有一点：@type不同，必填字段不同。下面只列差异字段。

首页 WebSite 类型差异字段

@type改为WebSite，去掉author与datePublished，保留：

name：取config.title
url：取config.base_url
potentialAction.target：站内搜索地址，配合query-input声明必填参数

产品页 Product 类型差异字段

@type改为Product，保留publisher，新增：

name：产品名，放page.title
image：产品主图，走get_url
offers：price与priceCurrency两项，建议放 front matter 的extra

事件页 Event 类型差异字段

@type改为Event，新增：

startDate/endDate：RFC3339 字符串，放 front matter 的extra
location：嵌套Place对象，含名称与地址
image：活动主图

按 section 自动切换 include

把三段标记拆到templates/partials/下，主模板里按 section 分发：

{% if page.section == "products" %} {% include "partials/product.html" %} {% elif page.section == "events" %} {% include "partials/event.html" %} {% else %} {% include "partials/article.html" %} {% endif %}

如果你的主题上下文没有page.section，可在 front matter 加一个schema字段，改读page.extra.schema判断。

避坑与验证

坑 1：assets 循环导致 JSON 非法症状：image字段出现空数组或末尾多逗号，解析器直接报错。原因：用 for 循环手动拼逗号，page.assets为空时不产生任何元素。修复：过滤出图片后缀后用join一次性输出，或先判空再决定是否保留该字段。

坑 2：logo 路径 404症状：Rich Results Test 报 logo 无法加载，富媒体降级为纯文本。原因：get_url指向的文件既不在static也不在主题目录里。修复：构建后确认输出目录中该文件真实存在，路径写相对base_url的形式。

坑 3：日期格式不匹配症状：datePublished输出空值，或构建直接失败。原因：front matter 日期写成2026/09/09这类非标准形式。修复：统一用2026-09-09写法，带日期前缀的文件名 Zola 会自动解析。

本地验证两步走。第一步，起开发服务器看源码：

zola serve

访问本地地址（默认http://localhost:1111）下的文章页，查看源代码确认脚本标签完整、JSON 合法。第二步，部署后打开 Google 的 Rich Results Test，粘贴线上 URL，确认结果里没有 error 项。

延伸与自检清单

几条值得坚持的做法：

只标记与页面强相关的实体，文章页不要挂 Product
logo 用 PNG 或 JPG 的绝对 URL；svg 尺寸不可靠，多数解析器会跳过
keywords最多放 3 个真实主题词，别堆同义词
headline超过 110 字符时在模板里截断
多语言站点每个语言版本输出自己的标记与 URL

上线前逐项核对：

文章页<head>内存在application/ld+json脚本
zola build后输出的 JSON 可通过在线解析器校验
headline、datePublished、author三个字段非空
publisher.logo指向状态码 200 的绝对 URL
首页已输出 WebSite 类型标记
Rich Results Test 无 error 项

🔥【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zola

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考