Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Highlight code blocks with Rouge instead of highlight.js, add code block dark mode #124

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Highlight code blocks with Rouge instead of highlight.js, add code block dark mode #124

wants to merge 3 commits into from

Commits on Aug 25, 2023

  1. Replace highlight.js with server-side Rouge highlighting 

    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
    @tchebb
    tchebb committed Aug 25, 2023
    Configuration menu
    Copy the full SHA
    61bdb66 View commit details
    Browse the repository at this point in the history

  2. Add a dark theme for code blocks 

    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
    @tchebb
    tchebb committed Aug 25, 2023
    Configuration menu
    Copy the full SHA
    1a91020 View commit details
    Browse the repository at this point in the history

  3. Prevent code badges from scrolling along with code 

    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
    tchebb committed Aug 25, 2023
    Configuration menu
    Copy the full SHA
    994e176 View commit details
    Browse the repository at this point in the history