Conditional content

When reusing topics or pieces of content, you can add conditions to customize content based on the current instance or any custom filter.

Filter by instance

If a topic is used in several instances, you can specify elements that should or should not be included when building a specific instance.

Add the instance attribute to any element and list the instances separated by commas in which this element should be included. If you want to exclude an element from some instances, precede the list with an exclamation mark !.
Use the <if> element to wrap multiple elements with a condition.
<chapter title="Included everywhere" id="included_everywhere"> This chapter and paragraph is included everywhere. <if instance="foo,bar"> This paragraph and the following image is filtered for instances `foo` and `bar`. <img src="image.png" alt="Image"/> </if> </chapter> <chapter title="Excluded from `foo`" id="excluded_from_foo_" instance="!foo"> This chapter is excluded from the instance `foo`. <if instance="bar">And this part of the paragraph is included only in `bar`.</if> </chapter>
## Included everywhere This chapter and paragraph is included everywhere. <if instance="foo,bar"> This paragraph and the following image is filtered for instances `foo` and `bar`. ![Image](image.png) </if> ## Excluded from `foo` {instance="!foo"} This chapter is excluded from the instance `foo`. <if instance="bar">And this part of the paragraph is included only in `bar`.</if>

Filter by custom conditions

When you include a snippet, you can specify custom filters that should apply for this specific include.

Add the filter attribute to any element in the snippet and specify a comma-separated list of custom filters.
<snippet id="os_dependent_procedure_steps"> <step>Do this first</step> <step filter="macos">Step for macOS</step> <step filter="windows">Step for Windows</step> </snippet>
Use the <if> element to wrap multiple elements with a condition.
Add the use-filter attribute when including the snippet.
<procedure title="Install on macOS" id="install"> <include from="lib.topic" element-id="os_dependent_procedure_steps" use-filter="empty,macos"/> </procedure> <procedure title="Install on Windows" id="install"> <include from="lib.topic" element-id="os_dependent_procedure_steps" use-filter="empty,windows"/> </procedure>
The empty value is a special designation for content without any filters, which means generic content that applies to all filters. If you want to include only the step marked with the macos filter, set use-filter="macos".

Conditional titles

You can use use filters to adjust titles in reusable topics, chapters, procedures, and any other elements with titles.

            <snippet id="connect-to-db">
                <procedure title="Connect to database">
                    <title instance="web">Connect to database in web application</title>
                    <title instance="mob">Connect to database in mobile application</title>
                    <title filter="mysql">Connection to MySQL</title>
                    <title filter="postgres">Connection to PostgreSQL</title>

                    <step>...</step>
                </procedure>
            </snippet>
        

Instance groups

If you have many instances because you are maintaining documentation for various products or editions, it may be convenient to group several instances into a group with a dedicated ID instead of always referencing the IDs one by one.

Define instance group

In your documentation module root, create a file for defining instance group IDs, for example:
<instance-groups> <group id="free" instances="a,b,c"/> </instance-groups>
In the writerside.cfg file, register this file as follows:
<instance-groups src="instance-groups.xml"/>
Reference this group as @free in the instance attribute, for example:
<if instance="@free">text only for free editions a, b, and c</if>

Last modified: 05 August 2024