A collection of 20 things you can do with GitHub-flavoured markdown to spice-up your projects readme!
Include Notes and Warnings
> [!IMPORTANT]
> This is some important text.
> [!WARNING]
> This is a warning.
> [!NOTE]
> This is just a note.
Will render:
Note that this feature is still in beta.
Mermaid Diagrams
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.
Embedding Files
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.
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>
Underlined Text
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 <b></b> and <i></i> tags) - but you can also have underlined text, using the <ins></ins> tag.
<ins>I'm Underlined!</ins>
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
Want sections to be open by default? Just append the open attribute. For example:
<details open><summary><h2>I'm Open</h2></summary>
...
</details>
Indentation
Using <dl>, <dt> and <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").
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:→
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.
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"/>
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)
Sub-Directory Readmes
You can also place a README.* / 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 - reStructuredText
.rst- Primarily used in Python projects, can work with tools like Sphinx for complex docs sites - AsciiDoc
.adoc- Contains semantics and options for modular / reusable content - MarkDown
.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 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.
Single-Cell Tables
This is a great way to draw attention to an important message
| Hello World! |
|-|
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]**
Task Lists
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
References
Some text[^myreference] Clicking the here will scroll down to references.
[^myreference]: Here's a reference (include links or something)
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
https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html
Further Links
- GitHub Docs: Working with advanced formatting
