# Instances

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

An instance is a set of content files ([topics](topics.html)) organized into a hierarchical structure ([table of contents](table-of-contents.html)) 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](projects.html) 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](single-sourcing.html).

Procedure: Add help instance

1. In the  Writerside tool window , right-click the current help instance name, select New Instance, and click New.

![Create a new instance](https://resources.jetbrains.com/help/img/writerside/create-a-new-instance.png)

> **Note:**
> If you have existing documentation authored in Markdown files, click From Local Markdown Files to import them as a new instance.

2. Specify a name, which will be the main title of the produced output. If necessary, modify the proposed instance ID.

![The New Instance dialog](https://resources.jetbrains.com/help/img/writerside/create-instance-2.png)

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](conditional-content.html).

3. If necessary, specify other settings:

Webpath
: Setting the web path can help during publication to upload the help website to the proper location. For more information, see [web-path](writerside-cfg.html#instance_web-path).

Version
: The version will be displayed next to the main help title in the header. For more information, see [version](writerside-cfg.html#instance_version).

Allow search engine indexing
: Let search engines crawl and index the content of your help website. For more information, see [Allow search engine indexing](allow-search-engine-indexing.html).

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](offline-documentation.html).

4. 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](writerside-cfg.html)`  as `<instance src="web.tree"/>`. You will see the new instance in the  Writerside tool window.

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

Procedure: Rename instance

1. In the  Writerside tool window , right-click an instance and select Edit.

2. 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
<?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:

### <instance-profile>

This is the root element of a tree file.

Child elements
: [&lt;include&gt;](#include) [&lt;snippet&gt;](#snippet) [&lt;toc-element&gt;](#toc-element)

Attributes:

id
: Specify the unique ID of this instance.

is-library
: Specify whether this is a library of [reusable TOC snippets](reuse-topics.html#reuse-section) 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.

### <toc-element>

Add an entry to the TOC.

This is usually a topic:

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

Parent elements
: [&lt;instance-profile&gt;](#instance-profile) [&lt;snippet&gt;](#snippet) [&lt;toc-element&gt;](#toc-element)

Child elements
: [&lt;include&gt;](#include) [&lt;snippet&gt;](#snippet) [&lt;toc-element&gt;](#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.
:
:
:
:
:
:
: ```XML
: <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](help-modules.html#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.
:
:
:
:
: ```XML
: <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 [&lt;ref&gt;](#toc-element_ref).
:
:
:
:
:
:
: ```XML
: <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 [&lt;in&gt;](#toc-element_in).
:
:
:
:
:
:
: ```XML
: <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`. Since this is a redirect, the TOC element itself must [be hidden](#toc-element_hidden) and should not reference any topic or external link.
:
:
:
:
: ```XML
: <toc-element toc-title="Redirect to some URL" hidden="true"
: accepts-web-file-names="some-old-page.html"
: target-for-accept-web-file-names="https://www.jetbrains.com/help/idea/some-new-page.html"/>
:
: ```

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.

wip
: Mark this TOC item as "work-in-progress". If you set `wip="true"`, the TOC item will render with an icon and a tooltip that says `Will be available soon`.

### <include>

Reuse a part of another tree file.

```XML
<include from="lib.tree" element-id="intro"/>
```

Parent elements
: [&lt;instance-profile&gt;](#instance-profile) [&lt;toc-element&gt;](#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:
:
:
:
:
: ```XML
: <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.

### <snippet>

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

```XML
<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
: [&lt;instance-profile&gt;](#instance-profile) [&lt;snippet&gt;](#snippet) [&lt;toc-element&gt;](#toc-element)

Child elements
: [&lt;include&gt;](#include) [&lt;snippet&gt;](#snippet) [&lt;toc-element&gt;](#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.