Build groups

Last modified: 06 March 2025

In most cases, you build a single documentation instance, but sometimes you need to build several instances as one documentation website. This is when you need to configure a build group that defines the instances to be built.

Define build group

  1. Create a file named build-groups.xml in the cfg directory.

    You can right-click the cfg directory, then select New | build-groups.xml.

  2. Define one or several build groups, specifying the instance IDs that should be built together in each group. 

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE build-groups SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-groups.dtd">
<build-groups
        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-groups.xsd"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <build-group name="all-user-docs">
        <instance instance-id="ug" alias="User Guide" path="/userguide"/>
        <instance instance-id="cr" alias="Client Reference" path="/clientref"/>
    </build-group>

</build-groups>

You can select this build group in the local build configuration, when building with docker, or when automating the build and publication via GitHub, GitLab, or TeamCity.

When you build a group of instances, Writerside produces a ZIP archive with a separate directory for each instance and the index.html file in the root. The index file redirects from the root to the home page of the first documentation instance in the group.

If we consider the example build-groups.xml above, the all-user-docs group will produce an archive with the following:

  • Two directories: userguide with the ug instance website and clientref with the cr instance website.

  • index.html file in the root directory that redirects to the home page of the ug instance.

  • In each help instance, there will be a switcher with two items: User Guide to open the ug help instance website and Client Reference to open the cr help instance website.