Content Reuse

This page describes how to create reusable text files or code examples that can be added to multiple pages.

If there are sections of text or code examples that appear in more than one location in Chef’s documentation, that text should be sourced from a single file. Store these files in a headless subdirectory named reusable in the content directory and use the readfile shortcode to add the file text to a page.

reusable directory

Store reusable files in a subdirectory called reusable in the content directory. For example, content/server/reusable or content/workstation/reusable.

Make the reusable directory a headless bundle by adding an index.md file to the directory and add headless = true to the file’s front matter. This directory must be a headless bundle because it prevents Hugo from publishing this directory and its contents on https://docs.chef.io.

See the content/reusable/index.md file in chef-web-docs for an example of an index.md file that makes a headless bundle.

Reusable file organization

Store reusable text files in subdirectories organized by file type.

For example:

• content/server/reusable/md/FILENAME.md
• content/server/reusable/rb/RUBY_EXAMPLE.rb
• content/server/reusable/go/GO_EXAMPLE.go

readfile shortcode

The readfile shortcode adds text from a file to a page. You can add a Markdown file, HTML file, or code file by specifying the path to the file from the project root directory.

By default it accepts a Markdown file:

{{< readfile file="content/workstation/reusable/md/example.md" >}}

You can also add an HTML file:

{{< readfile file="content/workstation/reusable/html/example.html" html="true" >}}

You can pass in a sample code file:

{{< readfile file="content/workstation/reusable/rb/example.rb" highlight="ruby" >}}

or:

{{< readfile file="content/workstation/reusable/json/example.json" highlight="json" >}}

See the full list of highlighting languages and aliases that Hugo accepts.