Semantic markup reference

<a>

Add a hyperlink to another topic or an arbitrary URL. The link can be plain text, an image, a shortcut, or a property value.

Link to a topic and render the topic title as the text of the link:

Link to a topic and specify the text of the link:

Link to a specific anchor in the target topic:

<a href="my-topic.topic" anchor="intro">Link to anchor</a>

An anchor can be any element's id attribute or an explicit <anchor> element with a name.

You can omit the href attribute when linking to an anchor inside the same topic.

Set nullable="true" to render just the link text without the actual hyperlink if the target topic is not available when building your help. Otherwise, the target topic must exist to avoid build failures.

To add an external hyperlink, specify the full target URL in the href attribute:

<a href="https://www.jetbrains.com">Link to the JetBrains website</a>

Attributes:

anchor

Specify the ID of an element from the target topic. For example, if you want to link to a specific chapter. You can also use standard URL notation for anchors:

caps

Specify the capitalization style. The builder will automatically apply the style to make this title, for example, sentence case or all upper case.

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.

href

Specify the link target: either a topic file name or an external URL.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

ignore-vars

Do not treat two percent characters with text between them %foo% as Writerside variables.

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

nullable

Render just the link text without the actual hyperlink if the target topic is not available when building your help. For example, if a referenced topic is included only in one help instance, then you do not want a non-working link for the other help instance.

origin

If you want to include or reference something from another help module, specify this module as the origin.

summary

Override the link summary. By default, when you hover over an internal link, Writerside shows a popup with the first paragraph of the target topic or chapter. You can also use the <link-summary> element inside the topic or chapter to define a different link summary. This attribute will override everything for this specific link.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

target-switcher-key

Specify the switcher-key from the target topic, if you want the link to open with a non-default switcher value.

type

Specify the type of the card in the spotlight group of a section starting page. The card type defines the icon used for it.

This does not affect regular links.

<anchor>

DEPRECATED: use the id attribute on the relevant element instead.

Add an anchor to which you can create a hyperlink.

Parent elements: <topic>

Attributes:

name: DEPRECATED: use the id attribute on the relevant element instead.

<api-doc>

Generate API reference from an OpenAPI specification file. You can generate a full reference or only the operations marked with a specific tag.

Here is how to generate the full API reference:

<api-doc openapi-path="path/to/file.yaml"/>

Here is how to generate a reference of operations marked with the User tag:

<api-doc openapi-path="path/to/file.yaml" tag="User"/>

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <topic>
Child elements: <api-endpoint>

Attributes:

depth

Specify the maximum header level allowed in the topic navigation component.

display-links-if-available

Specify whether to display links to corresponding API schema objects when possible.

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.

generate-samples

Generate request samples automatically.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

openapi-path

Specify the path to the OpenAPI specification.

tag

Generate API reference only for operations marked with this tag.

<api-endpoint>

Generate a reference for a single API endpoint and its HTTP method (operation).

<api-endpoint openapi-path="path/to/file.yaml" endpoint="/users" method="GET"/>

You can generate a reference for several endpoints and methods. In this case, put them inside the <api-doc> element to define the path to the spec only once:

    <api-doc openapi-path="path/to/file.yaml">
        <api-endpoint endpoint="/users" method="GET"/>
        <api-endpoint endpoint="/users" method="POST"/>
    </api-doc>
                    

By default, Writerside generates request and response samples from the spec. You can provide custom samples inside the <api-endpoint> tag using <request> and <response> tags. To prevent generating samples without the need to provide custom ones, set the generate-samples attribute to none:

<api-endpoint endpoint="/users" method="GET" generate-samples="none"/>

You can also one of the following values:

ALL (default) - generate samples for all requests and responses
REQUEST - generate samples for requests only
RESPONSE - generate samples for responses only
NONE - do not generate samples

<api-endpoint endpoint="/users" method="GET" generate-samples="request"/>

You can also specify the depth of the generated reference using the depth attribute. The depth defines how many levels of nested objects to include in the reference. The default value is null (all levels).

<api-endpoint endpoint="/users" method="GET" depth="null"/>

Parent elements: <api-doc> <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <topic>
Child elements: <request> <response>

Attributes:

depth

Specify the maximum header level allowed in the topic navigation component.

display-links-if-available

Specify whether to display links to corresponding API schema objects when possible.

endpoint

Specify the endpoint for which you want to generate reference.

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.

generate-samples

Generate samples of requests and responses from the specification.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

method

Specify the method for which you want to generate reference.

openapi-path

Specify the path to the OpenAPI specification.

<api-schema>

Define data objects or schemas within your API documentation. This tag is particularly useful for documenting the structure and details of nested data objects.

The <api-schema> tag accepts several attributes to provide context and reference to external specifications:

openapi-path: specifies the path to an OpenAPI file with schema definitions.
name: defines the schema name as it is defined in components.schemas (for openAPI 3.0) or definitions (for swagger 2.0).

<api-schema openapi-path="path/to/spec.yaml" name="User"/>

The previous example will generate a reference for the User object.

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <topic>

Attributes:

depth

Specify the maximum header level allowed in the topic navigation component.

display-links-if-available

Specify whether to display links to corresponding API schema objects when possible.

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

name

Specify the schema name as it is defined in components.schemas (for openAPI 3.0) or definitions (for swagger 2.0).

openapi-path

Specify the path to the OpenAPI specification with schema definitions.

NO DESCRIPTION

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

<card-summary>

Add a summary of the topic that will be displayed for cards in a <section-starting-page>. By default, it will render the first paragraph of a topic. However, if you want to override it, define a <card-summary>.

    <topic title="Foo" id="foo">
        <card-summary>
            This topic is about Foo.
            This text will not render in the topic.
            It is used only in the link popup.
        </card-summary>
    
        ...
    </topic>
                    

You can use an existing element with an id as a summary (for example, any paragraph). To do this, refer to the id using the rel attribute in <card-summary>:

    <topic title="Foo" id="foo">
        <p id="intro">
            This topic is about Foo.
            This text will render as a regular paragraph.
        </p>
    
        <card-summary rel="intro"/>
    </topic>
                    

Parent elements: <if> <snippet> <topic>
Child elements: <if> <include> <snippet> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

rel

Specify an ID of a paragraph to use as a <link-summary>, <card-summary>, or <web-summary> instead of the default first paragraph.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<cards>

Add a custom group of links to topics that you would additionally like to list on the starting page of the section. This is a child of the <misc> element in a <section-starting-page>. A group of cards must have a <title> and may have any number of links, but preferably keep them between 2 and 6.

    <misc>
        <cards narrow="false">
            <title>Other tools</title>
            <a href="copy_cat.topic" description="Copy any text from any document.">Copy Cat</a>
            <a href="paste_dog.topic" description="Paste anything from the clipboard history.">Paste Dog</a>
            ...
        </cards>
    </misc>
                    

You can set narrow="true" to render three cards in a row.

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary, unless the topic has a <card-summary> element defined.

Parent elements: <misc>

Attributes:

narrow: Use three narrow columns for links instead of the default two wide columns.

<category>

Specify the category for a group of links in the <seealso> section.

Parent elements: <if> <seealso> <snippet>
Child elements: <a> <include> <resource> <snippet>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

ref

Reference the category by its ID.

sorted

Automatically sort items in a list or table when building your help instance.

<chapter>

Add a chapter with a title and an identifier.

    <chapter title="Do a barrel roll" id="barrel-roll">
        <p>Whenever you are not sure what to do, try a barrel roll first, then ask for help.</p>
    
        ...
    </chapter>
                    

You can set the title as a child element <title>, for example, if you want to have a custom chapter title depending on the product:

    <chapter title="Do a barrel roll" id="barrel-roll">
        <title instance="anotherApp">Do another barrel roll</title>
        <p>Whenever you are not sure what to do, try a barrel roll first, then ask for help.</p>
    
        ...
    </chapter>
                    

You can add subchapters inside chapters. The header level of the chapter depends on the chapter level.

To collapse a chapter by default, set default-state="collapsed". To make an expanded chapter collapsible, set default-state="expanded".

Attributes:

caps

Specify the capitalization style. The builder will automatically apply the style to make this title, for example, sentence case or all upper case.

collapsible

Make the chapter, procedure, or deflist collapsible. By default, the element will appear collapsed with an icon to expand it.

default-state

By default, all items of a collapsible definition list are collapsed. Override this if you want some items to be expanded by default.

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

level

Specify the heading level from 2 to 6. It is not recommended to set the heading level explicitly because it will break the natural chapter hierarchy, making it harder to follow structured content.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

title

Specify the title.

<code>

Format inline code fragments. Use it to format names of keywords, variables, functions, methods, classes, properties, commands, and so on.

Use the <code>foo()<code> method to do something cool.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<code-block>

Add a code fragment as a block of code. Use the lang attribute to define the language of the code block:

    <code-block lang="java">
        public class Main {
            public static void main() {
                System.out.println("Here is some sample Java code.");
            }
        }
    </code-block>
                    

This will inject the code block adding code highlighting, formatting, and any other available language-specific coding assistance. It will also let the build engine know how to highlight this block in the output. If you want a plain-text block, set lang="plain text". If you don't want to inject the code in the editor (for example, it's not a complete piece of code, which produces syntax errors), but still want to have proper highlighting for the specified language in the output, set noinject="true".

Parent elements: <chapter> <compare> <def> <if> <li> <procedure> <snippet> <step> <tab> <tabs> <td> <topic>

Attributes:

collapsed-title

Specify text to display when the code block is collapsed.

collapsed-title-line-number

Specify the line number with text to display when the code block is collapsed.

collapsible

Make the chapter, procedure, or deflist collapsible. By default, the element will appear collapsed with an icon to expand it.

default-state

By default, all items of a collapsible definition list are collapsed. Override this if you want some items to be expanded by default.

disable-links

Do not treat triple square brackets as links [[[JetBrains website|https://www.jetbrains.com]]].

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

ignore-vars

Do not treat two percent characters with text between them %foo% as Writerside variables.

include-lines

Specify line numbers from the source file to include in the code block.

include-symbol

Specify a class, method, or another symbol from the source file to include in the code block.

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

lang

Specify the language for highlighting in this sample.

noinject

Do not inject the code. By default, Writerside injects the specified language in the editor to highlight, validate, and provide various assistance features directly in the code block element. If the code sample is not complete and valid, it will show a syntax error. To avoid this, do not inject incomplete code samples by specifying noinject="true".

prompt

Specify a non-selectable prompt marker to use for rendering the code block.

For example, if the code block shows interaction with the command line, specify a prompt that indicates the operating system or interpreter language, such as prompt=">>>" or prompt="$". You can also indicate the current expected location context, such as the host name and directory, for example: promt="username@hostname current-dir $".

If the code block contains a runnable command, the prompt marker will help your readers understand this, but it will not be copied with the command.

show-white-spaces

Show spaces and tabs in the code block.

src

Specify the source file with code that you want to include in the code block.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

validate

Validate the code block when building the help instance.

<compare>

Display two code blocks next to each other for comparison:

    <compare>
        <code-block lang="java">
            public static void main(String[] args) {
                System.out.println("Hi!");
            }
        </code-block>
        <code-block lang="kotlin">
            @JvmStatic fun main(args: Array<String>) {
                println("Hi!")
            }
        </code-block>
    </compare>
                    

By default, this displays the two code blocks side-by-side with the first one titled "Before" and the second one titled "After". Use the type attribute to change the arrangement to top-bottom. Use the first-title and second-title attributes to change the titles.

    <compare type="top-bottom" title-before="Java" title-after="Kotlin">
        <code-block lang="java">
            public static void main(String[] args) {
                System.out.println("Hi!");
            }
        </code-block>
        <code-block lang="kotlin">
            @JvmStatic fun main(args: Array<String>) {
                println("Hi!")
            }
        </code-block>
    </compare>
                    

Parent elements: <chapter> <if> <li> <snippet> <step> <tab> <td> <topic>
Child elements: <code-block>

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.

first-title

Specify the title for the first code block in the comparison.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

second-title

Specify the title for the second code block in the comparison.

style

DEPRECATED: Use type instead.

Specify the layout of the comparison block: left-right or top-down.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

type

Specify the layout of the comparison block: left-right or top-down.

<contribute-url>

Specify the link for the dedicated topic to the documentation source where users can contribute, for example, a public GitHub repository. It must point to the folder where the topic is located.

If the link points to GitHub, the corresponding icon will be displayed.

Example:

    <contribute-url>https://github.com/JetBrains/intellij-sdk-docs/edit/main/topics/intro</contribute-url>
                    

Parent elements: <topic>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

<control>

Add a GUI element label, such as a button, a checkbox, or a dialog title.

<p>To show the recipe, select <control>Show recipe</control> and click <control>OK</control>.</p>

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<def>

Add a definition entry in a <deflist> with a mandatory title attribute (the name of the term).

    <deflist>
        <def title="Foo">Description of "Foo"</def>
        <def title="Bar">Description of "Bar"</def>
        <def title="Baz">Description of "Baz"</def>
    </deflist>
                    

Attributes:

collapsible

Make the chapter, procedure, or deflist collapsible. By default, the element will appear collapsed with an icon to expand it.

default-state

By default, all items of a collapsible definition list are collapsed. Override this if you want some items to be expanded by default.

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

title

Specify the title.

<deflist>

Add a list of terms with their corresponding definitions (descriptions):

    <deflist>
        <def title="Foo">Description of "Foo"</def>
        <def title="Bar">Description of "Bar"</def>
        <def title="Baz">Description of "Baz"</def>
    </deflist>
                    

A definition list is preferable to a table with two columns (name and description) or a simple unordered list of terms and descriptions.

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>
Child elements: <def> <if> <include> <snippet> <title> <var>

Attributes:

collapsible

Make the chapter, procedure, or deflist collapsible. By default, the element will appear collapsed with an icon to expand it.

default-state

By default, all items of a collapsible definition list are collapsed. Override this if you want some items to be expanded by default.

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

sorted

Automatically sort items in a list or table when building your help instance.

style

DEPRECATED: Use type instead.

Specify the ratio of the definition and description widths.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

type

Specify the width ratio between the definition and description.

type="full": render the definition title on a separate line (default)
type="wide": render the definition title and the description side-by-side with a 1:1 ratio. This can be a good choice for a reference of REST API endpoints.
type="medium": render the definition title and the description side-by-side with a 1:2 ratio. This can be a good choice for a reference of methods or functions.
type="narrow": render the definition title and the description side-by-side with a 2:7 ratio. This can be a good choice for a reference of command-line options.
type="wide": render the definition title and the description side-by-side with a 1:8 ratio. This can be a good choice for a reference of abbreviations or single-letter options.

<description>

Add a description for the starting page of a section.

Parent elements: <section-starting-page>
Child elements: <if> <include> <snippet> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<emphasis>

Mark emphasized text to display it in italic and pronounce it with an emphasis by a screen reader. Use it to stress out a certain word or phrase, or introduce new terms, names, concepts, and so on.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<format>

Change the font style and color of text. It is not recommended to format text directly. Use semantic markup elements, such as <control> for UI controls, <code> for inline pieces of code, and <path> for paths and file names.

However, you can do it if necessary. Examples:

<format style="bold,italic" color="RosyBrown">Hello, world!</format>

<format style="subscript" color="Red">Hello, world!</format>

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

<group>

Add custom groups of links to topics that you would additionally like to list on the starting page of the section. This is a child of the <links> element.

    <links>
        <group>
            <title>Frameworks</title>
            <a href="some_topic.topic" description="First topic description.">Some topic</a>
            <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
            ...
        </group>
        ...
    </links>
                    

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary, unless the topic has a <link-summary> element defined.

Parent elements: <links>

<help-id>

Specify a unique context help identifier to reference this topic from a related dialog in the product. The same identifier must be assigned to the corresponding interface in the product's sources. This will generate a redirect in the output pointing from this help ID to the element where you specified it.

<help-id>some.help.id</help-id>

Parent elements: <chapter> <if> <procedure> <snippet> <topic>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<icon>

Insert an icon from the designated directory for icons defined in buildprofiles.xml.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

Attributes:

alt

Specify the alternate text for the icon.

dark-src

NO DESCRIPTION

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.

height

Specify the height of the icon.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

ignore-vars

Do not treat two percent characters with text between them %foo% as Writerside variables.

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

origin

If you want to include or reference something from another help module, specify this module as the origin.

src

Specify the icon file.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

width

Specify the width of the icon.

<if>

Filter out content based on product, platform, or a custom filter.

    <p>
        This <if instance="SimpleApp">word</for><if instance="OtherApp">weird phrase</for>
        will be different depending on the instance.
    </p>
                    

You can wrap any elements inside <if>. For example, in a <snippet>, you can use <if> for filtering:

    <if filter="advanced">
        <p>For example:</p>
    
        <list>
            <li>Like</li>
            <li>this</li>
        </list>
    </if>
                    

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<img>

Add an image, for example: a screenshot, an icon, or a diagram. Use the src attribute to specify the name of the image file. Use the alt attribute to describe the image: this makes your documentation more accessible for users of screen readers and provides additional information about your content for search engines.

Use the width attribute to resize the rendered image if necessary. By default, it will resize the height proportionally, but you can explicitly set the height using the height attribute.

Inline vs block images

Any small image (16 pixels or less) is considered an inline icon that should go into a paragraph. If you put it outside of a paragraph, you will get a warning. To insert a small image as a separate block element, set type="block" for it.

Images larger than 16 pixels are considered separate block elements by default. If you try to inline it into a paragraph, you will get a warning. To insert a large image into a paragraph, set type="inline" for it.

Thumbnails

If you have a very large image with a lot of details, by default, it will be scaled down to fit the viewport (706 pixels). To avoid this, set thumbnail="true", which will generate and insert a small thumbnail of the image that the reader can click to expand and view at full size.

Alternatively, you can specify a custom preview image instead of the automatically generated small thumbnail using the preview-src attribute.

Animated GIFs

Writerside will automatically detect an animated GIF and insert the first frame that the user can click to run the animation. Instead of the first frame, you can specify a custom preview image using the preview-src attribute.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

Attributes:

alt

Specify the alternate text for an image. This is a short description of the image, which is rendered when the image cannot be displayed, used by screen readers, and helps with search optimization.

border-effect

Add a border around the image or video to prevent the edges from blending with the web page background.

border-effect="none" is the default value, which does not add a border
border-effect="line" adds a rectangular border along the edges
border-effect="rounded" adds a border with rounded corners

GIF animations always have a border, so none is not applicable for them.

dark-src

NO DESCRIPTION

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.

height

Set the height for the image. By default, images are rendered in their actual size or shrink to fit the viewport. The width is adjusted proportionally, unless you set it explicitly.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

ignore-vars

Do not treat two percent characters with text between them %foo% as Writerside variables.

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

origin

If you want to include or reference something from another help module, specify this module as the origin.

preview-src

Specify the initial image to show for an expandable image.

scale

Set the scale ratio for this image..

src

Specify the name of the image file from the designated images directory or its subdirectories. Completion always suggests these files before any others.

You can specify the path to any image file in your project relative to the current topic file using the ./ and ../ notations. In this case, you will see helpful path completion suggestions.

You can use $PROJECT_DIR$ and $WRS_MODULE$ to reference images relative to the documentation project or module root.

You can also specify a URL to a file hosted somewhere on the web. In this case, make sure that the file is accessible from where you are going to host your documentation.

<img src="https://www.jetbrains.com/company/brand/img/jetbrains_logo.png" alt="Alt text" width="450"/>

style

Force the image to be rendered inline or as a separate block element. By default, Writerside decides based on the image size:

Any image larger than 32 pixels is always rendered as a separate block element, even if you put it inside a paragraph. If you want to render a large image inline with the paragraph text, set style="inline" to indicate your intent.
Any image up to 32 pixels located in a paragraph is considered an inline image, and Writerside renders it inside the paragraph. If you want to render a small image as a separate block, set style="block" or put it outside the paragraph according to your intent.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

theme

Specify the theme in which to display the image.

thumbnail

Make this image expandable.

width

Set the width for the image. By default, images are rendered in their actual size or shrink to fit the viewport. The height is adjusted proportionally, unless you set it explicitly.

<include>

Reuse an element by its identifier.

Attributes:

element-id

Specify the element ID.

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.

from

Specify the topic from which you want to include content.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

nullable

Do not include anything if the source topic is not available in the current context.

origin

If you want to include or reference something from another help module, specify this module as the origin.

use-filter

Insert content with conditions: only content marked by the specified custom filters, separated with commas.

<inline-frame>

Insert an iframe.

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <topic>

Attributes:

height: Specify the height of the iframe. Height cannot be 100%.
src: Specify the URL of the iframe.
width: Specify the width of the iframe.

<li>

Add a list item.

Do not leave any dangling text inside list items: wrap it with  elements to distinguish paragraphs.

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<link-summary>

Provide some text to display as a topic or chapter summary inside a link popup that shows on mouse hover. The popup renders as plain text, so formatting is not allowed inside <link-summary>.

By default, the popup on a link renders the first paragraph of a topic. However, if you want to override it, define a <link-summary>.

    <topic title="Foo" id="foo">
        <link-summary>
        This topic is about Foo.
        This text will not render in the topic.
        It is used only in the link popup.
        </link-summary>
    </topic>
                    

You can use an existing element with an id as a summary (for example, any paragraph). To do this, refer to the id using the rel attribute in <link-summary>:

    <topic title="Foo" id="foo">
        <p id="intro">
        This topic is about Foo.
        This text will render as a regular paragraph.
        </p>
    
        <link-summary rel="intro"/>
    </topic>
                    

Parent elements: <chapter> <if> <snippet> <topic>
Child elements: <if> <include> <snippet> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

rel

Specify an ID of a paragraph to use as a <link-summary>, <card-summary>, or <web-summary> instead of the default first paragraph.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<links>

Add one or more custom groups of links to topics that you would additionally like to list on the starting page of the section. This is a child of the <misc> element in a <section-starting-page>.

Use the <group> element to group separate link collections with a <title> and any number of links in each group, but preferably keep them between 2 and 4 in each collection.

You can set narrow="true" to render the links in three columns (groups).

    <misc>
        <links narrow="true">
            <group>
                <title>Frameworks</title>
                <a href="tupleconverter.topic" description="Everything you need to convert tuples.">TupleConverter</a>
                <a href="img_edit.topic" description="Automate your image editing needs.">ImgEdit</a>
                ...
            </group>
            ...
        </links>
    </misc>
                    

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary in a popup when you hover over the link, unless the topic has a <link-summary> element defined.

Parent elements: <misc>
Child elements: <group>

Attributes:

narrow: Use three narrow columns for cards instead of the default two wide columns.

<list>

Add a list of items.

    <list>
        <li>List item</li>
        <li>Another list item</li>
        <li>One more list item</li>
    </list>
                    

By default, lists are unordered and rendered in one column. Use the type attribute to create a numbered list designated with numeric values (1, 2, 3, ...) or letters (a, b, c, ...). For example, if you need to describe numbered annotations on a screenshot that mark various UI elements:

    <list type="decimal">
        <li>Editor</li>
        <li>File tree</li>
        <li>Status bar</li>
    </list>
                    

However, if you are documenting an ordered sequence of steps (actions) to perform some task, use the <procedure> element, not an ordered list.

If you have a long list of relatively short items, you can render the list in several columns by setting the number of columns in the columns attribute.

    <list columns="3">
        <li>this</li>
        <li>is a</li>
        <li>list</li>
        <li>with</li>
        <li>many</li>
        <li>short</li>
        <li>items</li>
        <li>they</li>
        <li>will be</li>
        <li>rendered</li>
        <li>in three</li>
        <li>columns</li>
    </list>
                    

Use the sorted attribute to sort the list items alphabetically (either ascending or descending).

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>
Child elements: <if> <include> <li> <snippet> <var>

Attributes:

columns

Render the list in multiple columns.

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

sorted

Automatically sort items in a list or table when building your help instance.

start

Specify the first item number in a numbered list.

style

DEPRECATED: Use type instead.

Specify whether this list should be numbered or bulleted.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

type

Specify whether this list should be numbered or bulleted.

type="bullet": use bullet points (default)
type="decimal": use decimal digits (1, 2, 3, and so on) when the order or total number of items is important
type="alpha-lower": use letters (a, b, c, and so on) for ordered nested lists
type="none": render list without markers

<math>

Add an inline LaTeX formula or equation.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<misc>

Add custom groups of cards and links to topics that you would additionally like to list on the starting page of the section. This is a child of the <section-starting-page> element.

    <misc>
        <cards narrow="false">
            <title>Other tools</title>
            <a href="some_topic.topic" description="First topic description.">Some topic</a>
            <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
            ...
        </cards>
    
        <links narrow="true">
            <group>
                <title>Frameworks</title>
                <a href="some_topic.topic" description="First topic description.">Some topic</a>
                <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
                ...
            </group>
            ...
        </links>
    </misc>
                    

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary on the card or a popup on the link, unless the topic has a <card-summary> and <link-summary> elements defined.

Parent elements: <section-starting-page>
Child elements: <cards> <links>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

<note>

Add a note with important information (restrictions, prerequisites, and possible problems that you think the user should be aware of).

<note>Only users with administrator privileges can perform this operation.</note>

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>

Add a paragraph.

Although the builder will add the necessary paragraphs, it is recommended to always clearly distinguish paragraphs from other elements: images, lists, and so on. Don't leave text dangling outside of  tags. Don't use  to break content. Separate content into paragraphs in chapters, tables, list items, definition list items, procedure steps, tips, notes, and warnings.

To reference a paragraph with a link, as with any other element, you can add the id attribute to it.

    <p id="intro">
        This is an introductory paragraph.
    </p>
                    

You can add links to any element with an ID: <a anchor="intro"/>.

Or include it: <include from="some.topic" element-id="intro"/>.

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <tldr> <topic>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<path>

Mark text as a file name or a path in the file system.

Specify the configuration file: <path>path/to/config</path>

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<primary>

Add a group of cards with links to the most important topics in the section. This is a child of the <section-starting-page> element. Add a <title> and any number of links, but preferably keep them between 4 and 8.

    <primary>
        <title>Quick start</title>
        <a href="Hello_World.topic" description="Write your first Hello World program.">Hello, World!</a>
        <a href="Barrel_Roll.topic" description="Learn how to do a barrel roll properly.">Do a barrel roll</a>
        ...
    </primary>
                    

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary, unless the topic has a <card-summary> element defined.

Parent elements: <section-starting-page>

<primary-label>

Add a primary label to the topic or a chapter

Parent elements: <chapter> <if> <snippet> <topic>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

ref

Specify the ID of a primary label defined in labels.list

<procedure>

Add an ordered list of steps describing how to perform a task.

    <procedure title="Become a professional">
        <step>Learn something</step>
        <step>Get paid for doing it</step>
        <step>(Optional) Do a barrel roll</step>
    </procedure>
                    

The title attribute is optional if the title of the procedure is obvious from the containing topic or chapter title. Procedures without titles do not produce anchors and do not appear in the in-topic table of contents.

You can add paragraphs before and after steps in a procedure if you need to describe prerequisites, consequences, expected output, and any other useful information that is not part of the actual steps.

Use the default-state attribute to make the procedure collapsible and specify if it should initially be rendered as collapsed or expanded.

If there is only one step in the procedure, it will be rendered with a bullet point instead of a numeric value.

If the procedure is a choice between several steps, set type="choices". Then all steps will be rendered as an unordered list with bullets.

Attributes:

caps

Specify the capitalization style. The builder will automatically apply the style to make this title, for example, sentence case or all upper case.

collapsible

Make the chapter, procedure, or deflist collapsible. By default, the element will appear collapsed with an icon to expand it.

default-state

By default, all items of a collapsible definition list are collapsed. Override this if you want some items to be expanded by default.

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

style

DEPRECATED: Use type instead.

Specify whether this procedure should be a sequence of steps or a choice.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

title

Specify the title.

type

Specify whether this procedure should be a sequence of steps or a choice.

<property>

Specify the property key from a specific resource bundle:

This will render the relevant key value, which is helpful for UI strings extracted from your product.

If the property contains variables, you can pass their values using the args attribute.

If you need to specify a property from a resource bundle for a specific product, use the from-product attribute.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

Attributes:

args

For properties with variables ({0}, {1}, and so on), specify a comma-separated list of values.

bundle

Specify the property bundle name.

cleanup-mode

Specify the mode for cleaning up property values if they contain some special characters.

cleanup-pattern

Specify a regex pattern to clean up from property values, for example, […_] to match all ellipsis and underscore characters.

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.

from-product

Specify the product to force for choosing the property bundle.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

key

Specify the property key from the bundle.

origin

If you want to include or reference something from another help module, specify this module as the origin.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<request>

Specify request information within an <api-endpoint> tag to provide developers with a clear understanding of the expected input and structure when making requests to an API endpoint.

The <request> tag is exclusively used within the context of an <api-endpoint> to describe the expected request structure. It can contain one or more <sample> tags to illustrate various request examples for different languages.

Here's an example of how to use the <request> tag within an <api-endpoint>:

    <api-endpoint endpoint="/users" method="POST">
        <request>
            <sample lang="JSON" title="Payload">
                {
                "id": 123,
                "name": "John Doe",
                "email": "john.doe@example.com"
                }
            </sample>
            <sample lang="javascript" title="JavaScript">
                const data = {
                id: 123,
                name: "John Doe",
                email: "john.doe@example.com"
                };
            </sample>
        </request>
    </api-endpoint>
                    

This example defines two request samples: JSON and JavaScript.

Parent elements: <api-endpoint>
Child elements: <sample>

<resource>

Add a link to a file that the reader can download.

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

origin

If you want to include or reference something from another help module, specify this module as the origin.

src

Specify the name of the file from the resources directory.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<response>

Specify response information for an API endpoint. This tag must define a required attribute type to specify the response code (e.g., default, 1XX, 2XX, 4XX, 5XX).

You can include a <sample> tag to provide sample response data. Here's an example of how to use this tag:

    <api-endpoint endpoint="/users/{id}" method="GET">
        <response type="200">
            <sample>
                {
                "id": 123,
                "name": "John Doe",
                "email": "john.doe@example.com"
                }
            </sample>
        </response>
        <response type="400">
            <sample>
                {
                "error": "text"
                }
            </sample>
        </response>
    </api-endpoint>
                    

This example defines an <api-endpoint> for retrieving user details by ID. There are two <response> tags to describe potential responses: one for a successful response with the status code of 200 and another for an error response with the status code 400.

Parent elements: <api-endpoint>
Child elements: <sample>

Attributes:

type: Specify the response code.

<sample>

Define a custom request or response example to help developers understand the expected input and output of an API endpoint.

Use the <sample> tag inside a <request> or a <response> tag.

For request samples, use the optional lang attribute for code highlighting and title as the name of the tab with the sample. Here is a JavaScript request code sample:

    <request>
        <sample lang="javascript" title="JavaScript">
            const data = {
            id: 123,
            name: "John Doe",
            email: "john.doe@example.com"
            };
        </sample>
    </request>
                    

If you store samples in a separate file you can specify it in the src and even reference specific lines from it using the include-lines attribute.

    <response>
        <sample src="example.js" include-lines="5-10"/>
    </response>
                    

Parent elements: <request> <response>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

include-lines

Specify line numbers from the source file to include in the sample.

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

lang

Specify the language for highlighting in this sample.

src

Specify the source file with code that you want to include as a sample.

title

NO DESCRIPTION

<secondary>

Add a group of cards with links to topics in this section that you would like to highlight. This is a child of the <section-starting-page> element. Add a <title> and any number of links, but preferably keep them between 2 and 4.

    <secondary>
        <title>Migration guides</title>
        <a href="migrate_from_foo.topic" description="Switch from FooApp to our awesome product.">Migrate from FooApp</a>
        <a href="migrate_from_bar.topic" description="Switch from BarApp to our awesome product.">Migrate from BarApp</a>
        ...
    </secondary>
                    

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary, unless the topic has a <card-summary> element defined.

Parent elements: <section-starting-page>

<secondary-label>

Add a secondary label to the topic or a chapter

Parent elements: <chapter> <if> <snippet> <topic>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

ref

Specify the ID of a secondary label defined in labels.list

<section-starting-page>

Add a starting page for a section of topics. Mandatory child elements are:

<title> is the title of the section starting page
<description> is a paragraph that briefly introduces the section
<spotlight> defines two featured topics
<primary> defines more topics that are important to read in this section
<secondary> defines several more topics that you would like to highlight in a separate group

You can also add the <misc> element to add any number of additional topic groups.

    <section-starting-page>
        <title>This is the title</title>
        <description>Description of the starting page</description>
    
        <spotlight>
            <a href="some_topic.topic" description="First topic description.">Some topic</a>
            <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
        </spotlight>
    
        <primary>
            <title>Main group title</title>
            <a href="some_topic.topic" description="First topic description.">Some topic</a>
            <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
            ...
        </primary>
    
        <secondary>
            <title>highlighted group title</title>
            <a href="some_topic.topic" description="First topic description.">Some topic</a>
            <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
            ...
        </secondary>
    
        <misc>
            <cards narrow="false">
                <title>Other tools</title>
                <a href="some_topic.topic" description="First topic description.">Some topic</a>
                <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
                ...
            </cards>
    
            <links narrow="true">
                <group>
                    <title>Frameworks</title>
                    <a href="some_topic.topic" description="First topic description.">Some topic</a>
                    <a href="some_other_topic.topic" description="Second topic description.">Some other topic</a>
                    ...
                </group>
                ...
            </links>
        </misc>
    </section-starting-page>
                    

Parent elements: <topic>
Child elements: <description> <misc> <primary> <secondary> <spotlight> <title>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

<seealso>

Add links to topics and external resources that may be relevant to the current topic.

    <seealso>
        <category ref="settings">
            <a href="drum_settings.topic"/>
        </category>
        <category ref="external">
            <a href="https://blog.post.com/drums-are-cool">Why drums are cool</a>
        </category>
    </seealso>
                    

Separate links into categories defined in the c.list file.

Parent elements: <if> <snippet> <topic>
Child elements: <category> <if> <include> <snippet> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

style

Render this seealso block as a list of links or as cards with a title and summary.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<shortcut>

Add a shortcut by an identifier from a keymap file or hardcoded.

To copy the selected text, press <shortcut key="$Copy"/>.

To copy the selected text, press <shortcut>Ctrl+C</shortcut>.

If you have multiple keymap files, there will be a switcher with available keymaps at the top of the page. Shortcuts added via identifier keys will dynamically render from the selected keymap. Hardcoded shortcuts will stay the same regardless of the selected keymap.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

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.

force-layout

Render the shortcut from the specified layout regardless of what the reader selects in the shortcut switcher.

from-keymap-of

Use a shortcut defined in a keymap for another help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

key

Specify the key of the action from the keymap definition file.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<show-structure>

Configure the navigation component inside the topic. By default, Writerside renders links to first-level chapters on the right side of the topic page. If you want to have both chapter and procedure titles up to level 2, add this:

<show-structure for="chapter,procedure" depth="2"/>

Parent elements: <topic>

Attributes:

depth

Specify the maximum header level allowed in the topic navigation component.

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.

for

Specify the elements allowed in the topic navigation component: chapters, procedures, or both.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

<snippet>

Define a chunk of content with more than one element to insert using the <include> element.

    <snippet id="settings">
        <p>You can change the following settings:</p>
    
        <list>
            <li>Volume</li>
            <li>Brightness</li>
            <li>Dimensions</li>
        </list>
    </snippet>
                    

This chunk should reside in a library topic that you reference with the from attribute:

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<spotlight>

Add a group of exactly two cards with links to featured topics in the section. This is a child of the <section-starting-page> element.

    <spotlight>
        <a href="Try_This.topic" description="If you haven't already, you should try it.">Try this</a>
        <a href="Important_Stuff.topic" description="Learn what is most important when you begin.">Important stuff</a>
    </spotlight>
                    

If you don't provide the description attribute, it will render the first paragraph of the referenced topic as a summary, unless the topic has a <card-summary> element defined.

Parent elements: <section-starting-page>

<step>

Add a step to a procedure.

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<tab>

Define at least two tabs inside the <tabs> element, each with a unique title attribute:

    <tabs>
        <tab title="Foo">Content of tab Foo</tab>
        <tab title="Bar">Content of tab Bar</tab>
    </tabs>
                    

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.

group-key

Specify the key within the synchronization group, which is defined by the group attribute in <tabs>. When your reader opens this tab, it will also open all tabs marked by this key in the same synchronization group.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

title

Specify the title.

<table>

Add a table with rows <tr> and cells <td>.

    <table>
        <tr>
            <td>First cell in the first row</td>
            <td>Second cell in the first row</td>
            <td>Third cell in the first row</td>
        </tr>
    </table>
                    

By default, the table dynamically adjusts the widths for columns depending on the content. To define fixed widths, set the widths for the first cell in each column:

    <table>
        <tr>
            <td width="100">First cell in the first row</td>
            <td width="200">Second cell in the first row</td>
            <td width="300">Third cell in the first row</td>
        </tr>
    </table>
                    

Use the style attribute to specify header rows and columns:

header-row: Use the first row as column headers (default)
header-column: Use the first column as row headers
both: Use both the first row and first column as headers
none: Do not highlight header rows or columns

Use the cellpadding attribute to specify the space between the border of table cells and their content.

Use the cellspacing attribute to specify the space between table cells.

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>
Child elements: <if> <include> <snippet> <tr> <var>

Attributes:

border

Specify whether the table should have borders.

border="false": no borders
border="true": all regular borders

column-width

Specify whether table column widths should be fixed. By default, column widths are automatically adjusted based on the content and the size of the window. If you want to ensure that the columns in a table have a consistent width, set column-width="fixed".

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

style

Specify which cells to use as the header for this table.

style="header-row": Use the first row as column headers (default)
style="header-column": Use the first column as row headers
style="both": Use both the first row and first column as headers
style="none": Do not highlight any cells as headers

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<tabs>

Separate related groups of content into switchable tabs. For example, instructions for different operating systems, languages, roles, and so on.

The <tabs> element must contain at least two <tab> elements, each with a title attribute:

    <tabs>
        <tab title="Foo">Content of tab Foo</tab>
        <tab title="Bar">Content of tab Bar</tab>
    </tabs>
                    

Alternatively, you can use <code-block> elements instead of <tab> elements to show code blocks separated into tabs by language name. In this case, make sure that all <code-block> elements define their lang attribute, and languages do not repeat:

    <tabs>
        <code-block lang="java">Java code</code>
        <code-block lang="groovy">Groovy code</code>
    </tabs>
                    

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>
Child elements: <code-block> <if> <include> <snippet> <tab> <var>

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.

group

Specify the synchronization group to which these tabs should belong.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<td>

Add a cell to a table row <tr>.

    <table>
        <tr>
            <td>First cell in the first row</td>
            <td>Second cell in the first row</td>
            <td>Third cell in the first row</td>
        </tr>
    </table>
                    

Use the colspan and rowspan attributes to merge neighbouring cells in the corresponding column or row.

Use the width attribute in the top cell of any column to define the width for the whole column.

Parent elements: <if> <snippet> <tr>
Child elements: <a> <code> <code-block> <compare> <control> <deflist> <emphasis> <format> <icon> <if> <img> <include> <list> <math> <note> <path> <property> <resource> <shortcut> <snippet> <table> <tabs> <tip> <tooltip> <ui-path> <var> <video> <warning>

Attributes:

colspan

Span this cell across multiple columns.

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.

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

rowspan

Span this cell across multiple rows.

sorted

Automatically sort items in a list or table when building your help instance.

width

Set the width for the column with this cell.

<tip>

Add a tip with additional information (alternatives, hints, and suggestions that may be helpful but not important for the task).

<tip>Alternatively, you can change the settings directly in the configuration file.</tip>

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>

<title>

Override the title of a topic, chapter, procedure, or any other element that can have a title. In general, you define the title as an attribute for the corresponding element. However, if you need different titles for different products, platforms, or sections, use the <title> element as a child.

    <chapter title="How to play drums" id="play_drums">
    
        <title instance="app">How to play drums like a pro</title>
    
        <p>
            This topic will render with the title "How to play drums" for all instances except `app`,
            where the title will be "How to play drums like a pro".
        </p>
    
    </chapter>
                    

Parent elements: <chapter> <def> <deflist> <if> <procedure> <section-starting-page> <snippet> <tab> <topic>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

Attributes:

caps

Specify the capitalization style. The builder will automatically apply the style to make this title, for example, sentence case or all upper case.

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

<tldr>

Document the most important simple "facts" about the subject of the topic or chapter: the shortcut to use the described feature, path to the relevant settings, critical prerequisites, an illustrative example, and so on.

Each "fact" is formatted as a separate paragraph inside a  element. Keep them simple, short, and concise. They are not meant for explaining complex concepts, but rather to give the user quick guidance for exploring the feature themselves.

This block will be rendered at the very beginning of the topic or chapter, directly below the title.

    <tldr>
        <p><ui-menu>File | Save</ui-menu> or <shortcut>Ctrl + S</shortcut></p>
        <p>You can't save if the file is open in another application</p>
    </tldr>
                

Parent elements: <chapter> <if> <snippet> <topic>
Child elements: <if> <include> <snippet> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

Show a tooltip with the definition of a term from the glossary on mouse hover.

Choose your <tooltip term="OS">OS</tooltip>.

If you have the <term name="OS"> defined in glossary.xml, the definition will pop up when you hover the mouse pointer over OS in the mentioned paragraph.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

term

Specify the term from the glossary.

<topic>

Wrap all topics with this top-level element that defines important topic attributes:

title specifies the title of the topic
id specifies a unique identifier for the topic
help-id specifies an additional context help identifier to reference this topic from a related UI in the product
switcher-label specifies the label for the <switcher-key> (by default, it is labeled as "Section")
is-library specifies whether this is a library of content snippets (by default, set to false)
xsi:noNamespaceSchemaLocation specifies the location of the XML schema

Example:

    <topic xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
        title="How to play the drums"
        id="drum-guide"
        help-id="drums.dialog"
        switcher-label="Level">
    
        <p>Hit the drums with sticks.</p>
        ...
    </topic>
                    

Attributes:

help-id

Specify the ID for redirects from your product to specific topics and chapters in your help instance.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

is-library

Mark this topic as a library of reusable snippets, not used as an actual topic in any help instance.

switcher-label

Specify a label for the custom content switcher in the header.

title

Specify the title.

<tr>

Add a row to a <table>.

    <table>
        <tr>
            <td>First cell in the first row</td>
            <td>Second cell in the first row</td>
            <td>Third cell in the first row</td>
        </tr>
    </table>
                    

Parent elements: <if> <snippet> <table>
Child elements: <if> <include> <snippet> <td> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<ui-path>

Add a sequence of menu items or other clickable UI elements.

From the main menu, select <ui-path>File | New | Project</ui-path>.

Parent elements: <a> <chapter> <code> <control> <def> <emphasis> <if> <li> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>
Child elements: <a> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<value>

Specify the value of a variable. For a single value, you can use the value attribute in <var>. However, if you need to conditionalize values, add them as child elements:

    <var name="my_var">
        <value instance="foo">value for foo</value>
        <value instance="bar">value for bar</value>
    </var>
                    

Parent elements: <var>

<var>

Define a variable anywhere inside a topic by specifying its name and value:

You can refer to this variable throughout the topic as %myvar%. If you define the same variable's value multiple times, it will use the last defined value.

Use variables to render repeating elements, such as the name of your product or a directory path. You can filter the variable by products:

    <var name="product" value="Foo Sprinkler" instance="foo"/>
    <var name="product" value="Bar Annotator" instance="bar"/>
                    

Attributes:

default

Specify an optional default value for this variable.

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

name

Specify the name of this variable.

value

Specify the value of this variable.

<video>

Add a video in a topic for illustrating a process.

To embed a video from YouTube, specify a link to it in the src attribute:

To add a video stored in the project files, specify the file name in the src attribute:

The file must be stored in the images directory along with a preview image of the same name. For example, titanic_rip.mp4 and titanic_rip.png.

Use the width and height attributes to change the size of the player. If you set only one of the dimensions, the proportions are preserved.

Use the mini-player attribute to hide all video controls except the Play and Pause buttons.

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>

Attributes:

border-effect

Add a border around the image or video to prevent the edges from blending with the web page background.

border-effect="none" is the default value, which does not add a border
border-effect="line" adds a rectangular border along the edges
border-effect="rounded" adds a border with rounded corners

GIF animations always have a border, so none is not applicable for them.

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.

height

Set the height for the video.

id

Specify an identifier for an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

ignore-vars

Do not treat two percent characters with text between them %foo% as Writerside variables.

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

mini-player

Use a minimalistic player for the video with all controls hidden except the play and pause buttons.

origin

If you want to include or reference something from another help module, specify this module as the origin.

preview-src

Specify the initial image to show before the reader starts the video.

src

Specify the name or path to a local video file or a URL to a YouTube or Vimeo video. For YouTube, you can use both the full and the shortened link formats.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

width

Set the width for the video.

<warning>

Add a warning with critical information about possible data loss, physical, financial, or other kind of damage.

<warning>If you delete a user, all their transactions will also be erased from the database.</warning>

Parent elements: <chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <td> <topic>

<web-file-name>

Specify the exact name for the web file that will be produced from this topic. By default, Writerside takes the topic file name, converts all letters to lower case and all special characters to dashes, so My_Topic.topic becomes my-topic.html. If you want it to be My_Topic.html, add this:

<web-file-name>My_Topic.html</web-file-name>

Parent elements: <topic>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

<web-summary>

Add a web description for the topic that will be used by search engines. By default, search engines will display the first paragraph of a topic. However, if you want to override it, define a <web-summary>.

    <topic title="Foo" id="foo">
        <web-summary>
            This topic is about Foo.
            This text will not render in the topic.
            It is used only in the link popup.
        </web-summary>
    
        ...
    </topic>
                    

You can use an existing element with an id as a summary (for example, any paragraph). To do this, refer to the id using the rel attribute in <web-summary>:

    <topic title="Foo" id="foo">
        <p id="intro">
            This topic is about Foo.
            This text will render as a regular paragraph.
        </p>
    
        <web-summary rel="intro"/>
    </topic>
                    

Parent elements: <if> <snippet> <topic>
Child elements: <if> <include> <snippet> <var>

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 an element:

This is an introduction.

You can use this identifier as an anchor for a link:

<a href="topic.topic" anchor="intro">Link to intro</a>

You can also include the whole element via its identifier:

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.

<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>

rel

Specify an ID of a paragraph to use as a <link-summary>, <card-summary>, or <web-summary> instead of the default first paragraph.

switcher-key

Specify the switcher key to which an element should apply. Writerside renders a switcher in the header to dynamically switch content depending on the user's environment, for example.

<a>

<anchor>

<api-doc>

<api-endpoint>

<api-schema>

<br>

<card-summary>

<cards>

<category>

<chapter>

<code>

<code-block>

<compare>

<contribute-url>

<control>

<def>

<deflist>

<description>

<emphasis>

<format>

<group>

<help-id>

<icon>

<if>

<img>

<include>

<inline-frame>

<li>

<link-summary>

<links>

<list>

<math>

<misc>

<note>

<p>

<path>

<primary>

<primary-label>

<procedure>

<property>

<request>

<resource>

<response>

<sample>

<secondary>

<secondary-label>

<section-starting-page>

<seealso>

<shortcut>

<show-structure>

<snippet>

<spotlight>

<step>

<tab>

<table>

<tabs>

<td>

<tip>

<title>

<tldr>

<tooltip>

<topic>

<tr>

<ui-path>

<value>

<var>

<video>

<warning>

<web-file-name>

<web-summary>