A collection of 20 things you can do with GitHub-flavoured markdown to spice-up your projects readme!
Include Notes and Warnings
> **Note** > This is a note > **Warning** > This is a warning
Note that this feature is still in beta.
You can add live diagrams to your documentation, using Mermaid Syntax. Check the docs for syntax, then use the Live Editor to build out your diagrams, then embed the code into your readme, where they'll be rendered.
Just add the
mermaid identifier to the start of your code block. For some examples, see the mermaid repo.
You can embed any code, markdown or media file into GitHub markdown, by copying it's permalink, and pasting it into your document. Note that the content must be located in the same repository.
<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)
You probably already know that you can make bold text with
**Bold!**, and italic text with
_Italic!_ (both of which can also be done with the
<i></i> tags) - but you can also have underlined text, using the
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
Want sections to be open by default? Just append the
open attribute. For example:
<details open><summary><h2>I'm Open</h2></summary> ... </details>
<dd> you can create indented paragraphs, with a nicer aphetic. The indented text can wrap multiple lines, while maintaining indentation.
<dl> <dt>This is a list</dt> <dd>With hanging indentation</dd> </dl>
Embedding a Video
You can embed an MP4, simply by including the URL to the raw video in your markdown file (see example)
This doesn't (yet) work with YouTube videos (unless you download and re-upload them). But here's a trick to embed a frame, which will take the user to the video on-click:
<a href="http://www.youtube.com/watch?feature=player_embedded&v=YOUTUBE_VIDEO_ID_HERE" target="_blank"> <img src="http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg" alt="IMAGE ALT TEXT HERE" width="240" height="180" border="10" /> </a>
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>
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...
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
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.
<img src="https://i.ibb.co/sCwYpZ8/general.gif" alt="Video Preview Gif" align="right" width="500px"/>
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)
You can also place a
readme.* (see supported extensions below) into any directory of your GitHub repo, and it will be rendered when the user views that folder.
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)
Using other Formats
Markdown isn't the only supported format for rendering readmes and docs on GitHub.
- Org Mode
.org- Useful for notes, lists, timelines and planning documents
.rst- Primarily used in Python projects, can work with tools like Sphinx for complex docs sites
.adoc- Contains semantics and options for modular / reusable content
.md- The classic
- Plain text
.txt- Just monospace plaintext
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.
This is a great way to draw attention to an important message
| Hello World! | |-|
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]**
You can create tasks lists too, useful for adding into Pull Request templates or showing task progress in readme.
A list of things: - [X] Googley Eyes - [X] Tesco Clubcard - [ ] The Elizibeth Line - [ ] Beans on Toast - [ ] My Current Account
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
- GitHub Docs: Working with advanced formatting