# writerside.cfg

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/writerside/llms.txt).

`writerside.cfg` is the main configuration file of a Writerside project. It is located in the root of the [help module](projects.html#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
<?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.

Parent elements
: [&lt;ihp&gt;](#ihp)

Attributes:

dir
: Specify the name of the directory where API specification files are stored. By default, it is `specifications/`.

##  <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
: [&lt;ihp&gt;](#ihp)

Attributes:

dir
: Specify the build configuration directory in the module root, that is, on the same level as `writerside.cfg`. For example: `<build-config dir="custom-cfg-dir"/>`.

##  <caps> 

Specify in which capitalization style to display titles.

```XML
<caps style="title" for="toc-element"/>
```

In this case, titles in the table of contents will be rendered in title case.

Parent elements
: [&lt;settings&gt;](#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`.

```XML
<categories src="c.list"/>
```

Parent elements
: [&lt;ihp&gt;](#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.

```XML
<default-property element-name="img" property-name="border-effect" value="line"/>
```

Parent elements
: [&lt;settings&gt;](#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
: [&lt;settings&gt;](#settings)

##  <ihp> 

This is the root element.

Child elements
: [&lt;api-specifications&gt;](#api-specifications) [&lt;build-config&gt;](#build-config) [&lt;categories&gt;](#categories) [&lt;images&gt;](#images) [&lt;instance&gt;](#instance) [&lt;instance-groups&gt;](#instance-groups) [&lt;module&gt;](#module) [&lt;settings&gt;](#settings) [&lt;snippets&gt;](#snippets) [&lt;topics&gt;](#topics) [&lt;vars&gt;](#vars)

Attributes:

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

##  <images> 

Specify the image directory settings.

Parent elements
: [&lt;ihp&gt;](#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.

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

Parent elements
: [&lt;ihp&gt;](#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.

versionName
: Specify the display name for the version in the version switcher.
:
:
:
: If not specified, the value of the `version` attribute is used.

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

##  <instance-groups> 

Specify the name of a file where instance groups are declared, e.g., `instance-groups.xml`.

Parent elements
: [&lt;ihp&gt;](#ihp)

Attributes:

src
: Specify the name of a file in the module root, that is, on the same level as `writerside.cfg`.

##  <module> 

Specify settings for the help module.

Parent elements
: [&lt;ihp&gt;](#ihp)

Attributes:

name
: Specify the name of the help module.

##  <settings> 

Specify additional help module settings.

Parent elements
: [&lt;ihp&gt;](#ihp)

Child elements
: [&lt;caps&gt;](#caps) [&lt;default-property&gt;](#default-property) [&lt;disable-web-name-preprocessing&gt;](#disable-web-name-preprocessing) [&lt;smart-ignore-vars&gt;](#smart-ignore-vars) [&lt;webstats-cache&gt;](#webstats-cache) [&lt;wrs-supernova&gt;](#wrs-supernova)

##  <smart-ignore-vars> 

Do not interpolate variables in code blocks and URLs.

By default, Writerside resolves `&percnt;var&percnt;` 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.

Parent elements
: [&lt;settings&gt;](#settings)

##  <snippets> 

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

Parent elements
: [&lt;ihp&gt;](#ihp)

Attributes:

src
: Specify a directory in the help module root.

##  <topics> 

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

Parent elements
: [&lt;ihp&gt;](#ihp)

Attributes:

dir
: Specify a directory in the help module root.

##  <vars> 

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

```XML
<vars src="v.list"/>
```

Parent elements
: [&lt;ihp&gt;](#ihp)

Attributes:

src
: Specify the file in the help module root.

##  <webstats-cache> 

Specify the webstats cache configuration. This allows you to show the view statistic for each topic.

The `enabled` attribute enables or disables the feature. The `location` attribute specifies the location of the webstats data. This can be a path to a file or a versioned resource.

```XML
<webstats-cache enabled="true" location="version:pageviews-20250101"/>
```

Parent elements
: [&lt;settings&gt;](#settings)

Attributes:

enabled
: Enable or disable the webstats cache.

location
: Specify the location of the webstats data.

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

```XML
<wrs-supernova use-version="2.1.1477-p3867"/>
```

Parent elements
: [&lt;settings&gt;](#settings)

Attributes:

use-version
: Specify the version of the help builder.