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.18+ (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>}}