Content reuse

In this article

Important

Our current content reuse strategy is based on AsciiDoc (guidelines forthcoming). The following information is deprecated, but may be useful in the meantime.

Liquid and Markdown includes are a useful way to produce chunks of documentation content that must be reused in several documentation articles. They make content maintenance much easier while reducing documentation update errors since modifications are only made to a single document.

Depending on your use case, you can use the following to create Liquid and Markdown includes.

Warning

Do not use the include_relative directive, and never put includes in the collection folder. Markdown and liquid includes must be located in a clearly named folder within the _includes/md-includes/ folder.

  1. In the Doc_Jekyll-Public-Site project, in the _includes folder, locate or create an appropriate folder for your article or topic, and create a new file.

  2. Give the file a significant name that clearly describes its content or purpose, and then, depending on your needs, use the .liquid or .md file extension.

  3. In the file that you just created, write the content that you want to reuse.

  4. At the exact place in the Markdown files where the reusable content should be displayed, use the following syntax to add the reusable content:

    {% include /md-includes/<FOLDER>/<NAME_OF_THE_FILE>.<FILE_EXTENSION> %}

  5. Save the Markdown file in which you added the include to see the new content.

Limitations

While being an efficient way to reuse content throughout our documentation, Liquid and Markdown includes have their limitations:

  • Integrating an include in an article can sometimes be tedious, especially when the include must be added to a list and/or contains divs (for example, note boxes). To facilitate the include integration, you should avoid using them for large walls of text. You should rather divide the content to reuse into multiple includes.

  • In a markdown (.md) file, where you must use a liquid include to create a note box within a bulleted list, create the note box in the article itself, and only create a liquid include for the content within the note box. Otherwise, the note box won’t align or render properly within the bulleted list.

  • Since the documentation team will eventually migrate the project repository to AsciiDoc, you must avoid using any kind of logic in your includes. If you need to use logic in your include, it may not be the right solution for your current use case.

  • If you’re performing a global 'search & replace' in the product documentation, the information that is specified in your liquid includes won’t show up in your search results.