Semantic markup reference

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:

<a href="my-topic.topic"/>

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

<a href="my-topic.topic">Link text</a>

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>

Parent elements

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

Child elements

<a> <br> <code> <control> <emphasis> <format> <icon> <if> <img> <include> <math> <path> <property> <resource> <shortcut> <snippet> <tooltip> <ui-path> <var>

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:

<a href="some.topic#this_chapter"/>

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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.

Generate API reference from an OpenAPI specification file. You can generate a full reference or only the operations and webhooks 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 and webhooks marked with the User tag:

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

Here is how to generate a reference with operations only:

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

Parent elements

<chapter> <def> <if> <li> <procedure> <snippet> <step> <tab> <topic>

Child elements

<api-endpoint> <api-webhook>

Attributes:

depth

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

display

Specify whether to display all operations and webhooks, only operations or only webhooks.

You can use one of the following values:

• all (default) - generate reference for all endpoints and webhooks

• endpoints - generate reference for endpoints only

• webhooks - generate reference for webhooks only

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 samples of requests and responses from the specification.

id

Specify an identifier for an element:

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

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 from="topic.topic" element-id="intro"/>

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 and webhooks marked with this tag.

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 use 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:

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

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 from="topic.topic" element-id="intro"/>

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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

Generate a reference for a single API webhook.

<api-webhook openapi-path="path/to/file.yaml" webhook="NewWebHook" method="POST"/>

You can generate a reference for several endpoints and webhooks at the same time. 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-webhooks webhook="NewWebHook" method="POST"/>
</api-doc>

Parent elements

<api-doc> <chapter> <def> <if> <li> <procedure> <snippet> <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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

webhook

Specify the name of webhook for which you want to generate reference.

NO DESCRIPTION

Parent elements

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

Add a card to a <section-starting-page>. Cards are links to existing topics. They can have an icon or a custom image. By default, a card displays the default <link-summary> as text, but you can override it using the summary attribute.

Attributes:

alt

Specify the alternative text for the image or icon of a card.

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:

<card href="some.topic#this_chapter"/>

badge

Specify one of the built-in icon badges for the card.

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.

icon

Specify a custom icon for the card.

id

Specify an identifier for an element:

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

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 from="topic.topic" element-id="intro"/>

ignore-vars

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

image

Specify a custom image for the card.

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.

target-switcher-key

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

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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" summary="Copy any text from any document.">Copy Cat</a>
        <a href="paste_dog.topic" summary="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 summary 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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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".

Parent elements

<chapter> <if> <snippet> <tab> <topic>

Child elements

<a> <api-doc> <api-endpoint> <api-schema> <api-webhook> <br> <chapter> <code> <code-block> <compare> <control> <deflist> <emphasis> <format> <help-id> <icon> <if> <img> <include> <inline-frame> <link-summary> <list> <math> <note> <p> <path> <primary-label> <procedure> <property> <resource> <secondary-label> <shortcut> <snippet> <table> <tabs> <tip> <title> <tldr> <tooltip> <ui-path> <var> <video> <warning>

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:

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

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 from="topic.topic" element-id="intro"/>

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>

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.

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

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

Parent elements

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

Child elements

<a> <br> <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:

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

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 from="topic.topic" element-id="intro"/>

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>

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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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:

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

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 from="topic.topic" element-id="intro"/>

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>

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> <p> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

Child elements

<a> <br> <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:

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

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 from="topic.topic" element-id="intro"/>

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>

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.

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>

Parent elements

<deflist> <if> <snippet>

Child elements

<a> <api-doc> <api-endpoint> <api-schema> <api-webhook> <br> <code> <code-block> <control> <deflist> <emphasis> <format> <icon> <if> <img> <include> <inline-frame> <list> <math> <note> <p> <path> <property> <resource> <shortcut> <snippet> <table> <tabs> <tip> <title> <tooltip> <ui-path> <var> <video> <warning>

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:

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

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 from="topic.topic" element-id="intro"/>

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>

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.

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:

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

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 from="topic.topic" element-id="intro"/>

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>

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="compact": 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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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> <p> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

Child elements

<a> <br> <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:

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

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 from="topic.topic" element-id="intro"/>

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>

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.

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> <p> <path> <procedure> <resource> <snippet> <step> <tab> <td> <title> <tooltip> <topic> <ui-path>

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" summary="First topic summary.">Some topic</a>
        <a href="some_other_topic.topic" summary="Second topic summary.">Some other topic</a>
        ...
    </group>
    ...
</links>

If you don't provide the summary 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>

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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

Parent elements

<a> <chapter> <code> <control> <def> <emphasis> <if> <li> <p> <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:

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

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 from="topic.topic" element-id="intro"/>

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.

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>

Parent elements

<a> <card-summary> <chapter> <code> <control> <def> <deflist> <description> <emphasis> <if> <include> <li> <link-summary> <list> <p> <path> <procedure> <resource> <seealso> <snippet> <step> <tab> <table> <tabs> <td> <title> <tldr> <tooltip> <topic> <tr> <ui-path> <web-summary>

Child elements

<a> <api-doc> <api-endpoint> <api-schema> <api-webhook> <br> <card-summary> <category> <chapter> <code> <code-block> <compare> <control> <def> <deflist> <emphasis> <format> <help-id> <icon> <if> <img> <include> <inline-frame> <li> <link-summary> <list> <math> <note> <p> <path> <primary-label> <procedure> <property> <resource> <secondary-label> <seealso> <shortcut> <snippet> <step> <table> <tabs> <td> <tip> <title> <tldr> <tooltip> <tr> <ui-path> <var> <video> <warning> <web-summary>

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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.

<img src="screenshot.png" alt="A screenshot of the Add dialog."/>

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> <p> <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:

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

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 from="topic.topic" element-id="intro"/>

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.

<img src="image.png" alt="Alt text" width="450"/>

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.

<img src="../myMediaDir/image.png" alt="Alt text" width="450"/>

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

<img src="$PROJECT_DIR$/allImages/image.png" alt="Alt text" width="450"/>

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.

Reuse an element by its identifier.

<include from="lib.topic" element-id="open-settings"/>

Parent elements

<a> <card-summary> <category> <chapter> <code> <control> <def> <deflist> <description> <emphasis> <if> <include> <li> <link-summary> <list> <p> <path> <procedure> <resource> <seealso> <snippet> <step> <tab> <table> <tabs> <td> <title> <tldr> <tooltip> <topic> <tr> <ui-path> <web-summary>

Child elements

<if> <include> <snippet> <var>

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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.

Add a list item.

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

Parent elements

<if> <list> <snippet>

Child elements

<a> <api-doc> <api-endpoint> <api-schema> <api-webhook> <br> <code> <code-block> <compare> <control> <deflist> <emphasis> <format> <icon> <if> <img> <include> <inline-frame> <list> <math> <note> <p> <path> <property> <resource> <shortcut> <snippet> <table> <tabs> <tip> <tooltip> <ui-path> <var> <video> <warning>

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:

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

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 from="topic.topic" element-id="intro"/>

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>

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.

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:

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

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 from="topic.topic" element-id="intro"/>

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.

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" summary="Everything you need to convert tuples.">TupleConverter</a>
            <a href="img_edit.topic" summary="Automate your image editing needs.">ImgEdit</a>
            ...
        </group>
        ...
    </links>
</misc>

If you don't provide the summary 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.

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:

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

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 from="topic.topic" element-id="intro"/>

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>

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