scholarslab/scholarslab.org

World Wide Web site! For the Scholars' Lab!

Scholarslab.org

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 ask any questions in the SLab Slack #slab-org channel.

Table of Contents

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

View the site

ScholarsLab.org

• Our "live" (aka production) website that the world can see.
• We change code in this repo, GitHub builds the site and serves the updated files, and the change appears on ScholarsLab.org a couple minutes later

Contribute to the site

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

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)

Get help or add an issue

• Need assistance? Definitely feel free to ask any questions in the SLab Slack #slab-org channel.

Working with the site locally

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

Prerequisites

• Ruby 2.4.1 (still true???)
  • 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.

Installation

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.

Building the site

To build the site:

bundle exec jekyll serve --watch

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

Rake tasks

The project includes several Rake tasks for creating new content. These need to be updated to work with the 2024 renewed site, so the following may not work OR may produce things that make broken site pages.

Make a new person

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

Make a new post given a title and an author name in the form of first_name last_name

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

Make a new research project given a title

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

Make a new event project given a title and the date of the event

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.

scholarslab.org's Issues

Clean up data

Lots of data cleanup that needs to happen on various parts of the site.

• - people
• - projects
• - posts especially re: podcasts and image links

Code blocks not parsing

https://scholarslab.github.io/scholarslab.org/visualization%20and%20data%20mining/working-with-d3-part-2/

Finish pre-release work on search feature

Context

1. What should the feature do?
   Allow basic and advanced search, with potential for search terms passed through dynamic urls
2. When and where should the feature appear?
   In the navbar search and on the search page

Associated Product Ticket

Process

1. Potential Impact on Code or Other Features
2. Suggested Implementation

Expected Result

search 🎉

Export Events

Tasty Hamburger Menu

Update global navigation to use a menu at smaller device widths.

Rake tasks

Spatial Tech unit landing page w/info

Update colophon

We'll need to update our Colophon as a result of this migration.

Mock up quick posts format

For displaying short news that we're not going to ever get to writing a blog post about. E.g. "X is at Y conference this week", update from Will's interns (via Twitter).

Test out display as paragraph with new sentence per item?

Fix broken internal links

Internal links are using the wordpress formulation for slugs, which includes categories. Our slugs won't have that, so the links are breaking.

Podcasts

It looks like only a few podcasts were actually hosted on wordpress. Most are on itunes u I think? So I wonder if we even need to do much beyond find ways to store the three localones and update the links.

LInks to library and DH@UVa

Add links to these...somewhere.

Footer contact info

• physical address (note the address in our footer is incorrect. It should be P.O. Box 400109)
• CC license
  X sign up for email announcements (NOPE: this is now in homepage body content)
• our email
• our phone
  X our fax?? (NOPE: let folks email us if they need it, not listing in footer)
• slab logo
• uva library logo
• twitter
• facebook
• github

Genealogy of people and projects

Display a genealogy of people and projects. See MITH's Research Page for an example of filtering.

Authors who are not People

Wordpress differentiates between people and authors. I.e. - we have people who have written blog posts who do not have people accounts associated with them. Normally this is fine, but since we're starting to draw upon that information, it looks like we'll need to create people pages for anyone who has a blog post published. Otherwise we'll get things like:

"Kelli Shermeyer is nothing."

That's not really fare to Kelli. Another option would be to just hide that bit at the bottom of the posts page if the person doesn't have a person file associated with the author.

modify people so you get family name

Download assets

Photos, podcasts, etc.

Rakefile Documentation

Related to #54 - the documentation lists quotation marks to be used in some arguments where that actually causes the rakefile to fail. E.g.-

rake new_person["Sarah","Berkowitz"]

will fail due to quotation marks, but the documentation says that is the proper syntax.

Twitter feed

Somewhere, perhaps after MITH's style

Add research projects

Related to #35, let's update our list of research projects. Some things missing:

• Take Back the Archive
• August 12 Rally Archive

others?

Workflow to tweet after publishing a post

Update our address

The address in our footer is incorrect. It should be P.O. Box 400109.

Organize web files

Organize the website file folder so it's easier to find things (e.g. all static pages in one folder)

Bring over newer content

Since we migrated the content wholesale in July, some new things have been added. Here are the things we should manually bring over:

• Blog posts
• People (including adding bio blurbs, latest titles for former Praxis students who later got other SLab fellowships/roles)
• Events
• Research project
• DH Fellowship and Grad Opportunities pages, which have been restructured

Travis Integration

Look for shortcodes

Review yml frontmatter

Establish Events metadata

Relevant to previous #20 - we will need to establish the metadata that we need for the events before we can export them

GitHub commit feed on site?

Improve/reduce blog post categories & tags

I think we need to keep the first listed category for any blog post when we migrate them, because slab.org/category-name/post-title is the old URL structure. Beyond that, let's

1. discuss what categories/tags are useful for on the new site (if anything), and
2. document what possible tags/categories people can include on new posts (in #38)

Need to look at this page and maybe remove single-post tags

RDF/Metadata/OtherGoodies in page header

• Let's add more descriptive metadata—maybe even RDF—for each page and post.
• It might be cool to add Open Graph, Twitter Cards, and/or oEmbed to the site. This would, among other things, facilitate rich linking for services that use it, like Slack

Responsiveness

Menu items weren't responsive when i checked last night

Personal R&D info for all staff

2? pages: formal named projects, works in progress

• Explore "projects" page that focuses instead on relationships (nodes for people?)
• Discuss and decide on how handling formal vs. informal project pages (named projects? lab experiments? work in progress?) Note that "scholarship" and "research" apply to both pages equally and we don't want to create the impression they don't.
• Get personal R&D info for all staff
• Projects page info architecture, filter/sort
  project weight= prioritize, neutral, sink; OR Current: false or true
  collaborator (faculty, student, external, in-house only)
  add events to research loop
  Example: http://mith.umd.edu/research/
  Filter by:
  Collaborators: people
  Research category filter: Scholarly Collaborations, Internal Projects and Community Service
  Topics?
  Existing blog post categories & blog post tags

{% for project in site.research %}
  <a href="{{ site.url }}/research/{{ project.slug }}">{{ project.title }}</a>
{% endfor %}
{% assign sorted_tags = site.data.tags | sort:"sort" %}
<div class="blocks">
<ul>{% for tag in sorted_tags %}
	<li>{% include tag_link_formatter.html tag=tag %}</li> 
{% endfor %}</ul>
</div>

Project metadata:
cite this project
link to archival snapshot
list all collaborators (including work on related events, website plugin updating, everything) and link these to their staff pages if current staff
explain process as well as product—a lot of the work on our projects is kind of hidden otherwise

People Categories

From @jeremyboggs
yup, you lose history
we need to figure out a couple of things in the new system

1. What is the person right now
2. What has this person been in the past
   and manage/display that
   like, now, when i remove student-assistant from Christian, it means forever
   no difference between current and past
   but that’s a known timeframe—an academic year.
   probably need like a start date and an end date for each role
   basically, a mini CV for SLab-affiliated people.

Template for new posts

Show YAML options (e.g. categories and tags to choose from, how to format your author name, how to not break the site with colons in titles) and also include a few markdown pointers in the body of the template (how to format images with captions, how to link internally)

Submenus for all static pages

Highlight some stuff that is fairly static - Particularly re: Makerspace and Graduate Fellowship application information

Migrate People Data

There are a number of people/authors who have not been migrated to the new site yet - either authors who did not have people pages or new authors. Collecting remaining people data that need to move here.

• Tanner Greene
• Ankita Chakrabarti
• Victoria Clark
• Spyros Simotas
• Ryan Maguire
• Julia Haines
• Sarah Berkowitz
• Lauren Reynolds
• Ben Gorham
• Katherine Donnally
• Catherine Addington
• Brandon Phan
• Nic Dalton
• Andrew Carl
• Marysia Serafin
• Zoe LeBlanc
• Elizabeth Mitchell

Use Jekyll

Migrate WordPress content and templates to Jekyll.

Different layouts/templates or site locations by type of post

E.g. to encourage quick news posts, game reviews, etc.

If layouts aren't that different, maybe just use tags/categories instead to pull these into separate places on site?

Workflow for drafting blog posts

Since we'll have people writing on this, we want a way for them to be able to draft things that won't be actually posted live.

Rakefile Flexibility for Arguments

The rake commands that I wrote this summer are a bit rigid:

rake new_person[Sarah,Berkowitz]

is ok, but

rake new_person[Sarah, Berkowitz]

fails. These should probably be a bit more flexible if we're expecting people to use them. I'm tinkering with this as I work through the people branch.

More better home page

Let's do more than list the recent blog posts.

Document Publishing Workflow

Add documentation in README for how folks can contribute to the site.

Account for multiple authors

Update templates to allow for specifying multiple authors on blog posts. It should be easy enough to specify multiple authors in the post YAML, like so:

---
author:
  - sarah-berkowitz
  - james-ascher
---

Our templates for displaying post author(s) should change to account for this.

Controlled Vocabulary for Project Metadata

@rondauva had the good point that we should have controlled vocabularies for the metadata that are looser.
The collaborator's role category would be one. We can autogenerate the list of potential fields in the rake
task for new_project.

Make citation easy

Info on how to cite each blog post and project on appropriate page

Update text on accessibility page

After #217
Design and testing

Search

Add better ways to search/browse content on the site.

Update design to make Scholars' Lab's presence within the library more apparent.