Styling comments with Markdown

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.

Markdown legend

Below is a list of various non-alphabetic characters that are used in Markdown and their corresponding names.

Headers

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.Creating Headers in Markdown

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 and the underscore _ for italicizing. Below is an example for each:

Markdown structure:

**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
Bolding or italicizing using Markdown
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.

Lists

There are two types of lists that can be created using ZenHub markdown: unordered lists created by putting the dash before text, or ordered lists, which are created by adding numbers with a dot (for example: 1.) before text. Below is an example of both list types:

Unordered lists

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!

Ordered lists

To create an ordered list, place the number, and a period before each line item.

  1. Need to add a structured order to a list? Use numbers instead of dashes!
  2. Your team will then know what comes first, second, third, and so forth.
  3. Ordered lists are great for indicating next steps as well.

Blockquotes

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.

Blockquotes with Markdown

Code snippets

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:In-line code snippets with MarkdownBlock code snippets with Markdown

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.Creating lines in markdown

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.Mentioning users in comments in GitHub Issues