README.md

Mattermost developer documentation

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

Contribute

Prerequisites

• Golang v1.19+ (download)
• NodeJS v14+ (download)
• cURL (download)
  • (optional) Used to update Compass Icons

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 github.com/gohugoio/hugo@v0.101.0

2. Fork the repository and clone the fork to your machine. Change directories to the cloned repo when it has finished.

   git clone git@github.com:<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 developers.mattermost.com should use the newtabref shortcode.

Hugo shortcodes

Collapse

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`
{{</collapse>}}

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

Mermaid

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.

{{<mermaid>}}
sequenceDiagram
    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
{{</mermaid>}}

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="https://pkg.go.dev/github.com/mattermost/mattermost-plugin-apps/apps#Manifest">}}) as a JSON object.

Note

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.
{{</note>}}

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>}}
{{<tab "tabid2">}}
- Content for tab #2
{{</tab>}}

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:

tab1_id,tab1_name;tab2_id,tab2_name;...

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">}}
...tab content defined here...
{{</tab>}}

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>}}
{{<tab "tab2_id">}}
- Content for tab #2
{{</tab>}}

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