GitHub Markdown pages support the use of images, but do not support the use of video files (of any description) or audio files (of any description).

GitHub supports the following image file formats:

Do not use bmp or gif formatted images (bmp files are superseded by png and webp types, gifs are too limited).

SVGs tend to be for drawn or computer generated images (rather than photographs &c.).

The general rule for which image formats to use is:

GitHub Markdown can be used to directly display images, but as with tables, HTML images have more flexibility (can be resized &c.) and you can do more with them.

GitHub Markdown also supports some built in mechanisms for creating diagrams and models:

All of these are covered in the following sections.

⬆️ Top

It is fairly easy to insert an image directly into a Markdown page, it’s a bit like a link.

The Markdown to insert an image is:

The ${\large \color{#ED7D31}\text{ImageTitle}}$ is optional, it is displayed if the mouse hovers over the image (like a tooltip in links).

The ${\large \color{#C00000}\text{Alternative\ Text}}$ is only displayed if the image file cannot be found (it is also used by specialist screen readers, it’s bad form not to include it).

The following is the Markdown to display the image of Henry (first seen in section 9.6.2):

![Henry the dog](./11-0000/02-images/figm-99-01.png "Henry")

If for whatever reason, the image file cannot be found (missing file, incorrect path &c.), GitHub will display the alternative text as follows:

Figure 11.1 — Markdown image broken link

It shows a broken image icon followed by the alternative text.

⬆️ Top

Image sizes when displayed using direct Markdown, are either always the full width of the screen area (i.e. full width of the main body text area, or if displayed in a footer or sidebar, the full width of those areas), or, the natural width of the image, whichever is smaller. The following shows an image as it would appear in the sidebar:

Figure 11.2 — Image in a sidebar

It is only possible to change the image width by using HTML.

⬆️ Top

It is possible in Markdown to make an image a clickable link (i.e. if you click the link it takes you to another page or website).

To make the image a link, surround it with brackets and then in parenthesis add the URL for the link (and any tooltip title):

To make the Henry picture a link to the PracticalSeries home page it would become:

[![Henry the dog](./11-0000/02-images/figm-99-01.png "Henry")](https://practicalseries.com "PracticalSeries")

If two tooltips are used, one for the image (${\large \color{#ED7D31}\text{ImageTitle}}$) and one for the link (${\large \color{#ED7D31}\text{LinkToolTip}}$), the image takes priority.

⬆️ Top

When constructing a page using the GitHub editor (via a browser), it is possible to drag and drop an image from your computer directly into the edit window.

In GitHub select the page you want to put the image in and select ${\large \color{#00B050}\langle\text{edit}\rangle}$, top-right.

Now using Windows file explorer navigate to the image you wish to put on the Wiki page and drag it from explorer into the edit window where you want it to appear:

Figure 11.3 — Drag and drop an image into a Wiki page

When you release the mouse, the link will be automatically created, it’s a bit odd:

Figure 11.3 — Drag and drop image created by GitHub

GitHub has done something funny with the image, look at the Markdown:

![fig 99-01](https://github.com/user-attachments/assets/32917acd-01c0-4e79-a81d-8a392a696407)

The ${\LARGE \color{#C00000}\text{Alternative\ Text}}$ is just the file name (without extension) of the file dragged into the edit window.

The link:

   https://github.com/user-attachments/assets/32917acd-01c0-4e79-a81d-8a392a696407

is something that GitHub has generated, it has taken the image that was dragged into the edit window and stored it on its own server at the address:

   https://github.com/user-attachments/assets/

Next, it’s given the image its own unique identifier:

   32917acd-01c0-4e79-a81d-8a392a696407

If you paste the link above into a browser, you will get the picture of Henry:

Figure 11.5 — The uploaded image

The unique identifier is, I think, some form of SHA key, just like a commit.

This is all fine, but it is also peculiar; GitHub has uploaded the image that was dropped into the file, but instead of storing it in the Wiki repository (or even the main repository), it has stored it in a directory that has nothing to do with the Wiki, the repository or even the user.

GitHub has stored the image in a directory of its own that neither you, nor I, nor anyone else has control over (except presumably GitHub).

It also means that anyone who uploads an image to GitHub has their image stored in the same directory, but with a different identifier. They’re all in the same place.

I don’t particularly have a problem with this, except: how do you ever delete the image if you don’t want it anymore?

If I delete the image link from the Wiki page and resave the page, the link above still works, the image is still in that https://github.com/user-attachments/assets/ directory.

${\large \color{#B00000}\text{It’s\ odd.}}$

⬆️ Top

I said above that I don’t have a problem with this arrangement, but the more I think about it, the more I do have a problem, several in fact:

I’ve done a bit of digging and I can sort of answer some of these questions:

Point ❶: The only way to delete the image is to delete the repository, GitHub will then remove the “assets” associated with the repository (including the Wiki files) as part of its cleanup process. It will however, take quite some time to do this (it is not instantaneous, think weeks rather than hours).

Point ❷: Anyone who knows the link has access to the file.

Point ❸: Technically, the image is available under the licence terms of the repository (I suppose), however, if all you have is the link, there is no way to identify the parent repository and see what the licence terms are. So the long and short of it is: I don’t know.

Point ❹: The link only expires if the associated repository is deleted (or possibly if some sort of abuse is reported).

Talking of abuse, it strikes me that this whole drag and drop thing can be abused. GitHub imposes size limits on a repository (5 GB and preferably less than 1 GB) and on individual files (50 MB). It does not, however, impose size limits on files that can be dragged and dropped in this fashion.

Similarly, GitHub does not particularly care what type of files are dragged and dropped. If you drag and drop a Word file, it just uploads the file, creates a link to it and stores it in the https://github.com/user-attachments/ area.

⬆️ Top

Like tables, HTML offers a lot more formatting options when used for images.

It is fair to say that HTML is the mechanism of choice when displaying images within Markdown pages.

Within HTML, images are defined with the <img> element (this tag has no closing </img>). It is in this form:

The ${\LARGE \color{#0050C0}\text{title="}\color{#ED7D31}\text{ImageTitle}\color{#0050C0}\text{"}}$ is optional, it is displayed if the mouse hovers over the image (like a tooltip in links).

As before, the ${\LARGE \color{#C00000}\text{Alternative\ Text}}$ is only displayed if the image file cannot be found. The following is the HTML to display the image of Henry (lots more pictures of Henry):

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Table 11.4 — HTML for a basic image

If for whatever reason, the image file cannot be found (missing file, incorrect path &c.), GitHub will display the alternative text as follows:

Figure 11.6 — HTML Broken link

It shows a broken image icon followed by the alternative text (just like Markdown).

⬆️ Top

HTML allows images to be resized (in pixels) using the ${\large \color{#00B050}\text{width}}$ or ${\large \color{#00B050}\text{height}}$ attributes (similar to cells in a table, see section 10.2.4 and section 10.2.5).

The following reduces the Henry image to 300 px wide:

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img width="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Table 11.5 — Resized width image

The height attribute is used in the same way, the following sets the image height to 300 px:

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Table 11.6 — Resized height image

If both the width and height attributes are used, the image can be distorted (this sets the width to 300 pixels and height to 200 pixels):

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img width="300" height="200" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Table 11.7 — Resized width and height image

Poor old Henry.

In all cases the image is left-aligned on the screen.

⬆️ Top

Like tables, HTML images can be left or right aligned on a page by using the ${\large \color{#00B050}\text{align}}$ attribute (note there is no centre alignment).

Left alignment first:

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img align="left" width="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry"> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis.</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis.
Table 11.8 — left aligned image

Now right alignment

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img align="right" width="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry"> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis.</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis.
Table 11.8 — right aligned image

This leads to the text wrapping problem we came across with tables (see section 10.2.3). With images we have an additional option to solve the problem.

The first solution is to use the ${\LARGE \color{#C00000}\text{<br\ clear="all">}}$ tag after the image (this is just like the solution for tables see here):

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img align="right" width="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry"> <br clear="all"> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis.</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis.
Table 11.10 — Right aligned image without text wrap

HTML also offers another solution, instead of using the align attribute within the image tag, surround the image tag with a <p> paragraph tag and use the align attribute within the paragraph tag instead:

<p align="right"> <img width="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry">
<br clear="all"></p>

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor 
a tortor ornare, non pretium diam faucibus. Morbi ut mollis.</p>

The difference here is that using the paragraph arrangement, there is proper line spacing between the image and the following paragraph.

The paragraph arrangement allows the image to be centred (which is not possible when using the align attribute directly with the <img> tag):

<p align="center"> <img width="300" src="./11-0000/02-images/figm-99-01.png" alt="Henry the dog" title="Henry">
<br clear="all"></p>

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor 
a tortor ornare, non pretium diam faucibus. Morbi ut mollis.</p>

There is a third option for controlling image alignment and that is to use a table, this is discussed in section 11.2.5 and section 16.5.4.

⬆️ Top

As with Markdown, it is possible to make an image a clickable link (i.e. if you click the link it takes you to another page or website) in HTML too.

To make the image a link, use the anchor <a> tag around the image:

<a href="LinkURL" title="ImageTitle"><img src="PathToImage" alt="Alternative Text" title="ImageTitle"></a>

To make the Henry picture a link to the PracticalSeries home page it would become:

<a href="https://practicalseries.com" title="PracticalSeries"><img src="./11-0000/02-images/figm-99-01.png" alt="Henry"></a>

If both the image and the link have a ${\large \color{#00B050}\text{title}}$ attribute, the image title will take preference.

The ${\large \color{#00B050}\text{width}}$ and ${\large \color{#00B050}\text{align}}$ attributes can still be used with the <img> tag in this format.

⬆️ Top

This I think give a much more professional look to an image; this is also the PracticalSeries mechanism for displaying an image.

It looks like this:

Figure 11.7 — Table used to hold an image and caption

The use of a table to surround the image gives the image a grey border (1 px wide) and allows for a figure number and caption to be given below the image (in the next row of the table), this caption is shaded (the shading of the caption is accidental, the second row of a table is always shaded).

The HTML behind this is:

1
2
3
4
5
6

<table name="f-11-07" align="center"><!-- Leave blank line above --- IMAGE TABLE START -->
  <tr><td>
<img width="400" src="./11-0000/02-images/figm-99-01.png" alt="Henry">
  </td></tr>
  <tr><th align="center"><sup>Figure 11.7 &mdash; Henry the dog</sup></th></tr><!-- CAPTION -->
</table>                             <!-- Leave blank line below --- IMAGE TABLE END-->

This is a table with two rows, each with a single cell.

The table is defined in line 1 to be ${\large \color{#00B050}\text{align="center"}}$, i.e. it appears in the centre of the main body text area. The table is also given a name (${\large \color{#00B050}\text{name="f-11-07"}}$), in this case the name is ${\large \color{#00B050}\text{f-11-07}}$ indicating figure 11.7 (this is the convention used in the PracticalSeries Wikis, you can use any name you like as long as it is unique within the Wiki page).

Line 2 defines the first row and its data cell.

Line 3 is the image, this is exactly as described previously, there is no alignment, it will fill the cell to which it is assigned (the alignment is handled at the table level in line 1).

Line 4 is the end of the first cell and its row.

Line 5 defines the second row and its data cell, in this case the text within the cell is centre aligned (${\large \color{#00B050}\text{align="center"}}$). The caption text (Figure 11.7 — Henry) is the text that will appear in the row below the image, the — is an em dash (—) that separates the figure number from the figure description.

The <sup>…</sup> puts the caption text as a superscript (see section 6.9), it raises the text and makes it smaller, this is just to make the text look more like a caption than body text.

Line 6 is simply the closing table tag to finish the whole thing off.

There is one final point, with the image in a table, it is possible to put a dark border around the whole table by using the border attribute discussed in section 10.2.9. To do this, change the first line to:

HTML and GitHub output
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<table name="f-11-07" align="center" border="1"><!-- Leave blank line above --- IMAGE TABLE START --> <tr><td> <img width="400" src="./11-0000/02-images/figm-99-01.png" alt="Henry"> </td></tr> <tr><th align="center"><sup>Figure 11.7 &mdash; Henry the dog</sup></th></tr><!-- CAPTION --> </table> <!-- Leave blank line below --- IMAGE TABLE END-->
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Figure 11.7 — Henry the dog
Table 11.16 — Image in a table with border

⬆️ Top

This is another oddball thing that crops up from time-to-time. It isn’t so much a GitHub thing as a browser thing.

When a link to an image is created on a Markdown page (either using Markdown or HTML) and that page is then viewed in a browser, the browser buffers all the images on the page and stores them in a cache on the local machine. It does this so that if the page is viewed again, it doesn’t have to reload the images and the page displays more quickly.

After a while, the browser will discard these images and reload them^💠1. This isn’t generally a problem, images on websites don’t change that frequently. It can however be a problem for us with a Wiki, particularly when it is the image that is being edited. If we change an image, we don’t really want to wait several minutes for the browser to refresh the image before we can see the changes.

If an image is changed in a GitHub Wiki, but its filename remains the same, the browser can’t tell the image in its cache is different to the image on the website (it doesn’t check anything other than the filename) and the cached image will be used by default (until such time as the browser refreshes the image).

It is possible to force a browser to do a hard refresh of a page (Edge uses ${\large \color{#00B050}\text{ctrl+F5}}$ to force a hard refresh), this reloads all the content of a page and ignores any cached images.

It is possible to add a “query” to an image link, this is a question mark followed by some text in the form:

${\LARGE \color{#1F883D}\text{AnyText1}}$ and ${\LARGE \color{#ED7D31}\text{AnyText2}}$ can be anything at all, they have no meaning. A query is simply a string of characters following a question mark that are supplied to the browser and forwarded to the host website (it’s how Google does searches), if the host website isn’t expecting a query, it is simply ignored

In the context of the previous example it might look like this:

![Henry the dog](./11-0000/02-images/figm-99-01.png?b=01)

img src="./11-0000/02-images/figm-99-01.png?b=01">

By adding the ?b=01 we have created a query that does absolutely nothing, the image will appear just as it did and no additional text will be displayed. The browser will cache the image and everything will be as it was before.

If the image is modified and its name left the same, the browser will still display the old cached image in place of the change image (it knows no different).

If, however, we now change the query (let’s say to ?b=02), the browser now sees a different link (the query is part of the link as far as the browser is concerned) and it reloads the image into its cache.

Changing the query reloads the image.

For PracticalSeries images, I use the query ?bxno=HHMM where bxno simply means build number and HHMM is the time (hours and minutes) when I pushed the change to GitHub (this is usually enough to force a refresh).

⬆️ Top

It is possible to use an image to force a space of a given number of pixels.

The following is a 1 px by 1 px transparent png file (it contains nothing, but a transparent image that is 1 pixel wide by one pixel tall), you can download it here:

   https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/00-0000/02-images/wi-spacer.png

It is called:

   wi-spacer.png

By inserting this image and setting its ${\large \color{#00B050}\text{width}}$ to a specific value, a space can be created between Markdown elements:

Start<img width="300" height="1" src="00-0000/02-images/wi-spacer.png" alt="spacer">End

There is exactly 300 px between the last "t" of the word "start" and the "e" of the word "end".

When setting the ${\large \color{#00B050}\text{width}}$ to the required value, it is important the ${\large \color{#00B050}\text{height}}$ is always set to 1. If no height is specified, increasing the width will also increase the height in the same proportion (in this case, the height would become 300 px too) and this will lead to large gaps above the spaced text.

⬆️ Top