search

rstudio / blogdown

Create Blogs and Websites with R Markdown
https://pkgs.rstudio.com/blogdown/
1.74k stars 331 forks source link

Documentation for syntax highlighting in Rmd posts #360

Closed mikemc closed 5 years ago

mikemc commented 5 years ago

Thanks for this project and the great documentation! I recently worked through the blogdown book and built my first website. I wanted to suggest an improvement to the documentation regarding syntax highlighting in Rmd posts that I think would be helpful for new blogdown users. A stumbling point was that I knew knitr has built in syntax highlighting, but it doesn't seem to work by default in blogdown Rmd posts. Eventually I figured out that it wasn't on by default in the blogdown::html_page doc type and could be turned on in the Yaml header of the post, 

output:
  blogdown::html_page:
    highlight: tango

But discussion of syntax highlighting in the book doesn't mention this and instead suggests that highlight.js and template customization is needed. It isn't really clear if Rmd or plain md posts are being considered there, but in other parts of the book Rmd posts are recommended and the distinctions between md and Rmd posts are clearly made. I think it could be very helpful to clarify in the docs/book that syntax highlighting can be turned on in Rmd posts and (if I'm understanding correctly) that the highlight.js and template-modding is only needed for code not in Rmd r-chunks.

Perhaps it is only with recent versions of blogdown / Hugo that this is possible? The theme I'm using is https://github.com/ribice/kiss which as far as I can tell does not include highlight.js but maybe has some other syntax highlighting support built in.

tcgriffith commented 5 years ago

Good point. if you have a mixture of Rmd/md/Rmarkdown posts, highlight.js should be more consistent in highlighting the code lines. Rmd-only blogs should be fine.

By the way, I would love to see that syntax highlight to be handled by Hugo(like pandoc did), instead of being handled on a per-theme basis that requires extra work from hugo users and theme authors.

mikemc commented 5 years ago

@tcgriffith After some further googling I saw that there is inbuilt syntax highlighting as of Hugo 0.28. Adding pygmentsCodeFences = true to config.toml gets syntax highlighting working in github-style code blocks in plain .md posts. There may be an easy way to get this working on Rmd posts as well, but it is also possible to use the "tango" pygments theme and knitr theme to get consistent highlighting in both types of posts (pygmentsStyle = "tango" in config.toml).

yihui commented 5 years ago

highlight.js is my personal favorite syntax highlighting library. It works for both Rmd and md. In general, I don't prefer built-in syntax highlighters (Pandoc or Hugo or Pygments) because they pre-generate static HTML tags for tokens. Syntax highlighting dynamically in browser on the client side is a cleaner (I mean the HTML source is clean) and more general approach (you don't need to think about Rmd or md).

And I tend not to spend much time on syntax highlighting :)