ReStructuredText Markup

The reStructuredText specification allows for a certain degree of flexibility in markup to achieve your goals. For example, you can use any one of more than a dozen characters for section title underlines, and you have the option of using an overline in addition to an underline.

However, for consistency and ease of use, the Mattermost documentation should use a single convention, despite the existence of allowable alternatives.

For more information about reStructuredText markup, see the reStructuredText Markup Specification. Additional markup constructs are implemented by Sphinx, the documentation generator used by Mattermost. For information about the additional constructs, see Sphinx Markup Constructs.

Use the following markup conventions in Mattermost documentation:

Page Titles

Underline page titles using =, with no overline. Underlines should be as long as the title text. For example:

Document Title
==============

Section Titles

Underline using - for section titles. For example:

Section Title
-------------

Underline subsections using ~ for the first subsection level, and ^ for the second subsection level. For example:

Subsection One
~~~~~~~~~~~~~~

Subsection Two
^^^^^^^^^^^^^^

Table of Contents

Insert a table of contents into a document using the following format:

.. contents::
    :backlinks: top

Inline Markup

Bold
Use double asterisks. For example: **bold text**.
Italic
Use single asterisk. For example: *italic text*.
Monospace
Use double backquotes. For example: ``monospace text``

Bullet Lists

For bullet lists and sublists, use - before the list item. For example:

- list item one
- list item two
  - sublist item one
  - sublist item two
- list item three

Numbered Lists and Procedure Steps

Create numbered lists and procedure steps using numbers for the top-level list and lower case alpha characters for the first nested list. For example:

1. This is item one.
2. This is item two.

  a. This is nested item one.
  b. This is nested item two.

3. This is item three.

Name-value Groups

To create a name-value group such as a definition list, type the term on a line by itself. On the next line, indent the definition. For example:

Total Users
  The total number of active accounts created on your system. Excludes inactive accounts.
Total Teams
  The total number of teams created on your system.

Images

Use the following construct to insert an image:

.. image:: ../images/choices.png

You should use alt tag for all images.

You can also add the following image options: height, width, scale, align, and target. For example:

.. image:: ../images/choices.png
  :alt: The choices that you can make.
  :height: 100px //number refers to pixels
  :width: 200px //number refers to pixels
  :align: left //left, right or middle
  :scale: 50 //number is a percentage

Inserting an inline image is a bit more complicated. It’s a two-part construct that consists of a label and the image directive. Surround the label text with vertical bars, the | character. For example:

Some of the emoji that you can use are |emoji|.

Then insert the following image directive at the bottom of the document:

.. |emoji| image:: ../images/emoji.png
  :alt: Some of the emoji that you can use.
  :align: middle

Literal Blocks

To use a literal block with no syntax highlighting, use the Sphinx code-block directive with the language set to none. For example:

.. code-block:: none

Code Blocks with Syntax Highlighting

To create a code block with syntax highlighting, use the Sphinx code-block directive with the language set to the language that you want highlighted. Many languages are available, but in Mattermost documentation the most likely ones are as follows:

  • go
  • rest
  • html
  • javascript
  • coffee
  • bash

The following example is a block of Go code using the :linenos: option, which causes line numbers to be displayed.

.. code-block:: go
  :linenos:

  newPassword := props["new_password"]
      if err := utils.IsPasswordValid(newPassword); err != nil {
              c.Err = err
              return
      }

The example produces the following output:

1
2
3
4
5
newPassword := props["new_password"]
      if err := utils.IsPasswordValid(newPassword); err != nil {
              c.Err = err
              return
      }