GitHub, being a software development platform, needs some mechanism for allowing code to be displayed. Since code languages often include formatting characters within the various syntax arrangements, it is necessary that GitHub displays any code fragments exactly as they are entered without interpreting the various dashes, dots and backslashes as text formatting commands.

I.e. it displays code fragments in the literal sense: exactly as they are entered.

GitHub supports such code fragments, these can be displayed at a basic level (simply as code fragments without any coloration), they can also be displayed with syntax highlighting^💠1 (for known languages).

It also allows framed or fenced code highlights (these are large blocks of code that can cover several lines), again these can contain syntax highlighting.

⬆️ Top

Inline code fragments can be inserted by surrounding the code with a single backtick character (`). On a UK keyboard, the backtick is usually the key to the right of the number 1 key (immediately below the esc key).

The Markdown and HTML is as follows:

The print command is `printf` in C.

The print command is <code>printf</code> in C

The code is displayed in a monospaced font (in this case Consolas) in a grey rounded rectangle rgb: (240,241,242) #F0F1F2. The font colour is the same as body text: rgb: (31,35,40) #1F2328.

With the HTML, the <code> tag carries out the same function as the backtick character in Markdown.

The <code> tag is always used for HTML inline code fragments (it does not need the <pre> tag discussed in the following section).

⬆️ Top

There are several ways to display code blocks in Markdown, some are more precise than others.

The simplest mechanism to display a block of code is to indent each line be at least four spaces (depending on the text editor, this is sometimes done with the tab key):

    #include <stdio.h>

    int main() {
        printf("Hello World");
        return 0;
    }

<pre><code>#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}
</code></pre>

#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}

The code is again displayed in a monospaced font (in this case Consolas) in a grey rounded rectangle (see the previous section for colour details).

The clipboard icon (highlighted) allows the code to be copied verbatim for pasting into some other editor.

With the HTML, the <pre><code> at the start informs the browser that what follows is to be rendered in a monospaced font and that spaces must be displayed (the <pre> tag does this) and that the content is a fragment of computer code (the <code> tag).

Technically, the <code> tag is for information only, the <pre> tag does everything we need; but syntactically <pre><code> is the correct format.

The <pre><code> is on the same line as the first line of the code, this stops additional line-breaks being inserted before the code fragment.

⬆️ Top

Although indenting code by four spaces forces GitHub to interpret the text as code, it is not the preferred mechanism for doing so. Using tabs and spaces can be a bit hit and miss.

The preferred mechanism for Markdown code fragments is to surround the block with three backtick characters (```). This is unambiguous and clearly marks the text as a code fragment. This is the preferred format for the previous example:

```
#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}
```

#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}

With this mechanism leading spaces are not required.

Each set of backticks must be on its own blank line.

To escape the triple backticks discussed in the previous section, wrap then in quadruple backticks:

````
```
#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}
```
````

```
#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}
```

How to escape four backticks? You guessed it, use five — now it just gets silly.

⬆️ Top

Syntax highlighting is used to colour certain aspects of the programming language to make the text more readable and easier to understand.

Syntax highlighting is only possible with GitHub Markdown (there is no HTML equivalent that works with GitHub).

The above code fragment looks like this with GitHub syntax highlighting (it is written in the C programming language):

```c
#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}
```

#include <stdio.h>

int main() {
    printf("Hello World");
    return 0;
}

To activate syntax highlighting, simply follow the first three backticks with the lowercase code for the language being used, the c in this case:

If the code were JavaScript, the three backticks would be followed by java for example (```java).

There is no space between the backticks and the language code.

⬆️ Top

GitHub supports syntax highlighting for many programming languages, the following lists them all and the language code that must follow the three backticks:

Yeah, I’ve no idea what most of them are either. Especially Brainfuck.

⬆️ Top

Things can get a bit confusing when using HTML to display an HTML code fragment.

Let’s say for example that you wanted to use HTML to display the following as a code fragment:

<table align="center">
<tr><td align="center"><img src="./01-0000/02-images/figm-01-01.png"></td></tr>
</table>

You would think we would simply wrap it in the <pre><code> tags as follows:

<pre><code><table align="center">
<tr><td align="center"><img src="./01-0000/02-images/figm-01-01.png"></td></tr>
</table></code></pre>

What this give however is this:

It has got the grey background of a code fragment, but the HTML starting with <table> has simply rendered as HTML, we don’t see the code, but the code has been executed and displays the image.

The solution to this problem is that we must replace all the greater than and less than symbols with their HTML escape codes (these were first discussed in section 7.1.2), the table of which is reproduced below:

To make the HTML code fragment work, it must be re-written as:

<pre><code>&lt;table align="center"&gt;
&lt;tr&gt;&lt;td align="center"&gt;&lt;img src="./01-0000/02-images/figm-01-01.png"&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;</code></pre>

<table align="center">
<tr><td align="center"><img src="./01-0000/02-images/figm-01-01.png"></td></tr>
</table>

⬆️ Top

Converting all the reserved characters in a HTML code fragment into escape codes, is, to put it bluntly, a pain in the arse.

It’s something I’ve had to do a lot when producing the PracticalSeries website. In the end I used a Word document with embedded macros to do the conversion, it is available here for you to use:

   ps-html-converter.docm

To use this document: download the document, open it and enable the macros^💠2 (Word will try to stop you, especially since you downloaded it from the internet).

Copy the HTML you want to convert onto a blank page in the document (the one starting paste your stuff here will do), in this example I’m copying the HTML table example from the previous section, it looks like this in the document

Figure 13.1 — HTML code copied into the conversion document

Now select the code to be converted:

Figure 13.2 — Select the code fragment

Now press ctrl+alt+R to run the macro to convert the code. It does this:

Figure 13.3 — Converted the code fragment

Cut and paste the converted code into the HTML code fragment:

<pre><code>&lt;table align=&quot;center&quot;&gt;
&lt;tr&gt;&lt;td align=&quot;center&quot;&gt;&lt;img src=&quot;https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01-0000/02-images/fig-01-01.png&quot;&gt;&lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;</code></pre>

<table align="center">
<tr><td align="center"><img src="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/01-0000/02-images/fig-01-01.png"></td></tr>
</table>

Hope this helps.

⬆️ Top