The code that forms our ScholarsLab.org site, and stuff related to improving the site (documentation, issue list of future work)

There's a homepage for all our SLab.org-related documentation here, but we've tried to also cover the most frequently useful info below.

Want help? Definitely feel free to either ask any questions in the SLab Slack #slab-org channel, or talk with Amanda. (It's fine if you haven't read through all the documentation below first—there's a lot, but that makes it harder to quickly find answers and we're happy to point you to what you need.)

1. View the site
2. Contribute to the site
3. Add an issue
4. Working with the site locally
   • Prerequisites
   • Installation
   • Building the site
   • Rake tasks

1. ScholarsLab.org

• Our "live" (aka production) website that the world can see.
• We change code in this repo, a service that Ammon created updates the UVA web server hosting our site, and the change appears on ScholarsLab.org a couple minutes later

2. Maybe.ScholarsLab.org

• Not our live site; lives on GitHub Pages server
• Gets updated when the repo gets updated, but! lacks some stuff that can't work on GitHub Pages (some Jekyll plugins, the nginx redirects that point old URLs to the current page locations (e.g. scholarslab.org/about/charter moved to scholarslab.org/charter when we moved from WordPress to Jekyll)
• So, maybe just ignore that this exists? I guess we could take it down?

3. "Old" WordPress site will live at: old.scholarslab.org (hasn't been moved there yet; #531 will accomplish this)
   • The Wordpress site that was ScholarsLab.org up until the end of 2018
   • No longer updated, but available in case we need to grab stuff from it

Check out the appropriate documentation for:

• editing or adding a new post or page
• template for new posts * template for new pages
• template for new events

...and then locate where you need to go in the repo:

1. Adding or changing language on the homepage? Edit the repo's top-level index.html file
2. Adding or changing language on other non-repeating pages? (NB: A "non-repeating page" is hereafter referred to as a "static page", e.g. the Makerspace homepage, the Praxis homepage, etc.). All such pages are in this "pages" folder.

If you can't find the text you want to alter, it may be something that lives in a separate file:

3. /_includes covers things like our footer, navbar, and
   A. Alerting folks to a snow day or other surprise/emergency notice: /_includes/snowday.html
   B. Updating the "Open Office Hours" sticky notice (in the homepage "upcoming events" list), e.g. when it's summer and we pause office hours until fall: /_includes/open-office-hours.html

4. /_layouts covers structural stuff that is the same on a bunch of pages, e.g. setting all our project pages to list the title of the project, years, and collaborator names happens in /layouts/work.html

5. /collections contain the following files, which get pulled into layouts to form posts or pages:
   A. /collections/_events: one file per event, containing all the info about the event (pulled into scholarslab.org/events, indvidual event pages, and places like the homepage list of upcoming events)
   B. /collections/_people: a file for every person currently or formerly part of the lab (used on scholarslab.org/people, individual bio pages, and places like the Spatial Tech page's gallery of SpIn staff photos)
   C. /collections/_posts: our blog posts! (appear on scholarslab.org/blog, individual blog post webpages, and possibly in future places like a list of student-authored posts on the /student-opportunities page)
   D. /collections/_spaces: info about some of our physical locations
   E. /collections/_work: our projects/chunks of work (on scholarslab.org/work and individual project pages)

If none of the above fit or you're not sure, definitely feel free to either ask in the SLab Slack #slab-org channel, or talk with Amanda.

• Need assistance? Definitely feel free to either ask any questions in the SLab Slack #slab-org channel, or talk with Amanda. And: it's totally fine to just ask, rather than hunt through our documentation trying to see if you question is already answered.

• Alerting the team to a bug, requested feature, possible future site work, or other fix? Add to our issues list; here's how to add an issue, plus how to look through our (often long) list of existing issues.

• Check out our list of frequent error messages encountered when working with Jekyll locally. Please add any you encounter (even if you can't document how to solve it.)

How to get the site up and running on your computer:

• Ruby 2.4.1
  • OSX: Install/manage using Ruby Version Manager
  • Windows: Install/manage using Uru
• Bundler
• NPM

NB for Windows folks: Uru is unzipped using 7-Zip, which can be downloaded here. If you're in a hurry, here's the executable for version 16.04. Additionally, this article is a great explainer on how to use Uru effectively, including command line instructions.

We use Jekyll for publishing our site. To run the site locally, clone this Git repository and change directory into the project folder:

git clone git://github.com/scholarslab/scholarslab.org.git
cd scholarslab.org

To install all the necessary gems specified in the Gemfile.lock, run Bundler:

bundle install

To install all the necessary node packages, run NPM:

npm install

If this results in an error message, make sure you have Node.js and npm installed. Check out this guide, or go straight to the download page.

To build the site and search corpus, run Rake:

rake

If this doesn't work, or you're on Windows, try:

bundle exec jekyll serve --watch

The site should build, and be locally accessible at http://localhost:4000.

The project includes several Rake tasks for creating new content.

rake new_person["First","Last"]
rake new_person["Brandon","Walsh"]

rake new_post["Title here","First Last"]
ex.
rake new_post["Brandon's best blog post ever","Brandon Walsh"]

rake new_project["The name of your project goes here"]

rake new_event["The name of your event goes here","2019-01-03"]

If you run into errors, double check that you are copying the syntax exactly - no extra spaces, comma outside the quotation marks, etc.