StaticAid

A Jekyll static site generator for archival description serialized in JSON, generated via the ArchivesSpace REST API, or by other modular backends which can be added to the system.

You can see a live version of this site with sample data here.

Requirements

• Python (tested on v2.7)

• Python Modules:

  • requests
  • requests_toolbelt
  • psutil

• Jekyll (to build the site)

• Node Package Manager or NPM

• Grunt (for running build and deployment tasks)

• An ArchivesSpace or Adlib instance with some data entered (sample data sets are included for testing).

Installation

Setup

1. Clone this repository git clone [email protected]:helrond/staticAid.git or download the ZIP file.
2. Install dependencies. See "Requirements" above for a list of things you'll need to have installed.
3. In this project's root directory, run npm install to install dependencies for Grunt.
4. Review the default settings in local_settings.default; if you'd like to change them, copy this file to local_settings.cfg and make your changes.

NOTE: For Linux-like systems, you can simply run install.sh. It has only been tested on Mint 18+, Ubuntu 16+ and Mac OSX, but should work on any Debian based distribution, RedHat, etc. with minimal modification.

Usage

Sample data

Three sample data sets are included in the data/ directory. To use, unzip and place in build/data before building the site.

Building the HTML Site

You have three options for building the HTML site using Jekyll. In all cases, Jekyll will place the generated site in build/site/.

Build without updating data

Running grunt build will build the site based on the data currently in the build/data directory.

Update data then build site

Running grunt update will fetch JSON for resource records, resource record trees and archival objects from ArchivesSpace using static_aid/getJson.py and save it in your build/data directory, then will build the site based on that data.

WARNING: Depending on the size of your ArchivesSpace installation, it could take quite a while for this script to loop through all resource records and components. Be patient!

Clean Build

By default, grunt update will only fetch JSON updated since the last time static_aid/getJson.py completed successfully. At any point, you can run grunt rebuild to wipe out the existing data and build the site from scratch.

WARNING: Depending on the size of your ArchivesSpace installation, it could take quite a while for this script to loop through all resource records and components. Be patient!

Starting the Local Server

To start a local server (useful for previewing the site), run grunt serve. You can then access the site by opening a browser and pointing it to http://localhost:4000. To stop the server, use ctrl + c.

This server will use the HTML generated by the last build, so if you've made changes to any of your templates or data you'll need to build the site in order to see those changes (see above).

JSON-LD Structured Data

By default, StaticAid is set up to generate structured data in your HTML in the form of JSON-LD objects, coded according to the conventions of schema.org. JSON-LD is Google's recommended method of delivering structured data for its indexing algorithms. (More information here.)

Currently, JSON-LD objects are formed on three kinds of pages:

• Main index page, describing the holding archive (Schema)
• Collection pages (Schema)
• Persona and Corporate Agent detail pages (Schemas)

Variables used in the JSON-LD objects (as well as a few others in building your site) are stored in _config.yml. If you don't want JSON-LD generated, you can comment the variables out. The JSON-LD will be broken, but it will not affect the display of the web pages.

Auto Generating StaticAid Content via Cron Job

If you would like to auto-generate StaticAid content using a cron job (on OSX/Linux systems), you can link one of the rebuild scripts to an appropriate cron job folder. To auto-generate full-page content every day, you could do this:

sudo ln -s scripts/static-aid-rebuild /etc/cron.daily/

or to auto-generate embedded content every week, you could do this:

sudo ln -s scripts/static-aid-rebuild-embedded /etc/cron.weekly/

NOTE: it is important to softlink (ln -s src dest) instead of copying (cp src dest).

Contributing

Pull requests accepted! Feel free to file issues on this repository as well.

Authors

Hillel Arnold / @helrond

Kevin Clair / @jackflaps

Luke Scott / @v-lukes

Erin O'Meara / @diplomatica

Scott Carlson / @scottythered

License

staticAid is released under the MIT License. See LICENSE.md for more information.