Writerside Help

writerside.cfg

writerside.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.

Here is a simple example config file that defines directories for topics and images as well as two help instances:

<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:

<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/.

Parent elements

<ihp>

Attributes:

dir

Specify the directory relative to the writerside.cfg file. For example: <build-config dir="custom-cfg-dir"/>.

<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.

Parent elements

<settings>

Attributes:

for

Specify the elements for which you want to apply the capitalization style, such as toc-element, topic, or chapter.

style

Choose between sentence, title, and aswritten.

<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"/>
Parent elements

<ihp>

Attributes:

src

Specify the name of the file.

<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"/>
Parent elements

<settings>

Attributes:

element-name

Specify which elements the attribute will be applied to.

property-name

Specify the attribute name to which this default value will be applied.

value

Specify the default attribute value.

<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>.

Parent elements

<settings>

<ihp>

This is the root element.

Child elements

<build-config> <categories> <images> <instance> <module> <settings> <snippets> <topics> <vars>

Attributes:

version

Set the global version for all help instances in this help module.

<images>

Specify the image directory settings.

Parent elements

<ihp>

Attributes:

dir

Specify the name of the directory where media files (images, GIFs, and videos) are stored. By default, it is images/.

version

Specify the image set version.

web-path

Specify the path where images should be located once the help instance is built.

<instance>

Specify the settings for a help instance.

<instance src="pd.tree" web-path="/plugin-developers/" version="main"/>
Parent elements

<ihp>

Attributes:

keymaps-mode

Specify the mode for the keymap file:

  • none if there is no keymap file

  • generated if the keymap file is automatically generated

  • provided if the keymap file is configured manually

src

Specify the .tree file name of the help instance.

version

Specify the help instance version displayed in the website header.

web-path

Specify the path that will be the last part of the URL for a particular help instance after it is built.

<module>

Specify settings for the help module.

Parent elements

<ihp>

Attributes:

name

Specify the name of the help module.

<settings>

Specify additional help module settings.

Parent elements

<ihp>

Child elements

<caps> <default-property> <disable-web-name-preprocessing> <wrs-supernova>

<snippets>

Specify the name of the directory where you put code snippets.

Parent elements

<ihp>

Attributes:

src

Specify a directory relative to the help module root.

<topics>

Specify the name of the directory where topic files are located. By default, it is topics/.

Parent elements

<ihp>

Attributes:

dir

Specify a directory relative to the help module root.

<vars>

Specify the name of the file where you put variables and their values. By default, it is v.list.

<vars src="v.list"/>
Parent elements

<ihp>

Attributes:

src

Specify the file relative to the help module root.

<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"/>
Parent elements

<settings>

Attributes:

use-version

Specify the version of the help builder.

Last modified: 26 March 2024