This site is hosted on GithHub at https://github.com/perl4science/perl4science.github.com. But wait! Thats not enough to go tinkering just yet. Please read at least through the section entitled For small changes before contributing. Thanks.

Octopress

This site uses Octopress to manage and publish a Jekyll site hosted on GitHub Pages. While GitHub Pages/Jekyll are cool, they aren’t the easiest to use/maintain; that’s where Octopress comes in. Before reading on, take a moment to read up on Jekyll and Octopress.

Structure

An Octopress site is one git repository with (at least) two branches.

• master - contains just the published site. This is autogenerated, don’t touch it.
• source - contains the source documents, the generated documents and the Octopress engine.

The Jekyll-formatted source documents are inside the source folder. The configuration is in the _config.yml and Rakefile files. Some of the style files are in the sass folder.

For small changes …

Running Octopress makes administering the site easy, but its rather heavy if you only want to make a few line changes. If this is all you want to do, then

1. Fork the repo
2. Be sure you are on the branch source
3. Edit the files in the folder source
4. Commit to your fork
5. Submit a pull request for consideration

If you want to create new pages or blog posts, or if you want to be able to deploy the site, you will need to read on!

Setting up your system

Be sure that your system is setup as detailed on the Octopress setup site. Currently Octopress uses Ruby 1.9.2. Here is a quick setup using rvm (which is like PerlBrew for Ruby).

First, be sure you have libssl-dev installed, Octopress has trouble if you don’t. On Debian/Ubuntu this is done with

$ sudo apt-get install libssl-dev

Install rvm by running

$ curl -L https://get.rvm.io | bash -s stable

and be sure to source the setup file (and add it to your .bashrc file if you want it to work after every boot).

Then install Ruby 1.9.2

$ rvm install 1.9.2

it will likely list a number of dependencies that you should install, do so in another shell, then continue.

Finally you will need the bundler gem, so do

$ gem install bundler

Fork/clone the repo

Remember, we will only talk aout the source branch, be sure you are always using it, not master.

Clone the site, directly to the source branch

$ git clone -b source git@github.com:perl4science/perl4science.github.com.git

Note that the url may be your fork if you do not have commit rights to the main repo.

Then cd into the new directory. Note that rvm may warn you here, enter y to continue. Now install the necessary bundles with

$ bundle install

Finally if you want to be able to deploy the site, if you have commit rights, you will need to run

$ rake setup_github_pages

and when prompted enter the ssh url of the repository git@github.com:perl4science/perl4science.github.com.git

Editing the site

Well thats a lot of stuff but you should be ready to go now!

Create a new post

Create a new blog post by issuing

rake new_post["title"]

This will create a new blog file. It will already contain some metadata in the usual Jekyll way. Under the metadata, add your markdown formatted content. Once the blog is regenerated the post should show up in the blog section of the site.

Create a new page

Like a new blog post, creating a page is as easy as

rake new_page["title"]

Again this will create a new file, but it will be in a folder based on the name, the file being index.markdown. Once you regenerate the site, the page will be available at http://perl4science.github.com/title. There will not be links to it however, so you will need to link to it appropriately. This might involve adding a link to the navbar source/_includes/custom/navigation.html, though you should do that infrequently, for obvious space reasons.

Generate local site from the source

Running

rake generate

will take the source from the source directory and copy it to the public directory filling in the data along the way.

Previewing the site locally

To start a local server to preview the site, run

rake preview

and then visit the site at localhost:4000 (or whatever it tells you). You should be able to see the site. When you save source files, it should regenerate the site for you, simply refresh the page to see the result.

Deploying the site

If you have commit privileges to the main repository, and assuming you did the required setup step above, you can issue

rake deploy

it should push the local changes to the master branch on GitHub and thus it will be publically viewable. Note that in this case you should also commit your changes to the source branch and push them.

git commit -a -m 'message'
git push origin source

If you don’t have commit rights, you should commit to your local fork, then issue a pull request from your source branch and we will evaluate your changes and hopefully deploy them soon.