Instances

An instance is a set of content files (topics) organized into a hierarchical structure (table of contents) in a tree file with a unique ID. You build an instance into a single help website, user guide, or some other output.

By default, a typical Writerside documentation project contains one instance. Add more instances if you need to produce multiple help outputs, for example, to document several products or editions of a product, produce documentation for different audiences, types of users, or output formats. You can reuse any content in your documentation project across instances. For more information, see Single sourcing and content reuse.

Add help instance

In the Writerside tool window, right-click the current help instance name, select New Instance, and click New.
If you have existing documentation authored in Markdown, click From Local Markdown Files to import them as a new instance.
Specify a name, which will be the main title of the produced output. If necessary, modify the proposed instance ID.
Make sure that the ID of every instance is unique and descriptive. It will be used as the name of the .tree file and you will use this ID to filter reusable content.
If necessary, specify other settings:
Webpath
Setting the web path can help during publication to upload the help website to the proper location.
Version
The version will be displayed next to the main help title.
Allow search engine indexing
Let search engines crawl and index the content of your help website. For more information, see Allow search engine indexing.
Offline artifact
Add all resources, such as the frontend application, styles, fonts, and favicons to the built artifacts so that documenation is self-contained, does not depend on external resources, and can be used in an isolated environment with no internet access. For more information, see Offline documentation.
Click OK.

As a result, Writerside will create a new tree file (like web.tree or whatever ID you specified) and register it in writerside.cfg as <instance src="web.tree"/>. You will see the new instance in the Writerside tool window.

Change instance icon color

To clearly distinguish instances from each other in the Writerside tool window, you may want to assign different color icons.

Right-click an instance and select the color that you want under Change Color.

Rename instance

In the Writerside tool window, right-click an instance and select Edit. .
Specify a new name for the instance and click OK.

Do not change the ID if it is not necessary. If you do change the ID, Writerside will find all references to this instance ID and suggest running the Rename refactoring to properly update all usages. It will also rename the corresponding .tree file. However, it will not update any of your publication scripts, so make sure you configure them correctly with the new instance ID.

Tree file

A tree file defines the hierarchical structure of topics in an instance. Here is a sample tree file that defines an instance with ID aug and name App User Guide:

            <?xml version="1.0" encoding="UTF-8"?>
            <!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">

            <instance-profile id="aug" name="App User Guide"
                              start-page="introduction.topic">

                <toc-element topic="introduction.topic"/>

                <toc-element topic="settings.topic">
                    <toc-element topic="settings_general.topic"/>
                    <toc-element topic="settings_advanced.topic"/>
                </toc-element>

                <include from="lib.tree" element-id="reference"/>
            </instance-profile>
        

A tree file can contain the following elements and attributes:

<include>

Reuse a part of another tree file.

Parent elements: <instance-profile> <toc-element>

Attributes:

element-id: Specify the element ID.
from: Specify the tree file from which you want to include content.
instance: Specify the conditions for an element. For example, you can define the help instances to which this element applies, and then it will not be present for other help instances. Or you can negate with ! to specify help instances from which to exclude this element:
<include from="lib.tree" element-id="reference" instance="!foo,bar"/>
origin: If you want to include something from a tree file in another help module, specify it as the origin.
use-filter: Insert content with conditions: only content marked by the specified custom filters, separated with commas, will be included.

<instance-profile>

This is the root element of a tree file.

Child elements: <include> <snippet> <toc-element>

Attributes:

id

Specify the unique ID of this instance.

is-library

Specify whether this is a library of reusable TOC snippets rather than a regular instance tree file.

name

Specify the name of this instance, which is used as the main title for the output.

start-page

Specify the topic that will open by default when the reader navigates to the root URL of your help website.

status

Specify the status of the instance

release is the default status that produces regular output.
deprecated is for outdated documentation. The output with this status will have a banner on every page warning your readers that the documentation is outdated or describes an old version of your product.
eap is for documentation still in development. The output with this status will have a banner on every page warning your readers that the documentation is subject to change. This may be because the documentation itself is not finished or it describes a product not in its final form, like an early access build or a beta version.

<snippet>

Define a chunk of a tree file hierarchy to reuse in other instances using the <include> element.

                <snippet id="intro">
                    <toc-element topic="getting_started.topic"/>
                    <toc-element topic="installation_guide.topic"/>
                    <toc-element topic="first_run.topic"/>
                </snippet>
            

It is recommended to keep all reusable tree chunks in a dedicated tree file that is not a published instance.

Parent elements: <instance-profile> <snippet> <toc-element>
Child elements: <include> <snippet> <toc-element>

Attributes:

filter: Specify a custom filter for an element. When defining a <snippet>, filter out content according to some criteria, and then specify the use-filter attribute on an <include> to reuse this snippet in different contexts.
id: Specify an identifier for the snippet.
instance: Specify the conditions for an element. For example, you can define the instances to which this element applies, and then it will not be present for other instances. Or you can negate with ! to specify help instances from which to exclude this element.

<toc-element>

Add an entry to the TOC.

This is usually a topic:

<toc-element topic="getting_started.topic"/>

Parent elements: <instance-profile> <snippet> <toc-element>
Child elements: <include> <snippet> <toc-element>

Attributes:

accepts-web-file-names

Specify an HTML page to create a redirect from it to this TOC entry. For example, if you removed a topic that produced some-topic.html from your published output, you probably want to add a redirect to some other related topic, so that readers with a direct link do not see just a 404 error.

<toc-element topic="related.topic" accepts-web-file-names="some-topic.html"/>

You can specify multiple HTML pages by separating them with commas.

accepts-web-file-names-ref

Specify a redirection rule ID from redirection-rules.xml.

filter

Specify a custom filter for an element. When defining a <snippet>, filter out content according to some criteria, and then specify the use-filter attribute on an <include> to reuse this snippet in different contexts.

hidden

Hide this entry from the TOC. The reader will still be able to access the associated topic with a link, but it will not have an entry in the TOC.

<toc-element topic="reference.topic" hidden="true"/>

href

Specify a URL to create a TOC entry that opens this URL instead of a topic.

id

Specify an identifier for the TOC element.

in

Specify another instance to create a reference to a topic in that instance. Used together with <ref>.

<toc-element ref="some.topic" in="ug"/>

instance

Specify the conditions for a reusable TOC chunk. For example, you can define the instances to which this element applies, and then it will not be present for other instances. Or you can negate with ! to specify help instances from which to exclude this element.

origin

If you want to include a topic from another help module, specify the module as the origin.

ref

Create a reference to a topic in another instance. Used together with <in>.

<toc-element ref="some.topic" in="ug"/>

target-for-accept-web-file-names

Specify a URL to create a redirect from an HTML page specified as accepts-web-file-names.

toc-title

Specify the title for the TOC entry if the topic title itself is too long.

topic

Specify the topic to associate with this TOC element.

Last modified: 05 August 2024