Markdown is a way to quickly & simply style text for the web by using .md
files.
GitHub Flavored Markdown add new functionnalities on top of regular markdown to let you create beautiful & interactive documents in GitHub and GitHub Enterprise.
This gist covers all the main & advanced options you have with markdown & github markdown.
This file itself is created with github markdown, click the "Raw" button to see its contents !
- Images Resizing & Alignment
- Dropdowns
- Buttons
- Anchor Links
- User mentions
- Issues, pull requests & commits reference
- Colors examples
- Colored text
- Footnotes
You can make Headers with "#" and a space betwxeen your text. The more the "#" the smaller the header.
You can also make level 1 & 2 headers (or H1 & H2, the two biggest) with "=" and "-" respectively.
Code :
-> This is a H1 tag
===============
-> This is a H2 tag
---------------
## -> This is also a H2 tag
#### -> This is a H3 tag
#### -> This is a H4 tag
#### -> This is a H5 tag
###### -> You have smaller & smaller headers until this size (H6 tag)
You can make italic text in two ways
Same for bold text!
You can also strikethrough
Finally you can combine them as you see fit !
Code :
You can make *italic text* in _two ways_
**Same** for __bold text!__
You can also ~~strikethrough~~
Finally *you **can** ~~combine~~ them* as you see fit !
Tip : the best practice is to always use * and not _, because underscores can be interpreted differently when between words with different markdown engines/
To nest a list you have to add 2 or 4 spaces before the item.
- Item 1
- Item 2
- Item 2a
- Item 2b
Code :
* Item 1
* Item 2
* Item 2a
* Item 2b
- Item 1
- Item 2
- Item 2a
- Item 2b
- Item 3
- You can mix ordered
- & unordered lists !
Code :
1. Item 1
2. Item 2
1. Item 2a
2. Item 2b
3. Item 3
* You can mix ordered
* & unordered lists !
You can include tooltips as well.
If the url isn't valid it will display the alternative text :
Code :
![Tesla Logo](https://upload.wikimedia.org/wikipedia/commons/thumb/2/2e/SpaceX_logo_black.svg/300px-SpaceX_logo_black.svg.png "Elon, please save us from AGI !!")
If the url isn't valid it will display the alternative text : ![Alt Text](invalid.url)
If you include a valid url : http://github.com - it link to it automatically. (You can disable the automatic link with "`" : http://www.example.com
)
You can also include link with any text : GitHub
And add a tooltip ! GitHub
Or an email address : a False Email
Code :
If you include a valid url : http://github.com - it link to it automatically. (You can disable the automatic link with "\`" : `http://www.example.com`)
You can also include link with any text :
[GitHub](http://github.com)
And add a tooltip !
[GitHub](http://github.com "This is a low-inspiration tooltip")
Or an email address :
[a False Email](mailto:metawhy@mail.com)
As Richard Branson said :
Do not be embarrassed by your failures, learn from them and start again. I got that from my good friend Metawhy, who also said to me :
Richard, to make nested block quotes on markdown you only have to add aonother ">" at the beginning of each line !
Code :
> Do not be embarrassed by your failures, learn from them and start again.
> I got that from my good friend Metawhy, who also said to me :
>> Richard, to make nested block quotes on markdown
>> you only have to add aonother ">" at the beginning of each line !
You can do a single line between two `
function say_hi() {console.log("hi :)");}
For multiple lines, you can add 4 (sometimes 2) spaces at the beginning of each line
function say_bye() {
console.log("bye !");
}
Or between two "```". You can even put the common abbreviation of the language to help the software do automatic formatting. Here I put "js" for Javascript. See how the syntax is automatically highlighted !
function say_what() {
console.log("whaaa?..");
}
Code :
`function say_hi() {console.log("hi :)");}`
function say_bye() {
console.log("bye !");
}
```js
function saywhat() {
console.log("whaaa?..");
```}
If you want to use any of these characters without making the associated formatting in markdown, you can do so by adding "" before the character. It can be useful for all these characters :
All characters | you can escape |
---|---|
\ backslash | * asterisk |
` backtick | {} curly braces |
_ underscore | [] square brackets |
# hash mark | () parentheses |
+ plus sign | - minus sign (hyphen) |
. dot | ! exclamation mark |
Github markdown adds new possibilities !
You can underline or super script your text,
You have also additional ways to :
- make text bold
- or italic.
make code blocks,
- lists
Finally you can manage text alignment :
Left
Centered
Or Right.
Code :
You can <ins>underline</ins> or <sup>super script</sup> your text,
You have also additional ways to :
<ol><li> make text <b>bold</b></li>
<li>or <i>italic</i>.</li>
<li><pre>make code blocks, </pre></li></ol>
<ul><li>lists</li></ul>
<li>and include pictures <img height="30" src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/bd/Tesla_Motors.svg/175px-Tesla_Motors.svg.png"> </li></ul>
<br/>
Finally you can manage text alignment :
<p align="left">Left</p>
<p align="center">Centered</p>
<p align="right">Or Right.</p>
By the way, these are interactive !
- Complete item
- Incomplete item
- Nested items
- You can use formatting inside items !
Code :
- [x] Complete item
- [ ] Incomplete item
1. [x] Nested items
2. [ ] You __can__ use *formatting* inside items
1st Header | 2nd Header | 3rd Header |
---|---|---|
Cell 1a | Cell 2a | Cell 3a |
Cell 1b | Cell 2b | Cell 3b |
Code :
1st Header | 2nd Header | 3rd Header
------------ | ------------- | -------------
Cell 1a | Cell 2a | Cell 3a
Cell 1b | Cell 2b | Cell 3b
๐ โจ ๐
To use an emoji, find it here & copy the corresponding text (including the ": :") in your .md
file
You can also simply copy/pase emojis, but it might be incompatible with other markdown languages.
To create a horizontal line like these :
Use either :
---
***
_____
To add extra space, use one or more:
<br>
Align an image :
- Left or right : you have to use a "img" html-like tag to include the image, then set the "align" attribute to either "left" or "right"
- Center : use a "p" html-like tag, then set its "align" attribute to "center"
**Resize an image :** Set its "width" or "height" attribute to to the desires value in pixels.
Examples :
Code :
<img align="left" width="150" src="https://apaskulin.github.io/waxtechnical/images/pup.jpg">
<br/>
<img align="right" width="100" src="https://apaskulin.github.io/waxtechnical/images/pup.jpg">
<br/>
<p align="center">
<img height="75" src="https://apaskulin.github.io/waxtechnical/images/pup.jpg">
</p>
To make a dropdown :
Code :
<details>
<summary>Visible text</summary>
This is a dropdown with text!<br>
<ul><li>It can contain</li>
<li>a list!</li></ul><br>
<img src="https://apaskulin.github.io/waxtechnical/images/pup.jpg" width="500"><br>
<pre>Or some <br>code !</pre>
</details>
You can also make it open by default, just add the "open" attribute !
Some good text
> Did someone compliment your hair today ? It looks ravishing.Code :
<details open>
<summary>Some good text</summary>
> Did someone compliment your hair today ? It looks ravishing.
</details>
You can create a single button, or multiple buttons:
Here is one button |
---|
Here is 1, | 2 | And 3 buttons ! |
---|
Use:
|[Here is one button](https://github.com/)|
|---|
|[Here is 1,](https://github.com/)|[2](https://github.com/)|[And 3 buttons !](https://github.com/)|
|---|---|---|
You can link any heading of your current markdown document by using its name (use dashes to replace spaces!)
This link leads to the current section's header.
Code :
This [link](#Anchor-Links) leads to the current section's header.
You can also create an anchor anywhere on the page, use:
Then reference it with its "name" attribute.
Code :
You can also create an anchor anywhere on the page, use:
<a name="my-special-anchor">
Then [reference it](#my-special-anchor) with its "name" attribute.
Using @
followed by a username or a team name. It will notify that person/team to come and view the file.
@Metawhy
Any number that refers to an Issue or Pull Request will be automatically converted into a link. By default, in the current github repository but you can link others. Here are all the references you can make :
Reference type | Example Markdown reference |
---|---|
Issue or pull request URL | jlord/sheetsee.js#26 |
# and issue or pull request number | #26 |
GH- and issue or pull request number | GH-26 |
Username/Repository# and issue or pull request number | jlord/sheetsee.js#26 |
Organization_name/Repository# and issue or pull request number | github-linguist/linguist#4039 |
For commits & SHA : it will automatically generate a link to the commit.
Reference type | Example Markdown reference |
---|---|
Commit URL | jlord/sheetsee.js#26 |
SHA | a5c3785ed8d6a35868bc169f07e40e889087fd2e |
User@SHA | jlord@a5c3785ed8d6a35868bc169f07e40e889087fd2e |
Username/Repository@SHA | User/Repository@SHA: jlord/sheetsee.js@a5c3785ed8d6a35868bc169f07e40e889087fd2e |
You can generate dynamically the colors :
Code :
- ![#f03c15](https://via.placeholder.com/15/f03c15/000000?text=+) `#f03c15`
- ![#c5f015](https://via.placeholder.com/15/c5f015/000000?text=+) `#c5f015`
- ![#1589F0](https://via.placeholder.com/15/1589F0/000000?text=+) `#1589F0`
There is to this date no direct way of adding color to your text (see here). If it is very important for you, here is a workaround :
- text in red
+ text in green
! text in orange
# text in gray
@@ text in purple (and bold)@@
text in black
It uses the syntax highlighting to color the line. We unfortunately have to keep the -/+/!/#/@@ to make the corresponding color work.
Code :
```diff
- text in red
+ text in green
! text in orange
# text in gray
@@ text in purple (and bold)@@
text in black
```
Finally, a last nice trick is adding footnotes1 to your work2.
1: Footnote 1
2: Footnote 2 with format, { and code }
Code :
Finally, a last nice trick is adding footnotes<sup>[1](#myfootnote1)</sup> to your work<sup>[2](#footnote2)</sup>
<a name="myfootnote1">1</a>: Footnote 1
<a name="myfootnote1">1</a>: Footnote 2 with **format**, `{ and code }`