Skip to content

Pages

General Issues, Pull requests and Discussions Wiki

General

This page lists all features that can be used across all places on GitHub, which support markdown formatting.

Table of Contents

Headers

Headers are larger text like shown above and also allow you to link to it, when used in Markdown files or the Wiki.

Example

# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header

----
Alternative Headers

Alt H1 Header
===

Alt H2 Header
---

H1 Header

H2 Header

H3 Header

H4 Header

H5 Header
H6 Header

Alternative Headers

Alt H1 Header

Alt H2 Header

Text formatting

GitHub offers normal Markdown formatting but also adds some own styling.

Italic

You can display a text in italic by surrounding it either with a single asterisks (*) or underscore (_).

Example

You can use *asterisks* to make text *italic*.

Alternatively can you also use _underscores_.

You can use asterisks to make text italic.

Alternatively can you also use underscores.

Bold

Using two Asterisks (*) or two underscores (_) before and after the text makes it bold.

Example

You can use **two asterisks** to make text **bold**.

Alternatively can you also use __two underscores__.

You can use two asterisks to make text bold.

Alternatively can you also use two underscores.

Strikethrough

This is a GitHub exclusive formatting code, where you use two tilde (~) before and after text to make it strikethrough.

Example

Don't like this text? Just ~~cross it out!~~

Don't like this text? Just cross it out!

Combinations

You can combine the above formatting options to have more special text.

Example

<!-- Note: You have to use underscores when already using asterisks -->
Here is some *italic text with __additional bold__*

Or how about ~~strikethrough with *italic?*~~

Here is some italic text with additional bold

Or how about strikethrough with italic?

Quotes

Starting a line with a > followed by a space makes it possible for you to quote a message.
The message will have a little bar on the left side and slightly different styling. All types of markdown formatting are supported including quotes in quotes!

Note that you need an empty line between a quote and any normal text below it to not include it in the quote.

Example

Albert Einstein once said:  
> Once you stop learning you start dying.

Albert Einstein once said:

Once you stop learning you start dying.

Special Quote blocks

MkDocs Extensions used

PyMdownx's Blocks.Admonition
(Custom CSS for styling)

GitHub implemented a feature where a Quote block starting with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] will be rendered as a callout block.
This callout block will have a border on the left like a quote, but also some smaller differences to it:

  • Border will be colored based on the type of callout
  • First line (The [!...]) will be colored the same as the border and prefixed with an icon.
  • Any displayed text in it will use the default text color used for rendered markdown files.

Important!

  • The first line needs to be > followed by [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION]
  • This feature is still in beta and may have bugs or not work across all GitHub.

Example

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Horizontal rule

Using three or more hyphens (-), astersisks (*) or underscores (_) will create a horizontal rule (line) which goes accross the entire text area.

Example

Use three or more hyphens, asterisks or underscores to make a line

---
But make sure there is no text directly above them or it will be converted to a H2 header!

Use three or more hyphens, asterisks or underscores to make a line

But make sure there is no text directly above them or it will be converted to a H2 header!

Line breaks

To indicate a line break, end a line with two spaces (indicated below using ◦), a backslash (\) or a <br> html tag.

Note

Issues and Pull requests don't require two spaces at the end for line breaks.

Example

We make line breaks, by ending a line with two spaces.◦◦
This line will show below the other.

For a new paragraph, leave an empty line in between.

We make line breaks, by ending a line with two spaces.
This line will show below the other.

For a new paragraph, leave an empty line in between.

Footnotes

MkDocs Extensions used

Python Markdown's Footnotes extension

The footnote syntax allows you to link text or URLs without destroying the text's look and formatting.
To use a footnote, simply use [^n] - where n is a number or text to use - in the place you want a footnote to be placed and use [^n]: <text> to make a link.

The [^n]: <text> part can be anywhere in your markdown file.

When generated will the footnotes always appear at the bottom of the page. They will also contain a link that goes back to the footnote's locations. Multiple [^n] can exist to link to the same repherence.

Example

Markdown[^1] is a lightweight markup language[^markup] used for creating formatted text.  
It also allows usage of HTML[^html] in it.

[^1]: https://daringfireball.net/projects/markdown/syntax
[^markup]: In computer text processing, a markup language is a system for annotating a document in a way that is visually distinguishable from the content.
  Source: https://en.wikipedia.org/wiki/Markup_language

<!-- This is a different syntax you can use for multi-line text -->
[^html]:
    Hypertext Markup Language.  
    Made by the World Wide Web Consortium (W3C).

Markdown1 is a lightweight markup language2 used for creating formatted text.
It also allows usage of HTML3 in it.

Lists

You can have various types of lists to order things.

Ordered

Starting a line with any number followed by a dot, space and text makes a new Ordered list.

Example

1. This is the first entry.
2. This is the second one.
4. The numbers don't even have to make sense!

----

1. To indent an entry...
   1. ...add 3 spaces before it.
  1. This is the first entry.
  2. This is the second one.
  3. The numbers don't even have to make sense!
  1. To indent an entry...
    1. ...add 4 spaces before it.

Unordered

The unordered list has the same behaviour as the ordered list, with the difference that it doesn't use a number and dot, but instead either an asterisk (*) or a hyphen/dash (-)

Example

- This list
- doesn't use numbers.

----

* Because it is
* unordered.

----

- Unordered lists...
    - ...also use 4 spaces for indents.
  • This list
  • doesn't use numbers.
  • Because it is
  • unordered.
  • Unordered lists...
    • ...also use 4 spaces for indents.

Task Lists

MkDocs Extensions used

PyMdownx's tasklist extension

Adding a [ ] after a hyphon or asterisks followed by text will create a task list item.
This task list item is "unchecked" (Shows an empty box) but can be "checked" by using [x] instead.

Another unique feature is that a task-list item containing an issue, Pull request or Discussion ID (#:id) will link to it and also display the status of said issue/PR/discussion.
Refer to the Issues, Pull requests and Discussions page for more info.

Example

- [x] Buy milk
- [x] Make laundry
- [ ] Take over the world
  • Buy milk
  • Make laundry
  • Take over the world

Unique behaviour of Task Lists

Task lists may show the issues icon () on the right-hand side if hovered over and when used in an issue or Pull request.
Clicking this icon will allow to open a new issue that links to this entry.

Note about mixed lists

You can mix the different list types, but keep in mind that you will need to use 3 or 4 spaces to indent a List of a different type.

MkDocs Extensions used

PyMdownx's magiclink extension

You can link to stuff in various ways

Normal

Linking to a page normally is simple. Either post the link directly, or use [text](link)

Example

You can link to sites by posting the URL: https://github.com

Or you link to it as an [embedded link](https://github.com).  
You can even give it [a title](https://github.com 'Go to GitHub!') to show on hover!

You can link to sites by posting the URL: https://github.com

Or you link to it as an embedded link.
You can even give it a title to show on hover!

Reference

Reference URLs are similar to normal ones, with the difference, that you only enclose the text in square brackets and it becomes a embedded link (when text matches).
You can use the same reference link at multiple places and use [text][reference link text] in case the text would be different than the reference link's text.

Names used in reference links are case-insensitive.

Example

[link]: https://google.com
[GitHub]: https://github.com

[Reference links][link] can be used like that to link to sites like [GitHub]!

Reference links can be used like that to link to sites like GitHub!

Image

Images can be added the same way as links (including reference link-style), but have an exclamation mark (!) before them.

Example

[github_logo]: https://docs.andre601.ch/GitHub-Markdown/assets/img/github.png

![name][github_logo]  
![github_text](https://docs.andre601.ch/GitHub-Markdown/assets/img/github-text.png)

name
github_text

Code

GitHub supports inline code and code blocks with syntax highlighting.

Inline code

To make inline code, surround the the text with a single backtick (`).

Tip

To display backticks within inline code, start and end it using 2 backticks.

Example

This is text with some `inline code`.

This is text with some inline code.

Code Block

Code blocks allow to display multi-line code and even have syntax highlighting.
To put text into a code block, surround it with three backticks (```).

Tip

To display three backticks inside a code block, start and end one with 4 backticks.

Example

This is some code block stuff
```
hello world!
```

This is some code block stuff 

hello world!

Syntax highlighting

GitHub provides syntax highlighting support which means that the content within a codeblock can be colorized, depending on what coding language was selected.

Note

GitHub supports displaying of Diagrams, Flowcharts, etc. through Mermaid.js.
To display such a graph, use mermaid as the syntax highlighting and provide a Mermaid-compatible format to turn into a graph.

Example

This here is some JSON with syntax highlighting:
```json
{
    "hello": "world!",
    "how": [
        "are",
        "you?"
    ]
}
```

This here is some JSON with syntax highlighting: 

{
    "hello": "world!",
    "how": [
        "are",
        "you?"
    ]
}

Tables

Making tables in Markdown is fairly simple.

Example

| Example      | One             |
|--------------|-----------------|
| You can make | it look pretty! |

Example | Two
---|---
Not so pretty... | Yet it still works.

----
Text alignment

| Title 1 | Title 2 | Title 3 | Title 4 |
|---------|:--------|:-------:|--------:|
| Default | Left    | Center  | Right   |
Example One
You can make it look pretty!
Example Two
Not so pretty... Yet it still works.

Text alignment

Title 1 Title 2 Title 3 Title 4
Default Left Center Right

Emojis

MkDocs Extensions used

PyMdownx's Emoji Extension

GitHub allows to render emojis.
A emoji is defined using a starting colon (:) followed by any alphanummerical text, hyphens (-) and underscores (_) amd ends with anothor colon.

All available Emojis can be found on ikatyang/emoji-cheat-sheet

Note that the emojis displayed may look different depending on the Operating System you use. This site uses Twemojis for consistent emoji display.

Example

Valid Emoji:
:smile:

Invalid Emoji:
:some emoji:

Valid Emoji:
😄

Invalid Emoji:
Some Emoji

Math expressions

MkDocs Extensions Used

PyMdownx's Arithmatex Extension

GitHub supports the LaTeX format to display complex math expressions using normal text.

To display a math expression, start and end the line(s) with dollar symbols ($).
One dollar symbol at the start and end is used to indicate an inline math expression, while two dollar symbols at the start and end indicate a block.

Alternative syntaxes

There are other syntaxes that can be used to indicate the start and end of a math expression, namely:

  • $`...`$ for inline.
  • Using math as syntax highlighting in code blocks.

Example

Inline math: $\sqrt{3x-1}+(1+x)^2$

Cauchy-Schwarz Inequality:

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Inline math: \(\sqrt{3x-1}+(1+x)^2\)

Cauchy-Schwarz Inequality:

\[\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)\]

  1. https://daringfireball.net/projects/markdown/syntax ↩

  2. In computer text processing, a markup language is a system for annotating a document in a way that is visually distinguishable from the content.
    Source: https://en.wikipedia.org/wiki/Markup_language ↩

  3. Hypertext Markup Language.
    Made by the World Wide Web Consortium (W3C). ↩