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.

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.

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