Markdown is a simple way to format comments when writing on the ZenHub platform.
Markdown changes the way text is displayed in comments by using common non-alphabetic characters to add formatting. Looking to make something bold? Add a header section? Or perhaps make a list of to-do items? Markdown helps you add these visual changes using characters as the #, *, or _ symbols.
Below is a list of various non-alphabetic characters that are used in Markdown and their corresponding names.
A great way to organize information into sections is to make use of headers. To make a header using Markdown, you use the # character.
The greater number of # used before the desired header text, the smaller the header will appear. Below are three different levels of headers.
When creating titles, it is important to leave a space between the # characters and the actual title name. If you do not leave a space, the header will not properly form.
3 levels of titles is most common, but you can go up to 6 #'s to make a really small header.
To make certain words or sentences appear bold or italicized in Markdown, you use the asterisk * for bolding, underscore _ for italicizing, and ~ for strikethrough. Below is an example for each:
Make a bolded, italicized sentence by putting them one after the other on either end of your text.
_**A bolded and italicized sentence.**_ will appear as: A bolded and italicized sentence.
When combining the * and the _, keep in mind that you have to add them at the end of your text in the opposite order that you applied them to the start of your text to make sure they close properly.
There are three types of lists that can be created using ZenHub markdown: unordered lists created by putting the dash ‐ before text, ordered lists, which are created by adding numbers with a dot (for example: 1.) before text, and checklists which are created using the [ and ] brackets. Below is an example of both list types:
To create an unordered list, place a dash before each line item. Each new list item should be on a new line.
To create an ordered list, place the number, and a period before each line item.
To create a task checklist place a dash before each line item before the brackets. Each new list item should be on a new line. Before to leave a space between each bracket to make it appear as interactive checklist item.
To create an in-line quote, use the greater-than character > before a block of text to make it appear as a blockquote.
Below is an example of how to use Markdown to create a blockquote and how it will render:
Place all the relevant text you would like to quote after the character.
Using the ` character, you can create code snippets in-line by placing 1 ` on either end of text. To make a code snippet block, place 3 `s and create a line break before adding text (you will also need to make a line break and add the ` at the end of a block of text). Adding a ` on the line above and below text makes the text appear as 1 full block.
Below are examples of in-line and block code snippets:
To create a horizontal line within a comment to make a section break, or visually create breaks within the comment you can use the ‐ character 3 times in a row. To create an in-comment line, and not just create a title, it is important to leave a line-break before and after the dash.
To create a cross-link between one Issue and another, use the # character and add the Issue number of the Issue you would like to mention.It is important when referencing other Issues to not leave a space between the # and the Issue information, otherwise a header will be created.
To mention other team mates in an Issue, use the @ character and then begin typing the individual's GitHub username. This will cause a dropdown of users to appear where you can select your team mate. Once mentioned, they will receive a notification with your comment and the Issue information so they can follow-up.