Skip to content

Instantly share code, notes, and snippets.

@Metawhy

Metawhy/Github-Markdown-beginner-to-advanced.md

Last active September 13, 2020 16:40
Show Gist options
  • Save Metawhy/b1188b74ff5c9d4fb315e495ad407e66 to your computer and use it in GitHub Desktop.
Save Metawhy/b1188b74ff5c9d4fb315e495ad407e66 to your computer and use it in GitHub Desktop.
Download ZIP
All of the main & in-depth tips for creating beautiful documents in GitHub Markdown
Raw
Github-Markdown-beginner-to-advanced.md

GitHub Markdown : Beginner to Advanced formatting tips !

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 !

1. Markdown basics

2. Github Markdown basics

3. Github Markdown advanced


References


1. Markdown basics

Headers

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.

-> 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)

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)

Emphasis

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/


Lists

To nest a list you have to add 2 or 4 spaces before the item.

Unordered

  • Item 1
  • Item 2
    • Item 2a
    • Item 2b

Code :

* Item 1
* Item 2
    * Item 2a
    * Item 2b

Ordered & nested

  1. Item 1
  2. Item 2
    1. Item 2a
    2. Item 2b
  3. 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 !

Images

You can include tooltips as well.

Tesla Logo

If the url isn't valid it will display the alternative text : Alt 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)

Links

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)

Quotes

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 !

Code blocks

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?..");
```}

Escaping characters

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

2. Github markdown basics

HTML/XHTML Tags

Github markdown adds new possibilities !

You can underline or super script your text,

You have also additional ways to :

  1. make text bold
  2. or italic.
  3. make code blocks,
  • lists
  • and include pictures

    • 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>

    Checklists

    By the way, these are interactive !

    • Complete item
    • Incomplete item
      1. Nested items
      2. You can use formatting inside items !

    Code :

    - [x] Complete item
- [ ] Incomplete item
  1. [x] Nested items
  2. [ ] You __can__ use *formatting* inside items

    Tables

    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

    Emojis

    👍 ✨ 🚀 :octocat:

    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.


    Horizontal line

    To create a horizontal line like these :

    Use either :

    ---

***

_____

    Extra space

    To add extra space, use one or more:

    <br>

    3. Github markdown advanced

    Images resize & alignment


    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>

    Dropdowns

    To make a dropdown :

    Visible text This is a dropdown with text!
    • It can contain
    • a list!


    Or some 
    code !

    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>

    Buttons

    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/)|
|---|---|---|

    Anchor links

    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.

    User mentions

    Using @ followed by a username or a team name. It will notify that person/team to come and view the file.

    @Metawhy


    Issues, pull requests & commits reference

    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

    Colors examples

    You can generate dynamically the colors :

    • #f03c15 #f03c15
    • #c5f015 #c5f015
    • #1589F0 #1589F0

    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`

    Colored text

    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
```

    Footnotes

    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 }`

    Congratulations 🤗
    If you've made it here & learned all these concepts, you are now a master Github markdown 👌



    References

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment