Primer Spec theme

[seshrs]

Context

Hello! 👋 I build and maintain the Primer Spec Jekyll theme, which is used by several courses at the University of Michigan. (Check out the showcase!)

I came across your course's website, and I felt like Primer Spec would be a great fit! (Before I built Primer Spec, UMich's courses also used the same Primer theme that your website uses 🙂)

Primer Spec adds a lot of features to your pages:

• Automatically generate a sidebar with a table of contents. (Very helpful for students reading long pages!)
• Built-in support for dark mode, mobile browsers and printing.
• Code blocks are "enhanced" by default. You can even highlight specific lines of code!
• Use Callouts to highlight important information.
• And much more!

This PR integrates Primer Spec with your website. I did make a few minor changes to each page (formatting, syntax-highlighting, callouts, etc.). (I even added support for footnotes and abbreviations when I realized that they were missing from Primer Spec!)

Let me know if you have questions about the theme. I'm happy to help work to address any concerns :)

Validation

I built the site locally and uploaded it to: https://preview.sesh.rs/previews/seshrs/isdt/

For instance:

• Lecture 1: https://preview.sesh.rs/previews/seshrs/isdt/lecture-notes/1-cli/
• Lecture 2: https://preview.sesh.rs/previews/seshrs/isdt/lecture-notes/2-vcs/
• Lecture 3: https://preview.sesh.rs/previews/seshrs/isdt/lecture-notes/3-bld/
• Lecture 4: https://preview.sesh.rs/previews/seshrs/isdt/lecture-notes/4-cor/
• Assignment 1: https://preview.sesh.rs/previews/seshrs/isdt/assignments/01-cli-investigative/

[tchebb]

It looks a bit jarring to have these headings be the same size as the page title above. I assume you changed this to make the sidebar look better, but would it be possible to have separate styling for the page title now that these are H1s?

[seshrs]

I understand the concern — my reasoning is that only the top of the page is affected, and students will spend very little time looking at that.

If this is a blocking concern, then here are two options we can consider:

1. Keep the changed header levels but add a custom style to make the headings look different. I don't prefer this option for the same reason that I pushed back on CSS customizations in Primer Spec theme #22 (comment). We can add a page-specific style just to make the title of the page look bigger than a typical <h1>, or we would need to add some global CSS customization.
2. Revert the header levels, and update Primer Spec to show the left-border to group top-level H2 items. I'll need some time to figure out how to achieve it in an aesthetic manner.

[tekknolagi]

Hi Sesh,

Thank you for the contribution! We like the look of the theme and would definitely be willing to integrate into the site. We are currently working on the course material and don't have time to review this PR in detail just yet. We will do our best to get to it before we teach the course again.

A couple of questions:

• How do we add CSS customizations on top of your theme -- for example, our old kbd styles and darker footnotes?
• Why did you specifically call out the default Jekyll gem set in the Gemfile?

Cheers,
Max & Tom

[tchebb]

Can you pin this to a tag or branch in your repository? Right now it tracks a moving target and might cause our site to change unexpectedly without any explicit action from us.

[seshrs]

Great question! Primer Spec uses Semantic versioning, and I usually only release minor version bumps between semesters at the University of Michigan.

Option 1: It seems like the Tufts semester schedule is somewhat similar to that of UMich. If you'd like, I can ensure that I do not make version bumps in the middle of a Tufts semester.

Option 2: You can pin to a specific minor version of Primer Spec. You will always receive automatic patch version updates (usually minor changes to JS, or very minor CSS fixes).

[seshrs]

Hi Max & Tom, thanks for your comments!

We are currently working on the course material and don't have time to review this PR in detail just yet.

I totally understand :)

How do we add CSS customizations on top of your theme -- for example, our old kbd styles and darker footnotes?

While there are options to customize the CSS, I'd like to try pushing back. Primer Spec (and the original Primer theme, for that matter) use GitHub's design system for colors and other style choices. Primer Spec's styles closely match those of GitHub, and are optimized to change subtly between the light and dark themes.

That said, if your CSS opinions are strongly held, I'll need to make a couple of changes on the Primer Spec side to allow you to make those customizations globally.

You can always make page-specific customizations by adding a <style> block on the page 🙂 (For example, see the page-specific <style> that I added to the course home page.)

Why did you specifically call out the default Jekyll gem set in the Gemfile?

My bad! I just found out that the github-pages gem actually includes most of the required gems as dependencies. I've cleaned them up in 75483e2. (I'll likely need to update the Primer Spec docs with this information.)