July 1, 2022•916 words
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
Note that this feature is still in beta.
<sub></sub> (Subscript) and
<sup></sup> (superscript) will generate tiny text. But to keep it vertically-centred, you can combine the two with:
Insert Keyboard Keys
Great for visually showing which keys to press, or drawing attention to something (see example)
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").
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:
- Neck Beard
- Troll Face
- Ship It
And a few more...
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!)
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
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.
In GitHub-flavoured markdown, the
<kbd> tags also make great buttons. for your readme header.
--- **[<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]** ---
Both superscript (top of line, like this) and subscript (bottom of line, and this) are supported.
Just use the
You can wrap these elements with non-HTML markers (like bullet lists, tables or titles) too. (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
rowspan attribute, with the number of cells horizontally or vertically that it should span.
<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.
- GitHub Docs: Working with advanced formatting