Variables
Last modified: 05 August 2024Variables 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:
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: %var%
.
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
:
<include from="lib.topic" element_id="save-options"/>
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
.
Thanks for your feedback!