writerside.cfg
Last modified: 31 January 2025writerside.cfg is the main configuration file of a Writerside project. It is located in the root of the help module and defines the help instances and locations of various configuration and content files.
note
In older versions of Writerside, the name of this file was project.ihp. If you have the old name in your project, there is no need to rename it, because they are equivalent.
Here is a simple example config file that defines directories for topics and images as well as two help instances:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
<ihp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/writerside-cfg.xsd">
<topics dir="topics"/>
<images dir="images"/>
<instance src="ug.tree"/>
<instance src="ag.tree"/>
</ihp>
writerside.cfg can contain the following elements and attributes:
<api-specifications>
Specify the designated directory for API specifications.
Attributes:
<build-config>
Specify the name of the directory for build configuration files, such as buildprofiles.xml
and build-script.xml
. By default, it is set to cfg/
.
Attributes:
<caps>
Specify in which capitalization style to display titles.
<caps style="title" for="toc-element"/>
In this case, titles in the table of contents will be rendered in title case.
Attributes:
<categories>
Specify the name of the file where you put the list of categories for grouping related links in the seealso section. By default, it is c.list
.
<categories src="c.list"/>
Attributes:
<default-property>
Specify the default properties for the particular markup elements. This setting is applied to all topics unless you explicitly override it by defining it on the topic level.
<default-property element-name="img" property-name="border-effect" value="line"/>
Attributes:
<disable-web-name-preprocessing>
Specify whether web file names should be normalized. By default, Writerside replaces all special characters with hyphens and lowercases all other characters in the topic file name to produce a normalized web file name. For example, My___Awesome.topic
becomes my-awesome.html
.
If you want to keep the web file names similar to topic file names (only replace characters that are not allowed in URLs), set <disable-web-name-preprocessing>true</disable-web-name-preprocessing>
.
<ihp>
This is the root element.
Attributes:
<images>
Specify the image directory settings.
Attributes:
<instance>
Specify the settings for a help instance.
<instance src="pd.tree" web-path="/plugin-developers/" version="main"/>
Attributes:
<instance-groups>
Specify the name of a file where instance groups are declared, e.g., instance-groups.xml
.
Attributes:
<module>
Specify settings for the help module.
Attributes:
<settings>
Specify additional help module settings.
<smart-ignore-vars>
Do not interpolate variables in code blocks and URLs.
By default, Writerside resolves %var%
variables in code blocks, links to URLs, and external image references, unless the user sets ignore-vars="true"
.
Set <smart-ignore-vars>true</smart-ignore-vars>
to change the default behavior and insert variables literally without interpolating them. In this case, you can set ignore-vars="false"
on code blocks, external links, and image references where you want to resolve the variables.
<snippets>
Specify the name of the directory where you put code snippets.
Attributes:
<topics>
Specify the name of the directory where topic files are located. By default, it is topics/
.
Attributes:
<vars>
Specify the name of the file where you put variables and their values. By default, it is v.list
.
<vars src="v.list"/>
Attributes:
<wrs-supernova>
Specify the version of the Docker help builder in the 'use-version' attribute. Your CI/CD scripts can use this value to determine which builder version should be used. For example:
<wrs-supernova use-version="2.1.1477-p3867"/>
Attributes:
Thanks for your feedback!