PacELF Digital Library

A static site for storing and searching the PacELF project's digital library of documents.

Prerequisites

To install this project, you'll need the following system-level requirements installed on a macOS platform.

1. Ruby
2. NodeJS

You will require the Homebrew package manager. Once you have brew installed, run the following command:

brew install node

To install ruby, run the following:

rvm install ruby 2.7
gem install bundler

Local Installation

1. Clone this repo, or download it into a directory of your choice.
2. Inside the project's root directory, run:

npm install

bundle install

Usage

Developing

Jekyll

To simply serve the site locally and/or to see development changes to the Jekyll datasets, layouts or includes, run;

bundle exec jekyll serve --watch --incremental

This will output a localhost development server.

To remove existing content in _site, which is where Jekyll builds to and serves from, run:

bundle exec jekyll clean

To rebuild the content of _site run:

bundle exec jekyll build

See the Jekyll docs for more options.

Javascript

When making changes to the Javascript within scripts/:

Re-compile the files using the provided webpack.config.js configuration using:

npm run build

View package.json for more commands and details.

Updating datasets

Currently this codebase requires the .xml, .txt and .pdf documents to be provided in the docs folder.
The xml documents contain the information about documents curated by the PacELF project, the .txt contains information about the availability of the document itself and the .pdf is the document referenced.

Process to obtain XML documents

A spreadsheet is maintained by the PacELF project and a snapshot of any new/updated entries are received by eResearch via email when made available by the PacELF team. Spreadsheet in this repo /PacELF_Phase3/rawdata/excel/PacELF Phases 1_2_3 13Dec2018.xlsx is updated with the new and admended entries. Convert updated spreadsheet to .xml documents via Python script /PacELF_Phase3/scripts/csvColumnToXMLFile.py.

Producing markdown document for each XML document

Once the XML documents are in located in docs/ you can install the Python dependencies in requirements.txt using your preferred tool.

e.g.

pip3 install -r requirements.txt

Then you can run the script

python3 convert-xml-to-md.py

With luck it will populate the _datasets/ folder with the original markdown output of each XML document.

Deployments via GitHub

The site is deployed by GitHub Pages to https://pacelf.github.io/

NOTE Changes can be made to deployed site by making changes to the GitHub repository gh-pages branch. The easiest workflow is:

bundle exec jekyll build

Copy the contents of _site/.

Switch to the gh-pages branch:

git checkout gh-pages

Replace the existing content, git commit and push in whatever way you like.

Tests

To locally run the tests on the static site produced, first install the project dependencies above.

Then install the testing dependencies via:

gem install html-proofer

Build the static site via:

bundle exec jekyll build

Run the tests:

htmlproofer ./_site

Further Documentation

Architecture

Currently built using Jekyll via the JKAN project.

JKAN Links

JKAN is organised in a particular way to suit it's usecase and it is helpful to understand before making changes. The architecture and development of it is documented here.

Analytics

Per PacELF project's request, Google Analytics is loaded into the site to count viewers.

It is currently stored under [email protected] Google Analytics account.

Recurring Reports

As requested, it sends monthly audience overview emails to [email protected] which are forwarded to Patricia Graves (patricia.graves@jcu.edu.au) as the PacELF project owner.