Add more highlighting support for HTML output

[cderv]

This PR aim to close #1881 by adding an option support for downlit highlighting using a new argument in the format, named highlight_downlit after the one chose in distill

To do

Support in html_document

• post processing step on the resulting html document
• All document based on html_document could benefit from this by activating the feature.

• Test it is working in gitbook)
• Choose the default highlight theme (see below)

Support in markdown output

• downlit::downlit_md_path() could be used, but only support Chroma for now
• Also it adds span tags for highlighting but we want only autolink ? 🤔 Pandoc may remove them depending on the extensions, so pre process ?

• Support in github_document
• Support in md_document

Edit: Won't add it here. See #1881 (comment)

About highlighting

• By default, rmarkdown uses highlightjs with the default them in html_document
• If downlit is enabled, default (highlight = "default") will be a pandoc style and not highlightjs.
• downlit requires to add a specific css code so that the code has links but the highligting stay the one expected from pandoc the highlight.

• improve documentation regarding highlighting, and explain difference between engine and color scheme. (see Add more highlighting support for HTML output #1941 (comment))
• Update the a11y.theme file after its update (see Add more highlighting support for HTML output #1941 (comment))

[cderv]

default syntax highlighting when downlit is used is now a11y.theme like in distill and bookdown::bs4_book()

[cderv]

Just a note that this is also working with gitbook as highlight_downlit = TRUE will be correctly pass to html_document

[cderv]

All this highlighting stuff started by downlit support in rmarkdown made me think. I found it was not clear enough in the current code, so I rewrote the whole function on the base of highlighting engine + syntax highlight theme. (Could still be clarified I think)

• Same logic as before - I added some tests to check that
• Rewrote the if-else code to be better align with engine + theme
• Added support for *.theme file passed in the highlight = arguement (no more match.args on pandoc highgligth style name)
• Added support for highlight = "a11y" and highlight = "rstudio", based on distill .theme file
• This allow also to be more aligned with recent change in distill (we may be able to refactor as distill uses html_document)

I did this only for the html format, but this could be apply also to other format (not downlit, but the use of .theme file).

I still need to update the documentation and look at the other reviews.

[cderv]

One thing I missed to handle here is that there are some cases where we want to use downlit to produce highlighting for Chroma CSS. This is the case for blogdown::html_page(). The current support in rmarkdown would allow to have downlit applies but will not produce the correct HTML tags for Chroma as it currently uses classes_pandoc() only and can only be activated if Pandoc highlighting style is used.

blogdown::html_page() would require highlight = NULL and highlight_downlit = TRUE with downlit::classes_chroma()

Either we should support both in here (using an option or another switch), or this is specific to blogdown and should be handle there directly.

[cderv]

@yihui as we are focusing on rmarkdown currently, I have updated the PR and checked everything is ok.
The above thread seems overwhelming but at the change is quite small thanks to the previous reviews and feedbacks I had last year. Maybe no need to go through all the thread.

To sum-up, this PR reworks and document the highlighting logic. It has several aims:

• Allow to pass a custom .theme file in highlight argument (Allow to load external highlighting theme for Pandoc HTML and PDF #2035)
• Add two custom themes: arrow.theme and rstudio.theme (related to Use a11y theme for default highlight style in html_vignette() #2221 and what has been done in distill)
• Add optional support for downlit as a syntax highlighter, using Pandoc's theme for styling. (Make it easy to use downlit from html_document() #1881)

This should work fine for html_documen(). However, there are other challenge to make it work in blogdown (when not using Pandoc as markdown renderer leading to Chroma for highlighting) and bookdown (because of the way xml2 is rewriting the HTML conflicting with bookdown processing).

Thanks.

[yihui]

Okay, I didn't review this PR carefully or read the conversations above. Please feel free to merge if/whenever you feel it's ready. Thanks!