Topic and chapter labels

Use labels to mark a topic or chapter that describes a commercial or internal feature, something that is still in development, or applies to a specific version or technology. Labels help your readers understand at a glance whether content is relevant for them.

Each header can have only one primary label and multiple secondary labels. Your readers can hover over any label to see a tooltip with details about what the label means. If you define a URL for a primary label, readers can also click it to go to this URL, for example, to see a comparison of plans or editions.

Define labels

To define labels, add the labels.list file to the help module root next to writerside.cfg.

Here is an example of the labels.list file:

            <?xml version="1.0" encoding="UTF-8"?>
            <!DOCTYPE labels SYSTEM "https://resources.jetbrains.com/writerside/1.0/labels-list.dtd">
            <labels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/labels.xsd">
                <primary-label id="label" short-name="L" name="Label">
                    This is an example label
                </primary-label>

                <primary-label id="jetbrains" short-name="JB" name="JetBrains" href="https://www.jetbrains.com" color="red">
                    Go to www.jetbrains.com
                </primary-label>

                <secondary-label id="wip" name="WIP" color="purple">Work in progress</secondary-label>
                <secondary-label id="beta" name="β" color="tangerine">Beta</secondary-label>

                <secondary-label id="experimental" name="Experimental" color="purple">This is an experimental feature</secondary-label>
                <secondary-label id="2023.3" name="2023.3" color="blue">New in version 2023.3</secondary-label>
            </labels>
        

Use the <primary-label> and <secondary-label> elements to define labels.

Every label must have an id used to reference the label. The name defines the text that renders next to the header, while short-name is used for primary labels in the topic navigation block. Primary labels can also define a href to point to some URL when the reader clicks the label.

Use the color attribute to define the color of the label.

To set the tooltip text for a label, define it as text inside the element, between the opening and closing tags.

Insert labels

To use labels, add them as <primary-label> and <secondary-label> elements inside <topic> and <chapter>.

                    <topic title="Labels" id="labels">
                        <primary-label ref="label"/>
                        <secondary-label ref="wip"/>
                        <secondary-label ref="beta"/>
                        <p>
                            This is a labeled topic about some Beta version of an unfinished feature.</p>

                        <chapter title="Some chapter" id="some-chapter">
                            <primary-label ref="jetbrains"/>
                            <secondary-label ref="2023.3"/>
                            <secondary-label ref="experimental"/>
                            <p>
                                This chapter is marked with the JetBrains label,
                                applies to version 2023.3, and describes something experimental.</p>
                        </chapter>
                    </topic>
                

                    # Labels

                    <primary-label ref="label"/>
                    <secondary-label ref="wip"/>
                    <secondary-label ref="beta"/>

                    This is a labeled topic about some Beta version of an unfinished feature.

                    ## Some chapter

                    <primary-label ref="jetbrains"/>
                    <secondary-label ref="2023.3"/>
                    <secondary-label ref="experimental"/>

                    This chapter is marked with the JetBrains label,
                    applies to version 2023.3, and describes something experimental.
                

Last modified: 07 August 2024