GitHub Markdown Tricks 🐙

A collection of 15 things you can do with GitHub-flavoured markdown to spice-up your projects readme.

Centre an image or other content

Make the title, sub-title and / or logo image centred (see example)

<p align="center">
  <img width="500" src="---" alt="---">
</p>

Include Notes and Warnings

> **Note**
> This is a note

> **Warning**
> This is a warning

Will render:

Note that this feature is still in beta.

Tiny Text

Using the <sub></sub> (Subscript) and <sup></sup> (superscript) will generate tiny text. But to keep it vertically-centred, you can combine the two with: <sub><sup>Small Text!</sup></sub>


Insert Keyboard Keys

Great for visually showing which keys to press, or drawing attention to something (see example)

<kbd>Key</kbd>

Collapsible Sections

Useful for including long blocks of text (like logs or API response), without clogging up your page (see example)

<details>
    <summary>Collapsable Title</summary>
    <p>Put Content Here</p>
</details>

Note that to include markdown within the <p></p> content block, you must pad it with blank lines, both top and bottom

Embedding a Video

You can embed an MP4, simply by including the URL to the raw video in your markdown file (see example)

Adding Title to Links

You can add a title to a link, which will be displayed when the user hovers over it. This is done by surrounding it in quotes immediately after the URL

[DuckDuckGo](https://duckduckgo.com "A great search engine for privacy").

GitHub-Specific Emojies

In GitHub flavoured markdown, emojis can be specified by their shortcode (e.g. :nerd_face:), here's a cheatsheet

But there are also some GitHub-specific emojis, including:

• Octocat :octocat: →
• Bowtie :bowtie: →
• Neck Beard :neckbeard: →
• Troll Face :trollface: →
• Ship It :shipit: →
• Suspect :suspect: →

And a few more...

• :rage1: → :rage2: → :rage3: → :rage4: →
• :hurtrealbad: → :goberserk: → :finnadie: → :feelsgood: →
• :atom: → :basecamp: → :basecampy: → :electron: →

Moving Readme

If it bothers you having your README.md file cluttering up your projects root directory, then you can place it in .github/README.md (along with any other GH stuff or assets). It will still be rendered as normal in your repositories home, but now you've got one less file in your project's base directory. (see example)

Including the code quote symbol (`) in a code block

Sometimes you may need to use the ` symbol within a code block.

Just wrap the code with double quotes ``, and ensure there is a space around the quote symbol

(here, I'm including quotes inside quotes inside quotes!)

https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html

Single-Cell Tables

This is a great way to draw attention to an important message

Creating Home Page .md

You can display a short markdown document at the top of your GitHub profile. To do so, just create a public repository with the same name as your GitHub username, and populate it with a non-empty README.md. For more info, see the Profile Readme Docs, or (see example)

Syntax Highlighting in Code Blocks

Code blocks become much easier to read with syntax highlighting. To use this, you must specify the language immediatley after the first ```.

For example:


typescript`
const name = 'Alicia';
`


You can view a full list of supported languages, here

Showing Code Additions (or Deletions)

Set the language type to diff, and then precede each line which indicates an addition with +, or a - if it's a deletion. Note that the sign must be the first character of the line (watch out for white space), and should be followed by at least one blank space/ tab.

Create Buttons

In GitHub-flavoured markdown, the <kbd> tags also make great buttons. for your readme header.

For example:

---

**[<kbd> <br> Install <br> </kbd>][Install]** 
**[<kbd> <br> Quick Start <br> </kbd>][Quick Start]** 
**[<kbd> <br> Configure <br> </kbd>][Configure]** 
**[<kbd> <br> Contribute <br> </kbd>][Contribute]**

---

Small Text

Both superscript (top of line, ^{like this}) and subscript (bottom of line, _{and this}) are supported.
Just use the <sup></sup> or <sub></sub> tags.

You can wrap these elements with non-HTML markers (like bullet lists, tables or titles) too. (see example)

Side-Aligned Images

In a similar way to centering images, you can also right align them, where the text will flow down the left-side. An example of this can be seen in the tuxi repo. (See example)

<img src="https://i.ibb.co/sCwYpZ8/general.gif" alt="Video Preview Gif" align="right" width="500px"/>

Merging Cells in Tables

It is possible to merge cells in tables (so that a given cell spans multiple rows or columns), but only if you define your table in HTML (see example).

This is done by adding the colspan or rowspan attribute, with the number of cells horizontally or vertically that it should span.

For example:

 <td colspan="2">I take up two columns!</td>

You can also set the text align property here too, using align="center" to centre text.

Further Links

• GitHub Docs: Working with advanced formatting