Semantic markup reference
Last modified: 09 January 2025This is a full reference of all XML markup elements available in Writerside topic files.
<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:
<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>
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 theuse-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>
- 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.
<anchor>
DEPRECATED: use the id
attribute on the relevant element instead.
Add an anchor to which you can create a hyperlink.
Attributes:
<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"/>
Attributes:
- 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 theuse-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>
<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 responsesREQUEST
- generate samples for requests onlyRESPONSE
- generate samples for responses onlyNONE
- 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"/>
Attributes:
- 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 theuse-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>
<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 incomponents.schemas
(for openAPI 3.0) ordefinitions
(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.
Attributes:
- 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 theuse-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>
<br>
NO DESCRIPTION
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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" 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.
Attributes:
<category>
Specify the category for a group of links in the <seealso>
section.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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"
.
- Child elements
<a> <api-doc> <api-endpoint> <api-schema> <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 theuse-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.
<code>
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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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"
.
Attributes:
- 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 theuse-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-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>
- 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=">>>"
orprompt="$"
. 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.
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
- style
DEPRECATED: Use
type
instead.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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
- Child elements
<a> <api-doc> <api-endpoint> <api-schema> <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 theuse-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>
<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.
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 theuse-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.
- 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.
<description>
Add a description for the starting page of a section.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
<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" 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.
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<icon>
Insert an icon from the designated directory for icons defined in buildprofiles.xml
.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
- origin
If you want to include or reference something from another help module, specify this module as the origin.
<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>
- 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> <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 theuse-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>
<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.
<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.
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 borderborder-effect="line"
adds a rectangular border along the edgesborder-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 theuse-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.
- 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.
<include>
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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<inline-frame>
Insert an iframe.
Attributes:
<li>
Add a list item.
Do not leave any dangling text inside list items: wrap it with <p>
elements to distinguish paragraphs.
- Child elements
<a> <api-doc> <api-endpoint> <api-schema> <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 theuse-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>
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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" 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.
Attributes:
<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).
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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.
- 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 importanttype="alpha-lower"
: use letters (a, b, c, and so on) for ordered nested liststype="none"
: render list without markers
<math>
Add an inline LaTeX formula or equation.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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" summary="First topic summary.">Some topic</a>
<a href="some_other_topic.topic" summary="Second topic summary.">Some other topic</a>
...
</cards>
<links narrow="true">
<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>
</misc>
If you don't provide the summary
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.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
<p>
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 <p>
tags. Don't use </br>
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"/>
.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<path>
Mark text as a file name or a path in the file system.
<p>Specify the configuration file: <path>path/to/config</path></p>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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" summary="Write your first Hello World program.">Hello, World!</a>
<a href="Barrel_Roll.topic" summary="Learn how to do a barrel roll properly.">Do a barrel roll</a>
...
</primary>
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.
<primary-label>
Add a primary label to the topic or a chapter
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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.
- Child elements
<a> <api-doc> <api-endpoint> <api-schema> <br> <code> <code-block> <control> <deflist> <emphasis> <format> <help-id> <icon> <if> <img> <include> <inline-frame> <list> <math> <note> <p> <path> <property> <resource> <shortcut> <snippet> <step> <table> <tabs> <tip> <title> <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 theuse-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>
- style
DEPRECATED: Use
type
instead.Specify whether this procedure should be a sequence of steps or a choice.
<property>
Specify the property key from a specific resource bundle:
<property bundle="FooBundle" key="some.property.string"/>
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.
Attributes:
- 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 theuse-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>
<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.
<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 theuse-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>
<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.
Attributes:
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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" summary="Switch from FooApp to our awesome product.">Migrate from FooApp</a>
<a href="migrate_from_bar.topic" summary="Switch from BarApp to our awesome product.">Migrate from BarApp</a>
...
</secondary>
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.
<secondary-label>
Add a secondary label to the topic or a chapter
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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" summary="First topic summary.">Some topic</a>
<a href="some_other_topic.topic" summary="Second topic summary.">Some other topic</a>
</spotlight>
<primary>
<title>Main group title</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>
...
</primary>
<secondary>
<title>highlighted group title</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>
...
</secondary>
<misc>
<cards narrow="false">
<title>Other tools</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>
...
</cards>
<links narrow="true">
<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>
</misc>
</section-starting-page>
- 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 theuse-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>
<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.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<shortcut>
Add a shortcut by an identifier from a keymap file or hardcoded.
<p>To copy the selected text, press <shortcut key="$Copy"/>.</p>
<p>To copy the selected text, press <shortcut>Ctrl+C</shortcut>.</p>
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.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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.
- 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>
<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"/>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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:
<include from="lib.topic" element-id="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
<a> <api-doc> <api-endpoint> <api-schema> <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 theuse-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>
<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" summary="If you haven't already, you should try it.">Try this</a>
<a href="Important_Stuff.topic" summary="Learn what is most important when you begin.">Important stuff</a>
</spotlight>
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.
<step>
Add a step to a procedure.
- Child elements
<a> <api-doc> <api-endpoint> <api-schema> <br> <code> <code-block> <compare> <control> <deflist> <emphasis> <format> <icon> <if> <img> <include> <inline-frame> <list> <math> <note> <p> <path> <procedure> <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 theuse-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>
<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>
- Child elements
<a> <api-doc> <api-endpoint> <api-schema> <br> <chapter> <code> <code-block> <compare> <control> <deflist> <emphasis> <format> <icon> <if> <img> <include> <inline-frame> <list> <math> <note> <p> <path> <procedure> <property> <resource> <shortcut> <snippet> <table> <tabs> <tip> <title> <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 theuse-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:
<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>
<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 headersboth
: Use both the first row and first column as headersnone
: 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.
Attributes:
- border
Specify whether the table should have borders.
border="false"
: no bordersborder="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 theuse-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>
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
<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>
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 theuse-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>
<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 <p>
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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<tooltip>
Show a tooltip with the definition of a term from the glossary on mouse hover.
<p>Choose your <tooltip term="OS">OS</tooltip>.</p>
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.
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<topic>
Wrap all topics with this top-level element that defines important topic attributes:
title
specifies the title of the topicid
specifies a unique identifier for the topichelp-id
specifies an additional context help identifier to reference this topic from a related UI in the productswitcher-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 tofalse
)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>
- Child elements
<a> <anchor> <api-doc> <api-endpoint> <api-schema> <br> <card-summary> <chapter> <code> <code-block> <compare> <contribute-url> <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> <section-starting-page> <seealso> <shortcut> <show-structure> <snippet> <table> <tabs> <tip> <title> <tldr> <tooltip> <ui-path> <var> <video> <warning> <web-file-name> <web-summary>
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:
<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.
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<ui-path>
Add a sequence of menu items or other clickable UI elements.
<p>From the main menu, select <ui-path>File | New | Project</ui-path>.</p>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
<var>
Define a variable anywhere inside a topic by specifying its name and value:
<var name="myvar" value="Hello"/>
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"/>
- 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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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:
<video src="https://youtu.be/R8QW8s4Ibio"/>
To add a video stored in the project files, specify the file name in the src
attribute:
<video src="titanic_rip.mp4"/>
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.
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 borderborder-effect="line"
adds a rectangular border along the edgesborder-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 theuse-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>
- 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.
- 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.
<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>
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
<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>
Attributes:
- filter
Specify a custom filter for an element. When defining a
<snippet>
, filter out content according to some criteria, and then specify theuse-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>
Thanks for your feedback!