Zola 加结构化数据：从一篇 Article 到全站 JSON-LD 的实战流程-迪斯科星球

Zola 加结构化数据：从一篇 Article 到全站 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

搜自己的文章时，Google 结果里只有标题和一段截断摘要，竞品那条却带着作者和日期。差的正是页面源码里那份「结构化数据」。Zola 默认不会输出这些标记，但在模板层补上 Zola JSON-LD，搜索引擎就能读懂你的页面。

为什么静态站也需要结构化数据

结构化数据是写给搜索引擎读、不渲染给访客看的页面元信息，用的是 Google、Bing 等几家共同认可的词汇表 Schema.org。页面带上 Article 类型的标记，搜索结果里就能显示作者与发布日期；带上 Product 类型，则能显示价格。这种带附加信息的展示叫「富结果」，直接影响搜索结果的点击率。

要清楚一点：Zola 的构建流程里没有输出这些标记的模块，它的职责是把 Markdown 变成 HTML。所以 JSON-LD（结构化数据的一种 JSON 写法）得由你写进模板。好处是 Zola 的产物是纯静态文件，模板里写了什么，最终 HTML 里就是什么，搜索引擎抓到的内容完全确定，没有运行时差异。

📦 准备：确认你的模板与变量

动手前先确认下面五项，每项花不了几分钟：

三个默认模板：index.html管首页，section.html管章节列表页，page.html管内容页；用了主题就看主题里同名模板，没有的话参考 test_site/templates/ 里的示例。
本文会用到的页面变量：page.title、page.description、page.date、page.updated、page.taxonomies、page.assets、page.extra，以及全局的current_url和config，完整字段清单见 docs/content/documentation/templates/pages-sections.md。
Front matter：Markdown 文件顶部+++块里的元数据头部，作者这类字段写在这里，通过page.extra读取。
本地预览：站点根目录执行zola serve，构建结果在http://localhost:1111，随时能查看页面源码。
确认 base_url：检查config.toml里的base_url指向真实域名，把本地路径转成完整网址的 get_url 函数依赖它。

📝 最小实现：一篇博客文章的 Article 标记

拿一篇博客文章打样，三步就能输出一段完整的 Article 结构化数据，改动全部在你自己站点的templates/目录里。

第 1 步：在 page.html 的 head 里放 JSON-LD 脚本标签

JSON-LD 是装在<script type="application/ld+json">标签里的一个 JSON 块，Tera（Zola 的模板引擎，语法接近 Jinja2）会在构建时把{{ }}变量替换成真实值。把这段放进 page.html 的<head>标签内，主题是现成模板的话，先把同名模板复制到自己目录再改：

<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") }}", "dateModified": "{{ page.updated | default(value=page.date) | date(format="%Y-%m-%d") }}", "author": {"@type": "Person", "name": "{{ page.extra.author | default(value=config.extra.author) }}"}, "mainEntityOfPage": {"@type": "WebPage", "@id": "{{ current_url }}"} } </script>

作者这里先取 front matter 的page.extra.author，取不到就回落到config.extra.author：在 config.toml 的extra里放一个默认作者，全站文章就都有了。

第 2 步：补上图片、发布者和关键词字段

往同一个 script 标签里的 JSON 对象中追加这三行，位置紧挨description字段即可：

"image": "{{ get_url(path=page.assets | first) }}", "publisher": {"@type": "Organization", "name": "{{ config.title }}"}, "keywords": "{{ page.taxonomies.tags | join(sep=", ") }}"

page.assets是和 Markdown 放在同目录的图片文件列表，get_url把首个路径转成带域名的完整网址；如果你的标签分类名不叫tags，就把字段名改成对应的那个；没有配图的页面可以把image换成固定 logo 路径。

第 3 步：核对日期格式与绝对 URL

两个最容易出错的位置不需要新语法。日期字段里的date(format="%Y-%m-%d")是 Tera 内置的 date 过滤器，把 front matter 里的page.date格式化成标准日期字符串；mainEntityOfPage里的current_url是 Zola 自动提供的当前页完整网址，不要手写相对路径替代它。对某个变量拿不准时，可以临时在模板里放一句{{ __tera_context }}打印完整上下文，确认后再删掉。

按页面类型切换：首页与产品页

Article 结构只适合内容页，其他页面要换@type，用 Tera 的 if 语句控制触发条件，完整文档只维护一份，其余靠差异字段拼装。

首页：在 index.html 里写 WebSite 标记

index.html只作用于首页，直接放即可，不需要判断。完整结构就是@context加上下面四行，放进 index.html 的<head>标签：

"@type": "WebSite", "name": "{{ config.title }}", "url": "{{ config.base_url }}", "potentialAction": {"@type": "SearchAction", "target": "{{ config.base_url }}/search?q={search_term_string}"}

最后一行 SearchAction 描述站内搜索入口，如果你的站点没有搜索页，删掉它。

产品页：按 components 切到 Product 类型

产品页如果都放在products/目录下，可以用page.components（页面从 content 根到文件的路径分段）触发：用{% if "products" in page.components %}包住下面的片段，只有产品页会输出。完整结构同样是@context加上这四行：

"@type": "Product", "name": "{{ page.title }}", "image": "{{ get_url(path=page.assets | first) }}", "offers": {"@type": "Offer", "price": "{{ page.extra.price }}", "priceCurrency": "CNY"}

价格与货币写在产品页 front matter 的extra里，数据来自内容文件而不是模板写死，改文章时顺手更新即可。

抽成可复用片段并接入

页面类型一多，主模板里的 if 条件会失控。把每类标记移进独立模板片段，再用 Tera 的 include 语法（把一个文件的内容原样嵌入当前模板）拉进来，目录这样组织：

templates/ └── schema/ ├── article.html ├── website.html └── product.html

在 page.html 的 head 里，原输出标记的位置改成：

{% if "products" in page.components %} {% include "schema/product.html" %} {% endif %}

schema/article.html的内容就是第 4 节第 1 步的完整块原样搬过去（），首页的 WebSite 片段放进schema/website.html后在 index.html 里 include 即可，主模板从此只留三行条件。

🔍 验证与一个最常见的坑

验证走两条路。把页面 URL 提交到 Google 官方的富结果测试工具 https://search.google.com/test/rich-results ，它会列出识别到的类型和出错的字段；本地开发则执行zola serve，浏览器打开文章页后查看源码并搜索ld+json，确认 JSON 完整、值都对。

最高频的坑是图片 URL 输出了相对路径。如果image字段直接写了page.assets | first而没经过 get_url，输出会是/2018/foo.png这样的站内路径，搜索引擎拉不到它，图片标记等于缺失。定位分两步：先查看源码搜ld+json，看 image 字段的网址是否以/开头；是的话，把该字段包上get_url(path=...)重新构建再查一次。

下一步

模板变量与内置函数（get_url、date、default 等）的完整清单，见官方模板文档 docs/content/documentation/templates/overview.md；个别过滤器的参数行为以官方文档为准。
结构化数据的完整类型与字段规范，参考 Google 的结构化数据文档 https://developers.google.com/search/docs/structured-data/intro-structured-data 。
遇到拿不准的写法，可以在 Zola 社区搜「Zola 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

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

企业官网建设流程全解析