Writers' Toolkit Write Reuse content Reuse shared content

Reuse shared content

Shared content is a sentence, paragraph, or page that makes sense in multiple contexts. Reusing shared content propagates changes from a single source file to one or more destination pages.

This topic describes how to extract and share a chunk of content to multiple pages.

Before you begin

• Identify a chunk of content that should be reused in multiple pages.

Steps

To reuse shared content, follow these steps:

Create a shared directory

1. Identify the sharing and consuming projects.

   • When sharing content within a single project, that project is both the sharing and consuming project.

   • However, when sharing content from one project to another then you must choose which is the sharing project and which is the consuming project. Because we rely on external contributions, sharing from open-source projects is preferred. For example, when sharing content between Tempo and Grafana Enterprise Traces, prefer Tempo to be the sharing project and Grafana Enterprise Traces to be the consuming project.

2. In the sharing project, create the docs/sources/shared/ directory if it does not exist.

3. In the sharing project, create the file docs/sources/shared/index.md if it does not exist, with the following contents:

   markdown

   ---
   headless: true
   ---

   The index.md file tells Hugo that the docs/sources/shared directory is a leaf bundle which is necessary for the docs/shared shortcode to access files stored within. For more information about leaf bundles, refer to Pages and page bundles.

   After performing the preceding instructions for the first time in a new repository, the directory structure looks similar to the following:

   console

   $ tree docs/sources/shared
   docs/sources/shared
   └── index.md
   
   0 directories, 1 file

Create a shared file

1. In the sharing project, create a file for the shared content in the docs/sources/shared/ directory.

   Name the file to reflect its contents.

   The file can be in a subdirectory, but that subdirectory must be in the docs/sources/shared/ directory. The docs/shared shortcode cannot lookup files outside of this directory.

   The file’s contents should be the chunk of writing you want to reuse and a front matter section with a title. You can include the appropriate labels in the front matter if you think it would be helpful information, but the labels won’t be visible in the consuming project:

   markdown

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

   You can include relref style links in the content. When doing so, set the destination path in relation to the location of the shared content file.

2. In the consuming project, use the docs/shared shortcode to include the shared content.

   To consume the file docs/sources/shared/common-introduction.md from the latest version of the tempo project documentation, the shortcode would be the following:

   markdown

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

   For more information about the docs/shared shortcode parameters, refer to docs/shared shortcode.

3. Verify the include.

   To review the changes to the documentation, refer to the steps in Review your changes