Loading a thumbnail into Gist for bl.ocks.org d3 graphs

The following post is a portion of the D3 Tips and Tricks document which it free to download. To use this post in context, consider it with the others in the blog or just download the pdf  and / or the examples from the downloads page:-)

--------------------------------------------------------

This description will start on the assumption that the user already has a GitHub / Gist account set up and running. It's purpose is to demonstrate how to upload an image as a file named thumbnail.png to a Gist so that when viewing the users home page on bl.ocks.org you see a nice little preview of what a visitor can anticipate when they go toy look at your work :-)

This description is a fleshed out version of the one provided by Christophe Viau on Google Groups (https://groups.google.com/forum/?fromgroups=#!topic/d3-js/FBosXiTB9Pc).

Setting the scene:

There you are a fresh faced d3.js user keen to share your work with the world. You set yourself up a GitHub / Gist account and put your code into a gist.  

Your graph is a thing of rare beauty and the community needs to marvel at your brilliance. Of course this is a breeze with bl.ocks.org. Once you have all the code sorted and any data files accessible, bl.ocks.org can display the graph with the code and can even open the graph in its own window. The person responsible for bl.ocks.org? Mike Bostock of course (wherever does he get the time?).

So clicking on the bl.ocks.org button on the gist page takes you to see your graph.

Wow! Impressive.

So you think that will make a fine addition to your collection of awesome graphs and if you click on your GitHub user name that is in the top left of the screen you go to a page that lays out all your graphs with a thumbnail giving a sneak preview of what the user can expect.

Aww... Rats! There's a nice place holder, but no pretty picture.

Hang on, what had Mike said on the bl.ocks.org main page?

“The main source code for your example should be named index.html. You can also include a README.md using Markdown, and a thumbnail.png for preview.”

Ahh.. you need to include a thumbnail.png file in your Gist!

So how to get it there? Well Gist is a repository, so what you need to do is to put the code in there somehow. Now from the Gist web page this doesn't appear to be a nice (gui) way to do this. So from here you will need to suspend your noob status and hit the command line.

The good news (if you're a windows user (and sorry, I haven't done this in Linux or on a Mac)) is that as part of the GitHub for windows installation a command line tool was installed as well! So you're going to use the Git Shell.

Enough of the scene setting. Let's git going :-).

Right, I'm going to describe the steps here in a pretty verbose fashion with pretty pictures and everything, but at the end I will put a simple set of steps in the form that Christophe Viau outlined on Google Groups.

First you will want to have your image ready. It needs to be a png with dimensions of 230 x 120 pixels. It should also be less than 50kB in size.

Now go to your public Gist that you have already set up and copy the link in the “Clone this gist” box.

(this should look something like https://gist.github.com/4414436.git)

Now you're going to clone this gist to a local repository using the Git Shell. Open it up from the desktop icon and you should see something like the following;

So you can clone the gist to a local folder with the command;

git clone https://gist.github.com/4414436.git

(or if you're using OSX, Alex Hornbake (see comments) has mentioned that the following command should be used to clone the gist using ssh (Thanks Alex!))

git clone git@gist.github.com:4414436.git

(The url is the one copied from the 'Clone this gist' box.)

 This will create a folder with the id (the number) of the gist in your local GitHub working directory.

And there it is (Ooo... Look almost New Years!).

Copy your thumbnail.png file into this directory.

Back to the Git Shell and change into the directory (4414436) . We can now add the thumbnail.png file to the gist with the command;

git add thumbnail.png

And now commit it to your gist with the following command in the Git Shell;

git commit -m "Thumbnail image added"

Now we need to push the commit to the remote gist (you may be asked for your GitHub user name and password if you haven't done this before) with the following command;

git push

OK, now you can go back to the web page for your gist and refresh it and scroll on down...

Woo Hoo!

(I know it doesn't look like much, but this is a VERY simple graph :-)).

Now for the real test. Go back to your home page for your blocks on bl.ocks.org and refresh the page.

Oh yes. You may now bask in the sweet glow of victory. And as a little bit of extra fancy, if you move your mouse over the image it translates up slightly!

Wrap up.

The steps to get your thumbnail into the gist aren't exactly point and click, but the steps you need to take are fairly easy to follow. As promised, here is the abridged list of steps that will avoid you going through the several previous pages.

1. Create your public gist on https://gist.github.com/
2. Get an image ready (230 x 120 pixels, named thumbnail.png)
3. Under "Clone this gist", copy the link (i.e., https://gist.github.com/4414436.git)
4. If you have the command line git tools (Git Shell), clone this gist to a local folder:
   git clone https://gist.github.com/4414436.git (or git clone git@gist.github.com:4414436.git  for OSX)
   It will add a folder with the gist id as a name (i.e., 4414436) under the current working directory.
5. Navigate to this folder via the command line in Git Shell: cd 4414436 (dir 4414436 on windows)
6. Navigate to this folder in file explorer and add your image (i.e., thumbnail.png)
7. Add it to git from the command line: git add test.png
8. Commit it to git: git commit -m "Thumbnail added"
9. Push this commit to your remote gist (you may need your Github user name and password):
   git push
10. Go back and refresh your Gist on https://gist.github.com/ to confirm that it worked
11. Check your blocks home page and see if it's there too. http://bl.ocks.org/<yourusername>

Just to finish off. A big thanks to Christophe Viau for the hard work on finding out how it all goes together and if there are any errors in the above description I have no doubt they will be mine.

The above description (and heaps of other stuff) is in the D3 Tips and Tricks document that can be accessed from the downloads page of d3noob.org.