GitHub Markdown Tricks π
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
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
Hello World! |
---|
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