Merge pull request #6 from ResearchSoftwareCulham/add-setup-guide

Add setup guide for serving locally

Author: jonmaddock

Gemfile

@@ -28,3 +28,5 @@ end
 # Performance-booster for watching directories on Windows
 gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
 
+# webrick apparently required for later Ruby versions
+gem "webrick"

Gemfile.lock

@@ -251,6 +251,7 @@ GEM
       unf_ext
     unf_ext (0.0.7.7)
     unicode-display_width (1.7.0)
+    webrick (1.7.0)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -263,6 +264,7 @@ DEPENDENCIES
   tzinfo (~> 1.2)
   tzinfo-data
   wdm (~> 0.1.1)
+  webrick
 
 BUNDLED WITH
    2.2.14

README.md

@@ -4,5 +4,31 @@
 
 A blog for Research Software at Culham.
 
+This site is hosted using [Github Pages](https://pages.github.com/) and is generated using the [Jekyll](https://jekyllrb.com/) static site generator. This means that a Markdown file (with some YAML front matter) on the `master` branch will be automatically published to [researchsoftwareculham.github.io](https://researchsoftwareculham.github.io/) as a blog post or page.
+
+## Setup for serving the site locally
+To serve the site locally and preview your changes before committing, you will need to set up Jekyll. The full Gitlab documentation for setting this up can be found [here](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll).
+
+First, [install Ruby](https://www.ruby-lang.org/en/documentation/installation/). On Ubuntu, using `apt`, this is:
+```
+sudo apt install ruby-full
+```
+
+Next, [install Bundler](https://bundler.io/), which manages Ruby gem dependencies:
+```
+gem install bundler
+```
+
+Then navigate to the project root directory and install the required gems:
+```
+bundle install
+```
+
+Then run `jekyll` using Bundler, generating and serving the Jekyll site locally:
+```
+bundle exec jekyll serve
+```
+
+To preview the site in your web browser, navigate to `http://localhost:4000`.
 [cc-by]: http://creativecommons.org/licenses/by/4.0/
 [cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg