Skip to content

Home

Jump to bottom
Nabil Kashyap edited this page Oct 20, 2018 · 9 revisions

Monument Lab 2017 Proposals

This Jekyll theme customizes the (excellent) Wax project and relies on the related gem Wax_Tasks. It disables IIIF image tiling and adds both a map view and a D3-based gallery overview.

The Wax project documentation contains more more details on building pages and search index available.

How do I _________ ?

The following commands assume gems (installed via bundle) and node modules have been installed locally.

Build pages

  • For unclear reasons Airtable csv export has issues when building pages while OpenRefine csv export has no issues
  • Much simpler to manage if _data/[filename].csv and collection in _config are matching strings
  • bundle exec rake wax:pagemaster [csv filename]

Regenerate the search index

  • Execute after pages are built
  • _config.yml contains array of metadata fields to include/exclude
  • `bundle exec rake wax:elasticlunr

Update SCSS and JS

  • There are a bunch of work arounds for long Jekyll builds, but they require some fiddling

  • The current _config.yml settings make use of the exclude parameter with wild abandon. Note that any files added to excluded folders will not appear in the site build, e.g., new or updated proposal images/thumbnails.

  • Most JS files are in the js folder -- however JS for the home page gallery appears inline (I know, I know) on index.html because it relies on templating.

  • Note that JS files are conditionally loaded in _layouts/default.html

  • Having run a successful site build, here is one workflow for updating SCSS/JS:

    • npm run watch (this runs two commands that appear in the package.json file under the scripts entry)
    • Note that Jekyll relies on yml frontmatter to compile SCSS while Node will bark if there's any frontmatter. You will need to comment out the frontmatter for Node to compile correctly (in which case Jekyll will skip SCSS on build)
    • Start any SCSS file with an extra newline and do not end with commments

Change what facets appear in the gallery view

  • YAML frontmatter on pages/gallery.md

Change what facets appear in the map view

  • YAML frontmatter on pages/map.html

Deploy changes to the server

  • May be better ways for ongoing development but a workable solution is the following command:
  • rsync -rav _site/* --exclude=assets/monuments 54.91.189.219:/var/www/monumentlab/

Update which fields appear on item (single proposal) pages

  • Edit _config.yml ml.item_fields parameter

Update the labels assigned to different metadata fields on item (single proposal) pages

  • Edit _config.yml ml.display_fields parameter

Update search parameters

  • Which fields are indexed _config.yml collections.[collection name].lunr_index parameter
  • Which fields searched, elasticlunr settings and HTML returned js/lunr-ui.js

Make sense of the SCSS/CSS

  • Wax is built on Bootstrap 4 which is loaded remotely in _includes/head.html
  • Leaflet and the Marker Cluster styles are loaded remotely in _includes/head.html
  • Wax styles appear in _sass/_wax-theme.scss (note this is a different filename from original repo due to how Node handles SASS compilation)
  • This theme's styles appear in _sass/_custom.scss
  • Font settings appear in _sass/_fonts.scss
  • Variables are set in assets/wax.scss

Make sense of the JS

  • JQuery and Bootstrap JS loaded remotely in _includes/head.html
  • Theme JS files are conditionally loaded in _layouts/default.html
  • Except inline JS for home gallery, which appears in index.html
  • js/gallery.js controls gallery view -- note this is written in ECMA6 but compiles down using babel in the package.json script watch:js
  • js/ml-leaflet-map.js controls map view

Update the data and rebuild the site

The current parent copy of the data is the .csv that appears in _data. It includes latitude and longitude coordinates, georeferenced general and specific neighborhood columns, and cleaned topic columns.

Currently, in order to update the site with new data, you will need to rebuild the collection and index using Wax, regenerate the geojson for the Map view, and rebuild the Jekyll site. After this, you can sync with the server folder according to the instructions above.

  • Rebuild collection and regenerate search index: Please see instructions above.
  • Regenerate the geojson for the Map view: this script will generate a new geojson file based on the parent csv. Please update file input/output parameters as indicated in the gist comments.
  • Rebuild Jekyll static files: bundle exec jekyll build
  • Resync with server: Please see instructions above.
Clone this wiki locally