Links

Markdown Style Guide

The Rocket.Chat documentation utilizes the Markdown Markup Language (a "Cheatsheet" is available here). Markdown can be composed in a variety of styles, but this document outlines the standard formatting guide for creating Rocket.Chat documentation. Please note, we are presently implementing a markdown linter on incoming Pull Requests. Therefore, it's advisable to ensure your commits pass the linting test prior to submitting a Pull Request. Each rule listed here includes its respective code, so if the linter flags an issue, you can refer back to this guide to identify the broken rule.
Rules
Description
Wrong
Correct
MD001 - Header levels should only increment by one level at a time
Headers should not be skipped, but instead incremented one by one.
# Header 1
### Header 3
We skipped out a 2nd level header in this document
# Header 1
## Header 2
### Header 3
#### Header 4
## Another Header 2
### Another Header 3
MD002 - First header should be a top-level header
The first header of the document should be a top-level header (H1).
## This isn't a H1 header
### Another header
# Start with a H1 header
## Then use a H2 for subsections
MD003 - Header style
The header style used on documents should be atx.
Setext style H1
===============
Setext style H2
---------------
# ATX style H1
## ATX style H2
MD004 - Unordered list style
Lists should be created using asterisks.
* Item 1
+ Item 2
- Item 3
* Item 1
* Item 2
* Item 3
MD005 - No inconsistent indentation for list items at the same level
Lists should maintain consistent indentation. Typically, any violation of this rule is due to a typographical error.
* Item 1
* Nested Item 1
* Nested Item 2
* A misaligned item
* Item 1
* Nested Item 1
* Nested Item 2
* Nested Item 3 --->Aligned
MD006 - Start bulleted lists at the beginning of the line
Lists with bullet points should commence at the start of the line
Some text
* List item
* List item
Some text
* List item
* List item
MD007 - Unordered list indentation
List items should be indented using 4 spaces.
* List item
* Nested list item indented by 3 spaces
* List item
* Nested list item indented by 4 spaces
MD009 - No trailing spaces
There should be no trailing spaces at the end of lines. To rectify this, locate the flagged line and eliminate any spaces trailing at its end.
MD010 - No hard tabs
Indentation should be achieved using spaces, not hard tabs.
MD011 - No reversed link syntax
When creating links you should use the [] surrounding the text and () surrounding the link.
(Incorrect link syntax)[http://www.example.com/]
[Correct link syntax](http://www.example.com/)
MD012 - No multiple consecutive blank lines
The document should not contain more than one consecutive blank line.
Some text here
Some more text here
Some text here
Some more text here
MD018 - Use space after hash on atx style header
There should be a space after the hashes on atx style headers.
#Header 1
##Header 2
# Header 1
## Header 2
MD019 - No multiple spaces after hash on atx style header
In atx style headers, there should not be more than one space following the hash symbol.
# Header 1
## Header 2
# Header 1
## Header 2
MD022 - Headers should be surrounded by blank lines
Every header should be preceded and followed by a blank line, unless the header is positioned at the start or end of the document.
# Header 1
Some text
Some more text
## Header 2
# Header 1
Some text
Some more text
## Header 2
MD023 - Headers must start at the beginning of the line
Some text
# Indented header
Some text
# Header
MD025 - No multiple top-level headers in the same document
A document should contain only one top-level header (h1)
# Top level header
# Another top level header
# Title
## Header
## Another header
MD027 - No multiple spaces after the blockquote symbol
Blockquote should not have more than one space after the blockquote symbol ( > ).
> This is a block quote with bad indentation
> there should only be one.
> This is a block quote with good indentation
> there should only be one.
MD028 - No blank line inside blockquote
A blockquote should not contain a blank line within it. However, if the lines are intended to be part of the same quote, then prepend the blockquote symbol to the start of the blank line.
> This is a blockquote
> which is immediately followed by
> this blockquote. Unfortunately
> In some parsers, these are treated as the same blockquote.
> This is a blockquote.
And Jimmy also said:
> This too is a blockquote.
MD029 - Ordered list item prefix
Ordered lists should be ordered by a prefix that increases in numerical order.
1. Do this.
1. Do that.
1. Done.
1. Do this.
2. Do that.
3. Done.
MD030 - Space after list markers
There should be only one space after a list marker.
*Foo
*Bar
*Baz
1. Foo
1. Bar
1. Baz
* Foo
* Bar
* Baz
1. Foo
1. Bar
1. Baz
MD031 - Fenced code blocks should be surrounded by blank lines
MD032 - Lists should be surrounded by blank lines
Some text
* Some
* List
1. Some
2. List
Some text
Some text
* Some
* List
1. Some
2. List
Some text
MD034 - No bare URLs
Bare URLs should not be present in the document; instead, enclose the links within angle brackets (< >).
For more information, see http://www.example.com/.
For more information, see <http://www.example.com/>.
MD035 - Horizontal rule style
Horizontal rules should be created using three slashes (---).
***
* * *
****
---
MD037 - No spaces inside emphasis markers
Spaces should not be present within emphasis markers (such as bold or italic).
Here is some ** bold ** text.
Here is some _ italic _ text.
Here is some **bold** text.
Here is some _italic_ text.
MD038 - No spaces inside code span elements
Spaces should not be included within code span elements.
` some text `
`some text `
` some text`
`some text`
MD039 - No spaces inside the link text
[ a link ](http://www.example.com/)
[a link](http://www.example.com/)
MD046 - Code block style
Code blocks should be fenced.
codeblock using indentation.
```
codeblock without indentation.
```
For a comprehensive guide on contributing to Rocket.Chat documentation, visit Documentation Contribution Guidelinesand Documentation Template
Last modified 6mo ago
Rocket.Chat versions receive support for six months after release.