eecs485staff/primer-spec

A Jekyll theme for sites with content-heavy pages

primer-spec's Issues

Code blocks inside a callout are rendered incorrectly

Using markdown of the form:

<div class="primer-spec-callout warning" markdown="1">
...
```console
$ echo 'eval $(/opt/homebrew/bin/brew shellenv)' >> ~/.zprofile
```
</div>

The code block renders as:

(Discovered on EECS 280 Project 1.)

Highlight line in code block

It would be nice if it were possible for the spec to highlight a particular line (or lines) in a code block for emphasis.

Something similar to GitHub highlighting a line when you click the line number in a file.

This is tricky because the Jekyll default code formatter (Rouge) doesn’t support it, and neither do traditional markdown code blocks.

Persist sidebar-shown preference on large screens

If a user has hidden the sidebar, we should keep it hidden when the page reloads. And vice-versa.

Question: Should we persist across the site (like subthemes) or only for the page?

Let’s persist this preference just for the page.

[Feature] Make sidebar resizable

On large desktop/laptop screens, there may be a lot of unused space on the right of the page. Users may want to customize the size of the sidebar to make it easier to read the sidebar contents.

Copy code block

Imagine the following code block:

$ ./insta485generator run
Error: Not implemented!

Wouldn’t it be cool if students could copy the command by clicking a copy button next to the code block?

Some initial thoughts on implementation complexity:

• With console blocks, there should be a way to copy just the command, not the output.
• There should be a way to specify if the entire block should be copyable (like a block of code), or if individual lines should be copyable (like console blocks), or if copying should be disabled.

Cannot scroll to heading with label "Contents"

Describe the bug
When a page contains a heading titled "Contents", AnchorJS gives it HTML id="contents". However, this conflicts with the Sidebar's "Contents" header with the same ID — as a result, using the internal link https://<page-url>#contents does not cause the page to scroll to the correct place. (In fact, this can be seen on the demo page for Primer Spec itself.)

To Reproduce
Steps to reproduce the behavior:

1. Go to the Primer Spec demo page: https://eecs485staff.github.io/primer-spec/
2. Click on 'Contents' in the Sidebar.

Page does not scroll.

Expected behavior
Page should scroll to the "Contents" section in the main content.

Spec doesn't print properly

Describe the bug
When I do a print preview or try to export a PDF, the text looks jumbled after the first couple of pages.

To Reproduce
Steps to reproduce the behavior:

1. Open a spec
2. On Chrome, click the three dots in the upper right corner of browser.
3. Click "Print"
4. View pages of spec

Expected behavior
I expect the pdf to have text like it appears on the screen.

Screenshots

Desktop (please complete the following information):

• OS: MacOS
• Browser Chrome
• Version 79

Additional context

Change default branch to master

With the changes in benbalter/jekyll-remote-theme#87, Jekyll Remote Theme will use the default repo branch if a ref is not specified in _config.yml. This won't break Primer Spec rendering, but it means that Primer Spec users will be building off of the develop branch instead of master by default!

(Note that the new version of Jekyll Remote Theme hasn't been released yet, but when it is adopted by GitHub Pages, this new behavior will kick in.)

To maintain the current process where master is only updated once every few months, we should either:

1. Make master the default branch for this repo
2. Update the setup instructions so that all users specify using the master ref instead of providing no ref.

I'm leaning towards option 2. However, that requires communicating with every existing user of Primer Spec to update their _config.yml file...

Spec change notification

As a student, I remember being extremely annoyed about how specs could change in the middle of a project. Many times, changelogs weren't posted on the spec itself, and were only posted on Piazza (where notes tend to be lost in the noise).

It would be nice if Primer Spec could determine if the page's content has changed since the last time the browser viewed the page. When a change is detected, maybe add some alert in the Topbar (next to the Settings icon), and provide an option to view changes since the last page visit.

I'm not entirely sure about the best way to implement this. Here are my current thoughts:

• Store the page content in local storage. (Need to test performance with large strings similar to an actual EECS project.)
• When the page loads, compare the content string with the locally stored string to determine if content has changed.
• If content has changed, alert the user. Perhaps add an "Alert" icon to the Topbar.
• Offer option to display changes. This would display a side-by-side or inline HTML diff view. This is probably the trickiest aspect of this feature. Perhaps we could take inspiration from: https://github.com/adamarthurryan/dubdiff
• Offer users the option to disable spec-change notifications in the Settings.

Image src with relative path in site preview

Describe the bug
The site preview hosted at https://preview.seshrs.ml/previews/ seems to rewrite relative img src paths as absolution paths. Here's an example:

To Reproduce
Steps to reproduce the behavior:

1. Make a subdirectory, e.g. /docs/w21/
2. Add an image /docs/w21/img/logo.png
3. Add HTML image with a relative src to /docs/w21/index.html, e.g. <img src="img/logo.png">
4. Create PR
5. View the site preview
6. Observe 404 in the console in response to a GET request to the wrong path, e.g., https://preview.seshrs.ml/previews/eecs280staff/eecs280.org/168/img/logo.png

Expected behavior
Actual path: https://preview.seshrs.ml/previews/eecs280staff/eecs280.org/<PR>/img/logo.png

Expected path: https://preview.seshrs.ml/previews/eecs280staff/eecs280.org/<PR>/w21/img/logo.png

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: macOS
• Browser: Firefox
• Version 83

Additional context
Local preview via bundle exec jekyll serve works as expected.

Syntax highlights for console block with multline output

Describe the bug
A console block with a command that produces multiple lines of output should color the output differently from the command. It looks like only the first line of output is recognized as output.

To Reproduce
This is a console block

$ pgrep -lf mapreduce-  # macOS
77760 /usr/local/Cellar/python/3.7.2_1/Frameworks/Python.framework/Versions/3.7/Resources/Python.app/Contents/MacOS/Python /Users/awdeorio/src/eecs485/p4-mapreduce/env/bin/mapreduce-manager 6000 5999
77811 /usr/local/Cellar/python/3.7.2_1/Frameworks/Python.framework/Versions/3.7/Resources/Python.app/Contents/MacOS/Python /Users/awdeorio/src/eecs485/p4-mapreduce/env/bin/mapreduce-worker 6001 6000 5999
77893 /usr/local/Cellar/python/3.7.2_1/Frameworks/Python.framework/Versions/3.7/Resources/Python.app/Contents/MacOS/Python /Users/awdeorio/src/eecs485/p4-mapreduce/env/bin/mapreduce-worker 6002 6000 5999

Expected behavior
All lines of output should appear grey, just like the first line.

Screenshots
Here's an example from EECS 485 P4 https://eecs485staff.github.io/p4-mapreduce/example.html#start-manager

Desktop (please complete the following information):

• OS: [e.g. iOS] macOS
• Browser [e.g. chrome, safari] Brave
• Version [e.g. 22] 98 or something

Additional context
Add any other context about the problem here.

Clicking section in ToC does not close Sidebar on mobile

Describe the bug
On mobile devices, clicking a section link in the Table of Contents does not close the Sidebar if I clicked the section before.

To Reproduce
Steps to reproduce the behavior:

1. Open any Primer Spec v1.3.0 page on mobile.
2. Open the Sidebar, click some section in the ToC. The page scrolls to that section and the Sidebar closes.
3. Scroll to some other section.
4. Open the Sidebar, click the same section from step 2. The page scrolls to the section, but the Sidebar remains open.

Expected behavior
Sidebar should close after scrolling to section.Z

Additional context
This issue was found while reviewing #63. The issue is that the TableOfContents listens to hashchange events. So if the user clicks the same sidebar item consecutively, subsequent clicks do not trigger this event.

primer-spec/src_js/components/sidebar/TableOfContents.tsx

Lines 33 to 42 in e103411

	const hash_listener = () => {
	if (props.isSmallScreen && props.sidebarShown) {
	props.onToggleSidebar();
	}
	if (props.settingsShown) {
	props.onToggleSettings();
	}
	};
	window.addEventListener('hashchange', hash_listener, false);

I'm not sure what the best way to fix this would be. Perhaps we need a custom click handler?

Issue with Primer Spec PR Previews

I'm having some issues in the EECS 370 repo with the Build and upload website preview, the issue seems to be with the
nokogiri-1.12.5-x86_64-linux package. Any ideas on how to get this feature working again?

raw text:
bundle install /opt/hostedtoolcache/Ruby/3.1.0/x64/bin/bundle config set deployment true /opt/hostedtoolcache/Ruby/3.1.0/x64/bin/bundle config path /home/runner/work/project_1_spec/project_1_spec/vendor/bundle /opt/hostedtoolcache/Ruby/3.1.0/x64/bin/bundle install --jobs=4 --retry=3 --gemfile=/home/runner/work/project_1_spec/project_1_spec/Gemfile Fetching gem metadata from https://rubygems.org/......... nokogiri-1.12.5-x86_64-linux requires ruby version < 3.1.dev, >= 2.5, which is incompatible with the current version, ruby 3.1.0p0 Error: Gemfile.lock probably needs updating. Run "bundle install" locally and commit changes. Exiting action Error: The process '/opt/hostedtoolcache/Ruby/3.1.0/x64/bin/bundle' failed with exit code 5 Took 3.74 seconds

[Enhancement] Use Theme Inheritance

The Primer Spec theme adds a new layout (and related content) to the original pages-themes/primer. Currently, the only way to keep up with changes from the upstream theme is to monitor the theme and to regularly merge changes from that repository.

With theme inheritance, we would simply have to monitor major releases of the original Primer theme, and even then, we would simply have to bump the version of the "parent theme" that we're using.

This will be possible once the features described in jekyll/jekyll#7344 (with PR jekyll/jekyll#7554) and benbalter/jekyll-remote-theme#35 are implemented.

Rename 'master' branch to 'main'

To follow the pattern of EECS 485 repos (and the broader movement across GitHub), let’s rename the master branch to main.

• Verify Jekyll Remote Theme support
  • Supported in v0.4.3. This version is also used by GitHub Pages.
• Freeze and release existing develop branch.
• Update GitHub Actions references to master branch.
• Also check other repo’s preview workflows.
  • Verified EECS 280, EECS 485
• Update README and other references in docs.
• Create new main branch on top of existing master branch.
• Make main the default branch (with master as shadow.
• Email course staff for all known users, ensure that their _config.yml files are updated to not specify master ref.
• Delete master branch. Bump major version.
• Remove temporary code in workflows and scripts that kept master synced with main.

Emoji Mismatch

Describe the bug
The :white_check_mark: emoji appears to differ from the GitHub version.

To Reproduce
Render a Markdown doc containing the :white_check_mark: ✅ emoji.

Expected behavior

Screenshots
From https://eecs280staff.github.io/p1-stats/setup.html#visual-debugger

Desktop (please complete the following information):

• OS: macOS
• Browser: Frefox
• Version: 84

Code block observes GitHub repo

Is your feature request related to a problem? Please describe.
Spec and code get out of synch.

Describe the solution you'd like
When code on main branch of a GitHub repo is updated, corresponding code in spec automatically updates. This would mean beyond simply linking to GitHub code as is done in Trello card, but to track commit/push history to link to the correct code as it moves around after updates.

Describe alternatives you've considered
Manual updates.

Additional context
I think one of the faculty candidate from UCBerkeley had a similar feature built into the equivalent of an IDE.

GitHub Markdown compatibility

Primer-spec doesn’t recognize ‘\’ as line-break marker, as GitHub Markdown does, requiring use of double spaces instead.

Unlink fork from Primer?

Primer Spec has diverged sufficiently enough from the original GitHub Pages Primer theme that I think it no longer makes sense to remain a “fork” of the original theme. The original theme is also very sparsely maintained — even its style dependencies aren’t up to date with the latest @primer/css releases.

Unlinking the fork could also help with discoverability, indicating that this repository is open to contributions from the public without the intention to merge back to the original Primer theme.

CC @awdeorio. I’ll email GitHub to unlink the fork in a couple of weeks, let me know if you have concerns about this. Thanks!

xcode Dark mode on sidebar as well

Would be nice and less contrasting if the dark mode also applied to the left side bar.

Regression tests

Currently, we have no test coverage of our custom code in Primer Spec. It would be nice to add visual regression tests (like BackstopJS) and/or functional regression tests.

Print preview is garbled on Chrome

Describe the bug
As described by a student on EECS 485 Piazza @512: On Chrome 79 on MacOS Catalina, specs that contain any emphasized or italicized text print with garbled text. For example, the Primer Spec demo page prints as follows:

Desktop (please complete the following information):

• OS: MacOS Catalina
• Browser: Chrome
• Version: 79.0.3945.88

Additional context
This is a Chromium bug (https://bugs.chromium.org/p/chromium/issues/detail?id=1018581), and the fix became available in Chrome Canary on Jan. 22, 2020 (version 81.0.4036.0). The fix will take a few months to reach stable Chrome.

Google Analytics support needs to be upgraded

Describe the bug

Primer-spec supports for google analytics still relies on Google's analytics.js script whereas Google has switched to gtag.js

https://developers.google.com/analytics/devguides/collection/upgrade/analyticsjs

Additional context

This page documents gtag.js:

https://developers.google.com/analytics/devguides/collection/gtagjs/

console copy to clipboard skip console prompts?

Is your feature request related to a problem? Please describe.
When clicking on copy to clipboard on a (multi-line) console code block, the console prompts are also copied.

Describe the solution you'd like
Would be nice if copy to clipboard on a (multi-line) console code block behaves similarly to per-line copy, i.e., the console prompt is not copied. It is not immediately obvious that one can click on the line number to copy a line.

data-highlight not working?

Describe the bug
The data-highlight demo on the GitHub Enhanced Code Block page doesn't display any highlights.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://github.com/eecs485staff/primer-spec/blob/develop/demo/enhanced-code-blocks.md#highlighted-lines
2. See no highlighting in the sonnet block.

Expected behavior
The second quatrain of the sonnet to be highlighted, along with the first line of the volta.

Screenshots

Desktop (please complete the following information):

• OS: macOS Monterey 12.3.1
• Browser: tried Safari, Chrome, and Firefox
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

Enhanced code block option to disable line numbers

Is your feature request related to a problem? Please describe.

In rare cases, the line numbers on enhanced code blocks can be confusing. From the EECS 485 P5 spec, there's an example where the output of a code block is a number, which is easily confused with the line number.

Describe the solution you'd like

An option to disable line numbers on an enhanced code block would be nice.

Describe alternatives you've considered

I used {: data-variant="legacy" }, but the downside is an inconsistent look and feel next to the other code blocks.

Broken URL in Preview

Describe the bug
Links from a preview to another page that is part of the same preview appear to be broken.

To Reproduce

1. Navigate to the preview for this PR
2. Using the sidebar, navigate to the "Mega Setup Tutorial"
3. Scroll down and find an internal link to another page within the same preview, say, the "Visual debugger" section. If you click the link of "VS Code Tutorial", the href is https://preview.seshrs.ml/setup_vscode.html

Expected behavior
I think https://preview.seshrs.ml/setup_vscode.html should be https://preview.seshrs.ml/previews/eecs280staff/p1-stats/199/setup_vscode.html

Additional context
Add any other context about the problem here.

Build fails with Ruby 3.0.0

Describe the bug
Local rendering fails with Ruby 3.0.0. The latest Ruby package available via Homebrew is 3.0.0.

To work around this issue, use Ruby 2.X. For example, on MacOS:

$ brew install [email protected]
$ export PATH="/usr/local/opt/[email protected]/bin:$PATH"
$ which ruby
/usr/local/opt/[email protected]/bin/ruby
$ which gem
/usr/local/opt/[email protected]/bin/gem
$ ruby --version
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-darwin19]
$ gem --version
3.1.4

To Reproduce
Install Ruby 3.0.0. These are the steps for MacOS.

$ brew update
$ brew upgrade ruby
$ export PATH="/usr/local/opt/ruby/bin:$PATH"
$ which ruby
/usr/local/opt/ruby/bin/ruby
$ ruby --version
ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin19]
$ which gem
/usr/local/opt/ruby/bin/gem
$ gem --version
3.2.3

Render the Primer Spec docs.

$ pwd
/Users/awdeorio/src/eecs485/primer-spec
$ rm -f Gemfile.lock
$ gem install bundler
$ bundle install
Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/.
Resolving dependencies...
Bundler found conflicting requirements for the Ruby version:
  In Gemfile:
    Ruby x86_64-darwin-19

jekyll-theme-primer-spec x86_64-darwin-19 was resolved to 0.1.0, which
depends on
      Ruby (~> 2.4)

Ruby (~> 2.4), which is required by gem 'jekyll-theme-primer-spec', is not
available in the local ruby installation

Expected behavior
Works fine with Ruby 2.7.

Install Ruby 2.7 on MacOS

$ brew install [email protected]
$ export PATH="/usr/local/opt/[email protected]/bin:$PATH"
$ which ruby
/usr/local/opt/[email protected]/bin/ruby
$ ruby --version
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-darwin19]
$ which gem
/usr/local/opt/[email protected]/bin/gem
$ gem --version
3.1.4

Render the Primer Spec docs.

$ pwd
/Users/awdeorio/src/eecs485/primer-spec
$ rm -f Gemfile.lock
$ gem install bundler
$ bundle install
$ bundle exec jekyll serve
...
Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.

Desktop (please complete the following information):

• OS: MacOS Catalina 10.15.7
• Browser N/A
• Version N/A

Allow defining light/dark mode variants of images like GitHub

GitHub already supports showing different images depending on whether the page is displayed in light-mode or dark-mode: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#specifying-the-theme-an-image-is-shown-to

Primer Spec should add support for this behavior too.

Sidebar has scrollbars for headings with code fomatting

Describe the bug
If there are headings that include code formatting, those headings are shown with individual vertical scrollbars in the sidebar

To Reproduce
Steps to reproduce the behavior:

1. Go to https://eecs485staff.github.io/p2-insta485-serverside/
2. Observe that there are scrollbars in the sidebar

Expected behavior
There are no scrollbars for individual headings in the sidebar.

Screenshots

Desktop (please complete the following information):

• OS: Windows 10
• Chrome
• Version 87.0.4280.88

no-line-numbers doesn't work if useLegacyCodeBlocks is true?

Describe the bug
I have a site wide userLegacyCodeBlock: true
On my page, I have:

server$ sudo apt update
server$ sudo apt install python3-pip python3-dev python3-venv libpq-dev postgresql postgresql-contrib nginx curl
server$ sudo ln -s /usr/bin/python3 /usr/bin/python

{: data-variant="no-line-numbers" data-highlight="3" }

Data highlight shows up but the code block still shows up with line numbers.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://eecs441.eecs.umich.edu/asns/lab0-chatter-backend#installing-packages
2. Scroll down to first code block
3. See error: code block shows up with line numbers

Expected behavior
Code block doesn't have line numbers

Screenshots

Desktop (please complete the following information):

• OS: macOS Monterey 12.3.1
• Browser: Safari
• Version: 15.4

Image/video enhancements

Some enhancements that I've been thinking about:

• Automatically center-align images and videos to the page
  • Is this a good thing though? GitHub images aren't auto-centered by default...
• Allow adding captions and permalinks to images and videos
• Make it easy to embed videos, maybe by auto-enriching a video URL
• Auto-enhance video tags / embeds to be "responsive", similar to what https://embedresponsively.com/ does.

Extra space on top when printing on mobile

Describe the bug
When printing a spec on mobile, extra space is visible at the top. (This is likely because of the extra margin to accommodate the topbar on small browsers.)

To Reproduce
Steps to reproduce the behavior:

1. Visit a spec (say, https://eecs485staff.github.io/primer-spec/) on a mobile browser like Safari on iOS.
2. Generate a print preview by attempting to print the page.

Expected behavior
Content should begin at the top of the page in the preview.

Screenshots
Notice the extra space at the top of the preview:

Compared to this spec that is generated without Primer Spec:

Desktop (please complete the following information):

• OS: iOS
• Browser: Safari
• Version: iOS 13.3

Additional context
The potential solution will involve either adding CSS styles to prevent the margin from being printed, or to modify the JS print handlers in NodeManager.ts to toggle the margin before printing.

[Feature] Scroll sidebar when scrolling page

When a user scrolls to a section whose sidebar item is not in view, the sidebar should scroll to make the item visible.

I think the sidebar should scroll so the active section is in the middle of the sidebar view, so that if the user scrolls to the previous or next section, no additional sidebar scrolling is required.

Edit: After some further thought, I wonder if this should be a choice that students can opt-in/out of from the settings view. Suggestions and opinions are welcome 😃

Broken URL History

Clicking an internal link in the sidebar does not update the URL bar and the window history as expected. This is because the custom scrolling code prevents default browser behavior:

primer-spec/_layouts/spec.html

Lines 206 to 224 in 859f9fd

	// When an internal link in the sidebar is clicked,
	// execute custom code.
	$('.primer-spec-toc-item > a').on('click', function() {
	var $scroll_target = $($(this).attr('href'));
	var scroll_position = $scroll_target.offset().top
	- internal_link_offset;
	// Scroll to the scroll_position.
	$(window).scrollTop(scroll_position);
	// If the settings pane is open, close it.
	if (settings_is_shown) {
	toggleSettings();
	}
	// On mobile, close the sidebar and settings.
	if (isSmallScreen()) {
	toggleSidebar();
	}
	return false;
	});

Update the custom code to also update the window history.

[Mobile] AnchorJS link does not jump correctly in Safari

On Safari in iOS 12.4.1 on an iPhone X, clicking an AnchorJS link next to a heading jumps underneath the section (the section is hidden by the top bar).

The fix is probably to use the existing hyperlink click handler to also listen to AnchorJS link click events.

Printing: Dark theme interferes with print quality

When printing a spec with the dark theme selected, the print preview shows light text on a dark background. This will not print well.

The fix should be that before printing, the theme should be toggled to the “default” theme. After the print preview has been generated, revert to the user-selected theme.

Inline code in tables have borders in dark mode

For instance, with this Markdown:

| `b main` | breakpoint on main function |
| `b 29` | breakpoint on line 29 of current file |
...

This is the result. Notice the borders around each code span (it shouldn't have a border):

Improved theme example

The current example web page is very simplistic and does not showcase the power of the theme. We should update it to look like an actual spec. This will help us test changes to the theme better, and may also help with promoting the theme externally.

triple click for one-line console copy ex console prompt

Is your feature request related to a problem? Please describe.
It's not obvious that clicking the line number copies a line on the console block. Plus if we choose the no-line-numbers variant, there's no line numbers to click.

Describe the solution you'd like
If you can detect triple click on the line, perhaps you can make a triple-click on a line to select the whole line without the console prompt.

If one wants to select the whole line with the console prompt, one can do drag to select or shift-triple-click or something else.

Describe alternatives you've considered
One could drag to select whole line without the console prompt, but it's easier to drag to select whole line than to start/stop at the console prompt, especially for those with accessibility issues.

Support Mermaid for Diagramming

GitHub now supports embedding Mermaid diagrams. (Source)

Primer Spec should support them too! (The integration doesn't look too complex 😄 )

Here's an example Mermaid diagram:

  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;

[RFC] Download as PDF

Motivation

One of Primer Spec's features is that print-previews are beautifully-formatted, so students can use their browsers' "Print to PDF" functionality to save copies of a spec for offline access.

However, I think I've seen Piazza questions from students asking the same question. I think many students may not be familiar with their browsers' "Print to PDF" capability, or maybe they assume that the spec won't look good when printed.

Ideally, Primer Spec should show some UI to let students know that they can save specs as a PDF. But how do we do it?

Options I considered

Option 1: Educate students about "Print to PDF"

Pros:

• "Easiest" to implement

Cons:

• This is hard to get right. Where would we show this UI in a way that is both useful and discoverable? Also we'd have to write concise instructions for all major browsers, or link to external websites that show students how to do it.
• In other words, I think this loads too much "unnecessary" cognitive overhead on students who are just looking for a way to download the spec.

Option 2: Generate the PDF from JavaScript

I explored multiple JS --> PDF options over the past few weeks. Click here for details.

• Browsers don't have a way to let website programmatically generate a PDF (unfortunately 😞).
• jsPDF produces a nice-looking PDF from HTML, but has bugs related to page margins. Also the text isn't selectable.
• PDFKit is a bit harder to use, and can only generate PDFs from scratch. Similarly PDFMake on its own is good at generating new PDFs, not converting HTML to PDF. Other libraries have similar constraints.
• I considered compiling existing libraries like wkhtmltopdf and WeasyPrint to WASM. But all of these libraries have external and OS dependencies to generate PDFs — this makes compiling to WASM hard!

It seems like the most appropriate implementation here is to use PDFMake in conjunction with html-to-pdfmake.

Pros:

• Text is selectable.
• Any Primer Spec page will be able to generate a PDF version of the page contents.

Cons:

• The generated PDF looks plain, and looks very different from the Primer Spec page. Some styling and customization is possible, but it's quite limited.

Example page generate by Option 2

Option 3: GitHub Actions generates PDF using headless Chrome

Click here for details on how it would work.

• Create a new GitHub Actions workflow. It should run on pushes to the `main` branch of the website repositories. The action performs the following steps:
  • Delete then create a `/pdf` directory.
  • Start Jekyll server with website files.
  • For each HTML file:
  • Query its content, compute a hash: CONTENT_HASH
  • Compute a hash from the relative path: PATH_HASH
  • Use headless Chrome to generate a PDF and store at filepath pdfs/_.pdf
• In the Primer Spec JS code:
  • Config option needs to be set to opt-in to looking for PDF files.
  • After page loads, use original HTML source to compute CONTENT_HASH. Also compute PATH_HASH.
  • Make HEAD request to pdfs/_.pdf. If the file exists, show a "download" button in the UI.

Pros:

• PDF quality is equivalent to printing the page. Text is selectable, the pages look beautiful.
• This basically builds the system needed for #92 to work!

Cons:

• Each repo that wants to make downloadable PDFs available to students needs to opt-in and add the GitHub action.

Option 4: Create an HTML --> PDF server

Like Prince. But the server could literally use Chrome to render the PDF and return it.

We'd probably need to create a system that prevents spamming the server.

Pros:

• PDF quality equivalent to option 3.
• Any Primer Spec repo can use it with a bit of effort.

Cons:

• Someone needs to pay for the server 😞
• We have to figure out how to prevent spam/abuse.

---

My opinion: I like Option 3 (GitHub Actions)

Personally, I prefer Option 3 (GitHub Actions workflow generates PDF). I like it best because of the high-quality PDFs, but I'm not super-happy that course websites need to integrate using GitHub Actions.

Option 2 (generate a bespoke PDF) is also good, but will involve much more work in figuring out how to make a nice-looking PDF. Also, the resulting PDF will never look like a Primer Spec page (but maybe that's a good thing...?)

I don't like Option 1 (UI to educate users) 😆
Option 4 (HTML --> PDF server) involves spam/abuse challenges, and there's a financial cost too.

NOTE: We also need to think about stale PDFs — what if the spec changes after a student has downloaded the PDF? It should be possible for a student to compare their PDF with the contents on a course's website. Essentially, this would be a combination of #92 and including the download-date in the PDF. (This is another reason I like Option 3, it builds the system needed for #92 to work.)

Request for Comments

Comments and suggestions are appreciated! Next week, I'll begin implementing Option 3 if there are no differing opinions.

Keyboard text is not optimized for dark mode

Describe the bug
<kbd> elements look great in light mode, but the colors need to be optimized for dark mode.

Screenshots
From a recent EECS 485 PR (notice how the light-colored keyboard text looks out-of-place on the page):

Thanks to @japplefield for using the <kbd> tags, that's how I noticed!

Code blocks with same title have the same anchor ID

When two enhanced code blocks have the same data-title, they are referenced by anchors with the same ID. Hence, clicking one of the anchors may make the page jump to the other code block!

Plugin for sites not using Jekyll

Tl;dr: I want to add a custom JavaScript "plugin" that can easily add Primer Spec to HTML websites without having to use Jekyll. Where should such a script live?

---

The long version of the context:

Dr. Kapritsos expressed interest in using Primer Spec with EECS 482 specs. However, their setup involves hosting plain HTML files on a private web server accessible only to students enrolled in the course.
I wrote a quick "plugin" script that adds the scaffolding that Jekyll would have otherwise provided. To demonstrate, I uploaded the Primer Spec theme files in a demo GitHub repo (and also uploaded the plugin code), and then created two test pages plain.html and spec.html. The two pages are identical except that the plugin is added as a script tag at the end of spec.html.

Where should this plugin live? Here are two options I thought of:

Option 1

Add custom plugin as an integration option built into Primer Spec.

Pros:

• Plugin code would live in this repo and would share code with the Jekyll theme (so they would always be in sync).
• Our current Jekyll theme can be modified to completely use the custom plugin. This could slightly reduce complexity introduced by Jekyll. This would also cause the Jekyll layout spec.html to look more similar to the upstream (GitHub's original Primer theme), possibly making maintenance easier.

Cons:

• Added complexity. There will be more moving pieces.
• We would have to generate two JavaScript targets.

Option 2

Custom plugin is maintained in a separate repository.

Pros:

• Separation of concerns. This repo would be dedicated as a Jekyll Theme.
• The plugin (which would not be used by EECS 485) would not necessarily have to be maintained by eecs485staff.

Cons:

• Additional maintenance work might be needed to keep the external plugin up-to-date with the Jekyll theme.
• Concerns about who controls and maintains the custom plugin...?

---

I initially started writing the plugin with option (1) in mind, but I'm beginning to lean towards option (2). @awdeorio what do you think? And who should own the plugin code?

Mobile: Tapping outside sidebar should close it

The sidebar can currently only be closed by the toggle buttons. This isn’t a great experience on mobile because (1) most users would expect to close it by tapping outside the sidebar, and (2) the toggle button is at the top of the sidebar, which means users may sometimes have to scroll in the sidebar to get to it.

Jekyll site does not build if not GitHub repo

While going through the setup instructions with @oliverdmiles, we encountered an issue where the Jekyll site would not build if the directory was not a GitHub repository.

@oliverdmiles also discovered the fix, which I believe involved updating the Gemfile with some additional dependencies. The Usage instructions need to be updated to address this issue.

Theme name discrepancy: modern vs. metro

The subtheme files (in CSS/SCSS) are all named metro, but the public name defined in _layouts/spec.html is modern. We should resolve this name discrepancy, especially if we choose to auto-generate some of the subtheme code scaffolding in future.

Let's consistently call the subtheme as modern because that is the name users are now acquainted with.

[Feature] Ability to set default style for site

Set default render style between default/bella/modern/xcode-dark

:D

Headers with inline italics don't show up properly in the TOC.

Describe the bug
There was a top-level header (single #) that had italics, and everything from the beginning of the italics to the end of the line was removed from the link in the Table of Contents.

To Reproduce
Include the following in a markdown file and build with the primer-spec:

# This is my _"Title"_

Expected behavior
Item renders well in the document body, but the TOC in the sidebar should include "Title" (preferably italicized).