Purpose of plugin-highlight.css?

[svanimpe]

I'm using Bookdown with the Gitbook template. I've noticed that this template contains a plugin-highlight.css stylesheet with rules for highlight.js. However, highlight.js is not enabled in the template and the default highlighting seems to user other scripts/styles.

I've now disabled the default highlighting with highlight: null in _output.yml and added highlight.js myself. When I do this, the template picks up the styles in plugin-highlight.css and these override the highlight.js stylesheet I've added myself.

So I'm wondering: What's the purpose of plugin-highlight.css in this template? Is it just a leftover? Or am I supposed to use this template when I use highlight.js, so it matches the Gitbook styles?

https://stackoverflow.com/questions/64646749/bookdown-whats-the-purpose-of-plugin-highlight-css

---

By filing an issue to this repo, I promise that

• I have fully read the issue guide at https://yihui.org/issue/.
• I have provided the necessary information about my issue.
  • If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
  • If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('bookdown'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('rstudio/bookdown').
  • If I have posted the same issue elsewhere, I have also mentioned it in this issue.
• I have learned the Github Markdown syntax, and formatted my issue correctly.

I understand that my issue may be closed if I don't fulfill my promises.

[cderv]

Hi thanks for the question.

gitbook() does not currently use highlight.js due to how it works with rmarkdown base format. I would tend to think this is not expected. highlight = "default" in gitbook() will be equivalent to highlight = "pygments" and use Pandoc highlighting.

I believe the CSS file plugin-highlight.css is there mainly because bookdown was created by using the gitbook format which was open source at the time and all included asset where imported here too. This file would be useful to support highlight.js with the gitbook feature of changing color theme (Normal, Sepia, Night).
This main drawback is that this will overwrite any highlight.js other css, and it would be hard to maintain.

Also with gitbook() format, it is good practice to use the full selectors to override gitbook's css. Otherwise, it may not work well. This is because Gitbook's CSS have selectors with lot of classes.

For this, we could also offer an argument in gitbook() to opt-out plugin-highlight.css - we have already done something similar for tables in #642

I believe gitbook() format could benefit an explicit support of highlight.js. We'll improve the highlighting mechanism and configuration in rmarkdown and hopefully this will allow to improve it in bookdown

@yihui, does gitbook() was supposed to support highlight.js explicitly through highlight argument already ?

For reference about the why,

• gitbook() uses rmarkdown::html_document() as base format and highlight= can be specified to be passed to rmarkdown::html_document
• highlight = 'default' is the default in rmarkdown::html_document but will behave differently depending on the template. It will activate highlight.js when used with the default template, and activate Pandoc's pygments otherwise
• gitbook() does not use the default template of html_document() but a custom one - this cause html_document() to activate Pandoc's highlighting and not highlight.js

We need to clean this highlighting opt-in between the different possibilities to make it explicit. This is in progress in rmarkdown to use either highlight.hs, Pandoc's skylighting or downlit for R.

[yihui]

It was first added in this commit: 7bdd62f#diff-4694e2fa1690b4bb68a6e0e1e3c9cb62028a1261493fee209078c177a6712659

This file would be useful to support highlight.js with the gitbook feature of changing color theme (Normal, Sepia, Night).

Yes, I think you are right.

Also with gitbook() format, it is good practice to use the full selectors to override gitbook's css.

I think that's right, too. Simply including a highlight.js stylesheet is unlikely to work in the gitbook format, because the CSS rules have to be extremely specific like .book .book-body .page-wrapper .page-inner section.normal pre .hljs-comment (whereas highlight.js's CSS only defines styles for the class .hljs-comment).

does gitbook() was supposed to support highlight.js explicitly through highlight argument already ?

I don't see why not, although I've never tried to use highlight.js in gitbook.