The Magic of Mattermost Markdown

We’re happy to announce that Mattermost is adopting markdown for text rendering. This lets Mattermost users communicate with greater expression and precision through font formatting, emoji, headings, bullet points, tables and many other options.

As an open source Slack-alternative, we get a lot of feature requests for functionality that Slack doesn’t provide, and markdown was high on the list.

Since Mattermost ships in the GitLab omnibus installer (as “GitLab Mattermost“, an MIT licensed binary configured with GitLab SSO), our aim was to be compatible with GitLab Flavored Markdown and its special references tailored for software collaboration.

Example: Sending richly formatted messages in Mattermost using GitLab Flavored Markdown

We’re hugely thankful to the GitLab and Mattermost communities for convincing us to build this, as we love the new functionality and it’s hard to imaging not having it.

For example, before this feature, if you wanted to have shortcuts in channel headers you’d need to use raw URLs–and a pop-over to see all the links:


Now we can turn long URLs into concise links using simple formatting:

[Repo](https://github.com/mattermost/platform) | [Forum](http://forum.mattermost.org/) | [Feature Requests](http://mattermost.uservoice.com/) | [Tickets](http://mattermost.atlassian.net)

Which renders neatly in your channel header:

You can also use image icons in place of words to create shortcut buttons–and this works on dynamic images as well, like build status indicators from systems like Travis CI:

[![Repo](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform) | [![Forum](https://cdn1.slant.co/16474-full.ico)](http://forum.mattermost.org/) | [![Feature Requests](https://cdn1.slant.co/14685-full.ico)](http://forum.mattermost.org/) | [![Tickets](http://www.wsit.me.uk/images/jira.ico)](http://mattermost.atlassian.net) | [![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform)

Here’s how the above renders in your header:

As a fun bonus feature, use “#” to show emoji in different heading sizes:

##### :sheep: 
#### :sheep: 
### :sheep: 
## :sheep: 
# :sheep:

Which renders as:

sheep

Markdown is incredibly compact and powerful, and we’re looking forward to all the creative uses from the community.

Below is an overview of all that it can do today–documentation written in markdown, describing markdown, rendered in markdown in a Mattermost channel:

ScreenClip [437]ScreenClip [438]ScreenClip [439]

Want to see how it works? The above message was generated with the raw markdown text below:

### Markdown Help

Markdown makes it easy to format messages. Type a message as you normally would, and use these rules to render it with special formatting. 

#### Text Style: 

You can use either `_` or `*` around a word to make it italic. Use two to make it bold.

`_italics_` renders as _italics_
`**bold**` renders as **bold**
`**_bold-italic_**` renders as **_bold-italics_**
`~~strikethrough~~` renders as ~~strikethrough~~

#### Code: 

Create a code block by indenting four spaces, or by placing ``` on the line above and below your code. 

Example:
 ```
 code block
 ```
Renders as: 
```
code block
```

Create in-line monospaced font by surrounding it with back spaces. 
```
`monospace`
```
Renders as: `monospace`.

#### Links: 

Create labeled links by putting the desired text in square brackets and the associated link in normal brackets. 
`[Check out Mattermost!](www.mattermost.com)`
Renders as: [Check out Mattermost!](www.mattermost.com)

#### In-line Images

Create in-line images using an `!` followed by the alt text in square brackets and the link in normal brackets. Add hover text by placing it in quotes after the link.
```
![alt text](link "hover text")

and

[![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform) [![Github](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform)
```
Renders as: 
![alt text](link "hover text")
and
[![Build Status](https://travis-ci.org/mattermost/platform.svg?branch=master)](https://travis-ci.org/mattermost/platform) [![Github](https://assets-cdn.github.com/favicon.ico)](https://github.com/mattermost/platform)

#### Emojis

Check out a full list of emojis [here](http://www.emoji-cheat-sheet.com/).

```
:smile: :+1: :sheep:
```
Renders as:
:smile: :+1: :sheep:

#### Lines:

Create a line by using three `*`, `_`, or `-`.

`***` renders as: 
***

#### Block quotes:

Create block quotes using `>`.
`> block quotes` renders as:
> block quotes

#### Lists: 

Create a list by using `*` or `-` as bullets. Indent a bullet point by adding two spaces in front of it.
```
* list item one
* list item two
 * item two sub-point
```
Renders as: 
* list item one
* list item two
 * item two sub-point

Make it an ordered list by using numbers instead:
```
1. Item one
2. Item two
```
Renders as: 
1. Item one
2. Item two

#### Tables: 

Create a table by placing a dashed line under the header row and separating the columns with a pipe `|`. (The columns don’t need to line up exactly for it to work). Choose how to align table columns by including colons `:` within the header row.
```
| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| Left column 1 | this text       |  $100 |
| Left column 2 | is              |   $10 |
| Left column 3 | centered        |    $1 |
```

Renders as:

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| Left column 1 | this text       |  $100 |
| Left column 2 | is              |   $10 |
| Left column 3 | centered        |    $1 |

#### Headings: 

Make a heading by typing # and a space before your title. For smaller headings, use more #’s. 
```
# Large heading
## Smaller heading
### Even smaller heading
```
Renders as: 
# Large Heading
## Smaller Heading
### Even smaller heading

Alternatively, for the large heading you can underline the text using `===`. For the smaller heading you can underline using `---`
```
Large Heading
=============

Smaller Heading
--------------
```
Renders as:
Large Heading
=============

Smaller Heading
--------------

 

There’s still work to be done to complete the full GitLab Flavored Markdown specification. Some of it is formatting, like adding syntax highlighting code from various programming languages, and some elements like GitLab Special References require deeper API integration between GitLab and Mattermost, and that’s planned as well.

Like what you see? Star us on GitHub!

Thanks for your interest in Mattermost and what we’re building. We look forward to your ideas, comments, and questions. You can reach us in many ways at: http://mattermost.org.

Markdown support is on master and ships with Mattermost v0.8.0 on October 2, and GitLab Mattermost on October 22. Please join our mailing list below to be notified of important updates.

Stay updated

Want to know about the latest releases? Subscribe to our monthly mailing list

By | 2017-07-17T04:58:15+00:00 September 24th, 2015|Blog|Comments Off on The Magic of Mattermost Markdown