add chroma CSS? - Githubissues

maelle commented 3 years ago

https://distracted-yonath-b034c9.netlify.app/blog/2021-01-04-hi-hugo/ from https://github.com/maelle/apresacademic where I used R/build.R to get downlit highlighting.

I think blogophonic has some special code highlighting (to number lines) :thinking:

maelle commented 3 years ago

And when not using downlit, I see a missing space after the line numbers:

apreshill commented 3 years ago

Hmm I think it is using Hugo, but not updated for goldmark rendering options:

from config.toml https://github.com/apreshill/blogophonic/blob/81181a6529087fc3d6931a2584bdf95c6619e864/config.toml#L10-L13

apreshill commented 3 years ago

May need to reconfigure: https://gohugo.io/getting-started/configuration-markup#highlight

maelle commented 3 years ago

Oops you are right, I should have known better, I removed these lines from the config. I suppose my issue is now

I'd like to have Chroma CSS as in your tidyverse&co theme
I'd like the default configuration to not have these pygments lines but instead pygmentsUseClasses = true.

apreshill commented 3 years ago

Ok, working on this in the chroma branch! Is this the setting for the classes variable now?

https://chroma--cranky-lalande-e3373f.netlify.app/blog/

[markup]
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineAnchors = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = false                    <--?
    style = "monokai"
    tabWidth = 4

Also some helpful links for me: https://discourse.gohugo.io/t/pygmentsuseclasses-true-not-generating-classes/15080/9 https://github.com/zwbetz-gh/minimal-bootstrap-hugo-theme/blob/master/README.md#syntax-highlighting

apreshill commented 3 years ago

OK hitting a stopping point. Notes:

If I use noClasses = true, I don't need to supply my own CSS. This works.
But I switch to noClasses = false, then I need to include my chroma.css file. BUT if I do that, the background color from the highlighter is overriden by the site background color. 😞 And more generally, you cannot select your highlighter style any longer, i.e., this style = "dracula" does nothing.

maelle commented 3 years ago

:sob: and if there is no chroma.css one cannot use downlit, right?

apreshill commented 3 years ago

I just don't know. I think the difference is that I can control everything within like tidyverse.org, because we don't want to configure things. But if I want to give users the option to change highlighters, I would need to configure each one to support individually. So, trade-offs. Relevant thread?

https://github.com/matcornic/hugo-theme-learn/issues/187

I think I have 3 choices to make a highlighter that people can choose:

I can keep noClasses = true and it works great, but not for .Rmd 😭 . But people can select any chroma style in config.toml using style = "manni" for example.
I can go with highlight.js instead- that would work for .Rmd and .Rmarkdown files, so has benefits. This now surprisingly feels like the easiest, but would also have to build in a config flag to turn "off" Hugo Chroma highlighting (maybe codeFences = false does this for me?).
I can use noClasses = false and add support for specific chroma highlight styles (i.e., maybe dracula, fruity, friendly, and pygments; list) by including some kind of "themeable" highlight style. This feels like the heaviest lift, and still won't work for .Rmd until downlit support gets integrated.

cderv commented 3 years ago

At the end this highlighting thing will always bit complicated. I would sum up technically with this:

At the end, it is a matter of who does the highlighting :

Pandoc ? => only works with markdown files processed by Pandoc so when using .Rmd to .html conversion. Styling is included by Pandoc in the CSS. Syntax highlither is in Haskell and called Skylighting
Goldmark ? => only works with markdown files processed by Goldmark so when using .Rmarkdown to .md conversion or using .md directly. Styting is included by Chroma as inline CSS in the HTML style. Or can be externalize using classes and a CSS needs to be provided (not included like with Pandoc). Syntax highlighter is in Go and called Chroma.
Highlight.js ? => Client-side highlighter so works with all HTML content generated and not already processed by an highlighter. Syntax highlither is in JS called highlight.js
R ? downlit is a syntax highlighter in R which only works for R code. It can process R code and mimic the ouput of Pandoc highlighter or Chroma highligther as it will add the classes expected for using the styling of Pandoc or Chroma. So you would use downlit in .Rmd file either to output for Pandoc or for Chroma. The latter would require to deactivate Pandoc highlighting.

First two will only work with one type of file only. having consistency in a website will require to use only one type of file. highlight.js is the more generic as it will apply no matter the format used. downlit would approach that but it will only work for .Rmd when using only R code. If you have for example a YAML chunk you want to highlight, and you configured the Rmd file to use downlit to output Chroma, then the other code non R code chunk would not be highlighted by Chroma at the end.

Hope it helps understand a bit more how all this works together to see what is possible.

One (crazy?) solution would be to some CSS for Pandoc and some CSS for Chroma using the same color ! The parser would result a bit different in what is highlighted with which color but I think it would be minimal difference.

maelle commented 3 years ago

Maybe there could be a few lines in the docs to tell people how they'd need to customize things based on their workflow? Or maybe this theme should discourage people from using Rmd to html 😜

In any case I think having an external css, not inline default Chroma style is better since none of the Chroma styles has high enough contrast (unless it changed since the last time I looked).

apreshill commented 3 years ago

@maelle

In any case I think having an external css, not inline default Chroma style is better since none of the Chroma styles has high enough contrast (unless it changed since the last time I looked).

I think this can always be an option for more advanced users- I'll build in a slot in the config file to name/import in your own CSS highlighter. For everyone else though, I'm going to go with option 1:

.Rmarkdown and .md will look the same, plus I have some layouts that bring in {{ .TableOfContents }} so this is good.
Users get to pick their highlight style of choice from the built-in Chroma options.
[x] TODO: add a slot in config.toml to specify custom CSS (for a highlighter or just any .css file)

apreshill commented 3 years ago

Done here: https://github.com/apreshill/apero/pull/62

hugo-apero / hugo-apero-docs

add chroma CSS? #26