文档 Writers' Toolkit 写作 复用 复用共享内容

复用共享内容

共享内容是指在多种上下文中都有意义的句子、段落或页面。复用共享内容可将来自单个源文件的更改传播到一个或多个目标页面。

本主题描述了如何提取并将一段内容共享到多个页面。

开始之前

• 确定您想在多个页面中复用的一段内容。

步骤

要复用共享内容，请按照以下步骤操作

创建共享目录

1. 确定共享和消费项目。

   • 当在单个项目中共享内容时，该项目同时是共享项目和消费项目。

   • 但是，当从一个项目向另一个项目共享内容时，您必须选择哪个是共享项目，哪个是消费项目。由于 Grafana Labs 重视外部贡献，因此优先从开源项目共享。例如，在 Tempo 和 Grafana Enterprise Traces 之间共享内容时，优先选择 Tempo 作为共享项目，Grafana Enterprise Traces 作为消费项目。

2. 在共享项目中，如果 docs/sources/shared/ 目录不存在，则创建它。

3. 在共享项目中，如果文件 docs/sources/shared/index.md 不存在，则创建它，并包含以下内容

   markdown 复制

   ---
   headless: true
   ---

   index.md 文件告诉 Hugo，docs/sources/shared 目录是一个叶子包，这是 docs/shared Shortcode 访问其中存储文件所必需的。有关叶子包的更多信息，请参阅页面和页面包。

   首次在仓库中执行上述说明后，目录结构将类似于以下内容

   console 复制

   docs/sources/shared
   └── index.md

创建共享文件

1. 在共享项目中，在 docs/sources/shared/ 目录中为共享内容创建一个文件。

   文件名应反映其内容。

   文件可以放在子目录中，但该子目录必须位于 docs/sources/shared/ 目录下。docs/shared Shortcode 无法查找此目录之外的文件。

   文件内容应包含您想要复用的文本段落以及一个带有标题的 front matter 部分。如果您认为有助于提供信息，可以在 front matter 中包含标签，但这些标签在消费项目中不可见

   markdown 复制

   ---
   labels:
     products:
       - cloud
       - oss
   title: A shared file
   ---

2. 在消费项目中，使用 docs/shared Shortcode 包含共享内容。

   要从 tempo 项目文档的最新版本中消费文件 docs/sources/shared/common-introduction.md，Shortcode 如下

   markdown 复制

   {{< docs/shared source="tempo" lookup="common-introduction.md" version="latest" >}}

   有关 docs/shared Shortcode 参数的更多信息，请参阅docs/shared Shortcode 参考。

3. 验证包含内容。

   要审查对文档的更改，请参阅审查您的更改中的步骤