文档

Writer's Toolkit

写作

Front matter

开源

最后评审时间：2024 年 9 月 3 日

Front matter

Grafana 文档的源文件使用 Front matter 来组织内容、对项目目录进行排序，并帮助用户在搜索引擎或社交媒体（如 Twitter）中搜索或查看内容时识别有用的页面。

所有 Front matter 都使用 YAML。除非 Front matter 字段文档说明支持 Markdown，不要在该字段中包含任何特殊的 Markdown 格式，例如斜体。

以下代码片段展示了 Markdown 文件开头的 Front matter 示例

---
description: Learn more about Grafana Mimir's microservices-based architecture.
labels:
  products:
    - oss
keywords:
  - Mimir
  - microservices
  - architecture
menuTitle: Architecture
title: Grafana Mimir architecture
weight: 100
---

参考

以下标题描述了每个 Front matter 字段的功能并提供了使用指南。

别名 (Aliases)

当页面更改或移动时，使用 aliases 创建从旧 URL 到新 URL 的重定向。

当您重命名或移动文件时，必须创建一个引用旧 URL 路径的别名，以创建从旧 URL 到新 URL 的重定向。在某些情况下，例如您删除内容或将文件拆分为多个主题时，可能无法为移动的内容创建别名。

注意
仅在 URL 中的旧文件名可能对读者造成混淆的情况下重命名文件。

示例

以下 Markdown Front matter 代码片段定义了一个别名 /original-url/。您必须将其与任何现有 Front matter 合并。

---
aliases:
  - /original-url/
---

指南

使用别名的正确方法取决于项目是否支持版本控制。

版本控制项目

别名必须是相对路径，以避免将最新内容重定向到旧版本。

如果旧文档中有一个页面包含版本“latest”的别名，并且该别名引用的页面在实际的最新文档中不存在，那么 Hugo 会在该别名引用的页面上创建重定向。

该重定向会将用户从最新文档重定向到旧文档。

别名应包含 YAML 注释，解释相对路径重定向到的绝对 URL 路径。这有助于审阅者确认您的别名是否正确。

YAML 注释以井号 (#) 开头。

例如，以下 Markdown Front matter 代码片段位于文件 new-url.md 中，定义了一个别名，用于重定向 /docs/grafana/<GRAFANA_VERSION/original-url/。注释 # /docs/grafana/<GRAFANA_VERSION>/original-url/ 指示了绝对 URL 路径。

---
aliases:
  - ./original-url/ # /docs/grafana/<GRAFANA_VERSION>/original-url/
---

确定相对别名

要确定相对别名，您必须首先理解当前目录 (.) 和父目录 (..) 路径元素在别名开头使用时的含义。

对于页面 /docs/grafana/latest/alerting/manage-notifications/ 中的别名

当前目录元素 (.) 指的是包含当前页面的目录，而不是当前页面所在的目录。
在本例中，这是页面 /docs/grafana/latest/alerting/。
父目录元素 (..) 指的是当前目录元素的父目录。
在本例中，这是页面 /docs/grafana/latest/。

在下表中

源页面：是需要重定向的页面，例如页面已被移动或不再存在。
目标页面：是读者被重定向到的页面，例如已重命名的页面或内容已移至的页面。
相对别名：必须添加到目标页面文件 Front matter 中的别名，以创建正确的重定向。

源页面	目标页面	相对别名
`/docs/grafana/latest/alerting.md`	`/docs/grafana/latest/alerting/manage-notifications/_index.md`	`./ # /docs/grafana/latest/alerting/`
`/docs/grafana/latest/alerting/silences/_index.md`	`/docs/grafana/latest/alerting/manage-notifications.md`	`./silences/ # /docs/grafana/latest/alerting/silences/`
`/docs/grafana/latest/alerting/manage-notifications/create-silence/index.md`	`/docs/grafana/latest/alerting/manage-notifications/_index.md`	`./manage-notifications/create-silence/ # /docs/grafana/latest/alerting/manage-notifications/create-silence/`
`/docs/grafana/latest/`	`/docs/grafana/latest/alerting/manage-notifications/`	`../ # /docs/grafana/latest/`
`/docs/grafana/latest/old-alerting/`	`/docs/grafana/latest/alerting/manage-notifications/`	`../old-alerting/ # /docs/grafana/latest/old-alerting/`

使用 `docs/alias` Shortcode

您可以使用 docs/alias Shortcode 来确定相对别名，但不能在 Front matter 中使用该 Shortcode。

您必须先在源文件中使用该 Shortcode，然后从本地 Web 服务器中的页面复制结果到源文件的 Front matter 中。

{{< docs/alias from="/docs/grafana/latest/old-alerting/" to="/docs/grafana/latest/alerting/manage-notifications/" >}}

生成结果

源页面	目标页面	相对别名
`/docs/grafana/latest/old-alerting/`	`/docs/grafana/latest/alerting/manage-notifications/`	`../old-alerting/ # /docs/grafana/latest/old-alerting/`

其他项目

为当前 URL 路径包含一个 aliases 条目。
添加 aliases 条目可以更安全地移动内容，因为旧页面位置到新页面位置的重定向已经设置好。当目录中已经填充了内容时，Hugo 不会创建重定向 .html 文件。
当页面移动时，使用新的 URL 路径更新 aliases。

测试别名

要测试别名是否产生正确的重定向，请使用您的浏览器或用于发出 HTTP 请求的命令行工具。

使用浏览器

使用 make docs 启动文档 Web 服务器。
浏览应被重定向的页面的 URL。
确认您已被重定向到目标页面。
例如，如果您希望页面 https://grafana.org.cn/docs/grafana/latest/panels/working-with-panels/ 重定向到 https://grafana.org.cn/docs/grafana/latest/panels-visualizations/panel-editor-overview/，请在浏览器中浏览以下 URL 以确认重定向正在工作：https://:3002/docs/grafana/latest/panels/working-with-panels/。

使用 `cURL`

使用 make docs 启动文档 Web 服务器。

在另一个终端中，向应被重定向的页面的 URL 发起 HTTP GET 请求。例如，请求页面 localhost:3002/docs/grafana/latest/panels/working-with-panels/

curl localhost:3002/docs/grafana/latest/panels/working-with-panels/

输出类似于以下内容

<!doctype html><html><head><script>const destination="https://:3002/docs/grafana/latest/panels-visualizations/panel-editor-overview/";console.log(window.location.search),document.head.innerHTML=`<meta http-equiv="refresh" content="0; url=${destination}${window.location.search}"/>`</script><title>https://:3002/docs/grafana/latest/panels-visualizations/panel-editor-overview/</title><link rel=canonical href=https://:3002/docs/grafana/latest/panels-visualizations/panel-editor-overview/><meta name=robots content="noindex"><meta charset=utf-8><noscript><meta http-equiv=refresh content="0; url=https://:3002/docs/grafana/latest/panels-visualizations/panel-editor-overview/"></noscript></head></html>

确认 <script> 标签中 destination const 的值是带有别名的页面的美化 URL。

规范URL (Canonical)

canonical Front matter 设置重复或非常相似页面的首选 URL。搜索引擎使用此信息，并且仅索引规范 URL。

canonical URL 的值应为规范页面的完整 URL。例如，https://grafana.org.cn/docs/writers-toolkit/。

使用 Hugo mount 复用的所有页面都应设置 canonical Front matter。对于在 Grafana Cloud 中复用的内容，首选开源文档作为规范页面。

级联 (Cascade)

Hugo 的 cascade Front matter 可以有两种形式：数组和映射。字段会从父级传递给页面的后代。

数组形式使用相同的映射集合，并额外包含一个 _target 映射。_target 映射通常包含一个 path 映射，用于匹配应用 Front matter 的路径。

您可以在以下标签页中比较相同级联 Front matter 的不同形式

cascade:
  labels:
    products:
      - oss

cascade:
  - _target:
      path: /docs/<PROJECT>/**
    labels:
      products:
        - oss

更多信息请参考 Hugo cascade Front matter 文档。

您可以使用 cascade 来定义变量。例如

cascade:
  PRODUCT_VERSION: 10.1
  PRODUCT_NAME: Grafana

cascade:
  - _target:
      path: /docs/<PROJECT>/**
    PRODUCT_VERSION: 10.1
    PRODUCT_NAME: Grafana

在主题正文中需要插入变量的地方使用 param Shortcode。

日期 (Date)

date 描述了页面的初始发布日期。Hugo 生成用于 RSS 源的 XML 页面输出，用户可以通过 RSS 源接收更新通知。客户使用发布说明页面的 RSS 源接收新版本通知。因此，建议发布说明页面使用 date Front matter。

date 字段的值应为完整的 ISO 8601 时间戳。例如，date: "2023-04-24T00:00:00Z" 表示协调世界时 (UTC) 4 月 24 日凌晨 12:00。

date Front matter 还会影响菜单排序。日期较新的页面在菜单中位置靠下。

描述 (必需)

使用 description 为搜索引擎提供主题的简短描述，包括 Grafana 文档站点中使用的搜索引擎。描述也会在社交媒体（如 Twitter）上显示，为用户提供页面内容的线索。

由于读者不在 Grafana 网站上，您的描述应包含上下文信息，例如产品名称。

字符数因媒体而异，因此请使描述简洁，但至少要包含 150 个字符。通过描述链接指向的内容，提供足够的信息来引导用户。通常，这不需要是原创文本。您可以扫描前几段，提取适当的术语或短语添加到描述中。如果描述过长，它会在社交媒体上被截断。

草稿 (Draft)

当 draft 设置为 true 时，此选项会阻止 Hugo 渲染内容。使用命令行标志 --buildDrafts 生成标记为 draft: true 的内容。

关键词 (Keywords)

网站使用 keywords 在相关内容部分生成指向相关页面的链接。它们不影响搜索引擎优化 (SEO)。

理想情况下，使用单个术语而不是短语。

标签 (Labels)

使用 labels 键添加一个或多个您希望显示在发布页面主题标题之前的值。网站仅支持特定的标签值。

您可以使用级联 Front matter 为页面及其子页面设置标签。

如果页面或页面目录的默认标签不正确，请更新标签。此外，如果您要添加新页面，请考虑默认标签是否合适。对于每个页面，请在 labels.products 序列中包含与该页面相关的每个产品的标签。

`labels.products`

labels.products 的值是一个包含以下一个或多个选项的数组

cloud: Grafana Cloud
enterprise: Enterprise
oss: 开源

您应使用适用于页面内容的所有标签。如果页面包含一些开源内容和一些 Grafana Cloud 内容，请同时设置这两个标签。

例如，如果单个页面描述了 Grafana Cloud 和 Grafana Enterprise 中可用的功能，则源文件的 Front matter 应包含以下内容

labels:
  products:
    - cloud
    - enterprise

对于描述仅在 Grafana Cloud 中可用的功能的页面目录，分支捆绑包 _index.md 文件的 Front matter 应包含以下内容

cascade:
  labels:
    products:
      - cloud

`labels.stage`

每个页面只能有一个阶段标签，并且应适用于整个页面。如果页面包含多个不同阶段的内容，则应在每个部分使用相应的发布生命周期文本。对于 labels.stage，支持的值和生成的已发布标签如下所示

experimental: Experimental
private-preview: Private preview
public-preview: Public preview
general-availability: General availability (GA)

例如，如果单个页面描述了实验性功能，则源文件的 Front matter 应包含以下内容

labels:
  stage: experimental

对于描述实验性功能的页面目录，分支捆绑包 _index.md 文件的 Front matter 应包含以下内容

cascade:
  labels:
    stage: experimental

菜单标题 (MenuTitle)

使用 menuTitle 在侧边栏导航中指定一个与 title 元素不同的标题。例如，如果您想在目录中缩写主题标题。

不要从任务主题标题中删除动词。动词有助于读者在点击链接之前了解他们将导航到一个任务主题。

如果包含的章节暗示了动词，您可以从 menuTitle 中删除动词。例如，如果页面“在 Docker 容器中安装 Grafana Alloy”位于名为“Install”的章节中，则可以缩写为“Docker”。

元图像 (Meta image)

使用 meta_image Front matter 设置 Open Graph 和社交媒体图像元数据。该值必须是网站上托管的图像的 URL。要添加新图像，请参考存储媒体资产的位置。

Ref (Refs)

对于大多数链接，自动挂载链接的行为是正确的，但有时您可能希望显式控制链接的多个目标。为此，请使用 ref URI 和 refs Front matter。

包含 refs 字段的部分 Front matter 如下所示

refs:
  <KEY>:
    - pattern: <URL PATH PREFIX>
      destination: <FULL URL>
    - pattern: <URL PATH PREFIX>
      destination: <FULL URL>

<URL PATH PREFIX> - 输入页面 URL 中代表发布文档的项目的部分。
destination - 输入该项目目标页面的完整 URL，包括尾部斜杠。

如果页面的 URL 匹配模式 <URL PATH PREFIX>，则 Hugo 使用 destination 作为链接目标。如果没有模式匹配当前页面，Hugo 会记录构建错误。

<FULL URL> 目标与链接到 grafana.com 页面中描述的行为相同

示例

以下 Markdown 代码片段展示了 refs Front matter 和使用 ref URI 的链接。

---
refs:
  find-plugins:
    - pattern: /docs/grafana/
      destination: /docs/grafana/<GRAFANA_VERSION>/administration/plugin-management/#browse-plugins
    - pattern: /docs/grafana-cloud/
      destination: /docs/grafana-cloud/introduction/find-and-use-plugins/
---

# Manage plugins

## Before you begin

- Find the plugin you want to install. To find a plugin, refer to [Find and use plugins](ref:find-plugins).

在 Grafana 文档页面的最新版本中，链接目标是 https://grafana.org.cn/docs/grafana/latest/administration/plugin-management/#browse-plugins。Hugo 会将版本替换语法 <GRAFANA_VERSION> 替换为从当前页面推断的版本。

在 Grafana Cloud 页面中，链接目标是 https://grafana.org.cn/docs/grafana-cloud/introduction/find-and-use-plugins/。

更多信息请参考ref URIs。

评审日期 (Review date)

使用 review_date Front matter 设置您上次评审页面以确保其正确性的日期。

使用 YYYY-MM-DD 格式设置日期，并使用连字符分隔元素。例如，将上次评审日期设置为 2024 年 6 月 6 日，使用 2024-06-06。

网站在页面内容的底部包含评审日期。您可以在 Writer's Toolkit 主页上看到其渲染效果。

Slug

slug Front matter 会覆盖 URL 路径的最后一个片段。它对 _index.md 文件无效，_index.md 文件也称为章节页面或分支捆绑包。更多信息请参考 Slug。

您应该优先更新文件名而不是使用 slug Front matter，因为这样更容易找到 URL 对应的正确源文件。

标题 (必需)

如果 Front matter 中未指定 menuTitle，Hugo 会使用 title 生成侧边栏目录。您的 title 应与您的第一个标题和 URL slug 匹配，以便进行搜索引擎优化 (SEO)。

title 成为 HTML 中的文档标题元素。通常，浏览器会在页面标签页中显示此内容。

优化标题以进行搜索引擎优化，一个好的标题应该

包含空格在内，长度小于 70 个字符
具有上下文，不仅仅是一两个单词
是独一无二的

权重 (Weight)

默认情况下，主题按 title 的字母顺序显示。

使用 weight 指定在 https://grafana.org.cn 左侧边栏中不同的主题顺序。数字越小，主题在指南或指南章节中的位置越靠前。权重相同的页面按字母顺序显示。

对于内容文件，使用 100 的增量。这样做可以方便您在添加新主题时重新排序现有主题。权重是按目录计算的。

教程

还有一些 Front matter 仅供教程使用。教程也应包含所有常规 Front matter。

作者 (Authors)

authors Front matter 是一个字符串序列，引用网站数据目录中定义的作者文件。如果您是 Grafana Labs 员工，可以在网站数据目录中查看和添加作者。

authors 的值是不带文件扩展名的文件名。例如，要引用在 grafana_labs.yaml 文件中定义的作者，请使用 grafana_labs。

如果不存在适当的作者文件，grafana_labs 是一个很好的默认值。

以下 YAML 示例演示了设置一个名为 grafana_labs 的作者。您必须将其与您的其余 Front matter 合并。

authors:
  - grafana_labs

摘要 (Summary)

summary Front matter 定义了用于 https://grafana.org.cn/tutorials/ 页面教程卡片的简短摘要。

以下 YAML 示例演示了 summary Front matter。您必须将其与您的其余 Front matter 合并。

summary: Use Telegraf to stream live metrics to Grafana.

标签 (Tags)

tags Front matter 是一个字符串序列，作为标签显示在教程页面作者部分下方。

通常，至少有一个标签是专业水平。专业水平包括

初级
中级
高级

以下 YAML 示例演示了设置一个专业水平为 Beginner 的标签。您必须将其与您的其余 Front matter 合并。

tags:
  - Beginner

本页面有用吗？

在 GitHub 中提出修改建议

创建 GitHub issue

发送邮件至 docs@grafana.com

帮助与支持

社区

Front matter

参考

别名 (Aliases)

示例

指南

版本控制项目

确定相对别名

使用 docs/alias Shortcode

其他项目

测试别名

使用浏览器

使用 cURL

规范URL (Canonical)

级联 (Cascade)

日期 (Date)

描述 (必需)

草稿 (Draft)

关键词 (Keywords)

标签 (Labels)

labels.products

labels.stage

菜单标题 (MenuTitle)

元图像 (Meta image)

Ref (Refs)

示例

评审日期 (Review date)

Slug

标题 (必需)

权重 (Weight)

教程

相关技术 (Associated technologies)

作者 (Authors)

摘要 (Summary)

标签 (Tags)

本页面有用吗？

使用 `docs/alias` Shortcode

使用 `cURL`

`labels.products`

`labels.stage`