First things first : create an online repository at Github

Once you have created a Github account, go to https://github.com/yourUserName, click on the + button and select new repository. Give it the name myoutputs (or whatever you want) :

github new repository screenshot

Eventually add a description and choose an existing .gitignore file and license and click on create repository. You are now on your Github myoutputs repository page. Click on the green button Clone or download, then on the link use HTTPS (you can of course also use SSH if you know what it means) and copy the link provided in the text box :

github clone screenshot

Sync (i.e. clone) this repository to your computer and create the gh-pages branch for auto-publishing to Github pages

Let’s create a folder called dev under your home directory into which we will clone the online repository by pasting its addresse as a parameter of the git clone command in your terminal (more about the use of git with the command line) :

$ mdkir ~/dev
$ cd ~/dev
$ git clone https://github.com/yourUserName/myoutputs.git

Enter your Github username and password (if you have choosen HTTPS instead of SSH), press enter and your dev folder now contains a myoutputs folder which is a git repository (i.e. the root of the myoutputs folder contains a hidden .git folder that manages all its git features). Let’s check this :

$ ls -al

If everything went OK, you should see the myoutputs and the .git folder listed in your terminal. Now, let’s create a specific branch (more about branches here) for automatic hosting and publishing of your outputs! Github uses gh-pages as the default branch name to create an hosted webpage version of your repository source code. So let’s create it and use it !

$ git checkout -b gh-pages

Code your interactive leaflet map with R !

Your are now ready to build some git versioned code and make it ready to be published on the web through the magic of git and Github pages !

Download the source of the demo-map.R (which is intended to produce an HTML leaflet map) script and save it under your myoutputs. Open your terminal inside this folder and execute it :

$ Rscript demo-map.R

The script has produced a demo-map.html file containing the interactive map plus a demo-map_files folder containing all the required javascript libraries required to make it interactive. It has also saved 3 files resulting from the download of the raster elevation data. The resulting map looks like this :

If you get errors it might be because you don’t have the required libraries installed. To avoid such problems, simply install the missing libraries (and if you are adventurous enough, you can have a look at my R + Docker tutorial!)

Your interactive web map is now built ! You can locally open it by right-clicking on the demo-map.html file and choose to open it with your favorite web-browser. Check the various buttons to be sure that everything works as expected. What is important to know is that this impressive web app does not need any backend to run. Once the page is loaded, everything works inside your web-browser thanks to HTML, CSS and Javascript !

Ok, but how is it then possible for me navigate and zoom in every part of the world without having to run a server to get the base layer tiles ?

That’s probably what you will tell ! The trick is that leaflet render tiles stored on a third party tiles provider (i.e. a web-server). It is actually a simple line of Javascript that does the magic of calling the tiles and serving these to your web-browser. If you turn your wifi off, you will see that you won’t be able anymore to see the base layer while navigating the world.

Publish it online using gh-pages !

Head back to your terminal (opened in your myoutputs folder) and save and publish your work to Github.

$ git add .
$ git commit -m "adding interactive demo-map.html"
$ git push --set-upstream origin gh-pages

Now the source code of your interactive map (both the demo-map.R and the demo-map.html ) has been pushed to https://github.com/yourUserName/myoutputs and your hosted interactive map is rendered at https://yourUserName.github.io/myoutputs/demo-map.html !

Great ! Simply share this link to your audience and you are done ! Your interactive webmap is available to them !

Sometimes github pages struggles to rebuild your rendered page when you commit your changes. If this happens, you can force github pages to rebuild it using these two git instructions (solution found on stackoverflow) :

$ git commit -m 'rebuild pages' --allow-empty
$ git push origin gh-pages

bash script to build the directory listing index.html file

Download and save this bash script under your myoutputs folder. Make it executable :

$ chmod a+x index-html.sh

This script is intendend to automatically generate an index.html files that lists all the files available in a specific folder. Let’s run it :

$ ls | ./index-html.sh > index.html

You now have a nice index.html files that lists all your files stored in your myoutputs folder.

pushing the index.html file to github

Each time, you run this bash script to update you index.html file, you of course have to push it to Github so that when your visitors head at https://yourUserName.github.io/myoutputs they get an updated list of all your files available. For this purpose we do as previsously mentioned : add, commit and push :

$ git add .
$ git commit -m "adding index.html and updating it with bash script"
$ git push origin gh-pages