Its almost Christmas time and that means presents.
It also means that sometime between today and December 25th you need to go out and buy other people some presents because you haven’t done it yet.
But there’s someone else special in your life that deserves an Xmas gift this year. That special someone is your open source projects.
You might think, “But, Dr Nic, what do I get for the open source project that already has everything? What gift would my open source projects possible appreciate?”
Its true – this year has been a boon for open source. You probably migrated your projects from SVN to Git this year. Specifically, you probably clicked the “create a new one” link on your GitHub home page a lot this year: either to migrate your old projects to github or start new ones. Lots of new ones.
And now that your code is on github, your README file is rendered beautifully on the home page, so you were more inclined to rename it to README.markdown or README.textile and thusforthly fill it full of education information about your projects.
More people would then instantaneously figure out what the f@#$ your project actually does, thus more people used it, thus more people wrote patches or forked your code and sent Pull Requests.
All round, in 2008, I bet your open source projects had a sweet year.
Nonetheless, it is Christmas time and you should now get them a present. Something they wouldn’t get for themselves. Something you wouldn’t have done for them except for the free loving spirit of Christmas.
The Gift for all Open Source projects
Oh sure, github renders your README.markdown file. Yeah, yeah, github gives you a wiki for your project. Sure, sure, Google Groups let you communicate with your co-developers and users. Certainly, you don’t need a website for your project.
That’s why its a Christmas gift. You’re going to do it because you care.
Websites sell your project. READMEs and Wikis educate. The project website will sell it and make people want to use your stuff.
A website could have a blog with an RSS/atom feed. Then you could post updates about your project. People could subscribe and also leave comments. Oh the novelty.
And if it only took 5 minutes to get all this setup – the website code, the blog engine, the RSS feed, the comments, and published to its own hosted server – then that would just be oh so sweet.
So we’re going to do some craft for our Xmas present. A little DIY project, if you will. You’ll need a few things that you’ll find around your house, a command-line interface, and a beer or perhaps some port or sherry. Christmas cake is good too.
The commands below take about 5 minutes to execute and you’ll have a sweet website for your project, setup on GitHub Pages, just like the macruby-tmbundle and jekyll_generator sites, and the sample image above.
Jekyll and GitHub Pages
Jekyll, by Tom Preston-Werner, is one of several static website generators. All your website content will be written in textile or markdown, rendered against some HTML layouts, and published on a website somewhere. We’re going to use GitHub Pages because they are new and shiny, and free, and I’ve written some sake tasks (below) to make it all easy peasy to get up and running.
There are a bunch of reasons we’re going to use Jekyll to render our website:
One, textile and markdown are much nicer to write/edit text than HTML.
Two, Jekyll is “blog enabled”. That is, some of your pages will be specifically “blog post” pages, and elsewhere in your layout you can programmatically list them. Like a blog. Yeah.
Three, GitHub Pages automatically supports Jekyll but no other static-website generators. This saves you from having to manually render your HTML from your Textile/Markdown pages before pushing the site to the remove server.
Four, I wrote a stand-alone generator to create a Jekyll website for any project. It is preconfigured with Disqus for comments, including badges for latest comments etc.
Living with a Jekyll
Jekyll comes as a RubyGem:
sudo gem source -a http://gems.github.com/ sudo gem install mojombo-jekyll
Alternately, you can cheat and use a generator.
sudo gem install jekyll_generator cd path/to/project jekyll_generator website --title "Project Name" cd website jekyll open _site/index.html
The final steps performs the local rendering of your website (
jekyll) and then on OS X it opens the rendered website into your browser. Otherwise, manually open the index.html from the _site folder.
Currently the generator assumes that your project is already in a git repository that is hosted on github (specifically that you’ve added the github project as the origin remote).
Living with GitHub Pages
GitHub recently released GitHub Pages as a place for you to publish a personal website and websites for each of your projects. Instead of requiring you to rsync or “rake website” your way to publishing glory, you just use git.
Specifically, you put your website in a branch called “gh-pages”. When you push commits in that branch to github it will automatically refresh your website. No rsyncing required. Also, it will run your website through Jekyll.
So much delicious magic.
Except our website is not currently in another branch. Its in master. In a folder called
website. Where it should be.
But the boffins at github say we need to move our shit across to a branch called
I personally will never be doing this migration manually. I figured it out once and slapped it into a sake task. It moves all the content in your website folder into this branch, and replaces it with a submodule link so you can access the website from your master branch. Didn't follow that? No, me neither. Let's just run the sake task and move on with our lives, and eat fresh prawns and Christmas pudding.
Sake tasks to get started with GitHub Pages
To install them from scratch (initial blog post):
sudo gem install sake cd /tmp git clone git://github.com/drnic/sake-tasks.git cd sake-tasks rake install:all
You can toss away the repo after installing the sake tasks.
You now have some tasks to manage github:pages:
sake github:pages:migrate_website # Migrates an existing website folder into a gh-pages branch, and links back as submodule sake github:pages:setup # Creates the gh-pages branch, and links to it as 'website' as submodule
Since we've already created the website above, we're going to use the first task to migrate this folder into the required gh-pages branch.
Um, and your done.
Note, if sake crashes and burns in your project it might be that you don't have a Rakefile. Try, "touch Rakefile" and rerun the sake command.
In 1-10 minutes your fancy new site will appear at http://username.github.com/projectname. It even has a complimentary first blog post. You might want to change it to something useful.
You can now update your website via your website folder, commit changes and they automatically appear, automatically rendered via Jekyll, on your website.
Disqus for comments
Since your new website is static text there is no way to support comments on the blog posts. I've bundled into the theme's layouts the access code for Disqus. Like the image above, each blog post has Disqus comments at the bottom, and the sidebar shows the latest comments from all your blog posts.
You need to create a Disqus account, and create a project with the same name as your github project name. For example, if
jekyll_generator is the project name on github, then make it the name on Disqus.
In my example above, my github project name was
jekyll_generator but I couldn't use underscores on Disqus, so it is
jekyll-generator. Fortunately, the generator templates already know this, and have converted your underscored name to hyphens already.
You can skip the "Choose your platform to install" steps as this is all done by the generator templates.
If you reload your project's website it should have Disqus badges on the sidebar, and the posts should have comment boxes.
Lighthouse for tickets
Lighthouse offers free access for open source projects to track their bugs. After you've created your Lighthouse project, you need to change the TODO values in
_layouts/post.html to your Lighthouse project number.
Updating your website
Your website now appears within your project source under the website folder. Though if you change it, add new posts, etc, you won't be able to commit the changes back normally. The contents of the website folder are effectively another git repository.
To commit changes to your website, go into the website folder and proceed normally:
project(master) $ cd website project/website(gh-pages) $ git commit -m "some changes" project/website(gh-pages) $ git push origin gh-pages project/website(gh-pages) $ cd .. project(master) $
Now your submodule may be dirty and need updating:
git submodule update --init
Not sure what this is all about.
A website is a great way to show that your pride and joy isn't ignored by new visitors and reminds existing users just how awesome the project is, and by clever association, how awesome you are.
A sexy website has to be even better.
Jekyll is great, and the Github Pages concept seems fun. Perhaps it wouldn't be necessary if the Github Wiki content was available as its own git repo, or if you could theme your project's source browser like a diry MySpace page.
Hopefully the sake tasks make migration of any existing websites to the Github Pages system easy peasy, and hopefully the jekyll_generator is useful for any new projects.
- Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
- Future proofing your Ruby code. Ruby 1.9.1 is coming. Bugger. I’m a Ruby monogamist. I use the Ruby...
- newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
- My attempt at sake task management I’ve used sake intermittently in my workflow. It competes...
- How to yell at people with GitHub from TextMate Sometimes when you are perusing code you ask the question:...