Let's Make a Framework: Project Websites

2011-01-27 00:00:00 +0000 by Alex R. Young

Welcome to part 48 of Let's Make a Framework, the ongoing series about
building a JavaScript framework.

If you haven't been following along, these articles are tagged with
lmaf. The project we're creating is called Turing.

Hosting Documentation

GitHub will host open source projects for free. It renders README files
on the project's page, and works with textile, markdown, and probably
more formats. Most open source projects I encounter include a nicely
formatted README with code examples.

But GitHub allows us to go beyond that with the GitHub
feature. This can be used to host the
documentation we generated with
dox last week at http://username.github.com/project-name. In this case it's

GitHub's documentation on Pages is actually very good, but I'll walk
through how I set up Turing's documentation here as well. Pages will
look for a gh-pages branch in your project. It would be
possible to fork the entire project, but I created a clean branch:

git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx

Then I added a quick Jakefile that downloads Turing's latest
documentation from GitHub:

var exec = require('child_process').exec;

desc('Updates the documentation from GitHub');
task('docs', [], function() {
  exec('curl -O https://github.com/alexyoung/turing.js/raw/master/docs/index.html');

Your projects might require totally unique hand-written documentation --
in which case use a clean branch -- or you might have a copy of your
main branch and just generate an index.html file (many projects work
this way).

Next I pushed the branch to GitHub:

jake docs
git add .
gc -m 'Created gh-pages branch with documentation and a Jake task to fetch the documentation from GitHub'
git push origin gh-pages

# Switch back to master
git checkout master

GitHub then sent me a notice to say the documentation was generated.

These branches can be viewed on GitHub:

Registering a Domain Name

Another nice GitHub Pages feature is custom domains. I registered
turingjs.com and set up a CNAME file in Turing's gh-pages branch. The CNAME file just contains turingjs.com,
then I set up a record pointing the domain to -- this is
an IP address at GitHub.

I bought this domain and configured the DNS through
NearlyFreeSpeech.NET, a company recommended to me by a friend. They have a fairly unique pricing
which seems
appropriate for an open source project, so check them out if you'd like
a domain or some hosting for your own work.

A Simple Project Site

I've adapted the documentation generated by dox to include some
introductory text with code examples. In general when writing your own
sites and READMEs, consider including the following:

This will make it easier for people to use your project and contribute.
It also makes it easier for journalists who want to write about your

I've started including a list of recent updates in some of my open
source projects. Technically this information can be obtained from the
version control system, but it's sometimes useful to draw attention to
certain updates.