Variables

Variables are named entities with a defined value that you can use across your documentation. Use them for things that must be consistent, such as the product or company name, version number, contact information.

Global variables

Declare global variables in the v.list file, for example:

            <vars>
                <var name="latest_version" value="1.8"/>
            </vars>
        

This variable will be available in all topics of the module with the v.list file.

                    <note>
                        <p>We recommend switching to the version %latest_version%.</p>
                    </note>
                

                    > We recommend switching to the version %latest_version%.
                    >
                    {style="note"}
                

Local variables

Declare a local variable in a topic or any specific element. It will exist only within this element. You can also override the value of a global variable if it should be different in some specific scope.

                    <var name="latest_version" value="2.0"/>

                    <note>
                        <p>Upgrade to the beta version %latest_version%.</p>
                    </note>
                

                    <var name="latest_version" value="2.0"/>

                    > Upgrade to the beta version %latest_version%.
                    >
                    {style="note"}
                

Built-in variables

Writerside includes several built-in variables:

%instance% is the name of the current instance, for example "Writerside"
%instance-lowercase% is the name of the current instance in lowercase, for example "writerside"
%currentId% is the ID of the current instance, for example "wrs"
%thisTopic% is the ID of the current topic, for example "Variables"

Variable interpolation

To escape a %var% variable and insert it literally, add a backslash after the first percent character: %\var%. Alternatively, you can use the HTML entity code instead of the percent character: &percnt;var&percnt;.

Some code blocks and URLs may have percent characters that should be used literally. However, by default Writerside tries to interpolate them as variables. To avoid this, add ignore-vars="true" to code blocks, external links, and image references:

            <code-block lang="console" ignore-vars="true">
                set PATH=c:\;%PATH%
            </code-block>
        

            <a href="https://www.w3schools.com/tags/ref_urlencode.ASP#:~:text=URL%20Encoding%20(Percent%20Encoding)"
               ignore-vars="true"/>
        

You can also change the default behavior using the <smart-ignore-vars> element in writerside.cfg.

Variables in snippets

If you use a variable in a <snippet>, set its value as a child of the <include> element.

            <snippet id="save-options">
                <var name="button" value="OK"/>

                Select the necessary options and click <control>%button%</control>.
            </snippet>
        

Here is how to include this snippet with the default value of OK:

Here is how you can include it with a different variable value:

            <include from="lib.topic" element_id="save-options">
                <var name="button" value="Save"
            </include>
        

Conditional variables

You can add filters to set different values for the same variable based on instance.

            <var name="product" value="MyWebApp" instance="web"/>
            <var name="product" value="MyMobApp" instance="mob"/>
        

When you add this %product% variable in reusable content throughout your documentation, it will resolve to MyWebApp for the web instance and to MyMobApp for the mob.

Last modified: 05 August 2024