Search code examples
rbookdownhighlight.js

Ugly dark stripe in code chunk of gitbook with highlight: espresso (R bookdown)

I use R bookdown package to create a gitbook. Recently I noticed an ugly dark stripe under the boxes of code chunks in rendered gitbook (see a printscreen below). It appeared with highlight set to espresso. Stripes like this one distract attention when one tries to read the book and looks unattractive.

I can reproduce the result by creating a new bookdown project with RStudio (most probably the same project as the minimal bookdown example) with the contents of file _output.yml replaced with two lines:

bookdown::gitbook:
  highlight: espresso
  1. Can anyone else reproduce the problem?
  2. How can I rid off the stripe, but still use highlight: espresso?

enter image description here

Solution

  • The problem comes from the use of pandoc 2.x.
    I reproduced the bug here and you can see the same gitbook with pandoc 1.19.x here.
    I wrote a note to explain my debugging worflow.

    In both versions, HTML sources are very close (I voluntary omit div and lines ids that @Yihui Xie dislikes). 

    <div class="sourceCode">
  <pre class="sourceCode r">
    <code class="sourceCode r">
     <span class="kw">install.packages</span>(<span class="st">&quot;bookdown&quot;</span>)
     <span class="co"># or the development version</span>
     <span class="co"># devtools::install_github(&quot;rstudio/bookdown&quot;)</span>
    </code>
  </pre>
</div>

    The problem you got is a consequence of a collision between gitbook theme and espresso highlighting.

    Firstly, the dark stripe is the "real" background color of espresso (see here): the background-color of espresso highlighting is set to #2a211c by pandoc (it is hard-coded here).

    The builtin espresso highlighting looks like this for pandoc v2.x (it is black, like an espresso):

    code span.kw {
    color: #43a8ed;
    font-weight: bold;
}
code span.st {
    color: #049b0a;
}
code span.co {
    color: #0066ff;
    font-weight: bold;
    font-style: italic;
}
div.sourceCode {
    color: #bdae9d;
    background-color: #2a211c;
}
div.sourceCode {
    overflow: auto;
}
div.sourceCode {
    margin: 1em 0;
}
pre.sourceCode {
    margin: 0;
}
    <div class="sourceCode">
  <pre class="sourceCode r">
    <code class="sourceCode r">
     <span class="kw">install.packages</span>(<span class="st">&quot;bookdown&quot;</span>)
     <span class="co"># or the development version</span>
     <span class="co"># devtools::install_github(&quot;rstudio/bookdown&quot;)</span>
    </code>
  </pre>
</div>

    It is slightly different of pandoc v1.19.x where the background-color is set for pre elements instead of div.sourceCode (it's important).

    Secondly, gitbook theme overrules only for pre elements the dark background color of espresso with a light grey background (Hex Gray97) and defines a bottom margin (contrary to pandoc CSS) see this file, line #9, column #31963:

    .book .book-body .page-wrapper .page-inner section.normal pre {
  overflow: auto;
  word-wrap: normal;
  margin: 0 0 1.275em;
  padding: .85em 1em;
  background: #f7f7f7;
}

    This bottom margin reveals the background color of the enclosing div element:

    • in pandoc 1.19.x, the enclosing div has no background-color rule (the background color is applied to pre element). So, there's no black stripe.

    • in pandoc 2.x, the background color is set at the div level. There's a black stripe.

    From your question, I understand that you want the espresso highlighting without its "ugly" dark companion. In other words, you want a "white coffee" highlighting.

    So, there are two options:

    • get rid-off the bottom margin
    • overrule the background color of espresso highlighting

    It is a matter of taste.

    First solution : get rid-off the bottom margin
    Save these lines in a file with .css extension (e.g. fix.css):

    .book .book-body .page-wrapper .page-inner section.normal pre {
  margin-bottom: 0!important;
}

    Include this CSS file in your bookdown modifying _output.yml:

    bookdown::gitbook:
  highlight: espresso
  css: fix.css

    Second solution: overruling the espresso background color with Hex Gray97
    In this case, you can include these lines in fix.css: 

    div.sourceCode {
  background-color: #f7f7f7!important;
}

    Since the use of the important rule is not recommended, you can obtain the same result in a more elegant fashion: with pandoc 2.x, you can customise the highlighting theme.
    This gist defines a whitecoffee theme (it is the espresso theme with a Hex Gray97 background).
    Save the whitecoffee.theme file at the root level of your project and modify the _output.yml file:

    bookdown::gitbook:
  highlight: whitecoffee.theme