The RailsApps Website

This repository contains the static web pages for the site at http://railsapps.github.com.

To update the content for this website, use the GitHub wiki:

• https://github.com/railsapps/railsapps.github.com/wiki

To change the layout and design, edit the _Layout.html file and CSS and Javascript in the railsapps.github.com.wiki repository.

Then use the gollum-site gem to generate static web pages from the wiki. To commit the generated web pages, you’ll need repository read+write permission as an organization team member.

Objectives

Here are the goals I had in mind when I set up the RailsApp site:

• I wanted to use GitHub’s capability for hosting the site. The hosting is free and the wiki is familiar to GitHub users. I didn’t want to deploy a dedicated CMS or use a wiki hosted elsewhere.

• I’d like any GitHub user to be able to add to the site (or make corrections) by editing the repository’s wiki pages directly.

• I like being able to edit the wiki pages locally using Textile markup and commit changes to the GitHub repository. I use the same text editor and workflow that I use for maintaining code.

• On its own, the GitHub wiki does not provide everything needed for the project website. I wanted to improve the layout and design to make the site more attractive and useful. I wanted to add Javascript for the Disqus commenting system as well as a Google Analytics tracking script. I anticipated I would use a tool such as Jekyll to combine the wiki files with a layout template and generate static web pages to upload to GitHub for site hosting.

• As the maintainer of the site, I anticipate generating static web pages from the wiki files periodically (or when I notice changes to the wiki pages or am alerted with a GitHub issue). I don’t need to have the site updated dynamically.

I looked at several static website generators, including Jekyll, and decided gollum-site most closely fit my requirements.

Publishing Workflow

You can edit the wiki pages online. Alternatively, you can edit them locally in a text editor after cloning the repository.

Here’s how you can edit the pages locally and generate a new version of the website from the wiki pages.

The gollum-site gem is used to generate static web pages from the wiki.

Install the Gollum-Site Gem

Install the gollum-site gem plus the RedCloth gem (to support Textile markup).

$ gem install gollum-site RedCloth

Clone the Repos

Note that there are two repositories: the site repo (for the static web pages) and the wiki repo (for the wiki pages).

We’ll assume you will create a directory for the project and download the needed files.

$ mkdir ~/railsapps
$ cd ~/railsapps
$ git clone [email protected]:RailsApps/railsapps.github.com.git
$ git clone [email protected]:RailsApps/railsapps.github.com.wiki.git

Edit the Content

Make sure you are in the git “master” branch. Edit the wiki pages and commit any changes.

$ cd railsapps.github.com.wiki
$ git checkout master
## edit wiki pages with a text editor
$ git commit -am "update wiki"

Change the Layout and Design

To change the layout and design, edit the _Layout.html file and change any CSS and Javascript files in the railsapps.github.com.wiki repository. Then commit any changes.

## edit the *_Layout.html* file with a text editor
## edit the *css/screen.css* file with a text editor
$ git commit -am "update layout"

Generate Static Web Pages

When you are ready to generate the static pages, use the gollum-site gem to generate the static web pages in the wiki repo. Gollum-site has a built-in web server if you want to view the site locally before committing and publishing to GitHub.

$ gollum-site generate ## to generate static webpages in "./_site" folder
$ gollum-site serve ## to view the static site at http://localhost:8000

Publish to GitHub

Copy the generated _site directory to the site repo. Rename the Home.html page as index.html. Commit the changes and push the repo up to GitHub.To commit the generated web pages, you’ll need repository read+write permission as an organization team member. GitHub will automatically publish the updated site in less than a minute.

$ cp -R _site/* ../railsapps.github.com
$ rm -rf _site/
$ cd ../railsapps.github.com
$ mv Home.html index.html
$ git add .
$ git commit -am "update website"
$ git push origin master

See the updated site at http://railsapps.github.com.

Alternative Approaches

I looked at Jekyll. It generates static pages from markup but it’s more complex and better suited to publishing a blog.

I looked at Smeagol. It is a server that hosts and renders a Gollum wiki (such as GitHub wiki pages). It requires installation as an app on a hosting site that runs Ruby. It would require maintaining a server and would not allow the site to be hosted on a GitHub subdomain.

Issues

Improvements or corrections to the web site? You can edit the wiki pages directly.

Suggestions? Questions? Please create a GitHub issue.

Credits

Daniel Kehoe (http://danielkehoe.com/) maintains the website.

You are welcome to contribute.

License

Public Domain Dedication

This work is a compilation and derivation from other previously released works. With the exception of various included works, which may be restricted by other licenses, the author or authors of this code dedicate any and all copyright interest in this code to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this code under copyright law.