Knitted output about collateral HOT 3 OPEN

Interestingly, the current pkgdown docs featured coloured output for collateral output in the reference pages, even though other pages (like knitted chunks on the home page) do not. Getting to the bottom of that difference might shed some light on this!

On the topic references:

On the home page:

The chunk option collapse = TRUE brings the output into the same cell as the input, but it doesn't colourise it.

from collateral.

More notes to myself on colourisation (which doesn't appear to be on the radar at the moment, going by issues 916 and 958 of pkgdown).

As far as I can tell, there are no differences in the way pkgdown attempts to render the article pages (including the homepage) and the example sections of reference topic pages.

However, the code and output is marked up differently (regardless of whether colour or formatting is involved). One exception to this is links, which are marked up correctly in both kinds of page.

The templates are mostly similar, but the content of articles is inserted simply using $body$, where as the example section of reference topics looks like:

{{#examples}}
    <h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
    <pre class="examples">{{{ . }}}</pre>
    {{/examples}}

The resultant code for articles has each line marked up with either sourceLine for otherwise unformatted text or a span with a class for oprators or specific kinds of input tokens (op for operators, etc.). Entire output lines are simply sourceLine wrapping a span with co.

In example sections, the wrapping code block is a <pre> with the class examples, then <div>s for subblocks of either input or output (output blocs are also wrapped in co). Input lines are similarly broken into <span>s with classes specifying the kind of input token. But output blocks, despite generally being wrapped in co, are further broken into <span>s with style attributes that apply crayon styles (italic, colour, etc.).

Output blocks being broken up with spans for crayon effects is funamentally the difference between articles and reference topics, but reference topics also group input and output into sub-blocks that are differentiated and well-structured. Articles appear to try and treat the input and output line by line, although code that isn't marked up for a link or some sort of input token end up being entirely unwrapped (and include raw new lines).

It's also worth noting that the CSS involved here isn't contingent on the classes of the wrapping <pre> or <code> blocks—the output colourisation simply isn't marked up in articles.

Why are they processed differently? It seems like this is probably down to how the whisker package handles the templates. The whisker documentation notes that the {{{triple brace}}} prevents HTML escaping. This pattern is used in examples blocks, suggesting that colourisation markup is anticipated in examples sections, but no such escaping is done in the article template. But what causes the crayon tags to be added in the first place (or does escaping simply mean stripping for the articles)?

When whisker::whisker.render() is called, it takes the template and a data object that contains the content to be rendered. This is rendered using data_reference_topic(), which accepts examples = TRUE. That doesn't happen at all for articles and home pages: they go through Rmarkdown, and the output from that goes into the HTML template.

Relevant function stack:

For reference topics:

• build_reference
  • build_reference_topic
    • data_reference_topic (examples = TRUE) (converts Rd to list)
      • run_examples
        • highlight_examples (! this checks crayon.enabled and crayon.colors)
          • replay_html (from the evaluate package: https://github.com/r-lib/evaluate)
        • highlight_text
    • render_page
      • find_template
      • render_template
      • data_template

For articles and home page:

• build_article
  • rmarkdown_template
  • build_rmarkdown_format
    • rmarkdown_template
  • render_markdown

So, tl;dr, it's two diferent rendering engines—examples use the evaluate package and whisker, and articles and the home page use Rmarkdown.

This SO answer suggests using a knitr hook to add colouration with fansi::sgr_to_html. That seems doable for the home page, but I might need to modify the article template to include it for articles.

If this is fundamentally an Rmarkdown issue, then fixing it might yield some more insights for the general question, which is about coloured knitr

from collateral.

Also note that the colours2 branch of pkgdown attempts to add colourisation for vignettes and articles:

r-lib/pkgdown@e41ccf9

And it uses fansi::sgr_to_html too. But it uses hooks that seem specifically taregtted at colourising side effects outputted directly, rather than allowing already colourised output (such as colourised output from packages like collateral) to work (or do I have this wrong?). I think this is a good place to test.

from collateral.