Switch from inline syntax highlighting styles to external CSS file

[crnh]

As documented in the wiki, stylesheets for syntax highlighting can be easily generated using Hugo.
This introduces a (small) breaking change: users who configured a different style using the markup.highlight settings will have to set noClasses to true.
However, it is no longer necessary to overwrite the code block background, as that is now handled by syntax-highlighting.css.

Closes #164

[tomfran]

Looks good to me thanks!

A small question, could someone override the code background by putting something like the following in custom.css?

.bg {
  background-color: ...;
}

If so, I would mention it in the wiki along your changes.
Regenerating the syntax highlight scheme is fine, but overriding everything transparently in custom.css would be better.

Custom generation would then mean appending to the custom.css file:

hugo gen chromastyles --style monokai >> assets/css/custom.css

[crnh]

A small question, could someone override the code background by putting something like the following in custom.css?

That doesn't work but this does:

.chroma, .bg {
  background-color: ...;
}

However, in this case it would be better to override the --code-background variable, since this variable is used by syntax-highlighting.css.

Regenerating the syntax highlight scheme is fine, but overriding everything transparently in custom.css would be better.

I deliberately created a separate file for syntax highlighting to make overriding the styles easier. Appending to custom.css would work as well, but then the styles would be defined twice.
In my opinion, this is still transparent, as I would not override this file in the theme itself, but instead in my website's assets/css/syntax-highlighting.css file.

[tomfran]

I deliberately created a separate file for syntax highlighting to make overriding the styles easier. Appending to custom.css would work as well, but then the styles would be defined twice.
In my opinion, this is still transparent, as I would not override this file in the theme itself, but instead in my website's assets/css/syntax-highlighting.css file.

Okay that's perfect then, thanks for clarifying :)

[tomfran]

Sorry I merged, but then realized that the code background in case of dark mode is not respected, perhaps something is missing?

Maybe it's an important here:

.bg {
  background-color: var(--code-background);
}

Please reopen, I'll make sure to test without merging next time

[crnh]

That's weird, I tested that behavior.
I'll look into this soon, but adding !important shouldn't be necessary here. I tested overrides with other colors without !important and that worked fine.

[tomfran]

What browser did you use? Maybe it's a Safari issue.

[crnh]

I see what's happening here: unfortunately, noClasses must be disabled in the site's hugo.toml.
Hugo does not merge markup settings from the theme configuration, to prevent theme authors from enabling unsafe settings: https://discourse.gohugo.io/t/storing-markup-override-settings-in-the-theme-settings/56032
If you add noClasses = false to your markup configuration, it should work.

With this in mind, do you still want this change?
Since markup settings must be changed by the user, the user must change the configuration anyways, so for new users it would be sufficient to mention this in the documentation.
However, existing users will have to change their configuration as well, also if they are using the recommended theme.

[tomfran]

With this in mind, do you still want this change?

Given the pros it brings, it's fine to have it in my opinion, as this will also go into a 3.0.0 release, which brings, as expected, breaking changes.

---

I updated the toml of my website and now it works as expected, only thing is that the theme is slightly different:

New on the left, old on the right:

[crnh]

I see, which one do you like better?

The left one looks more like the preview here: https://xyproto.github.io/splash/docs/algol.html. Maybe this changed between Hugo versions; which version do you use?
If you don't like the underlines, I could change the default style to algol_nu. If you're fine with the current style, I'll update the wiki and re-open this PR.

[tomfran]

I am not sure, I must have done something not really standard while setting it up the first time.

The current one seems to be algol without underlines or italics, maybe something is inherited from the stylesheet?

Let's start with algol_nu as it seems to be the closest to the original.
I don't love the grey on grey for function names 😅, but let's start with this and then maybe manually tweak it.

[crnh]

If I look at your website, it seems the inline styles only modify the font weight but not the colors. Since the colors are absent from the inline styles, I don't think it has to do with the stylesheet, but I don't have a clue why the colors are absent in the first place.

I'll make the proposed changes and open a new PR!