Specivo 文档

参考：模板标签

使用 {% load seo_suite %} 加载标签库。

{% seo_head %}

一次调用即可渲染完整的 <head> 元数据块。

{% load seo_suite %}
<head>
  {% seo_head %}
</head>

内部依次包含以下所有细分模板片段：

  1. seo_suite/_title.html：<title>
  2. seo_suite/_meta.html：description、keywords、robots
  3. seo_suite/_canonical.html：canonical 链接
  4. seo_suite/_hreflang.html：hreflang 备选链接
  5. seo_suite/_opengraph.html：og:* meta 标签
  6. seo_suite/_twitter.html：twitter:* meta 标签
  7. seo_suite/_jsonld.html：JSON-LD 脚本块
  8. seo_suite/_extra_head.html：来自渲染器和信号的 HTML 片段

如果模板上下文中没有 seo 变量（既没有上下文处理器，也没有使用 mixin），{% seo_head %} 会从 request 延迟解析元数据。如果上下文中连 request 也没有，则不输出任何内容。

细分标签

想把各个块放到特定位置，或者自定义 <head> 结构时，可以使用这些标签。

{% seo_title %}

{% seo_title %}

渲染 <title>{{ seo.full_title }}</title>。full_title 为空时不输出任何内容。

full_title 由 title 和 title_suffix 拼接而成。例如 title = "My Page"、title_suffix = " | My Site" 时输出：

<title>My Page | My Site</title>

{% seo_meta %}

{% seo_meta %}

渲染已设置的 meta description、keywords 和 robots 标签：

<meta name="description" content="...">
<meta name="keywords" content="...">
<meta name="robots" content="index,follow">

{% seo_canonical %}

{% seo_canonical %}

已设置 canonical 链接时渲染该链接：

<link rel="canonical" href="https://example.com/articles/my-article/">

{% seo_hreflang %}

{% seo_hreflang %}

为 seo.hreflang 中的每一项渲染一个 <link rel="alternate" hreflang>：

<link rel="alternate" hreflang="en" href="https://example.com/en/articles/my-article/">
<link rel="alternate" hreflang="fr" href="https://example.com/fr/articles/my-article/">
<link rel="alternate" hreflang="x-default" href="https://example.com/en/articles/my-article/">

seo.hreflang 为空列表时不输出任何内容。

{% seo_opengraph %}

{% seo_opengraph %}

为 seo.og 中每个值非空的条目渲染一个 <meta property="og:key" content="value">：

<meta property="og:type" content="article">
<meta property="og:title" content="My Page">
<meta property="og:description" content="...">
<meta property="og:url" content="https://example.com/articles/my-article/">
<meta property="og:image" content="https://example.com/media/cover.jpg">

{% seo_twitter %}

{% seo_twitter %}

为 seo.twitter 中每个值非空的条目渲染一个 <meta name="twitter:key" content="value">：

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="My Page">
<meta name="twitter:description" content="...">
<meta name="twitter:image" content="https://example.com/media/cover.jpg">

{% seo_jsonld %}

{% seo_jsonld %}

为 seo.jsonld 中的每一项渲染一个 <script type="application/ld+json"> 块：

<script type="application/ld+json">{"@context":"https://schema.org","@type":"Article",...}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList",...}</script>

seo.jsonld 为空列表时不输出任何内容。

{% seo_extra_head %}

{% seo_extra_head %}

渲染来自以下来源的额外 HTML 片段：

  • SeoMetadata 的 extra_head 字段（由 provider 或信号设置）。
  • 已注册的渲染器（renderer_registry）。
  • seo_head_rendering 信号的接收函数。

模板上下文变量

所有标签都从模板上下文中的 seo 变量读取数据。它是一个 FinalizedSeoMetadata 实例，由以下途径设置：

  1. SeoViewMixin.get_context_data()：使用该 mixin 的视图的主要途径。
  2. seo_suite.context.seo 上下文处理器：其他所有视图的延迟回退途径。

你可以在任何模板中直接读取它：

{{ seo.title }}
{{ seo.full_title }}
{{ seo.h1 }}
{{ seo.meta_description }}
{{ seo.canonical_url }}
{{ seo.robots }}
{{ seo.og.site_name }}
{{ seo.twitter.card }}

完整字段列表见 SeoMetadata 属性。