Skip to content


Mattermost developer documentation Mattermost dev docs status badge

Website for Mattermost developer documentation, built using Hugo. The master branch is continuously deployed to



Set up your environment

  1. Follow the Hugo documentation to install Hugo. This repo uses Hugo v0.101.0 to build the docs.

    # For example, on macOS:
    brew install hugo
    # Snapcraft on Linux:
    snap install hugo
    # or using golang directly:
    go install
  2. Fork the repository and clone the fork to your machine. Change directories to the cloned repo when it has finished.

    git clone<yourgithubname>/mattermost-developer-documentation.git
    cd mattermost-developer-documentation
  3. Generate JSON plugin docs; this must be done at least once.

    make plugin-data
  4. Start the Hugo development server.

    make run
  5. Open http://localhost:1313 in a new browser tab to see the docs

You're all set! You can start making changes as desired; the development server will automatically re-render affected docs pages.

Note: Before pushing changes to your fork, run a full build of the docs using make dist to make sure there are no build errors.

Best practices

  • The Mattermost developer documentation uses several custom Hugo shortcodes to control its presentation. Shortcodes are preferred over using raw HTML and should be used where possible.
  • Links that navigate away from should use the newtabref shortcode.

Hugo shortcodes


The collapse shortcode creates a collapsible text box.

{{<collapse id="client_bindings_request" title="Client requests bindings from server">}}
`GET /plugins/com.mattermost.apps/api/v1/bindings?user_id=ws4o4macctyn5ko8uhkkxmgfur&channel_id=qphz13bzbf8c7j778tdnaw3huc&scope=webapp`

Example of collapse shortcode

Note that the id attribute of the shortcode must be unique on the page.

Compass icon

The compass-icon shortcode displays an icon from the Compass Icon set. The shortcode takes 2 arguments: the ID of the icon and an optional icon description which is used as alt text.

{{<compass-icon icon-star "Mandatory Value">}}

Example of compass-icon shortcode


The mermaid shortcode allows embedding Mermaid diagram syntax into the page. Each page that uses a Mermaid diagram must also have a mermaid: true property set in the page's frontmatter.

    actor System Admin
    System Admin->>Mattermost server: install app
    Mattermost server->>Apps framework: install app
    Apps framework->>App: request manifest
    App->>Apps framework: send manifest
    Apps framework->>System Admin: request permissions
    System Admin->>Apps framework: grant permissions
    Apps framework->>Mattermost server: create bot
    Apps framework->>Mattermost server: create OAuth app
    Apps framework->>Apps framework: enable app
    Apps framework->>App: call OnInstall if defined

Example of Mermaid shortcode

Open links in a new tab

The newtabref shortcode creates a link that opens in a new browser tab. The link text is followed by a Compass Icon which indicates the link will open in a new tab.

All Apps should define a manifest ({{<newtabref title="godoc" href="">}}) as a JSON object.

Example of newtabref shortcode


The note shortcode displays a styled message box suitable for a note. The shortcode accepts 3 arguments: the title of the node, an optional Compass Icon ID, and an optional description for the Compass Icon.

{{<note "Mandatory values" "icon-star" "Mandatory Value">}} 
- The `app_id` and `homepage_url` values must be specified.
- At least one deployment method - `aws_lambda`, `open_faas`, or `http` - must be specified.

Example of note shortcode

Tabbed content

A combination of the tabs and tab shortcodes create a section of tabbed content. The tabs shortcode defines the list of available tabs in the tab "selection bar", each with a unique ID and name. The tab shortcode defines the content for an individual tab.

Example of using tabbed content shortcodes:

{{<tabs "tab_group_name" "tabid1,tabname1;tabid2,tabname2;..." "initial_tab_id">}}
{{<tab "tabid1" "display: block;">}}
- Content for tab #1
{{<tab "tabid2">}}
- Content for tab #2
tabs shortcode

The tabs shortcode creates the top portion of tabbed content: a list of available tabs, each with a click handler.

The general format of the shortcode is:

{{<tabs "tab_group_name" "list_of_available_tabs" "initial_tab_id">}}

To ensure tabs in one group don't affect another group, a unique tab_group_name is required. The available tabs in the group are defined in a single string of the format:


The following example defines a group of two tabs named Android and iOS:

{{<tabs "mobile" "mobile-droid,Android;mobile-ios,iOS" "mobile-droid">}}

The initial_tab_id specifies the ID of the tab that should be active when the page loads.

tab shortcode

The tab shortcode defines a section of content for a specific tab.

The general format of the shortcode is:

{{<tab "tab_id" "initial_tab_style">}} content defined here...

The tab_id must correspond to a tab ID defined in a tabs shortcode. The initial_tab_style is used to display the initial active tab's content by specifying a value of display: block;.

The following example defines content for two tabs with IDs tab1_id and tab2_id:

{{<tab "tab1_id" "display: block;">}}
- Content for tab #1
{{<tab "tab2_id">}}
- Content for tab #2
Limitations of tabbed content

Due to the implementation of the tab shortcode, there are some limitations on what information can be rendered:

  • note shortcodes cannot contain bulleted lists