Markdown can be used both in Github and Gitlab comments section. They have an implemented parser for it that turns plain text into HTML. So it is safe to say that Markdown is a plain text HTML preprocessor like haml or nunjucks. So these are the sections for example where you can use the Markdown syntax in write mode and visualize the result in Preview mode.
The new Issue section in Github:
Also the new Issue section in Gitlab:
The common thing in both is that each of them has the comment field that supports the Markdown language. Instead of writing plain text comments you are able to write rich-text comments, with tables, lists, emphasized text, links and images and so on.
The file extension for the Markdown files is the .md and you might have seen it before in github repositories, there is always a readme.md file that describes the project in a stylish fashion with bulleted lists, bolded text and whatnot.
You can also encounter Markdown in static site generators like Gatsby.
Ok, time for action. Let’s see what Markdown can do !
Headings(h1-h6)
Markdown can generate h1 to h6 by using the hash(#) character, the number of hashes representing the level of the heading. So h1 is one hash caracter, h6 is 6 hash character followed by the title text.
Lists
It is simple to create a bulleted list, you just have to add a dash and space before your text. The list can also be multi-level list / nested lists.
Note: The list items can be prefixed instead of dash with the + or the * sign also and it will generate the same bulleted unordered list. But beware of using them mixed in the same list, that is not good practice. If you choose one sign, stick with it till the end.
Numbered list or ordered list can also be generated with Markdown.
Even if you write the same number(with an editor without autocomplete numbering), it will still correct it and increment the numbering.
Emphasizing text
*italic text*
_italic text_
**bolded text**
~~strikethrough text~~
***bold and italic text***
***~~bold and italics and strikethrough text~~***In case you want to use one of the signs from above as a text you need to to escape it with backslash
\*Text with star\*Blockquotes
These blockquotes can be on one or multiple lines. In case if you want multiple blockquotes instead of one blockquote with multiple lines just put a new line between the 2 quotes.
Also you can make nested blockquotes:
In a normal fashion you can add any kind of element inside blockquote:
Links and referencing
[UI workarounds website](https://ui-workarounds.com "check out UI workarounds website here")This is the result in the DOM:
You can also make anchor links by adding in the round parenthesis the id with the hash like this
[UI workarounds contact section](#contact "check out UI workarounds contact section")In case you have a long link or you want to use the same link multiple times you can store it and then use it with a reference text like this:
[UI workarounds website][link1]
[link1]: https://ui-workarounds.com "check out UI workarounds website here"Images
The Markdown syntax for images is very similar to writing an anchor. You just have to add an exclamation mark to the beginning of the link:
Note: Referencing an image url works the same way as with the links.
Code blocks
I used the backtick sign to write a codeblock. If you decide to have a multiline codeblock you will have to write it with triple backtick signs:
If I want to use a backtick inside a codeblock I can do it by adding an additional backtick:
Codeblocks can be more syntax specific:
```javascript
function substract(a,b) {
return a + b;
}
```Tables and alignment
| Name | Email | Age |
| :--- | :---: | --: |
| Joe Black | joe@gmail.com | 10 |
| Joe | Joe | 20 |
| Black | Jack | 34 |
| joe: | | 30 |
You don’t even have to align the columns visually, just make sure that you have the same column number in each row.
The alignment works the following way:
:— Means left aligned
:—: Means center aligned
—: Means right aligned
Horizontal Rule
By adding one of the 3 options you can generate a horizontal rule in the page:
---
***
___Task list
You can add a task list in the following manner:
- [x] Task 1
- [x] Task 2
- [ ] Task 3
Footnotes
You can also add footnotes with explanations:
Conclusions: Markdown empowers your github or gitlab editor to support rich text. You can create tables, footnotes, emphasized text, lists, headings and much more. It makes your issue notes much more readable. Use Markdown to make your comments more appealing to the eye.
