Installation

Installing and Using Jekyll

This template is based on the Jekyll framework for simple production and release of static websites. To deploy locally, you must have a Ruby development environment installed as well as the actual Jekyll framework. Assuming you have a Ruby environment installed locally, Jekyll can be installed via

gem install jekyll bundler

Once you have Jekyll installed, you can install of the Ruby requirements for this website by running the following in the command line from the template directory:

bundle install

The build and preview the website locally, execute the following:

bundle exec jekyll serve --watch

This will build the website and serve it up at the address: http://127.0.0.1:4000.

Using this template as a stand-alone website

If you want to have a repository for your website which is completely separate from the repository where you are documenting your research, you can simply clone this repository with the following in the command line

git clone https://github.com/gchure/reproducible_website my_project_website

This will make a complete copy of this repository and store it locally on your machine with the folder name my_project website. You can then navigate into the directory and make the changes as is listed in the configuration page of this wiki.

Using this template in a branch of another repository

An alternative approach to using this template is to define the website on a new branch of another repository. This, in my opinion, is a better approach towards making your research reproducible as you will tie the actual research history to the data that is being presented on the website. This procedure is a bit more complicated, however, as is outlined in the following steps:

1. Clone this template repository to your machine with the new name template_website:

git clone https://github.com/gchure/reproducible_website template_website

2. Navigate to your research repository and make a new branch called gh-pages

cd my_project_repo
git checkout -b gh-pages

3. Copy all folders from the template repository in to your new branched research repository

cp -r template_website/* my_project_repo

4. Add all of the new files to the gh-pages branch, commit, and push to remote

git add .
git commit -m 'Initial commit of website files'
git push origin gh-pages

Deploying your website

Once you have set up the website to your liking, it's time to make it live! If you are using GitHub pages, GitHub handles all of the building steps and will publish your changes nearly instantaneously. The steps below demonstrate how enable a website on GitHub pages.

⚠️ ⚠️ ⚠️ Websites hosted through GitHub pages cannot be private and will be made available world-wide. This can open sensitive data to the world if your repository is set to private. :warning: :warning: :warning:

1. Navigate to the settings page of your repository.

2. Scroll down to the "GitHub Pages" section

3. From the dropdown menu under Source, select the branch of your repository where the template lives. If you are using this template as a stand-alone website, select the master branch. If you are working in the branch of another repository, select the gh-pages branch.

4. Do not select a theme. The theme is prepackaged with this template.

5. Click publish. Once hosted, you will be able to see your website at the address https://[username].github.io/[project_name].

If this works, but your page is broken (meaning you reach a 404 page or if all styling is gone), please see the troubleshooting page for tips.