Reuse directories of content with Hugo mounts

Wed, 29 Mar 2023 09:30:24 +0100

Reuse directories of content with Hugo mounts

Note
Only a Grafana Labs employee can perform the following task.

Before Hugo performs a build, it reads the Hugo module mounts configuration to construct a virtual filesystem. Each mount mounts a source directory at a destination directory within that filesystem. You can use Hugo mounts to reuse a whole directory of content in another part of the published technical documentation.

Before you begin

Identify a directory of content that you want to reuse.
Identify any pages to exclude. Typically, excluded pages are ones that don’t make sense in the context of the target directory.

Warning
Pages in the directory might have relative links to other pages that would be broken by their exclusion.

If the excluded page is replaced by another in the target directory, relative links continue to work.

Otherwise, you should make the links absolute so that they always refer to the page in the source directory.

Steps

To reuse a shared directory:

Determine the source and target directories.

The source directory is the path to a directory in the website repository. It always has the path prefix content/docs/. The source directory for all Grafana Cloud content at the URL https://grafana.com/docs/grafana-cloud/ is content/docs/grafana-cloud.

Similarly, the target directory has the path prefix content/docs. For the destination URL https://grafana.com/docs/target-directory/, the path is content/docs/target-directory.
For every page in the source directory, set the canonical URL using the canonical front matter, to the published open source page URL.

The canonical front matter indicates the preferred URL for duplicate or very similar pages. For more information, refer to Canonical.
Update the website repository Hugo configuration.

The configuration is in the website repository in the config/_default/params.yaml file.

Append the mount to the manual_mounts key in the YAML configuration.

For example, mount the source content/docs/source-directory at content/docs/target-directory and exclude the content/docs/source-directory/_index.md file:
YAML
```
- source: content/docs/source-directory
  target: content/docs/target-directory
  excludeFiles:
    - /_index.md
```

Reuse shared content

Wed, 22 Feb 2023 16:13:40 +0000

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 you want to reuse in multiple pages.

Steps

To reuse shared content, follow these steps:

Create a shared directory

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 Grafana Labs values external contributions, prefer to share from an open source projects. 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.
In the sharing project, create the docs/sources/shared/ directory if it doesn’t exist.
In the sharing project, create the file docs/sources/shared/index.md if it doesn’t 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 repository, the directory structure looks similar to the following:
console
```
docs/sources/shared
└── index.md
```

Create a shared file

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 can’t look up 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 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
---
```
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 the docs/shared shortcode reference.
Verify the include.

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

Reuse content on Grafana Labs

Reuse directories of content with Hugo mounts

Reuse directories of content with Hugo mounts

Before you begin

Steps

Reuse shared content

Reuse shared content

Before you begin

Steps

Create a shared directory

Create a shared file