Highlight code blocks with Rouge instead of highlight.js, add code block dark mode #124
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tchebb
force-pushed
the
highlight-with-rouge
branch
from
6418e50 to
3044ece
Compare
|
The static analysis issues are false positives, since that CSS file is tool-generated and not hand-written as per the documentation I added to |
Jekyll 3 and 4 process code blocks by default using Rouge[1], which adds <span>s of various classes to the code indicating how different parts should be highlighted. So to highlight code, all a theme needs to do is include an appropriate stylesheet, which can be easily created for a variety of color schemes using Rouge's `rougify style` command. YAT, however, ignores the Rouge highlighting and instead includes highlight.js, which does its own highlighting client-side. That increases both bandwidth and client CPU usage for no clear benefit. Furthermore, it tries to guess a language if none is specified even if `guess_lang` is turned off in Jekyll's configuration, since `guess_lang` only affects Rouge. Let me know if there's a good reason to prefer highlight.js over Rouge, but to me it it just looks like extra complexity for no gain. As such, this change removes it and adds a Rouge stylesheet instead. [1] https://github.com/rouge-ruby/rouge
Now that code highlighting is just a normal stylesheet, it's easy to add a separate set of dark-mode rules. Do so and update the documentation. Fixes jeffreytse#24
The `::before` trick we've been using to add badges has never interacted well with the `overflow-x: auto` we set on the parent `<pre>`: `position: absolute` positions relative to the unscrolled container and doesn't "stick" when the container is scrolled, resulting in the badge leaving the right edge of the block when wide code is scrolled. Until now, that issue has been masked by the fact that highlight.js gives the `<code>` its own `overflow-x: auto`. Since we've stopped using highlight.js, we need to fix the issue properly. The root cause is described well in this article[1]. As it demonstrates, all solutions not involving an extra wrapper div take a lot of code and are pretty hacky. In addition, the last example--closest to our case-- requires the badge itself to have nested divs, which can't be done with `::before`. As such, just use JS to add a wrapper div, which actually simplifies both the CSS and the JS significantly. [1] https://www.horuskol.net/blog/2022-04-13/relative-and-absolute-scrolling-blues/
tchebb
force-pushed
the
highlight-with-rouge
branch
from
e161525 to
994e176
Compare
|
Updated branch to rebase and fix code badges no longer showing up on Markdown code blocks when highlighting is disabled in the config. |
jeffreytse
force-pushed
the
master
branch
3 times, most recently
from
bd29ba6 to
df61d0c
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Jekyll 3 and 4 process code blocks by default using Rouge, which adds
<span>s of various classes to the code indicating how different parts should be highlighted. So to highlight code, all a theme needs to do is include an appropriate stylesheet, which can be easily created for a variety of color schemes using Rouge'srougify stylecommand.YAT, however, ignores the Rouge highlighting and instead includes highlight.js, which does its own highlighting client-side. That increases both bandwidth and client CPU usage for no clear benefit. Furthermore, it tries to guess a language if none is specified even if
guess_langis turned off in Jekyll's configuration, sinceguess_langonly affects Rouge.Let me know if there's a good reason to prefer highlight.js over Rouge, but to me it it just looks like extra complexity for no gain. As such, this change removes it and adds a Rouge stylesheet instead.
Another plus of Rouge is that it's easy to set alternate colors for dark mode since colors are set in CSS. This change also does that, which fixes #24.
This contribution is on behalf of my company.