markdown-style-guide.md

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.

{% hint style="warning" %} This markdown guide is intended solely for contributing to documentation. To view the supported markdown formats in a Rocket.Chat workspace, please refer to the Messages user guide. {% endhint %}

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

| | 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.




Do that.


Done.

|

1. Do this.



Do that.


Done.

| | MD030 - Space after list markers | There should be only one space after a list marker. |

*Foo
*Bar
*Baz



Foo


Bar


Baz

|

* Foo




Bar
Baz


Foo
Bar
Baz

| | MD031 - Fenced code blocks should be surrounded by blank lines | |

| | | MD032 - Lists should be surrounded by blank lines | |

Some text


Some
List


Some
List
Some text

|

Some text


Some
List


Some
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 

|

a link

| | MD046 - Code block style | Code blocks should be fenced. |

  codeblock using indentation.

|

```
codeblock without indentation.

</code></pre>                                                          |

{% hint style="info" %}
For a comprehensive guide on contributing to Rocket.Chat documentation, visit [.](./ "mention")and [documentation-template.md](documentation-template.md "mention")
{% endhint %}