Reuse pieces of content

To avoid writing the same content in different places, you can reuse any element by including it anywhere you need. Good candidates for content reuse are repeating notes and warnings, common instructions and references.

By reusing these elements, you ensure consistent wording and a single source for updating it everywhere.

Reuse single elements

Add the id attribute to any element, for example, a warning:
<warning id="generic-warning"> This version support ended on January 14, 2022. Download the latest version. </warning>
> This version support ended on January 14, 2022. > Download the latest version. > {style="warning" id="generic-warning"}
Insert it anywhere using the <include> element:
<include from="some.topic" element-id="generic-warning"/>

Reuse fragments with multiple elements

Surround the elements with <snippet> and assign a unique value for the id attribute:
<snippet id="prerequisites"> <p>Make sure you are logged in the account.</p> <img src="screenshot1.png" alt="Check login" border-effect="line" width="436"/> </snippet>
<snippet id="prerequisites"> Make sure you are logged in the account. ![Check login](screenshot1.png) {border-effect="line" width="436"} </snippet>
Markdown relies on blank lines to separate paragraphs from other elements. Put a blank line after the opening tag and before the closing tag.
Insert it anywhere using the <include> element:
<include from="some.topic" element-id="prerequisites"/>

Snippet library

Although you can reuse any element with an ID from one topic in another topic, it is better to store all reusable snippets in a dedicated library topic.

A library topic is a topic with the is-library="true" attribute. Do not include it in any instance and do not build it.

                    <topic title="Library" id="lib"
                           is-library="true">

                        <snippet id="generic-warning">
                            <warning>
                                This version support ended on January 14, 2022.
                                Download the latest version.
                            </warning>
                        </snippet>

                        <snippet id="prerequisites">
                            <p>Make sure you are logged in the account.</p>

                            <img src="screenshot1.png" alt="Check login" border-effect="line" width="436"/>
                        </snippet>
                    </topic>
                

                    # Library
                    {is-library="true"}

                    <snippet id="generic-warning">

                    > This version support ended on January 14, 2022.
                    > Download the latest version.
                    >
                    {style="warning"}

                    </snippet>

                    <snippet id="prerequisites">

                    Make sure you are logged in the account.

                    ![Check login](screenshot1.png) {border-effect="line" width="436"}

                    </snippet>
                

You can move a snippet from an ordinary topic to a library using the Move Snippet action.

Move snippet

Place the caret on the <snippet> element you want to move.
From the main menu, select Refactor | Move Snippet.
In the Move Snippet dialog, select the target library topic file and click OK.

Navigate to declaration

If you want to edit the source of the <include>, Ctrl+Click the element-id attribute value to navigate to this element.
Alternatively, press Ctrl+B with the caret on the element-id attribute value.

Find usages

If you want to see where a <snippet> or any other element is included, Ctrl+Click the id attribute value of the element.
Alternatively, press Ctrl+B with the caret on the id attribute value.

Filters and variables

Use filters to include only certain parts of the snippet. For more information, see Conditional content.

If there are variables defined in the snippet, set their values as child elements of the <include> element. For more information, see Variables in snippets.

Last modified: 05 August 2024