短代码
短代码是您在源文件中使用的片段，用于调用内置或自定义模板。短代码模板避免了在 Markdown 中使用 HTML 的需要，并确保了整个文档集的一致性。
以下部分描述了可在 Grafana Markdown 文件中使用的短代码。要了解其他短代码，请参阅 Hugo 短代码文档。
注意
网站团队在网站仓库的
layouts/shortcodes文件夹中维护短代码模板，该文件夹仅 Grafana Labs 员工可访问。要请求自定义短代码，请创建问题。
Anchorize
anchorize 短代码插入提供的第一个参数的锚点片段。您可以在 URL 中使用锚点片段来链接到具有特定标识符的 HTML 标签。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| 位置 0 | 字符串 | 是 |
示例
以下示例插入 Writers' Toolkit 的锚点片段。
{{< anchorize "Writers' Toolkit" >}}生成
writers-toolkitAdmonition
admonition 短代码将其内容渲染为块引用或风格化的横幅。风格取决于 Writers' Toolkit 风格约定中定义的提醒类型。
提醒的内容必须包含在开始和结束标签之间，提醒的类型必须用引号括起来。
| 参数 | 描述 | 是否必需 |
|---|---|---|
type | 提醒的类型。可以是 caution、note、tip 或 warning 中的一个。 | 是 |
当您想向读者展示如何执行某些可能并非显而易见的操作时，请使用提示。提示应该是有帮助的补充信息。您可以将某些提示视为技巧。如果读者愿意，可以随意跳过它们，因为它们不贡献于核心理解。
警告
如果您使用在主题级别定义的引用链接，则
[link text][label]或[link text][]等引用样式链接在短代码的内部文本中不起作用。要在提醒内使用引用链接，您必须使用标准的行内 Markdown 链接或在提醒短代码内定义引用链接。有关更多信息，请参阅短代码中的 Markdown 引用链接。
示例
以下示例渲染一个类型为 note 的提醒，消息为 Kingston is the capital of Jamaica.
{{< admonition type="note" >}}
Kingston is the capital of Jamaica.
{{< /admonition >}}生成
注意
Kingston is the capital of Jamaica.
以下示例渲染一个类型为 tip 的提醒，消息为 This also applies to headings that contain a forward slash or parentheses or square brackets.
{{< admonition type="tip" >}}
This also applies to headings that contain a forward slash or parentheses or square brackets.
{{< /admonition >}}生成
Tip
This also applies to headings that contain a forward slash or parentheses or square brackets.
卡片网格
card-grid 短代码渲染一个自适应的卡片元素网格，其宽度适应其容器的宽度。
网格参数
| 参数 | 描述 | 是否必需 |
|---|---|---|
key | Hero 字段的 Front matter 参数名称。默认值：hero。 | 是 |
items | 卡片参数的 Front matter 数组 | 是 |
type | 要使用的卡片类型。当前唯一选项是：simple。默认值：simple。 | 否 |
min | 设置最小卡片宽度。这会影响每行的卡片数量以及卡片换行的断点。选项：xs、sm、md、lg。这些对应于 100px、250px、350px、500px 的最小卡片宽度。默认值：sm。 | 否 |
wrapper_class | 包装器元素的可选 CSS 类。 | 否 |
grid_class | 网格元素的 optional CSS 类。 | 否 |
card_class | 卡片的可选 CSS 类。 | 否 |
卡片参数 (type="simple")
| 参数 | 描述 | 是否必需 |
|---|---|---|
title | 卡片标题文本。 | 否 |
href | 卡片目标的 URL。对于 grafana.com 域的链接，使用相对路径。例如，/docs/grafana/latest/。 | 是 |
description | 描述文本。接受 Markdown。 | 否 |
logo | Logo 图片 URL。 | 否 |
width | 对于位图图像（png、jpg、webp），这是图像的自然宽度。对于矢量图像（svg），这是期望的显示宽度。接受数字（像素）或百分比。像素值**不得**包含 px。默认值：auto。 | 否 |
height | 对于位图图像（png、jpg、webp），这是图像的自然高度。对于矢量图像（svg），这是期望的显示高度。接受数字（像素）或百分比。像素值**不得**包含 px。默认值：auto。 | 否 |
示例
渲染最小卡片宽度为 sm 且卡片类型为 simple 的卡片网格
---
my_card_grid:
type: simple
min: sm
items:
- title: Grafana Alerting
href: /docs/grafana-cloud/alerting-and-irm/alerting/
description: >-
Allows you to learn about problems in your systems moments after they occur. Monitor your incoming metrics data or log entries and set up your Alerting system to watch for specific events or circumstances and then send notifications when those things are found.
logo: /media/docs/grafana-cloud/alerting-and-irm/grafana-icon-alerting.svg
height: 24
- title: Grafana SLO
href: /docs/grafana-cloud/alerting-and-irm/slo/
description: >-
Provides a framework for measuring the quality of service you provide to users. Use SLOs to collect data on the reliability of your systems over time and as a result, help engineering teams reduce alert fatigue, focus on reliability, and provide better service to your customers.
logo: /media/docs/grafana-cloud/alerting-and-irm/grafana-icon-slo.svg
height: 24
---
{{< card-grid key="my_card_grid" >}}代码
code 短代码提供了以不同语言显示多个代码片段的能力。当用户选择一种语言时，页面上的其他代码块会切换到该语言。网站会将选择的语言保存在浏览器存储中，并在导航时保持。
示例
注意
如果您的仓库使用
prettier格式化文件，请在短代码标签周围使用 HTML 注释<!-- prettier-ignore-start -->和<!-- prettier-ignore-end -->以确保正确渲染。
{{< code >}}
```bash
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity"
```
```go
package main
import (
"context"
)
func main() {
...
```
```javascript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';
// https://grafana.org.cn/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
"https://your-stack.grafana.net",
serviceAccountToken
);
...
```
```json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...
```
{{< /code >}}生成
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity"package main
import (
"context"
)
func main() {
...import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';
// https://grafana.org.cn/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
"https://your-stack.grafana.net",
serviceAccountToken
);
...POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...可折叠
collapse 短代码切换内容部分的可见性，这在隐藏和显示大量内容时很有帮助。
| 参数 | 描述 | 是否必需 |
|---|---|---|
title | 解释隐藏内容的文本。 | 是 |
示例
{{< collapse title="Title of hidden content" >}}
Kingston is the capital of Jamaica.
{{< /collapse >}}生成
Kingston is the capital of Jamaica.
使用此短代码用于
添加一句引言和一个标题，两者结合起来要能充分描述折叠内容中包含的内容。不要在标题参数中重复标题。
您不能使用此短代码执行以下操作
- 将其用作页面标题
- 控制标题文本的大小
- 在短代码标签之间添加图片或视频
废弃示例
#### BoltDB (deprecated)
The following example is for a deprecated store and you shouldn't use it for new Loki deployments:
{{< collapse title="boltdb-shipper" >}}
Also known as _boltdb-shipper_ during development.
The single store configurations for Loki utilize the chunk store for both chunks and the index, requiring just one store to run Loki.
{{< /collapse >}}生成
BoltDB (废弃)
以下示例是关于已废弃存储的，不应在新的 Loki 部署中使用
在开发期间也称为 boltdb-shipper。它是 Loki 的单一存储配置，用于将块和索引都存储在块存储中，这使得运行 Loki 只需一个存储即可。
配置选项示例
#### `6-Compactor-Snippet.yaml`
The following partial configuration sets the compactor to use S3 and run the compaction every five minutes.
{{< collapse title="Example" >}}
```yaml
compactor:
working_directory: /tmp/loki/compactor
shared_store: s3
compaction_interval: 5m
```
{{< /collapse >}}生成
6-Compactor-Snippet.yaml
以下部分配置将 compactor 设置为使用 Amazon S3，并每隔 5 分钟运行一次压缩。
compactor:
working_directory: /tmp/loki/compactor
shared_store: s3
compaction_interval: 5m列式列表
将列表格式化为多列。内容在列之间平均分配，除非使用 count 参数指定。
| 参数 | 描述 | 是否必需 |
|---|---|---|
count | 桌面视图中的列数。您可以指定最少两列，最多四列。 | 否 |
示例
{{< column-list >}}
- Alertmanager
- Amazon CloudWatch
- Azure Monitor
- Elasticsearch
- Google Cloud Monitoring
- Graphite
- InfluxDB
- Jaeger
- Loki
- Microsoft SQL Server (MSSQL)
- MySQL
- OpenTSDB
- PostgreSQL
- Prometheus
- Pyroscope
- Tempo
- Zipkin
{{< /column-list >}}生成
- Alertmanager
- Amazon CloudWatch
- Azure Monitor
- Elasticsearch
- Google Cloud Monitoring
- Graphite
- InfluxDB
- Jaeger
- Loki
- Microsoft SQL Server (MSSQL)
- MySQL
- OpenTSDB
- PostgreSQL
- Prometheus
- Pyroscope
- Tempo
- Zipkin
Docs/alias
docs/alias 短代码确定两个页面之间的相对别名。它可以渲染为行内代码、表格行或完整的输出表格。
| 参数 | 描述 | 是否必需 |
|---|---|---|
from | 旧页面的 URL 路径。 | 是 |
to | 新页面的 URL 路径。 | 是 |
output | 可以是 "table"、"row" 或 "string" 中的一个。默认值为 "table"。 | 否 |
有关特定用法说明，请参阅使用 docs/alias 短代码。
Docs/copy
docs/copy 短代码注入网站仓库数据中维护的通用文本。
Grafana Labs 技术文档团队内部维护这些文本。如果您是 Grafana Labs 员工并想进行更改，请编辑copy.yaml。如果您不是 Grafana Labs 员工，请通过创建问题来请求更改。
| 参数 | 描述 | 是否必需 |
|---|---|---|
name | 数据 YAML 文件中的键的名称。 | 是 |
Docs/experimental-deployment
docs/experimental-deployment 短代码生成一个注意提醒，其中包含解释所述部署是实验性的首选文本。
它不接受任何参数。
示例
{{< docs/experimental-deployment >}}生成
注意
此部署仅作为示例提供；工程和排班支持不可用。文档有限或仅在代码注释中提供。不提供 SLA。此示例主要面向开源工程师。由于这是一个示例，因此不适用于生产环境，风险未知/高。
Docs/experimental
docs/experimental 短代码生成一个注意提醒，其中包含解释所述产品或功能是实验性的首选文本。
| 参数 | 描述 | 是否必需 |
|---|---|---|
product | 产品或功能的名称。 | 是 |
featureFlag | 用户用于启用产品或功能的标志名称。 | 是 |
示例
{{< docs/experimental product="experimental-feature" featureFlag="its-feature-flag" >}}生成
注意
experimental-feature 是一个实验性功能。Grafana Labs 提供尽力而为的支持，在功能正式发布之前可能会发生重大更改。在 Grafana 中启用 its-feature-flag 功能标志以使用此功能。联系 Grafana Support 以在 Grafana Cloud 中启用此功能。
Docs/ignore
docs/ignore 短代码忽略开始和结束标记之间的内容，因此它不会显示在渲染的网页中。
当您想将源文档转换为 Killercoda 教程，并希望某些内容仅存在于教程输出中时，请使用此短代码。您应该只使用普通 Markdown 作为短代码的内部内容。
有关 Killercoda 转换的更多信息，请参阅关于转换器工具。
示例
This is rendered before the ignore.
{{< docs/ignore >}}
This isn't rendered.
{{< /docs/ignore >}}
This is rendered after the ignore.生成
此内容在忽略之前渲染。
此内容在忽略之后渲染。
Docs/openapi/info
显示有关 OpenAPI 3.0+ 规范的信息，使用 url 或 data 参数指定 OpenAPI 规范。
| 参数 | 描述 | 是否必需 |
|---|---|---|
url | 要获取的 OpenAPI 规范的 URL。 | 否 |
data | 要使用的 OpenAPI 规范的文件名，该文件位于网站 data/docs/openapi/ 目录中。 | 否 |
从 URL 获取远程规范
{{< docs/openapi/info url="<SPECIFICATION_URL>" >}}使用网站 data/docs/openapi/ 目录中的本地规范
{{< docs/openapi/info data="<SPECIFICATION_FILENAME>" >}}示例
显示 https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore-expanded.json 处远程规范的 API 信息
{{< docs/openapi/info url="https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore-expanded.json" >}}显示名为 grafana 的本地规范的 API 信息
{{< docs/openapi/info data="grafana" >}}Docs/openapi/path
显示 API 路径信息，使用 url 或 data 参数指定 OpenAPI 规范。
| 参数 | 描述 | 是否必需 |
|---|---|---|
url | 要获取的 OpenAPI 规范的 URL。 | 否 |
title | 要使用的 OpenAPI 规范的文件名，该文件位于网站 data/docs/openapi/ 目录中。 | 否 |
scope | 用于限定输出范围的路径标签。 | 否 |
Grafana Cloud k6 REST API v6 文档使用 OpenAPI 短代码生成 API 文档。
如果您想与文档和技术写作团队合作发布您的 API 文档，请在 #docs Slack 频道中联系。
示例
显示 grafana 数据规范的所有路径
{{< docs/openapi/path data="grafana" >}}
or
{{< docs/openapi/path data="grafana" scope="" >}}仅显示带有 enterprise 标签的 grafana 数据规范的路径
{{< docs/openapi/path data="grafana" scope="enterprise" >}}Docs/play
docs/play 短代码生成一个注意提醒，其中包含链接到 Grafana Play 仪表盘的首选文本。
| 参数 | 描述 | 是否必需 |
|---|---|---|
title | Grafana Play 仪表盘的标题。 | 是 |
url | Grafana Play 仪表盘的 URL。 | 是 |
示例
{{< docs/play title="Time Series Visualizations" url="https://play.grafana.org/d/000000016/1-time-series-graphs" >}}生成
Docs/private-preview
docs/private-preview 短代码生成一个注意提醒，其中包含解释所述产品或功能处于私有预览阶段的首选文本。
| 参数 | 描述 | 是否必需 |
|---|---|---|
product | 产品或功能的名称。 | 是 |
{{< docs/private-preview product="private-preview-feature" >}}生成
注意
private-preview-feature 目前处于私有预览阶段。Grafana Labs 提供尽力而为的支持，在功能正式发布之前可能会发生重大更改。
Docs/public-preview
docs/public-preview 短代码生成一个注意提醒，其中包含解释所述产品或功能处于公开预览阶段的首选文本。
| 参数 | 描述 | 是否必需 |
|---|---|---|
product | 产品或功能的名称。 | 否 |
featureFlag | 用户用于启用产品或功能的标志名称。 | 否 |
{{< docs/public-preview product="public-preview-feature" >}}生成
注意
public-preview-feature 目前处于公开预览阶段。Grafana Labs 提供有限支持，在功能正式发布之前可能会发生重大更改。
{{< docs/public-preview product="public-preview-feature" featureFlag="its-feature-flag" >}}生成
注意
public-preview-feature 目前处于公开预览阶段。Grafana Labs 提供有限支持，在功能正式发布之前可能会发生重大更改。
要使用此功能，请在您的 Grafana 配置文件中或在 Grafana Cloud 的 **Administration > General > Feature toggles** 中启用 its-feature-flag 功能标志。
{{< docs/public-preview featureFlag="a-feature-flag" >}}生成
注意
要使用此功能，请在您的 Grafana 配置文件中或在 Grafana Cloud 的 **Administration > General > Feature toggles** 中启用 a-feature-flag 功能标志。
Docs/reference
警告
此短代码在文档中存在，但您应优先使用
refURIs。创建新文档或更新现有文档时请勿使用它。有关更多信息，请参阅链接。
docs/reference 短代码允许您为同一个链接指定不同的目标，具体取决于您发布源文件的位置。
您可以在文件的一部分（通常是文件末尾，如页脚）设置所有可能的目标。
例如，版本化 Grafana 文档中的页面也挂载在 Grafana Cloud 文档中。Grafana 中的页面应链接到 Grafana 仪表盘页面，但 Grafana Cloud 中的页面应链接到 Grafana Cloud 仪表盘页面。
按如下方式在页面末尾设置引用
{{% docs/reference %}}
[dashboards]: "/docs/grafana/ -> /docs/grafana/<GRAFANA_VERSION>/dashboards"
[dashboards]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/dashboards"
{{% /docs/reference %}}短代码标签中的内容如下
[LABEL]: "PROJECT PATH PREFIX -> REFERENCE"
_
<LABEL>_ - 您将在文件中引用样式链接中使用的标签。在上面的示例中，标签是dashboards。标签可以是多个词，例如[dashboard docs]，并且可以包含空格。_
<PROJECT PATH PREFIX>_ - 指定目标项目。在前面的示例中，Grafana 的路径前缀是/docs/grafana/，Cloud 的路径前缀是/docs/grafana-cloud/。_
<REFERENCE>_ - 目标文件的路径。此短代码支持使用<GRAFANA_VERSION>等值进行版本替换。要了解版本替换，请参阅关于版本替换。路径中不要包含尾部斜杠。
然后按以下格式在文件主体中添加链接
For more information about Grafana dashboards, refer to [Dashboards][dashboards].- 如果您所在的页面是
/docs/grafana-cloud/alerting/，则返回的链接是/docs/grafana-cloud/dashboards/。 - 如果您所在的页面是
/docs/grafana/latest/alerting/，则推断的版本是latest，返回的链接是/docs/grafana/latest/dashboards/。 - 如果您所在的页面是
/docs/grafana/next/alerting/，则推断的版本是next，返回的链接是/docs/grafana/next/dashboards/。
其他用例
当您想在一个文件中多次链接到同一个目标时，Markdown 引用样式链接也很有用。它允许您指定链接目标一次，而多次使用标签。例如
参考
[grafana website]: www.grafana.com正文
Find more information on [Grafana][grafana website].Docs/shared
docs/shared 短代码通过包含源内容仓库中的共享页面，允许您在整个 Grafana 网站上复用内容。源内容仓库必须通过将其放置在其 shared 目录中来明确共享该页面。
要共享内容，请按照以下步骤操作
- 创建一个包含共享源的 Markdown 文件，并在 front matter 中包含
headless: true，以防止网站发布该页面。 - 将文件存储在共享文件夹中。
- 要在 Markdown 文件中包含共享内容，请插入
docs/shared短代码，并包含以下命名参数
有关更详细的说明，请参阅复用共享内容。
| 参数 | 描述 | 是否必需 |
|---|---|---|
lookup | 相对于共享目录根目录的包含内容的路径。 | 是 |
source | 网站上显示的源内容的名称。例如，对于https://grafana.org.cn/docs/enterprise-metrics/ 内容，*source* 是 enterprise-metrics。 | 是 |
version | 要包含的源内容的版本。对于没有版本的源内容，请使用空字符串 "" 作为值。此短代码支持使用 <GRAFANA_VERSION> 等值进行版本替换。要了解版本替换，请参阅关于版本替换。 | 是 |
leveloffset | 操作源内容标题，最高级别为 h6。仅支持正偏移。leveloffset="+5" 确保源内容中的 h1 在目标内容中是 h6。 | 否 |
注意
当源文件在磁盘上发生变化时，Hugo 不会重新构建目标文件。要在更改源文件后触发重新构建，请对目标文件进行微小更改，并保存。
共享文件和标题
Hugo 单独于页面渲染短代码。因此，如果共享文件和包含它的页面中存在相同的标题，它们将具有相同的标题标识符。这种标题标识符的重复破坏了正确链接到标题的能力。
为了解决此问题，请在共享文件中设置标题标识符。如果存在两个共享文件包含相同标题，则只需在其中一个文件中设置标题标识符。要设置标题标识符，请参阅Markdown 指南。
指导
当包含 docs/shared 短代码的页面包含来自同一项目的共享页面时，您应该对 version 参数使用版本替换语法。这可以确保 docs/shared 短代码包含来自与短代码所在页面相同版本的页面。
否则，您应该使用适合您文档的版本。使用版本替换语法，并在项目根目录的 _index.md 文件中的 cascading front matter 中设置期望的版本。
示例
以下短代码插入来自 oauth2-block.md 文件的内容。lookup 路径相对于 agent 源仓库中的 shared 文件夹。
{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="<AGENT VERSION>" >}}以下短代码插入来自 enterprise-metrics 项目的 shared 文件夹中的 shared-page.md。使用的版本与包含文件的页面版本匹配。标题偏移一个级别，因此如果源内容包含 h1，则生成的标题是 h2。
{{< docs/shared lookup="shared-page.md" source="enterprise-metrics" version="<GEM_VERSION>" leveloffset="+1" >}}固定宽度表格
fixed-table 短代码通过在任何字符处（而不仅仅是单词之间的空格）将内容断到新行来防止列溢出。
示例
{{< fixed-table >}}
| Metric | CloudWatch Metric | Statistics |
| ------------------------------ | ----------------- | ------------------------------------------------------------------------ |
| **aws_amazonmq_info** | |
| **aws_amazonmq_ack_rate** | AckRate | **Average**, Maximum, Minimum, Sum, SampleCount, p50, p75, p90, p95, p99 |
| **aws_amazonmq_burst_balance** | BurstBalance | **Average**, Maximum, Minimum, Sum, SampleCount, p50, p75, p90, p95, p99 |
{{< /fixed-table >}}生成
| 指标 | CloudWatch 指标 | 统计 |
|---|---|---|
| aws_amazonmq_info | ||
| aws_amazonmq_ack_rate | AckRate | 平均、最大值、最小值、总和、SampleCount、p50、p75、p90、p95、p99 |
| aws_amazonmq_burst_balance | BurstBalance | 平均、最大值、最小值、总和、SampleCount、p50、p75、p90、p95、p99 |
不使用此短代码的情况
| 指标 | CloudWatch 指标 | 统计 |
|---|---|---|
| aws_amazonmq_info | ||
| aws_amazonmq_ack_rate | AckRate | 平均、最大值、最小值、总和、SampleCount、p50、p75、p90、p95、p99 |
| aws_amazonmq_burst_balance | BurstBalance | 平均、最大值、最小值、总和、SampleCount、p50、p75、p90、p95、p99 |
图
figure 短代码使用 HTML <figure> 元素渲染带有图注的图片。此短代码允许您更精细地控制如何渲染图片，但如果您不需要这些选项，可以使用基本 Markdown 添加图片。
要添加图，请插入 figure 短代码，并包含以下命名参数
| 参数 | 描述 | 是否必需 |
|---|---|---|
alt | 如果设置，alt 指定图片的 alt 文本。 | 否 |
animated-gif | 如果设置，HTML 包含一个带有图片链接的 div，而不是 <figure> 元素。它通常用于动态截图。设置此参数后，短代码会忽略其他参数，除了 caption 和 maxWidth。 | 否 |
caption | 使用 <figcaption> 元素描述图。如果未设置 alt，则短代码使用 caption 作为 alt 文本。 | 否 |
caption-align | 更改 caption 属性的对齐方式。可接受的值为 left、center 和 right。 | 否 |
class | 覆盖 <figure> 元素的 HTML 类。 | 否 |
link-class | 覆盖 <a> 元素的 HTML 类。 | 否 |
lazy | 如果设置为 "false"，则**不**会向图片应用额外的 lazyload 类。lazyload 类允许浏览器在图图片加载之前渲染页面。图片加载后，占位符框会过渡到加载的图片。默认为 "true"。 | 否 |
lightbox | 如果设置为 "true"，短代码会向 <figure> 应用额外的 figure-wrapper__lightbox 类。 | 否 |
link | 如果设置，该值会覆盖 src 短代码参数，作为 <figure> 中 <a> 元素中 href 的值。 | 否 |
height | 如果设置，_height_ 使用 height CSS 属性控制 <img> 元素的高度。指定值时，它应该是一个表示像素的整数，不带末尾的 "px" 字符串，例如 "500"。 | 否 |
width | 如果设置，_width_ 使用 width CSS 属性控制 <img> 元素的宽度。指定值时，它应该是一个表示像素的整数，不带末尾的 "px" 字符串，例如 "500"。 | 否 |
max-width | 如果设置，_max-width_ 使用 max-width CSS 属性控制 <figure> 元素的最大宽度。指定长度或百分比时，值应包含度量单位，例如 "75px" 或 "25%"。 | 否 |
show-caption | 如果设置为 "true"，则渲染的 <figure> 包含一个带有在 *caption* 中设置的图注的 <figcaption> 元素。默认为 "true"。 | 否 |
src | 设置图片的源。 | 是 |
注意
强烈建议包含原始图片尺寸作为 'width' 和 'height' 属性，因为这可以提高页面性能和 SEO。
这些值**仅**用于确定图片宽高比，并不等于最终显示的尺寸。
图片居中示例
您可以使用 figure 短代码通过添加以下属性来将图片居中
添加
class="w-100p"属性。添加
link-class="w-fit mx-auto d-flex flex-direction-column"属性。添加
max-width="WIDTHpx"属性，将WIDTH替换为您希望显示图片的 最大宽度 值。此属性仅影响原始宽度大于此属性值的位图图像，例如 PNG 或 JPG 文件。您可以选择添加
width和height属性作为最佳实践，以帮助图片和页面优化。对于位图图像，例如 PNG 或 JPG 文件，您可以将属性设置为原始图片值，不带像素或百分比。例如，对于原始尺寸为 800x600 像素的 PNG 文件，您可以添加
width="800" height="600"。对于矢量图像，根据所需图片宽度使用公式计算值：
(new_width / full_width) * full_height = new_height。有关此步骤的详细说明，请参阅后面的**图片居中属性**部分。
以下示例展示了如何将原始尺寸为 1275x738 像素的 PNG 文件居中
{{< figure src="/static/img/docs/grafana-cloud/k8sPods.png" width="1275" height="738" max-width="500px" class="w-100p" link-class="w-fit mx-auto d-flex flex-direction-column" caption="Pod view in Grafana Kubernetes Monitoring" caption-align="center" >}}有关每个参数作用的更多详细信息，请参阅以下部分。
将图片在页面上居中时，您必须添加到 <figure> 短代码中的每个属性都有不同的用途
class="w-100p"属性指定<figure>元素应占据其容器宽度的 100%。link-class属性值为w-fit指定包裹图片的<a>元素的宽度应与其内容相符。例如，如果图片宽度为 500px，其父级<a>元素的宽度将设置为匹配。mx-auto将链接两侧的 X 轴外边距设置为自动占据容器中剩余的空间。例如，如果图的容器宽 750px，图片宽 500px，则图片两侧的外边距将为 125px ((750 - 500) / 2)。这就是实际执行居中的部分。d-flex将图元素设置为 flex 容器。flex-direction-column指定 flex 容器的布局方向。在这种情况下，子元素垂直堆叠，这与水平显示子元素的 flex-direction-row 相反。
width或max-width属性对于计算图片宽度与容器尺寸之间的差异是必需的。虽然只有width或max-width值对于居中目的是必需的，但设置width和height是最佳实践。
设置 width 和 height 属性是推荐的，因为它允许浏览器优化图片的交付，并考虑用户的设备和显示尺寸，以及在不需要全尺寸图片时提供较小的图片。提供这两个值还允许浏览器在延迟加载图片时正确计算占位符空间。这有助于防止回流，回流是文章目录中的链接无法准确跳转到正确部分的大多数原因。
对于位图图像，例如 PNG 或 JPG 文件，width 和 height 通常应设置为图片的原始尺寸。这样做为图片优化提供了最大的灵活性。但是，对于 SVG 图像，width 通常应设置为 100%，而 height 应留空。这将使图片扩展以填充其容器，同时保持图片的宽高比。
在期望的图片显示宽度小于容器最大宽度的情况下，计算正确的高度以保持图片的宽高比而不使图片变形非常重要。为此，您可以将期望的图片宽度除以图片的完整宽度，然后乘以原始高度：(new_width / full_width) * full_height = new_height。例如，如果原始图片尺寸为 1000px x 750px，并且您希望图片以 500px 宽显示，您可以计算 (500 / 1000) * 750 = 325，即 width="500" height="325"。
示例
在此示例中，图片有一个 CSS 类，使其浮动到右侧显示。
{{< figure class="float-right" src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" >}}此示例将图片的显示尺寸的最大宽度设置为 50%。max-width 值必须包含度量单位，例如像素或百分比。
{{< figure max-width="50%" src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" >}}Grot 指南
Grot 指南是嵌入在文档页面中的交互式指南，人们可以按照这些指南获取主题的帮助和指导，并指向文档资源。
要了解有关 Grot 指南的更多信息，请参阅 Writers' Toolkit 中的Grot 指南文档。
主图 (简单)
主图部分是一个较大的部分，包含标题、描述和图片，通常放置在页面顶部。
hero-simple 短代码渲染一个带有可选标题、描述和图片的主图部分。要添加简单主图，请使用以下命名参数插入 hero-simple 短代码
| 参数 | 描述 | 是否必需 |
|---|---|---|
key | Hero 字段的 Front matter 参数名称。默认值：hero。 | 否 |
title | 标题文本。 | 否 |
level | 标题级别。默认值：3。 | 否 |
image | 图片 URL。 | 否 |
width | 对于位图图像（png、jpg、webp），这是图像的自然宽度。对于矢量图像（svg），这是期望的显示宽度。接受数字（像素）或百分比。像素值**不得**包含 px。默认值：auto。 | 否 |
height | 对于位图图像（png、jpg、webp），这是图像的自然高度。对于矢量图像（svg），这是期望的显示高度。接受数字（像素）或百分比。像素值**不得**包含 px。默认值：auto。 | 否 |
description | 描述文本。接受 Markdown。 | 否 |
wrapper_class | 包装器元素的可选 CSS 类。 | 否 |
hero_class | 主图元素的可选 CSS 类。 | 否 |
img_class | 图片容器元素的可选 CSS 类。 | 否 |
title_class | 标题元素的可选 CSS 类。 | 否 |
description_class | 描述元素的可选 CSS 类。 | 否 |
您可以通过以下方式提供短代码参数
- 添加 front matter 并使用
key参数引用 front matter。 - 直接将它们添加到短代码本身。
短代码参数会覆盖 front matter 中的参数。如果您不提供任何参数，短代码将使用默认值。
示例
使用 front matter 插入简单主图
---
my_hero:
title: Alerts and IRM
level: 1
image: /media/docs/grafana-cloud/alerting-and-irm/grafana-cloud-docs-hero-alerts-irm.svg
width: 110
height: 110
description: >-
Alerts & IRM is Grafana Cloud's Incident Response Management (IRM) solution, which enables you to detect, respond, and learn from incidents in one centralized platform.
---
{{< hero-simple key="my_hero" >}}使用短代码参数插入简单主图
{{< hero-simple title="Alerts and IRM" level="1" image="/media/docs/grafana-cloud/alerting-and-irm/grafana-cloud-docs-hero-alerts-irm.svg" width="110" height="110" description="Alerts & IRM is Grafana Cloud's Incident Response Management (IRM) solution, which enables you to detect, respond, and learn from incidents in one centralized platform." >}}Param
param 短代码提供了构建时变量替换。
要添加新的变量定义
- 在父主题中定义
cascade变量。 - 在父主题和子主题中需要的位置插入
param变量。
如果在标题中使用 param 短代码，则必须使用 % 代替 < 和 >。例如
# Heading {{% param VARIABLE %}}示例
产品版本的 front matter 定义
cascade:
PRODUCT_VERSION: 10.2主题正文文本中的 param 短代码
Welcome to Grafana {{< param PRODUCT_VERSION >}}. Read on to learn about changes to dashboards and visualizations, data sources, security and authentication, and more.主题标题中的 param 短代码
## What's new in Grafana {{% param PRODUCT_VERSION %}}.Pyroscope 火焰图
pyro-flame-graph 短代码嵌入上传到https://flamegraph.com/ 的 Pyroscope 火焰图。
| 参数 | 描述 | 是否必需 |
|---|---|---|
id | 火焰图 ID | 是 |
火焰图 id 值是火焰图 URL 中 /share/ 后面的路径元素。
例如，要嵌入 URL 为https://flamegraph.com/share/a8c6e7a9-f360-11ec-bcfa-beb8fdeeb850 的火焰图，请使用以下短代码
{{< pyro-flamegraph id="a8c6e7a9-f360-11ec-bcfa-beb8fdeeb850" >}}Relref
警告
此短代码在文档中存在，但您应优先使用完整 URL。创建新文档或更新现有文档时请勿使用它。
有关更多信息，请参阅链接。
relref 短代码提供了构建时链接检查，以确保目标文件存在。
例如：{{< relref "./path/to/file" >}}。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| 位置 0 | 文件查找。 | 是 |
参数是绝对或相对文件查找。绝对查找以斜杠 (/) 开头，并从站点根目录开始。例如，要链接到 Grafana Cloud 索引页，relref 短代码参数是 {{< relref "/docs/grafana-cloud/_index.md" >}}。
使用包含扩展名的完整文件路径可能会在目标文件从页面更改为 leaf 或 branch bundle 时破坏查找。为避免这种情况，请省略文件扩展名以及查找中的任何 /_index 或 /index 部分。使用前面 Grafana Cloud 索引页的示例，首选的 relref 短代码参数是 {{< relref "/docs/grafana-cloud" >}}。
Hugo 链接检查仅适用于构建时可用的内容。在大多数项目中，本地构建和 CI 期间唯一可用的内容是当前项目文档。
Hugo 在构建文档时会发出 REF_NOT_FOUND 警告，指示此类引用的文件名和位置，例如在 grafana/grafana 中运行 make docs 或在 grafana/website 中运行 make server-quick
WARN 2022/08/04 21:35:37 [en] REF_NOT_FOUND: Ref "../../enterprise": "/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md:14:47": page not found在此示例中，
Ref "../../enterprise"是 Hugo 无法解析的引用的目标\/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md是包含引用的文档，其中/next/后面的路径是相对于组件仓库的文档根目录的:14表示包含未解析引用的行号:47表示该行中未解析引用开始的字符位置
如果您看到此错误，则引用的目标无效。这可能是由于引用中的拼写错误或到目标目录的路径不正确。通过更正引用目标来修复错误。
有关 Hugo 错误输出的其他信息，请参阅测试文档修改。
确定 relref 短代码参数
要确定源内容和目标内容之间的路径，请执行以下操作
找到目标内容所在的目录。找到源目录和目标目录共有的目录。记下从共有目录到目标目录的相对路径。计算从源目录到共有目录的文件夹数量，该数量等于需要添加到相对路径中的父目录路径元素 (..) 的数量。使用正斜杠 (/) 将所有路径元素连接起来。
例如，对于以下文件夹结构
Vehicles
├── Trucks
│ ├── F150
│ └── 1999 F150
└── Vans在此示例中，源内容位于 1999 F150 目录中，目标内容位于 Vans 目录中。两个内容共有的文件夹是 Vehicles 目录。
1999 F150 的父目录是 Trucks，需要一个 .. 路径元素。Trucks 的父目录是 Vehicles，需要另一个 .. 路径元素。因此，从源目录 1999 F150 到共有目录 Vehicles 的相对路径是 ../..
从共有目录 Vehicles 到目标目录 Vans 的路径是 vans。相对路径是 ../../vans
如果源目录是 Vans，目标是 1999 F150，则相对路径将是 ../trucks/F150/1999-F150。
章节
section 短代码渲染一个无序列表，包含指向页面子页面的链接。要添加章节，请插入 section 短代码，并包含以下可选参数
| 参数 | 描述 | 是否必需 |
|---|---|---|
menuTitle | 如果设置为 "true"，则 menuTitle 参数会修改模板，以使用子页面的 menuTitle front matter 作为链接文本，而不是使用页面标题。如果子页面没有 menuTitle 参数，短代码将使用 title。 | 否 |
ordered | 如果设置为 "true"，则 ordered 参数会修改模板，使用有序列表而不是无序列表，每个项目显示一个数字标记 | 否 |
withDescriptions | 如果设置为 "true"，则 withDescriptions 参数会修改模板，以包含具有 front matter 描述的子页面的描述内容。 | 否 |
depth | 控制输出中包含多少层子页面。默认深度为 "1"，仅显示直接子页面。 | 否 |
示例
以下短代码插入一个指向子页面的链接列表。链接文本使用子页面 front matter 中 menuTitle 的值。
{{< section menuTitle="true">}}以下短代码插入一个指向子页面的链接列表，并包含每个子页面 front matter 中的 description 内容。
{{< section withDescriptions="true">}}共享
shared 短代码设置一个用于共享的片段。您可以使用 shared-snippet 短代码在另一个页面中复用该片段。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| id | 指定给片段的标识符，在页面内唯一 | 是 |
共享片段
shared-snippet 短代码包含另一页面中标记在 section HTML 标签之间的部分。您应该只在学习旅程中使用此短代码。
要设置共享片段，请将其包裹在带有有意义 ID 的 shared shortcode 中。例如
A Grafana dashboard is a set of one or more
panels, organized and arranged into one or more rows, that provide an at-a-glance view of related information. These panels are created using components that query and transform raw data from a data source into charts, graphs, and other visualizations.
然后您可以使用 shared-snippet shortcode 在另一个页面中使用该部分
{{% shared-snippet path="/docs/grafana/next/dashboards/_index.md" id="dashboard-overview" %}}注意
对于
shared-snippetshortcode，您必须使用百分号 (%) shortcode 语法，因为它返回的是 Markdown 而不是 HTML。
sharedshortcode 返回其内部内容为 HTML，应使用常规的 shortcode 语法。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| 路径 | 页面源文件路径 | 是 |
| id | 与 shared shortcode 上设置的 id 匹配的标识符 | 是 |
目录
table-of-contents shortcode 在页面正文中渲染页面的目录。通常应避免使用此 shortcode，因为每个文档页面都已在页面正文中渲染了目录。
{{< table-of-contents >}}选项卡
tabs shortcode 创建通用的选项卡式内容。网站会将选定的选项卡保存到浏览器存储中，并在导航过程中保留。
您可以在 tabs shortcode 中使用 tab-content shortcode 创建选项卡。tab-content 的内部可以是任何 Markdown 内容。
注意
您可以将
codeshortcode 嵌套在tab-contentshortcode 中，但不能将tabsshortcode 嵌套在tab-contentshortcode 中。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| name | 选项卡头部显示的选项卡名称 | 是 |
示例
{{< tabs >}}
{{< tab-content name="One" >}}
This is the first tab.
{{< /tab-content >}}
{{< tab-content name="Two" >}}
This is the second tab.
{{< /tab-content >}}
{{< /tabs >}}生成
术语
term shortcode 允许在用户将鼠标悬停在被该 shortcode 包围的文本上时显示工具提示。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| 位置 0 | 术语表查找键 | 是 |
示例
{{< term "data source" >}}data sources{{< /term >}}Grafana comes with built-in support for many {{< term "data source" >}}data sources{{< /term >}}.生成
Grafana 内置支持多种数据源 。
Grafana Labs 技术文档团队内部维护相关定义。如果您是 Grafana Labs 员工并希望进行更改，请编辑 glossary.yaml。如果您不是 Grafana Labs 员工，请通过创建问题请求更改。
指导
对于具有多个定义的术语，请遵循通用词典的做法，对每个备选定义进行编号。例如，请参阅 graph 的定义。
翻译
translate shortcode 在 Hugo 国际化表中查找一个键，并返回该键在页面语言中引用的单词或短语。
网站使用国际化表来翻译页面模板 HTML 中的一些单词和短语，例如 本页面有帮助吗？ 标题。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| 位置 0 | 查找键 | 是 |
该 shortcode 需要一个参数作为查找键。例如，{{< translate "docs_feedback_heading" >}}。Grafana Labs 的员工可以在国际化目录中查找这些键。
示例
{{< translate "docs_feedback_heading" >}}生成
本页面有帮助吗？视频嵌入
video-embed shortcode 在页面中嵌入视频。请使用 10 MB 或更小的 .mp4 文件。
该 shortcode 需要一个参数 src 来设置图像源。为此，请使用录制文件的路径
{{< video-embed src="<PATH>" >}}Vimeo
vimeo shortcode 嵌入托管在 vimeo.com 上的视频。
| 参数 | 描述 | 是否必需 |
|---|---|---|
| 位置 0 | 视频 ID | 是 |
该 shortcode 需要一个参数作为视频 ID。例如，{{< vimeo 1111111 >}}。
您可以在 URL 的末尾找到视频 ID。在此示例中，视频是 Tempo 2.0 和 TraceQL 的预览：https://vimeo.com/773194063。
{{< vimeo 773194063 >}}YouTube
youtube shortcode 嵌入托管在 YouTube 上的视频。
| 参数 | 描述 | 是否必需 |
|---|---|---|
id | 视频 ID | 是 |
开始 | 开始时间（秒） | 否 |
结束 | 结束时间（秒） | 否 |
id 是 YouTube URL 中的 v URL 参数。例如，对于 YouTube URL https://www.youtube.com/watch?v=g97CjKOZqT4，shortcode 如下
{{< youtube id="g97CjKOZqT4" >}}您可以配置 start 和 end（以秒为单位），使用
{{< youtube id="g97CjKOZqT4" start="100" end="200" >}}您可以配置自动播放，使用
{{< youtube id="g97CjKOZqT4" autoplay="true" >}}转义 Hugo shortcode
如果您需要显示 shortcode 的语法，可以使用此语法进行转义
生成
{{< myshortcode >}}关于版本替换
版本替换允许使用绝对路径，无论版本如何都能正确解析。它使用尖括号分隔符的特殊语法，例如 <GRAFANA_VERSION>。
按照惯例，目标项目的名称使用全大写。例如，grafana 变成 GRAFANA，grafana-cloud 变成 GRAFANA_CLOUD。
该 shortcode 将特殊语法 <SOMETHING_VERSION> 替换为从页面 URL 推断出的版本。如果页面 URL 具有前缀 /docs/grafana/latest/，则 shortcode 会将语法 <SOMETHING_VERSION> 在最终 URL 中替换为 latest。
您可以通过在文件的前置元数据 (front matter) 中包含额外信息来覆盖版本推断。要覆盖 <GRAFANA_VERSION> 的值，请在页面前置元数据中设置 GRAFANA_VERSION 参数。例如，无论源内容版本如何，要将版本设置为 next，请在前置元数据中添加以下内容：GRAFANA_VERSION: next。