Computational Literacies Lab

Editing the site

In the spirit of computational literacies, all members of the lab are invited to contribute to the lab site by adding profiles, news items, developing descriptions of projects you're working on, and even improving the site's layout and style. This documentation explains how to get started editing the site.

Setup

To contribute to the site, you need a few skills. If you don't know how to do any of these, ask Chris. They take some practice, but they're not too hard.

  • Writing in markdown, for editing the site's content.
  • Running commands in the terminal.
  • Managing source code with git
  • HTML and CSS, if you're planning to edit the site's templates or style.

Clone the site repo: https://github.com/cproctor/computationalliteracies. This is a private repository. If you don't have access, ask Chris.

Install Zola. Zola is a static site generator which assembles a site from source code. The basic idea of a static site generator is that you should be able to write the site content in markdown, and the generator will take care of all the fancy work of building the site's webpages.

In the terminal, navigate to the site directory within the repo and run zola serve. You should see:

Repos/computationalliteracies/site % zola serve
Building site...
Checking all internal links with anchors.
> Successfully checked 4 internal link(s) with anchors.
-> Creating 40 pages (0 orphan) and 51 sections
Done in 194ms.

Web server is available at http://127.0.0.1:1111

This terminal session is now running a web server. Open http://127.0.0.1:1111 in your web browser, and you'll see a locally-built version of the lab site. The server is also watching all the source code files, and will rebuild the local site every time you save changes to a file.

Now you can edit files in the project source code, and you'll immediately see their effect on the site.

Your first edit

A good first edit is adding your profile to the site. All the site content lives in the content directory. Look in content/people and you'll see directories for each member of the site.

Copy an existing folder, rename it with your name, and edit the files inside. Use the local build of the site to make sure things look the way you want them to.

When you finish, commit and push your changes.

Site Content

Profiles

Profile front matter should look like this:

+++
title = "Chris Proctor"
weight = 10

[taxonomies]
roles = ["PI"]

[extra]
image = "people/chris/chris.jpg"
+++
  • Weight defines the order in which profiles appear on the site. Your profile's weight should be based on the first role which matches you:
    • PI is a leader of the lab. Currently just Chris.
    • Affiliate is a faculty member who collaborates with lab members.
    • Postdoc is a postdoctoral scholar working in the lab.
    • GRA is a graduate research assistant, funded to work on a lab project.
    • Advisee is a student whose advisor is a PI in the lab.
    • Alum is someone who's not an active part of the lab anymore.
  • The roles taxonomy lists one or more of your roles in the lab.
  • Every profile should have an image, specifying the path to a picture of you. Pictures will be cropped to square.

Projects

A project is an ongoing research effort. Theming is provided for projects. Details:

  • Speecify extra.project_root = true in the base section for a project. Projects can be nested; the closest upstream section with extra.project_root will be active.
  • Specify an extra.hero url for an hero image in the project root. Pages and sections within the project will inherit this hero image for visual consistency. (Hero image inheritance is actually true for all pages and sections on the site, not just projects.)
  • A project will display a responsive nested menu of sections and pages within the project. Specify extra.hidden = true for pages or sections which should be built but not included in the menu.

Courses

Sometimes, when courses are aligned with lab research interests, it makes more sense to use this site as a course homepage than UBLearns. Possible benefits:

  • Easier maintenance and updates year-over-year
  • Ability to publicly post course events and projects
  • Ability to more gracefully arrange course materials

Theming is provided for hosting courses. A course should be considered as a special kind of project. It's probably easiest to look at the code for some existing courses, but here's an overview.

  • Like projects, courses should specify extra.project_root in the base section.

Slides

You can create slides using Markdown. Here's a demo explaining how slides work, and here are the slides from Chris's UB job talk, showing a full example of what's possible.