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:
- Do not try to add your images to the repository itself and then use a reference to a
- 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
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.
After each upload, GitHub will update the text the markdown link to the 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
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
- Repository: anglarjs-Quizzler
If you commit the demo files to the branch
Then the demo will be available at
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
--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).
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.
Finally do not forget the following facts regarding your
gh-pages (for your live demo or documentation):
gh-pagescontent is delivered as web pages when accessed via
- The content needs to have an
index.htmlfile to load/show the demo or documentation as a default.
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.