A Jekyll-based static site generator for archival description in JSON.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
data
scripts
site
static_aid
.gitignore
Gruntfile.js
LICENSE.md
README.md
install.sh
local_settings.default
package.json
setup.py

README.md

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

Installation

Setup

  1. Clone this repository git clone git@github.com:helrond/staticAid.git or download the ZIP file.
  2. 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.
  3. Run install.sh. This 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 local_settings.cfg. If you don't want JSON-LD generated, you can leave those variables undefined. 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.