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.
- # Hashtag (Used to create Headers or to reference another Issue)
- * Asterisk (Used to make text bold)
- _ Underscore (Used to italicize text)
- ~ Tilde is used to strikethrough text in comments.
- [ Opening square brackets, and ] Closing square brackets are used to make checklists
- ‐ Dash (One dash is used before text to make an unordered list. Three dashes in a row between paragraphs is used to make a line)
- > Greater-than symbol (Used to indicate a blockquote)
- ` Backtick (Used to create code snippets)
- @ Mention character (Used to reference another user)
- ` Backtick (Used to create snippets of code and have them appear as one block)
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.
Markdown header examples
# I am the largest header
I am the largest header
## I am a slightly smaller header
I am a slightly smaller header
### I am a small header
I am a small header
3 levels of titles is most common, but you can go up to 6 #'s to make a really small header.
Adding emphasis to text
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:
**Text with two asterisks at the start and end of it appears bold**
Text with asterisks at the start and end of it appears bold
_Text with underscore at the start and end of it appears italicized_
Text with underscore at the start and end of it appears italicized
You can use both the * and the _ together to make text appear both bold and italicized
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 listscreated 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.
- Lists are great for to do items.
- Or when needing to list out findings.
- They are also very scannable when reading an Issue!
To create an ordered list, place the number, and a period before each line item.
- Need to add a structured order to a list? Use numbers instead of dashes!
- Your team will then know what comes first, second, third, and so forth.
- Ordered lists are great for indicating next steps as well.
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.
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
To create a link, you need to add two sets of brackets: square brackets for the text that you'd like to display, oval brackets for the link that will target where you'd like the text to hyperlink out to
- [ Opening square brackets, and ] Closing square brackets are used around the text section
- ( Opening oval brackets, and ) Closing oval brackets are used around the link section
Ensure there are no spaces between the oval brackets surrounding the text that you'd like to appear, and the link in oval brackets.
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.
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:
Creating section lines
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.
Referencing other GitHub Issues
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.
Mentioning another user in a comment
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.