Edit tango highlight

[clara.rodriguez]

Does anyone know how to edit / create a new style like tango, pygments, kate, monochrome, espresso... to render html pretty documents with markdown?

[jdblischak]

The syntax highlighting is provided by pandoc.

$ pandoc --list-highlight-styles
pygments
tango
espresso
zenburn
kate
monochrome
breezedark
haddock

To see which one you'd like to modify, Garrick Aden-Buie has a convenient blog post that displays all the options.

According to the pandoc manual, you can export a JSON config file from one of the available styles for customization:

pandoc --print-highlight-style pygments > my.theme

Note that this requires pandoc 2 (at the very least the above command failed when I tried to run it with pandoc 1.19.2.4).

After customizing the style file, you can pass it to pandoc via the rmarkdown package using the argument pandoc_args, e.g.

---
output:
  html_document:
    pandoc_args: "--highlight-style=my.theme"
---

And actually unfortunately I can't get that to work. The rmarkdown code by default sets the pandoc flag --no-highlight so that it can instead use highlight.js. Setting the argument highlight to be NULL similarly causes it to set --no-highlight.

I tried tricking rmarkdown by specifying a dummy theme. This prevented the addition of the --no-highlight flag, but unfortunately it adds --highlight-style=tango after --highlight-style=my.theme, which then overrides the custom style.

---
output:
  html_document:
    highlight: tango
    pandoc_args: "--highlight-style=my.theme"
---

The relevant function is pandoc_html_highlight_args.

Thus the two main options I see to use a custom syntax style are:

1. Send a Pull Request to update pandoc_html_highlight_args to allow the use of a custom syntax style file
2. Have rmarkdown export a Markdown file, and then run pandoc yourself manually with the exact flags you want (you can copy-paste the pandoc command output by rmarkdown::render and modify it)

[cderv]

To pass a argument to --highlight-style pandoc args, you can just provide it in the yaml header

---
output:
  html_document:
    highlight: my.theme
---

rmarkdown pandoc_html_highlight_args knows how to deal with that. It will pass --highlight-style = my.theme to pandoc.

[jdblischak]

@cderv

To pass a argument to --highlight-style pandoc args, you can just provide it in the yaml header

That would be really convenient, but I wasn't able to get it to work. I tried using that YAML header with rmarkdown 1.14 and 1.15.1 (installed from GitHub).

> rmarkdown::yaml_front_matter("highlight.Rmd")
$output
$output$html_document
$output$html_document$highlight
[1] "my.theme"



> rmarkdown::render("highlight.Rmd")
Error in match.arg(highlight, html_highlighters()) : 
  'arg' should be one of “default”, “tango”, “pygments”, “kate”, “monochrome”, “espresso”, “zenburn”, “haddock”, “breezedark”, “textmate”

[cderv]

Oh I see ! I missed that.

This happens with the default template. If you use a custom template, there should not be this check on the highlight argument. I think this is because the included default template is made to be functionnal with pandoc theme, and rmarkdown check that the argument provided is one the pandoc highlight styles list.

Try this:

---
output:
  html_document:
    template: my_template.html
    highlight: my.theme
---

I don't know if you want to provide a custom template too. You can just check it works as you expect.

There may be a Feature Request to open in rmarkdown there, but I am not sure this is a good idea to remove the check. However, there could be a check about the hightlight argument: if this is of the form *.theme, consider user is trying to use a custom theme and add it using pandoc_args. Would that be interesting ?

Does the custom theme working well with pandoc ?

[jdblischak]

@cderv

If you use a custom template, there should not be this check on the highlight argument.

@cderv This worked! Thanks!

I exported the default HTML template to my_template.html:

$ pandoc --print-default-template html > my_template.html

And then the pandoc command executed by rmarkdown::render() properly included the flags --template my_template.html and --highlight-style my.theme. And as a test, I changed the theme Keyword to be purple (#543a54 to be specific), and confirmed that the change was made in the HTML file:

@cderv

There may be a Feature Request to open in rmarkdown there,

I agree this has the potential to be useful. I hesitate mainly because the rmarkdown package has so many moving parts. For example, this strategy generates the following warning message about MathJax, but I'm not sure how big of a deal that is:

Warning message:
MathJax doesn't work with self_contained when not using the rmarkdown "default" template. 

@cderv

Does the custom theme working well with pandoc ?

@clara.rodriguez Could you please give this a try and let us know what you think? In other words, when you edit the syntax highlighting theme, does it display well when using the default pandoc template?

[cderv]

@jdblischak

I'm not sure how big of a deal that is:

I think this is just a warning because there is specific things done in rmarkdown pandoc template to make mathjax works as expected in self contained document. When you use another template, rmarkdown is just warning you that you need to take care of this is you want self contained. I think it is just that.

For the feature, you could always ask in the repos what the developers think. I guess that if this is useful, a small change could be made, when using default template, to detect a *.theme argument in highlight argument and if so consider this is a custom theme and not a pandoc highghlight know theme. I don't think this would have a big impact...