Zola 结构化数据完全指南：4 段 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 博客，别人的文章在搜索结果里是带摘要、作者、日期的富卡片，你的却只有一行光秃秃的标题。差距不在内容质量，而在结构化数据：往模板里嵌入几段 Schema.org 的 JSON-LD 标记，搜索引擎就能读懂你的页面结构，把点击率换回来。这篇教程给你 4 个可直接复用的 Tera 模板，从最小实现讲到验证通过。
🧩 一分钟看懂结构化数据
搜索结果页面其实是在"翻译"你的网页。搜索引擎抓到的是一大坨 HTML，它需要自己从里面猜：哪个是标题？哪天发布的？谁写的？猜错了，摘要就只能是一行链接。结构化数据就是替它把这道猜题做了——你在 HTML 里附上一段机器可读的字段说明，它照着渲染卡片即可。
最常用的载体是JSON-LD：一段 JSON，包在<script type="application/ld+json">标签里，塞进页面任意位置，不影响渲染。字段名则来自Schema.org这套社区维护的词汇表：Article（文章）、Product（商品）、WebSite（站点）……每个类型规定了哪些字段是必填的。
打个比方：结构化数据就是你替搜索引擎预填好的一张登记表。
- 搜索引擎：拿到表直接展示富结果（摘要、日期、图片、评分）
- 用户：看到更多信息，更愿意点击
- 你：多写几行模板，静态产物里自动带上标记
Zola 的主题生态里已经有主题内置了这套东西，例如 Academic Paper 主题在元数据中实现了 JSON-LD，效果类似 Jekyll SEO Tag：
⚡ 最小可行方案（MVP）：一个 Article 模板跑通全文
目标很明确：给每一篇带日期的文章挂上Article标记，让搜索结果能展示标题、日期和作者。全程只动三个文件。
第 1 步：新建一个独立的 Schema 模板。在templates下建 schema 目录，放入article.html，内容如下：
<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "Article", "headline": "{{ page.title }}", "datePublished": "{{ page.date | date(format='%Y-%m-%d') }}", "dateModified": "{{ page.updated | default(value=page.date) | date(format='%Y-%m-%d') }}", "description": "{{ page.description | default(value='') }}", "inLanguage": "{{ lang }}", "author": { "@type": "Person", "name": "{{ config.extra.author }}" }, "publisher": { "@type": "Organization", "name": "{{ config.title }}", "logo": { "@type": "ImageObject", "url": "{{ get_url(path=config.extra.logo) }}" } }, "mainEntityOfPage": "{{ current_url }}" } </script>关键字段就五个：headline和datePublished是 Google 对 Article 的硬性要求；author/publisher让卡片能展示署名；mainEntityOfPage用 Zola 全局变量{{ current_url }}锁定当前页地址，搜索引擎靠它判断这条数据属于哪个 URL。
第 2 步：在 文章模板 里按条件引入。只有带date的页面才是文章，其他页面不该输出 Article 标记：
<head> <meta charset="utf-8"> <title>{{ page.title }} | {{ config.title }}</title> {# 只给带日期的文章页输出 Article 标记 #} {% if page.date %} {% include "schema/article.html" %} {% endif %} </head>{% if page.date %}这一句是关键：front matter 里写了date的页面才会注入标记，首页、关于页自动跳过，不会输出半成品 JSON。
第 3 步：把站点级信息放进 配置文件。模板里引用的config.extra.author和config.extra.logo需要真实来源：
title = "我的技术博客" description = "记录工程实践与踩坑笔记" [extra] author = "张三" logo = "logo.png"logo 放在static/目录，get_url会自动补上正确的访问路径。跑一次zola build，打开任意文章页源码搜ld+json，能看到完整 JSON，MVP 就通了。
🔀 按场景扩展标记类型
文章之外，不同内容类型对应不同的 Schema 类型。下面两个片段都是"关键骨架"，按你站点实际情况补全即可。
产品页：Product 类型
卖东西的页面用Product+Offer，让搜索结果有机会展示价格。价格不写死在模板里，而是从每篇产品页的 front matter 读出来，page.extra.price = 99就能生效：
<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "Product", "name": "{{ page.title }}", "description": "{{ page.description }}", "image": "{{ get_url(path=page.assets[0]) }}", "offers": { "@type": "Offer", "price": "{{ page.extra.price }}", "priceCurrency": "{{ page.extra.currency | default(value='CNY') }}", "availability": "https://schema.org/InStock" } } </script>offers是触发价格展示的开关；image直接取page.assets里的第一张同目录素材，省得维护第二份字段。
首页：WebSite 类型 + 站内搜索框
WebSite标记挂在首页模板上。重点不是站点名称本身，而是potentialAction里的SearchAction——相当于给搜索引擎留了一张搜索入口的名片，配了它的站点在结果里可能直接带一个搜索框：
<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "WebSite", "name": "{{ config.title }}", "url": "{{ config.base_url }}", "potentialAction": { "@type": "SearchAction", "target": "{{ config.base_url }}/search?q={search_term_string}", "query-input": "required name=search_term_string" } } </script>target里的{search_term_string}是固定占位符，/search要替换成你站点的真实搜索页路径；Zola 的build_search_index开启后前端搜索就能接上。
用主题？先查文档
如果你用的主题已经内置了结构化数据，别重复造轮子。比如 AdiDoks 主题在[extra.schema]配置段里直接暴露了 JSON-LD 开关，改配置即可：
🔍 验证与避坑：3 个最常见的 JSON-LD 错误
本地自查：zola serve后访问http://localhost:1111，浏览器开发者工具里按Ctrl+F搜ld+json，肉眼确认 JSON 没被模板变量打烂——尤其是值为空时会不会留下"headline": ,这种残缺语法。
在线验证：把页面 URL（或直接粘贴 HTML 源码）提交给 Google 的结构化数据测试工具，它会按类型列出必填字段缺失、类型不符等问题，比自己猜快得多。
三个高频错误及一句话解法：
- JSON 语法残缺：Tera 输出空值导致逗号悬空——给可选字段都套上
| default(value='')，验证工具会立刻指出错行 - 日期格式不合法：
2024/1/5这种裸格式搜索引擎不认——统一走| date(format='%Y-%m-%d')输出 ISO 格式 mainEntityOfPage指向错误页：多语言站点下复制了默认语言的 URL——确认用的current_url是当前语言的地址，而不是硬编码的config.base_url
⚙️ 效率技巧
- ✅控制 JSON-LD 体积：只输出该类型必填和常用字段，单块控制在 2KB 内，别把整篇正文塞进
description - ✅利用 Zola 的
reading_time：page.reading_time变量可直接映射为预估阅读时长相关字段，不用自己数单词 - ✅条件隔离：每种类型单独一个
schema/*.html文件，用{% if %}按page.date、section 名分流，避免首页和文章页互相污染 - ✅缓存放心配：JSON-LD 是构建期生成的静态 HTML，CDN 缓存策略与普通页面一致即可，无需特殊处理
- ✅规范会演进：Schema.org 持续修订属性语义，每年用测试工具批量复查一遍已部署页面，比一次写对更现实
下一步
今天就建好article.html并挂进page.html；本周用测试工具跑一遍验证；之后按站点内容逐个补 Product、WebSite 标记。三步走完，你的 Zola 站点就拿到了富结果的入场券。
【免费下载链接】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），仅供参考
