GitHub Tricks: Upload Images & Live Demos

Often developers will publish source code to a custom application or library on GitHub. Experienced developers will also document their code/solution with a detailed README, and perhaps Wiki pages. But those same developers often do not have convenient answers to the following issues:

  • How do you upload images that you want to be shown in the README file(s)?
  • How do you deploy a live demo of your application or library?

The following two sections will show you how to accomplish these easily!


(1) Uploading Images, PDFs, and other assets

When adding files to the repository, you are asking GitHub to track changes and commits for each asset in your repository.

In most cases your CDN assets do not, however, need to be version controlled. And while Amazon CloudFront or Akamai offer great CDN solutions, such approaches (a) physically separates your repository from your images, and (b) becomes an upload and maintenance PITA when you have a simple set of static assets.

So the summary advice is:

  1. Do not try to add your images to the repository itself and then use a reference to a raw path.
  2. Do not worry about deploying your static images and other file attachments to Amazon CloudFront or Akamai…

GitHub Asset Management

Github does not currently provide an asset management tool for developers repositories. But GitHub DOES have a hidden feature that can be used as a CDN for assets (images, attachements, etc). it’s called the Issues feature!

Smart use of Issues makes it super easy to uploaded files that are associated with your repository… and these files not part of its commit/change processes. If you create an Issue within your repository, you can drag-n-drop files to the issue comments to automatically upload and attach static content to your repository.

Here are samples steps:

Step 1) Click on Issues tab:

Create an issue with title appropriate to the context of your images

image

Step 2) Create a new issue

In the samples below, I am uploading images that will be used within the README.md document, so I will create an issue title: Images for README. Notice the instructions on the bottom of the Write tab? You can drag-n-drop 1 or more images onto the Leave a Comment box and those files will be instantly uploaded to the hidden GitHub asset manager.

image

After each upload, GitHub will update the text the markdown link to the image

image

Step 3) Using uploading images or assets (e.g. PDF, SWF, etc)

After your submit the new issue, you will be able see recently attached image(s) rendered correctly. And finally, you can copy the URL with a right-click on the image

image

You can add more images to an issue at any time. Best of all, these images can now be referenced in your README docs or the Wiki pages [using the link URL].

Now I will admit this is a HACK only useful until GitHub finally provides a more intuitive CDN upload feature. But until that happens… enjoy!


(2) Publishing Demos


It is also ridiculously easy to publish live demos on Github… once you know the trick(s).

In many coding projects the code is kept in one repository [branch] and the documentation or demo is kept in another [branch]. In Git you can have it all in one (1) repository and keep things separated and isolated in branches. You commit your demo files to the gh-pages branch and push it to origin. If your master branch has the source to your application or library, then the gh-pages branch will provide version control AND access for your demo(s) or documentation… two (2) total distinct branches in one (1) repository.

Consider the following

If you commit the demo files to the branch

Then the demo will be available at <userName>.github.io/<repositoryName>


Developers should have care when creating the gh-pages branch. You do not want to clone the contents of the master or current HEAD branch. Normally branches share files from the directory, but in Git it is possible to create empty branches.

You can create a new empty branch like this:

$ git checkout --orphan NEWBRANCH

The parameter --orphan creates a new branch, but it starts without any commit. After running the above command you are on a new branch NEWBRANCH, and the first commit you create from this state will start a new history without any ancestry. The --orphan command keeps the index and the working tree files intact in order to make it convenient for creating a new history whose trees resemble the ones from the original branch.

Since you want to create a new empty branch that has nothing to do with the original branch, you can delete all existing files in the new working directory:

$ git rm -rf .

Now you can start adding your demo or documentation files and commit them and they will live in their own branch. If you take a look at the log, you will see that it is isolated from the original log. And your demo/documentation will have its own version control… separate from your source in master (or other branches).

Using the checkout command you can switch back and forth between the different branches like this:

  • $ git checkout master (back at the master branch)
  • $ git checkout NEWBRANCH (back at the new isolated branch)

You need to run git version 1.7.2 or higher in order for the –orphan option to be supported. Thanks to [bitFlop](http://bitflop.com/document/116) for these awesome command-line tips on how to create an empty branch with its own commit log.


image

Finally do not forget the following facts regarding your gh-pages (for your live demo or documentation):

  • The gh-pages content is delivered as web pages when accessed via http://<userName>.github.io/<repositoryName>
  • The content needs to have an index.html file to load/show the demo or documentation as a default.

Summary

No matter how valuable your library/project may be:

If your docs [ Wiki or READM] are crude or missing, or

If you do not have blog or interactive/live demo to allow visitors to experiment and play

…then your project’s value will not be fully appreciated!

These two hidden features (1) Upload Images and (2) Publish Demos allow you to create superb, informative project releases… rich with images and demos! Do not limit yourself and remember that your demo [ gh-pages ] could even be an HTML page with embedded Plunkr or JSFiddle or Flash examples.

Tags: , , , , ,

GitHub Tricks: Upload Images & Live Demos

2 Responses

  1. Why would you not just clone your GitHub wiki for that project and commit the image there? It could then be used in the README.md or within the wiki pages.

    Kevin Lanni February 19, 2014 at 1:41 pm #
    • @Kevin, you miss out on a lot of benefits using the wiki for images.

      - It’s easier to upload images in issues due to upload options like browse, drag-and-drop, and copy-paste uploading (the last option is especially useful if you don’t want to save the screenshot to disk, reducing yet another step).

      - Issues send out notifications, so others can be notified. If they don’t want to be, they can unsubscribe from the issue.

      - You can reference issues on GitHub, e.g. user/repo#123 or just #123 if you’re in the same repo.

      - If you post an image per issue comment, then it’s easy to delete images you no longer want by deleting the comment. No need to go through the editing step.

      Dennis May 29, 2014 at 11:05 am #

Leave a Reply