Table of contents | Writerside Documentation

The table of contents (TOC) represents the structure of an instance. It is defined in a tree file using the <toc-element> tags.

Your readers see the TOC rendered in the left part of the published help website and can use it to navigate the sections and topics. By default, every topic also has an in-page TOC that renders on the right side of a topic page and shows first-level chapter titles.

As an author, you can use the Writerside tool window to see everything included in the current instance, add, remove, and move topics around. The TOC uses various icons and fonts to distinguish different types of TOC elements.

Writerside TOC	Generated help TOC

Regular TOC elements, which directly reference a topic file, are displayed without any icons and in regular font. Hover over it to see the associated topic file name.

If you hide a TOC element, Writerside will display it in gray font. Writerside will build the associated topic with the instance, but readers will not be able to navigate to it from the TOC, only through search or a direct link.

The Writerside tool window uses the following icons for various TOC element types:

	This TOC element is included from another instance. Hover over the TOC element to see where it is included from. For more information, see Reuse sections with multiple topics.
	This is the Home page of the current instance. It is where readers land when they open the URL to your help website root. For more information, see Define the home page.
	This TOC element is a wrapper – an empty TOC element without an associated topic file that is used to group other topics into a section. For more information, see Topic order and hierarchy.
	This TOC element references an external URL, not a topic file. Hover over the TOC element to see the URL. For more information, see Link a TOC element to an external URL.

In the TOC, you see the topic titles as they will be published, not the topic file names or topic IDs. If necessary, you can specify a TOC-only title or an instance-specific title. If you need to change the topic title, right-click the topic in the TOC and select Edit Title.

Open topic files

Double-click any item in the TOC to open the corresponding topic file in the editor.
If it is an empty wrapper, Writerside will navigate you to the relevant <toc-element> in the corresponding tree file.

Alternatively, you can click Synchronize TOC and Editor in the Writerside tool window toolbar to open the currently selected topic in the editor. This also works the other way: if the focus is on the editor with an open topic file, click Synchronize TOC and Editor to select the relevant item in the TOC.

Change topic order and hierarchy

Drag items around in the Writerside tool window.

You can also edit the tree file directly.

Edit tree file directly

Right-click the necessary instance in the Writerside tool window and select Open TOC File.
Alternatively, right-click any item in the TOC and select Go to TOC Element.

In the tree file, change the order and hierarchy of <toc-element> tags. For convenience, press Ctrl+Shift+Home to move a line up and Ctrl+Shift+End to move a line down.

You can also remove or add new <toc-element> tags and nest them inside each other to create hierarchy:

            
            <toc-element topic="Manage_a_documentation_project.topic">
                <toc-element topic="Create_a_project.topic"/>
            </toc-element>

Add existing topic file to TOC

In the Writerside tool window, select where you want to add the topic, then click New Topic and select Link Topic Files to TOC.
Writerside shows the list of topic files that exist in the project but are not yet added to the current instance.
Select the necessary topic from the list of existing topic files. You can start typing the name to filter the list.

For more information about content reuse, see Single sourcing and content reuse.

Define the home page

Every help website must have one topic designated as the home page. By default, when you add the first topic to an empty instance or when you import a project from Markdown sources, Writerside sets the first topic as the home page.

In the Writerside tool window, right-click any topic and select Set as Home Page.
The home page is defined by the start-page attribute of the root <instance-profile> element in the tree file.

Hide topic from TOC

You can include a topic in an instance, make it accessible by a direct link, but hide it from the TOC structure for your readers. This can be useful for reference topics or legal documents that are not directly related to any other of your content. You do not want them in the TOC, but you still want the information to be available and searchable by readers. Another example might be some feature still in development or no longer supported.

Open the tree file and add the hidden="true" attribute to the corresponding <toc-element>.
<toc-element topic="legal_info.topic" hidden="true"/>

Link a TOC element to an external URL

You can add a TOC entry that is not associated with a topic, but leads to an external URL, like your company's blog, support portal, or a comparison of paid plans. If the info on a subject is already documented elsewhere, there is no reason to duplicate it in your help as a topic: just put a link to it in the TOC.

Open the tree file and add a <toc-element> without an associated topic, but with the href attribute that specifies an external URL.
By default, Writerside will use the URL as the TOC entry title, but you can also give it a more readable title via the toc-title attribute.
<toc-element toc-title="JetBrains Writerside" href="https://www.jetbrains.com/writerside"/>

Topic order and hierarchy

You can drag items in the Writerside tool window around to change the order and hierarchy of topics. For example, drop a topic or multiple topics on another topic to create a section:

            <toc-element topic="getting_started.md">
                <toc-element topic="Installation.md"/>
                <toc-element topic="Configuration.md"/>
            </toc-element>
        

It is generally better to have such an introductory topic for a group of subtopics. You can use a section starting page to create an overview topic for a section.

However, if you do not want any introduction for a group of topics, nest them under a wrapper TOC element. A wrapper has a TOC title and no associated topic file. When readers click an empty wrapper element in the TOC, it expands the corresponding section of the TOC and does not open any topic.

As wrappers do not have an associated topic file, they also do not produce any URL reference, so they do not accept such attributes as accepts-web-file-names.

Create empty section

In the Table of Contents pane of the Writerside tool window, click New Topic | Section.
In the New Section dialog, specify the TOC title for the section.

Writerside will create a <toc-element> in the tree file with the specified TOC title and no associated topic file:

<toc-element toc-title="Getting started"/>

In the Table of Contents pane of the Writerside tool window, the new section will be designated with the icon.

Group topics

Select the topics that you want to group, right-click and then click Group.
In the New Group dialog, specify a name for the group and press Enter.

In the tree file, Writerside will wrap the TOC elements of the selected topics with a wrapper TOC element:

                <toc-element toc-title="Getting started">
                    <toc-element topic="Installation.md"/>
                    <toc-element topic="Configuration.md"/>
                </toc-element>
            

Sort child topics alphabetically

After you add multiple topics to a section, you may want to sort them. For example, if the section has topics for various commands or options, it is usually more convenient to sort them alphabetically.

In the Writerside tool window, right-click any TOC element with child topics and select Sort Child Topics Alphabetically.

Last modified: 06 December 2024