Technically, images can be stored in various 3rd-party online services and referenced from within our wiki. However, this introduces a dependency on such services and has a risk that our information in the wiki becomes incomplete or incorrect if the external service shuts down or changes their policy.

A much better approach is to maintain control over our images by hosting them ourself. GitHub has such functionality built in, although it requires some more advanced steps to make use of it. This tutorial explains how we can upload and store images into the wiki's underlying git repository, and embed them within our wiki pages.

There are several requirements before starting the tutorial:

• A basic understanding of git repositories and the associated workflow. There are many good tutorials on this online (e.g. tutorial 1, tutorial 2, tutorial 3, tutorial 4, tutorial 5)
• An installed git client on your computer. For this tutorial we use only terminal commands, but there are are also many graphical clients that offer similar functionality.

In a nutshell, git repositories that are hosted on GitHub should be cloned on your local PC to make make changes. Your local changes can then be committed to the local clone of the repository, after which they can be pushed back to the central online repository for others to see.

Underneath the nice webbased frontend, the wiki text & images are also just files stored in such a regular git repository. As a result, they can also be cloned, edited, merged, branched, pulled and pushed in the same way as regular repos. (Unfortunately pull requests don't seem to be implemented for wikis)

Assuming you have a git commandline client installed and setup, open a terminal of your choice and go to an empty directory. Then clone the wiki repository to your PC: git clone https://github.com/utwente-interaction-lab/interaction-lab.wiki.git then browse to the new directory interaction-lab.wiki. You should see a full copy of all the pages on the wiki along with a folder images and folder files:

In the images folder you can create a new subfolder to store the images for your wiki page. Please give it a short descriptive name. There you can place images related to your wiki page, again making sure to give them a short descriptive name.

Now you can start writing / editing your markdown page content, and add images where required. There are various ways to embed an image in the wiki page:

Markdown syntax

Wiki pages use Markdown syntax for embedding images. Here is an easy shorthand way to embed an image that gets scaled to the default page width:

[[images/git-wiki-tutorial/image-example.png]]

HTML '<img>' tag

Wiki pages also support some basic HTML tags that can be used for embedding images. For example using the '<img>' tag you can position and scale the image as required:

<img width="400px" align="right" src="/utwente-interaction-lab/interaction-lab/wiki/images/git-wiki-tutorial/image-example.png">

Your local clone of the git repository is not automatically synchronised with the remote repo hosted on the GitHub servers. Before you add and commit your images and changes it is good practice to first pull any changes from the remote that may have happened in the meantime: git pull

If there are errors at this point you should try to fix them. In some cases you can simply stash your changes, do the pull, and then re-apply the stashed changes on top of it.

1. git stash save - this stashes all your uncommitted local changes so that the working directory is clean
2. git pull - pull the latest changes from the online central repository and apply them to your local clone
3. git stash pop - re-apply you changes on top of the most recent version

Once you have added your image files and have embedded them in the wiki page you need to add the files to your local clone of the git repository. First, check the status of your repo, to ensure it lists only changes that you actually intend to add: git status

Then you add the files that you modified or created to your staging area, for example: git add Using-images-in-GitHub-wiki.md and git add images/git-wiki-tutorial/

Then the new and modified files should show up in green with git status.

Then you can commit the staged changes so they are tracked in your local repository: git commit -m "write a short descriptive commit message to explain what was changed"

Finally, once you have added and committed your changes, have pulled the remore changes, and fixed all potential merge conflicts, you can push your local changes to the online repository: git push

You should now see the modifications in the regular github wiki web interface.