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.
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.
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
Rakefile files. Some of the style files are in the
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
- Fork the repo
- Be sure you are on the branch
- Edit the files in the folder
- Commit to your fork
- 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
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
Clone the site, directly to the
$ git clone -b source email@example.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.
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
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
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
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
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
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
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.