Gardener Jekyll Theme for Treebank Publications

This guide should help you self-publish a collection of treebank fixes produced on the Perseids platform with Arethusa, hosting them in a simple Jekyll-based site via GitHub Pages.

Prerequisites for using this theme include:

• The ability to use the command line on your operating system.
• Basic knowledge of how to use GitHub
• Treebank files produced on Perseids with Arethusa

To publish your own treebank collection, follow the below instructions. (Command line examples are given as they would be executed on Linux-based operating system).

1. Create your repository
   1. Create a GitHub account (if you don’t have one already) and familiarize yourself with how GitHub works.
   2. Fork this repository (https://github.com/perseids-project/Gardener) to your own GitHub account.
   3. If you like, you can rename the repository in your account.
   4. We encourage you to use your github account to create a Zenodo account, and to use Zenodo to set up a DOI for your treebank collection.
   5. Clone the forked repository to your local environment, so that you can work with it and test it locally.
2. Install Ruby (version 2.5.3) in your local environment
   1. Install Ruby and Rubygems.
   2. Install the Jekyll and Bundler gems:

      gem install bundler

3. Configure your site. Edit the _config.yml file to set the things that are specific to your site:
   1. Set title to the Title you wan to to appear for your site.
   2. Set email to your email address (if you want to publish it, otherwise set it to be empty)
   3. Set description to the text you would like to appear on the home page of your site
   4. Set baseurl to "/" plus the name of your forked repository (this will be normally be '/Gardener' unless you have changed the name of the repository after forking it.).
   5. Set url to the full Github.io URL for your repository (e.g. 'https://youraccount.github.io/Gardener'
   6. Set twitter_username and github_username as appropriate
   7. If you set up a Zenodo account, and created a first relase of your collection, Set DOI to your current release (e.g. this will be something like '10.5281/zenodo.XXXXXX') .
4. Load your treebanks into the xml directory
   The Gardener theme is designed to work with data files which adhere to a specific directory naming convention:

   /xml/uniqueid/data/treebankfilename.xml

   (This is the same structure you will find in the BagIt archives you can export directly from Perseids by clicking the little shopping bag icon that appears to the right of your file on the Perseids home screen. When you unzip the Perseids BagIt Zip Archive, the files will be in a base directory named according to the Perseids publication id and download date, and within there in a "data" subdirectory.)
   1. Download the bag from Perseids
   2. Unzip the downloaded bag in the xml subdirectory of your repository.

                   cd xml
                   unzip /path/to/downloaded/file .
      	   

   3. You should end up with a directory structure that looks like this:

                 xml
                   perseidspublication_99999_2017-06-08T11:58:10+00:00
                     data
                       perseus-grctb.9999.1.xml
                 

   4. There will be other metadata files extracted from the Perseids bagit archives, but you can ignore them.
   5. Repeat this process for as many files as you want to publish.
5. Create index files for each treebank. You can do this in a very basic text editor, or in-browser on GitHub. For each treebank file you publish, add a file in the _tbpages directory of your repository. The filename can be whatever you want but for simplicity we recommend a name that is related to the name your treebank file. E.g.

               _tbpages
                 9999.1.html
   	

   The contents of the file should adhere to the format described below under "Template Treebank Index Files"
6. Install dependencies and use Jekyll to build the site
   1. Build and test your site locally (see full instructions):

      	   bundle install
                 bundle exec jekyll build
                 bundle exec jekyll serve
      	   

   2. Once you are satisfied, you can push to GitHub. Because the Gardener theme uses Jekyll extensions, you must push the locally built files to GitHub, rather than having GitHub generate the files dynamically. This means that you must be sure that the docs directory created by the jekyll build command is included in what gets committed and pushed to GitHub.
7. Setting up GitHub-pages
   1. Once you have pushed your site to GitHub, you will need to turn on GitHub Pages. Make sure to identify the docs directory as the source for your site.

Template Treebank Index Files

The benefit of using Gardener is that you do not need to understand basic html in order to create a basic blog for your trees. In order to generate each treebank display page, you will need to create a simple html file for each treebank file. But that file can be almost entirely empty and only needs to have a yaml header.This header contains the important data that the system needs in order to generate the treebank displays, and the list of treebanks on the main page. Here is a sample yaml header and a breif explanation of what each element of the header means:

---
layout: tbpage
title: "Plato Apology"
work: "Apology"
author: Plato
editor: Tim Buckingham
locus: 20b-22b.2
pubdir: perseidspublication_99999_2017-06-08T11:58:10+00:00
tbfile: perseus-grctb.1911.1.xml
---

• Layout: leave this value as tbpage, this determines which page template jekyll will use when it builds the site. For these treebank display pages, you will always want to use tbpage.
• Title: this can be whatever you want to call the treebank, it will appear at the top of the page
  
• Work: the title of the original source of the text for your treebank
• Author: the author of the Text for your treebank
• Editor: the person(s) who annotated the treebank
• Locus: the section(s) of the original text for your treebank
• Folder: the name of the folder within the xml directory that contains your treebank file. If you followed the above instructions to export a Perseids BagIt archive, it will contain the publication id and date as in the example.
• Tbfile: the name of the treebank file you want to associate with this treebank page. The example is the default naming convention for treebank files when they are downloaded from Perseids.

Any additional content that you want to add to the tbpage, you can add below the yaml header. Even unformated text will appear in the final version of the page above the treebank display.
These html files can be written up in any simple text editor.

The repository contains one sample publication. Use it as a template for your own tbpage files.