Documentation formatting¶

Robot Framework supports various documentation formats in different contexts:

Suite and test documentations use Robot Frameworks own custom format.
Library and keyword documentation processed by Libdoc can be written using Robot Framework format, Markdown, reStructuredText, HTML and plain text.
Error messages support plain text and HTML.

The two main documentation formats are Robot Framework's custom format and Markdown, and they are documented thoroughly in this section. Before that, this section explains how to handle whitespace in Robot Framework data when writing documentation.

Handling whitespace¶

This section explains how newlines and spaces are handled in Robot Framework data when writing documentation. These rules are the same regardless the documentation format that is used.

Newlines¶

When documenting and adding metadata to suites, tests and keywords, newlines can be created by using the \n escape sequence:

*** Settings ***
Documentation    First line.\n\nSecond paragraph. This time\nwith multiple lines.
Metadata         Example list    - first item\n- second item\n- third

Note

As explained in the Paragraphs section below, the single newline in Second paragraph, this time\nwith multiple lines. does not actually affect how that paragraph is rendered. Newlines are needed when creating lists or other such constructs, though.

Adding newlines manually to a long documentation takes some effort and extra characters also make the documentation harder to read. This can be avoided, though, as newlines are inserted automatically between continued documentation and metadata lines. In practice this means that the above example could be written also as follows:

*** Settings ***
Documentation
...    First line.
...
...    Second paragraph. This time
...    with multiple lines.
Metadata
...    Example list
...    - first item
...    - second item
...    - third

No automatic newline is added if a line already ends with a literal newline or if it ends with an escaping backslash:

*** Test Cases ***
Ends with newline
    [Documentation]    Ends with a newline and\n
    ...                automatic newline is not added.

Ends with backslash
    [Documentation]    Ends with a backslash and \
    ...                no newline is added.

Spaces¶

Unlike elsewhere in Robot Framework data, leading spaces and consecutive internal spaces are preserved in documentation and metadata. This makes it possible, for example, to split list items to multiple rows and have preformatted text with spaces:

*** Test Cases ***
Long list item
    [Documentation]
    ...    List:
    ...    - Short item.
    ...    - Second item is pretty long and it is split to
    ...      multiple rows. Leading spaces are preserved.
    ...    - Another short item.

Preformatted text
    [Documentation]
    ...    Example with consecutive internal spaces:
    ...
    ...    | *** Test Cases ***
    ...    | Example
    ...    |     Keyword

Note

Preserving spaces in documentation and metadata is new in Robot Framework 6.1. With earlier versions spaces need to be escaped with a backslash.

Paragraphs¶

Lines separated with a single newline are combined into a paragraph regardless whether the newline is added manually or automatically. Multiple paragraphs can be separated with an empty line (i.e. two newlines) and also tables, lists, and other specially formatted blocks end paragraphs.

For example, this documentation:

*** Settings ***
Documentation
...    First paragraph has only one line.
...
...    Second paragraph, this time created
...    with multiple lines.

will be formatted in HTML like this:

First paragraph has only one line.

Second paragraph, this time created with multiple lines.

Robot Framework format¶

Robot Framework has its own simple plain text documentation format. It can be used when documenting suites and tests as well as when writing library documentation. Its main benefit is that it does not require any additional modules to be installed, but being a custom format means that it does not work well with external documentation tools and that users new to Robot Framework need to learn it.

Inline styles¶

The documentation syntax supports inline styles bold, italics and code. Bold text can be created by having an asterisk before and after the selected word or words, for example *this is bold*. The italics style works similarly, but the special character to use is an underscore, for example, _italics_. It is also possible to have bold italics with the syntax _*bold italics*_.

The code style is created using double backticks like ``code``. The result is monospaced text with light gray background.

Asterisks, underscores or double backticks alone, or in the middle of a word, do not start formatting, but punctuation characters before or after them are allowed. When multiple lines form a paragraph, all inline styles can span over multiple lines.

Inline style examples
Source	Formatted
bold	bold
_italics_	italics
_bold italics_	bold italics
`code`	`code`
bold, then _italics_ and finally `some code`	bold, then italics and finally `some code`
This is bold\n on multiple\n lines.	This is bold on multiple lines.

URL detection¶

All strings that look like URLs are automatically converted into clickable links. Additionally, URLs that end with extension .jpg, .jpeg, .png, .gif, .bmp or .svg (case-insensitive) will automatically create images. For example, URLs like http://example.com are turned into links, and http:///host/image.jpg and file:///path/chart.png into images.

The automatic conversion of URLs to links is applied to all the data in logs and reports, but creating images is done only for test suite, test case and keyword documentation, and for test suite metadata.

Custom links and images¶

It is possible to create custom links and embed images using special syntax [link|content]. This creates a link or image depending are link and content images. They are considered images if they have the same image extensions that are special with URLs or start with data:image/. The surrounding square brackets and the pipe character between the parts are mandatory in all cases.

Link with text content¶

If neither link nor content is an image, the end result is a normal link where link is the link target and content the visible text:

1 2	`[file.html\|this file] -> <a href="file.html">this file</a> [http://host\|that host] -> <a href="http://host">that host</a>`

Link with image content¶

If content is an image, you get a link where the link content is an image. Link target is created by link and it can be either text or image:

1
2
3

[robot.html|robot.png] -> <a href="robot.html"><img src="robot.png"></a>
[robot.html|data:image/png;base64,oooxxx=] -> <a href="robot.html"><img src="data:image/png;base64,oooxxx="></a>
[image.jpg|thumb.jpg] -> <a href="image.jpg"><img src="thumb.jpg"></a>

Image with title text¶

If link is an image but content is not, the syntax creates an image where the content is the title text shown when mouse is over the image:

1 2	`[robot.jpeg\|Robot rocks!] -> <img src="robot.jpeg" title="Robot rocks!"> [data:image/png;base64,oooxxx=\|Robot rocks!] -> <img src="data:image/png;base64,oooxxx=" title="Robot rocks!">`

Section headers¶

If documentation gets longer, it is often a good idea to split it into sections. It is possible to separate sections with headers using syntax = My Header =, where the number of equal signs denotes the header level:

= First section =

== Subsection ==

Some text.

== Second subsection ==

More text.

= Second section =

You probably got the idea.

Notice that only three header levels are supported and that spaces between equal signs and the header text are mandatory.

Tables¶

Tables are created using pipe characters with spaces around them as column separators and newlines as row separators. Header cells can be created by surrounding the cell content with equal signs and optional spaces like = Header = or =Header=. Tables cells can also contain links and formatting such as bold and italics:

1
2
3

| =A= |  =B=  | = C =  |
| _1_ | Hello | world! |
| _2_ | Hi    |

The created table always has a thin border and normal text is left-aligned. Text in header cells is bold and centered. Empty cells are automatically added to make rows equally long. For example, the above example would be formatted like this in HTML:

A	B	C
1	Hello	world
2	Hi

Lists¶

Lists are created by starting a line with a hyphen and space (-). List items can be split into multiple lines by indenting continuing lines with one or more spaces. A line that does not start with - and is not indented ends the list:

Example:
- a list item
- second list item is split
  to multiple lines

This is outside the list.

The above documentation is formatted like this in HTML:

Example:

a list item
second list item is split to multiple lines

This is outside the list.

Preformatted text¶

It is possible to embed blocks of preformatted text in the documentation. Preformatted block is created by starting lines with |, one space being mandatory after the pipe character except on otherwise empty lines. The starting | sequence will be removed from the resulting HTML, but all other whitespace is preserved.

In the following documentation, the two middle lines form a preformatted block when converted to HTML:

Doc before block:
| inside block
|     some    additional whitespace
After block.

The above documentation is formatted like this:

Doc before block:

inside block
    some    additional whitespace

After block.

Horizontal ruler¶

Horizontal rulers (the <hr> tag) make it possible to separate larger sections from each others, and they can be created by having three or more hyphens alone on a line:

Some text here.

---

More text...

The above documentation is formatted like this:

Some text here.

More text...

Markdown format¶

Markdown is a lightweight plain text markup syntax that is very widely used for documentation, README files, and technical content across the software development industry.

Starting from Robot Framework 7.5, Markdown is supported by Libdoc and can be used for documenting libraries and user keywords. The plan is to add support for using Markdown in suite and test documentation in the future as well.

Markdown flavors¶

The biggest problem with Markdown is that different Markdown implementations are not fully compatible with each others. The original Markdown implementation had a somewhat informal specification and also lacked commonly needed features such as tables. The Markdown ecosystem diverged when new implementations handled ambiguous cases differently and implemented missing features in different ways.

The CommonMark specification tries to unify Markdown syntax, but especially older tools still follow the original specification. The good news is that basic features work the same way across implementations.

Robot Framework uses the Python-Markdown module as its underlying Markdown engine. It follows the original implementation closely and is explicitly not CommonMark compliant. It supports basic Markdown features out-of-the-box, but the following extensions are enabled and provide some more functionality:

Code Hilite for syntax highlighting.
Fenced Code Blocks for common code block syntax.
Sane Lists to make lists syntax less surprising.
Table of Contents for automatically generating table of contents.
Tables for table support.
Custom extensions to support admonitions and auto-linking URLs.

This appendix covers the most important Markdown features and also explains when the syntax varies between implementations. For details about the supported syntax, it is best to refer to the original Markdown specification that Python-Markdown closely follows. The specification covers also various useful Markdown features that are not documented here.

Installation¶

Python-Markdown is an optional dependency and users need to install it themselves. That is typically done by running:

1	`pip install markdown`

If syntax highlighting is needed, also Pygments needs to be installed:

1	`pip install pygments`

Inline styles¶

Markdown supports inline styles bold, italics and code. Bold text can be created by surrounding text with two asterisks or underscores like **this is bold** or __this is bold__. The italics style works similarly, but there must be only a single asterisk or underscore like *italics* or _italics_. Using three asterisks or underscores produces bold italics like ***bold italics*** or ___bold italics___.

The code style is created using backticks like `code`. Asterisks or underscores do not have a special meaning inside backticks, so something like `__str__` is formatted as code with __str__ and not as bold code with only str.

Example:

Here we have some **bold text**, some *italics* and finally some `code`.

Linking¶

Inline links¶

The most common way to create links in Markdown is using inline links like [an example](http://example.com). This link syntax supports also optional title text like [an example](http://example.com "Optional title").

Example:

[Robot Framework](http://robotframework.org) development is supported by
[Robot Framework Foundation](http://robotframework.org/foundation "Join us!").

Reference links¶

Markdown also supports reference links like [link text][reference]. This is especially convenient if the link target is long or if it is used multiple times. Using this style requires the reference to be created separately using syntax [reference]: http://example.com "Optional title" somewhere in the document.

Example:

[Robot Framework][robot] development is supported by
[Robot Framework Foundation][foundation].

[robot]: http://robotframework.org
[foundation]: http://robotframework.org/foundation "Join us!"

If the link text matches the reference name, it is possible to omit the refence name like [reference][]. The empty reference part can also be dropped altogether like [reference], but this syntax is not supported by all Markdown flavors. Reference matching is case-insensitive in general and in with Robot Framework also spaces and underscores are ignored.

Example:

[Robot Framework] development is supported by [Robot Framework Foundation].

[Robot Framework]: http://robotframework.org
[Robot Framework Foundation]: http://robotframework.org/foundation "Join us!"

Depending on the context, there may also be automatic reference targets available. For example, Libdoc makes keywords, section headers and argument types available as link targets automatically.

Autolinks¶

URLs and email addresses inside < and > are automatically made clickable links and the surrounding angle brackets are removed:

1	`Our website is at <http://example.com>. You can reach us via <info@example.com>.`

URLs are recognized also without special formatting:

1	`Robot Framework website is at http://robotframework.org.`

Note

Automatic URL detection without the angle brackets is not a standard Markdown feature, but various Markdown implementations support it for convenience.

Tables¶

Tables are created by separating columns with pipes and using hyphen for separating headers from rest of the table. The whole table can be surrounded with pipes as well, but that is not required.

Example:

Header 1 | Header 2 | Header 3
-------- | -------- | --------
First    | Second   | Third
a        | b        | c

Headers are center aligned and other cells left aligned by default. That can be controlled by starting or ending the hyphen line with a colon like :--- (left), ---: (right) and :--: (center), but this then affects the whole column.

Example:

| Left   |  Center  |  Right |
| :----- | :------: | -----: |
| First  |  Second  |  Third |
| a      |     b    |      c |

Tables support inline styles and links, but not block level content like lists.

Note

Tables are supported via Python-Markdown's tables plugin.

Note

Tables are not a standard Markdown feature and neither the original Markdown implementation nor CommonMark supports them. The above syntax is somewhat widely used, though.

Lists¶

Unordered lists¶

Unordered lists can be created using *, + or - as the list marker followed with one or more spaces:

- First item.
- Second item.

Ordered lists¶

Ordered lists are created with a number followed by a period and one or more spaces:

1 2	`1. First item. 2. Second item.`

Splitting lines¶

If a list item is long, it can be split to multiple lines. Indenting lines is not necessary, but it makes the syntax easier to read.

Example:

- This list item is pretty long. It is thus
  split to multiple lines.
- The second item is short.

Nested content¶

Nested lists are supported, but they must be indented by four spaces. Empty rows can be added between lists, but they are not mandatory.

Example:

1. First item.
    - Nested unordered item.
    - Another nested item.
2. Second item.
    1. Nested ordered item.
    2. Another nested item.

If a list item has multiple paragraphs or other content such as tables, also they must be indented with four spaces. The initial content can be aligned to the same level to avoid inconsistent alignment.

Example:

-   First item has multiple paragraphs. This is the first one.
    Notice the optional four space alignment.

    This is the second paragraph. Here the four space
    alignment is mandatory.

-   Second item has a table. Empty rows above and below this
    paragraph are optional, but enhance readability.

    H1 | H2 | H3
    -- | -- | --
    a  | b  | c
    1  | 2  | 3

Note

The required list item indentation varies between Markdown implementations and some implementations also require empty lines before lists. Test your markup with different tools if you have strict interoperability needs.

Section headers¶

The most common syntax for section headers is # Header where the number of hash characters specifies the header level. This syntax supports up to six header levels.

Example:

# Top level heading

## Second level

Some content.

## Second level again

### Third level

The end.

Alternatively headers can be underlined with = (level 1) and - (level 2). This syntax supports only two header levels.

Example:

Top level heading
=================

Second level
------------

Some content.

Second level again
------------------

The end.

Table of contents¶

Table of contents can be inserted by using a %TOC% marker. It is generated automatically based on the used section headers so that the two highest level headers are included.

Example:

%TOC%

# Top level

This section is included in TOC.

## Second level

Also this section is included in TOC.

### Third level

This section is not included in TOC.

# Top level again

This section is included in TOC.

Note

Generating table of contents is not a standard Markdown feature. The %TOC% marker used by Robot Framework is also different to what Python-Markdown's toc plugin uses by default.

Note

Libdoc supports the same %TOC% marker also when creating table of contents with the Robot Framework custom format.

Code blocks¶

Fenced code blocks¶

Fenced code blocks are the most common way to format code in Markdown. They start with an opening fence of three or more backtick (```) or tilde (~~~) characters and are closed with a matching fence. The opening fence can also contain the language name and possible other information for the underlying Markdown engine.

Example:

Here's some Python code:

```python
def hello(name):
    print(f"Hello, {name}!")

hello("Robot")
```

Warning

Fenced code blocks are only supported at the document root level. They cannot be nested inside lists, admonitions, or other such elements.

Syntax highlighting¶

If a language is specified and Pygments syntax highlighter is installed, the code will be syntax highlighted. Pygments supports also Robot Framework out-of-the-box which makes creating examples easy.

Example:

def hello(name):
    """Keyword to greet the thing specified with `name`.

    ```robotframework
    *** Test Cases ***
    Example
        Hello    Robot
    ```
    """
    print(f"Hello, {name}!")

Indented code blocks¶

Code blocks can also be created by using four space indentation. The used CodeHilite plugin supports highlighting also in that case if the code starts with shebang like #!python or with three colons followed by the language name like :::robotframework.

Example:

Here's some Python code:

    #!python
    def hello(name):
        print(f"Hello, {name}!")

    hello("Robot")

Admonitions¶

Admonitions, also known as alerts or callouts, make it easy to create notes, tips and warnings that stand out from the normal text. Robot Framework supports them using the following syntax:

> [!TYPE] Optional title
> Admonition text. Can contain multiple paragraphs and normal *formatting*.

Admonitions are not a standard Markdown feature, but GitHub and various other implementations support them using the above syntax as well. All implementations, including GitHub, do not support using a custom title, though. The admonition syntax is based on the Markdown blockquote syntax, so also tools that do not recognize it ought to handle it reasonably well.

Admonitions get different styles depending on their type. Robot Framework supports the same types that GitHub does:

NOTE (blueish)
TIP (greenish)
IMPORTANT (purplish)
WARNING (yellowish)
CAUTION (reddish)

If a type is not recognized, it is treated the same way as the NOTE type. If the optional title is omitted, the capitalized type name is used instead.

Examples:

> [!NOTE]
> Markdown support is new in *Robot Framework 7.5*.

> [!WARNING] Interoperability risk
> Differences between Markdown flavors can cause problems.