Change of highlighting themes

[kimikage]

I'm currently working on ANSI color support for the @example/@repl blocks. (cf. PR #1441) I would like to support LaTex output in the future, but I'm targeting HTML first.

There are several ways to specify ANSI colors, of which the terminal-dependent 16 colors are the most commonly used. Since those colors are not standardized, I'm going to style them based on the colors (variables) of the theme, rather than hard-coding the color codes. Consequently, I'm planning to change the default theme slightly.

By contrast, in terms of thematic consistency, I have two gripes with the syntax-highlighting with highlight.js. One is that the color scheme of the dark theme (a11y-dark) doesn't match the rest of the documenter-dark theme, and the other is that there is no consistency between the dark theme and the light theme (highlight.jl's default).

Additionally, @fredrikekre has greatly improved Julia's syntax highlighting. So, I see it as an opportunity to reconsider the themes.

Although I haven't decided on a specific theme selection and design approach yet, here's a demo of the new highlight.js.

example dark theme

.hljs {
  display: block;
  overflow-x: auto;
  padding: 0.5em;
  background: #282f2f;
}

.hljs,
.hljs-params {
  color: #f0f8f8;
}

.hljs-formula,
.hljs-keyword,
.hljs-link,
.hljs-selector-tag {
  color: #be7dda;
}

.hljs-class,
.hljs-name,
.hljs-quote,
.hljs-title,
.hljs-variable {
  color: #b5ddd4
}

.hljs-built_in,
.hljs-builtin-name,
.hljs-bullet,
.hljs-doctag,
.hljs-emphasis,
.hljs-strong {
  color: #9baae5;
}

.hljs-template-tag,
.hljs-type {
  color: #1db5c9;
}

.hljs-code,
.hljs-meta,
.hljs-regexp,
.hljs-symbol,
.hljs-selector-id,
.hljs-tag {
  color: #1abc9c;
}

.hljs-addition,
.hljs-meta-string,
.hljs-section,
.hljs-selector-attr,
.hljs-selector-class,
.hljs-string {
  color: #6cbe5e;
}

.hljs-attr,
.hljs-attribute,
.hljs-function,
.hljs-meta-keyword,
.hljs-selector-pseudo {
  color: #c3de84;
}

.hljs-comment {
  color: #9b9891;
}

.hljs-link_label,
.hljs-literal,
.hljs-number {
  color: #dab426;
}

.hljs-deletion,
.hljs-subst,
.hljs-template-variable  {
  color: #ff8873;
}

.hljs-emphasis {
  font-style: italic;
}

.hljs-section,
.hljs-strong {
  font-weight: bolder;
}

[mortenpi]

The more colorful version is the new theme, right? If yes, then that's a massive improvement and it would be great to have! I'll just admit here that I picked the first one that kinda worked and didn't think about it since.

I think it would make sense if the highlighting theme and the theme for the ANSI colors match. That's what you're suggesting, right? Since we have to vendor in the hljs themes anyway, we could easily roll our own. Might be a little bit of maintenance work when upgrading the hljs dependency, but I think we can tolerate that.

If you're going to mess around with the themes and the highlighter anyway, it might be worth updating highlight.js to the latest version, since there might be slight differences between the versions (especially since we're using v9 and the latest is v10). I believe it would be necessary to update to v10 anyway to get Fredrik's updates once it lands in a release.

[kimikage]

FYI, I have confirmed that Documenter works with v10.3.1. However, since v10 the module has been anonymized, we need to specify the exports keyword argument.

        hljs_version = "10.3.1"
        push!(r, RemoteLibrary(
            "highlight",
            "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/$(hljs_version)/highlight.min.js",
            exports = "hljs"
        ))

Also, we should use "nohighlight" instead of "language-none".

My main concern about migrating to v10 is that the support for IE11 is dropped, but since highlighting is not a mandatory feature, I think the benefits of migration are greater.

Edit:
cf. PR #1503

[mortenpi]

My main concern about migrating to v10 is that the support for IE11 is dropped, but since highlighting is not a mandatory feature, I think the benefits of migration are greater.

Good to know. Out of curiosity, I checked the analytics for the main Julia docs -- 0.8% of user over the past year were using IE (vs. 4.6% using Edge). I think we can tolerate breaking highlighting for those users, if we get better highlighting in return.

[kimikage]

I've created a playground repository to consider the color schemes, including tweaks to Documenter's default themes.
(cf. kimikage/july-morning-theme#1)
Although I don't have all the material for discussion yet, I plan to post a topic in the Discourse, once things settle down.
This is related to PR #1441, but they can be considered independently of each other.