eecs485staff / primer-spec Goto Github PK
View Code? Open in Web Editor NEWA Jekyll theme for sites with content-heavy pages
Home Page: https://eecs485staff.github.io/primer-spec/
License: MIT License
A Jekyll theme for sites with content-heavy pages
Home Page: https://eecs485staff.github.io/primer-spec/
License: MIT License
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.
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.
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:
Page does not scroll.
Expected behavior
Page should scroll to the "Contents" section in the main content.
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.
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.
Primer-spec doesn’t recognize ‘\’ as line-break marker, as GitHub Markdown does, requiring use of double spaces instead.
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.
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!
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:
Expected behavior
There are no scrollbars for individual headings in the sidebar.
Desktop (please complete the following information):
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:
/docs/w21/
/docs/w21/img/logo.png
/docs/w21/index.html
, e.g. <img src="img/logo.png">
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):
Additional context
Local preview via bundle exec jekyll serve
works as expected.
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.
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:
master
the default branch for this repomaster
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...
Some enhancements that I've been thinking about:
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:
Expected behavior
I expect the pdf to have text like it appears on the screen.
Desktop (please complete the following information):
Additional context
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:
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:
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
I'm not sure what the best way to fix this would be. Perhaps we need a custom click handler?
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:
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.
Describe the bug
Links from a preview to another page that is part of the same preview appear to be broken.
To Reproduce
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.
Set default render style between default/bella/modern/xcode-dark
:D
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!
To follow the pattern of EECS 485 repos (and the broader movement across GitHub), let’s rename the master
branch to main
.
develop
branch.master
branch.main
branch on top of existing master
branch.main
the default branch (with master
as shadow._config.yml
files are updated to not specify master
ref.master
branch. Bump major version.master
synced with main
.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.
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):
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.
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
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.
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.
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!
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 😃
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.
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:
Expected behavior
The second quatrain of the sonnet to be highlighted, along with the first line of the volta.
Desktop (please complete the following information):
Additional context
Add any other context about the problem here.
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
Update the custom code to also update the window history.
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.
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?
Pros:
Cons:
It seems like the most appropriate implementation here is to use PDFMake in conjunction with html-to-pdfmake.
Pros:
Cons:
CONTENT_HASH
PATH_HASH
pdfs/_.pdf
CONTENT_HASH
. Also compute PATH_HASH
.pdfs/_.pdf
. If the file exists, show a "download" button in the UI.Pros:
Cons:
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:
Cons:
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.)
Comments and suggestions are appreciated! Next week, I'll begin implementing Option 3 if there are no differing opinions.
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/
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:
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):
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.
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:
Expected behavior
Code block doesn't have line numbers
Desktop (please complete the following information):
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):
Additional context
Add any other context about the problem here.
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.
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.
Screenshots
From https://eecs280staff.github.io/p1-stats/setup.html#visual-debugger
Desktop (please complete the following information):
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.
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.
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:
Add custom plugin as an integration option built into Primer Spec.
Pros:
spec.html
to look more similar to the upstream (GitHub's original Primer theme), possibly making maintenance easier.Cons:
Custom plugin is maintained in a separate repository.
Pros:
eecs485staff
.Cons:
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?
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):
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.
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).
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.