Development

This document is designed to help you get up-and-running with developing the website. It is designed for a computer-literate user but, where possible, effort has been taken to make it as accessible as possible. If you encounter any problems following the steps here, please submit an issue describing it so that we can fix the problem.

Overview

The website is run using GitHub Pages and the Jekyll static site generator. Content is hosted directly on GitHub and Jekyll transforms this into web pages, served via our GitHub Pages endpoint.

Content is written using markdown and should be easily readable and editable in the browser. GitHub allows files to be edited directly and offers a preview function for Markdown files, which should eliminate the need for locally-hosted copies. For more information about the content, see here.

The domain name is configured using the provider's management tool and the CNAME file in the project's root directory.

Setting up your environment

Before you can begin development you must install the tools locally. GitHub has provided documentation for doing this here.

Macintosh OSX

To set up your development environment, open a terminal window and navigate to a directory of your choice. The website files will be stored in this directory so choose somewhere memorable and easy to find. To change directory inside the terminal, use the cd command.

1. Download git by typing brew install git in a terminal window. This is a version control system that GitHub is based around. Using version control allows changes to be undone if something has gone wrong, or for the history of a project to be viewed at a later date.

2. Download ruby by typing brew install ruby in a terminal window. This is a programming language used by Jekyll.

3. Download the bundler tool by typing gem install bundler in a terminal window. This is a tool that manages dependencies on Ruby packages, known as Gems. These dependencies are pieces of software written by others that have been used in the project.

4. Grab a copy of the project repository by typing git clone https://github.com/PieceOfEarth/pieceofearth.github.io.git in a terminal window. This will download the files for the website and all of the historical changes.

5. Navigate to the project directory by typing cd pieceofearth.github.io in a terminal window.

6. Use Bundler to set up GitHub Pages and Jekyll locally by typing bundle install. You may be prompted for your user's password at this step.

7. Run the Jekyll static page generator by typing bundle exec jekyll serve in a terminal window. The website should now be hosted at http://127.0.0.1:4000/! 🎈