Skip to content

Add dark style for fenced code blocks#1355

Merged
ang-zeyu merged 19 commits intoMarkBind:masterfrom
ryoarmanda:code-fence-dark-mode
Oct 4, 2020
Merged

Add dark style for fenced code blocks#1355
ang-zeyu merged 19 commits intoMarkBind:masterfrom
ryoarmanda:code-fence-dark-mode

Conversation

@ryoarmanda
Copy link
Contributor

@ryoarmanda ryoarmanda commented Sep 15, 2020

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Enhancement to an existing feature

Resolves #1219

What is the rationale for this request?
Fenced code blocks are presented with a light style. It would be better to include dark style as well, and provide user to toggle between the two (with dark style being the default).

What changes did you make? (Give an overview)

  • Added minified CSS vs2015.min.css from Highlight.js
  • Added optional site.json config highlightStyle to indicate which style the fenced code blocks should be presented. The default is "dark".
  • Adjusted assets preparation to include either github or vs2015 depending on the value in site.json
  • Adjusted CSS for code block background, line highlighting, and print view.

Provide some example code that this change will affect:
Preview of the new dark mode style:

image

Is there anything you'd like reviewers to focus on?
N/A

Testing instructions:
npm run test (to test) or markbind serve -d (to view the site)

Proposed commit message: (wrap lines at 72 characters)
Code fences are presented on a light background, and it is the only
style available.

Let's provide a dark style for the code block presentation and provide
user configuration to specify which styles to use.

<link rel="stylesheet" href="../markbind/glyphicons/css/bootstrap-glyphicons.min.css">
<link rel="stylesheet" href="../markbind/css/octicons.css">
<link rel="stylesheet" href="../markbind/css/github.min.css">
<link rel="stylesheet" href="../markbind/css/vs2015.min.css">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm, does this mean no light mode? =\

To clarify, what I meant is to use the light styles (github.min.css) during printing when dark mode is on (default) and under normal operation if dark mode is off (provide some way to toggle off dark mode)

e.g.

in site.json, maybe add a style key

{
  style: {
    codeTheme: "light" // implicitly dark by default
  }
}

the problem shifts to us needing to provide the whole 'light' styling inside the rule.

regarding your earlier comment on duplication as well, you could try the not print operator https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries for the dark mode styles

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I thought you want to set it as default (like the only one) as well from what I read on the issue 😅 I'll add the toggle on site.json

@ryoarmanda ryoarmanda changed the title Change default code presentation to dark mode Add dark style for fenced code blocks Sep 16, 2020
Copy link
Contributor

@ang-zeyu ang-zeyu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Some issues:

"faviconPath": "myfavicon.png",
"titlePrefix": "FooBar Dev Docs",
"theme": "bootswatch-cerulean",
"highlightStyle": "light",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we do

style: {
  codeTheme: "..."
  theme: ... // later pr
}

instead? so we can move theme inside there later on since there's now multiple style properties

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

highlightStyle sounds a little like the highlight text style we have, https://deploy-preview-1355--markbind-master.netlify.app/userguide/formattingcontents#text-styles, should we change this to something more explicit?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style looks more apt to consolidate all the style configurations for the site (I don't know how it will be in the future, we only have two style properties so far). I'll introduce that property, and also rename highlightStyle to codeTheme.

Copy link
Contributor Author

@ryoarmanda ryoarmanda Sep 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, a quick question, what do you think should happen when authors write a wrong option to codeTheme (e.g. "qwerty")? Should MarkBind halt or let it quietly discard the option and continue to use the default?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm haven't thought of validating site.json before, my preference here is to logger.warn the user softly and fall back to the dark theme since style isn't critical

for other properties like baseUrl that are we could throw exceptions (in a later pr perhaps)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if you're interested, you could add validation for all applicable properties together in a later pr as well, and just leave this one be for now :-)

}

adjustHighlightStyle() {
const $ = cheerio.load(this.content);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm, parsing the entire document for this seems pretty expensive (its current liberal use is also our main performance bottleneck); let's try to to move it to the main html processing area in ComponentParser

<link rel="stylesheet" href="markbind/glyphicons/css/bootstrap-glyphicons.min.css">
<link rel="stylesheet" href="markbind/css/octicons.css">
<link rel="stylesheet" href="markbind/css/github.min.css">
<link rel="stylesheet" href="markbind/css/vs2015.min.css">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice, swapping the entire style sheet out should be more printer friendly

}

pre > code.hl-dark {
background: #1e1e1e;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no comments about the vs2015 theme choice, maybe we can get @damithc's opinion though

the background here does seem a little too dark though, propose: #333333 (lightness +8%) if its not just me =P

Copy link
Contributor

@ang-zeyu ang-zeyu Sep 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah the background is actually identical to the default theme in VS Code so personally I've grown accustomed to it haha, the line numbering color is also similar. But #333333 is also not bad as an alternative. Would like to know what @damithc prefers as well

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are my choices? I don't mind going with a scheme used by another popular tool.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@damithc The theme choices are available on Highlight.js' demo here https://highlightjs.org/static/demo/ (there are loads of it, light and dark). The dark theme implemented in this PR is Vs 2015, but it's just my pick as it is very similar to VS Code which I'm very familiar with. You can check how it looks like on the links @ang-zeyu posted above.

Also, if you're okay with it, are you also okay with the current background color (re: #1e1e1e or #333333)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Untitled

Like this image? (current) It is already slighty darker than the code text

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like this image? (current) It is already slighty darker than the code text

Yes, that works. I thought the same color is being used (I saw something like that earlier in the thread).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ahhh no that was my original suggestion to @ryoarmanda

Hmm, now that you mention it, editors do stylize the line numbers to be a bit darker than normal text.

lets go with this instead, as you guys mentioned the line numbers shouldn't receive too much attention

Copy link
Contributor Author

@ryoarmanda ryoarmanda Sep 29, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay then, we'll use that color for the line numbers, thanks all 👍

Edit: oh wait, that is the original color! It's the same as the light style 😅

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Edit: oh wait, that is the original color! It's the same as the light style 😅

yes, we went full circle 😅

@ryoarmanda
Copy link
Contributor Author

I found a complication. Because the asset provided for Highlight.js styling is universal for all code highlighting in the site, inline code is also stylized that way. This causes unexpected presentation like this:

image

In light of this, should we also present inline code in dark theme, or should we reserve the theming only for the code blocks?

If we choose the former, it's easier to act on (only need to adjust CSS for the inline code, will likely need to introduce a little bit of padding), but I don't know if this would be desirable to you guys. If we choose the latter, then the bad news is that I'd need to scrap the current approach of swapping the CSS according to theme (as we need two separate stylings happening at once now), and probably just pasting the whole dark theme CSS (<100 lines, with some slight selector adjustment) onto our MarkBind CSS.

Any suggestion for this? @ang-zeyu @damithc

@ang-zeyu
Copy link
Contributor

In light of this, should we also present inline code in dark theme, or should we reserve the theming only for the code blocks?

If we choose the former, it's easier to act on (only need to adjust CSS for the inline code, will likely need to introduce a little bit of padding), but I don't know if this would be desirable to you guys. If we choose the latter, then the bad news is that I'd need to scrap the current approach of swapping the CSS according to theme (as we need two separate stylings happening at once now), and probably just pasting the whole dark theme CSS (<100 lines, with some slight selector adjustment) onto our MarkBind CSS.

The former should be more consistent, maybe to distinguish it you could use a slightly lighter background color than code blocks (like the subtle difference in the current light style)

}

code > span.highlighted {
code > span.highlighted-light {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, since you already havemutually exclusive stylesheets, how about moving all code related styles into github.min.css / vs2015.css (renaming appropriately and preserving license notices)?

should be easier to implement than requiring separate classes for light / dark

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea, I'll try to move the theme-specific styling to their respective CSS files, but some will be kept in markbind.css for identical things like layouting and common colors (if any) so that it can be shared by both.

I'll also keep the license but add something like (slightly modified for MarkBind) to preserve credits

@damithc
Copy link
Contributor

damithc commented Sep 22, 2020

The former should be more consistent

I agree. If possible, apply it for both types.

@ryoarmanda
Copy link
Contributor Author

@ang-zeyu @damithc here's the updated dark style, changes are on the heading and inline code styling. Reviews are welcome

image

@damithc
Copy link
Contributor

damithc commented Sep 29, 2020

@ang-zeyu @damithc here's the updated dark style, changes are on the heading and inline code styling. Reviews are welcome

Looks OK to me 👍

@ang-zeyu
Copy link
Contributor

The heading background looks great 👍

Are there specific languages in which the inline code styling would apply only?
It dosen't seem to be showing up on the netlify preview https://deploy-preview-1355--markbind-master.netlify.app/, also tried locally

some regressions with the light style too:
Untitled

@ryoarmanda
Copy link
Contributor Author

ryoarmanda commented Sep 29, 2020

The inline styling do appear on the Netlify. Though it only applies to syntax-colored variant of inline code.

image

I'll handle the regression in a minute

@ang-zeyu
Copy link
Contributor

The inline styling do appear on the Netlify

it applies only when you specify a language;
https://deploy-preview-1355--markbind-master.netlify.app/userguide/formattingcontents#horizontal-rules

per the code here https://github.com/MarkBind/markbind/blob/master/packages/core/src/lib/markdown-it/index.js
let's move the token.attrSet('class', hljs inline ${lang}) upward to apply in both cases

@ang-zeyu
Copy link
Contributor

Though it only applies to syntax-colored variant of inline code.

Let's keep it consistent! A little strange for it to go back and forth between light / dark =X

@ryoarmanda
Copy link
Contributor Author

let's move the token.attrSet('class', hljs inline ${lang}) upward

As the lang variable will be null if the language is not specified, I think it would be cleaner to omit it entirely in that case. So probably I would just make another token.attrSet in the else branch but with class just hljs inline only.

@@ -1 +1 @@
.hljs{display:block;overflow-x:auto;padding:0.5em;color:#333;background:#f8f8f8}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:bold}.hljs-number,.hljs-literal,.hljs-variable,.hljs-template-variable,.hljs-tag .hljs-attr{color:#008080}.hljs-string,.hljs-doctag{color:#d14}.hljs-title,.hljs-section,.hljs-selector-id{color:#900;font-weight:bold}.hljs-subst{font-weight:normal}.hljs-type,.hljs-class .hljs-title{color:#458;font-weight:bold}.hljs-tag,.hljs-name,.hljs-attribute{color:#000080;font-weight:normal}.hljs-regexp,.hljs-link{color:#009926}.hljs-symbol,.hljs-bullet{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:bold}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold} No newline at end of file
.hljs{display:block;overflow-x:auto;padding:.5em;color:#333;background:#f8f8ff}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:700}.hljs-literal,.hljs-number,.hljs-tag .hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:700}.hljs-subst{font-weight:400}.hljs-class .hljs-title,.hljs-type{color:#458;font-weight:700}.hljs-attribute,.hljs-name,.hljs-tag{color:navy;font-weight:400}.hljs-link,.hljs-regexp{color:#009926}.hljs-bullet,.hljs-symbol{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:700}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}.hljs>span.highlighted{background:#e6e6fa}.hljs.inline{background:#f8f8f8}.hljs:not(.inline){border:1px solid #c8c8c8;border:1px solid rgba(200,200,200,.3)}.code-block-heading{background:#f2f2ff;color:#8787a5}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pink highlight is missing:
Untitled

let's rename these files as well #1355 (comment), since they contain custom styles now too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wondering if we should separate and format our styles as well
I believe the extra whitespace is hardly an issue over being able to figure out which are our custom additions

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have to add a no-lang class here to detect this. Okay then.

Copy link
Contributor Author

@ryoarmanda ryoarmanda Oct 4, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wondering if we should separate and format our styles as well

I agree, it would be easier to read. How about we move these CSS files into core-web/src/styles folder instead, so that it's now alongside markbind.css? Reason is that we have already customized it, so it's not purely a third-party asset anymore, like the ones in the current asset folder. We can deem it as a part of our core-web assets (with proper crediting to the original author of the theme of course).

I think if we do that, and (if I'm not wrong) webpack will build all CSS inside that folder, then we can just store the un-minified version of it, and we'll pick and choose which one to include during copyCoreWebAsset in Site/index.js. That way, we can make the CSS readable on development end while still providing the minified version on deployment. Not sure if my understanding is correct on this, but what do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have to add a no-lang class here to detect this. Okay then.

okay

alternatively you could do [class="hljs inline"], but I don't there's much of an issue in either case

How about we move these CSS files into core-web/src/styles folder instead, so that it's now alongside markbind.css?

Yes that'd be really nice, your understanding is correct too. (also you get the hot reload package when modifying the styles)

The issue at the moment is that there is no webpack configuration-compilation going at site-building time, which requires some amount of groundwork to implement. (currently its only updated at every release)
I'm ok if you want to take this route, but it'll likely take a substantial amount of time to do; Leaving it as assets for the moment may be a more feasible approach

We also have another issue #903 which definitely requires this (configuring webpack compilation at site building time)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I see. Well, let's put a pin on this and revisit in the future when the webpack configuration is able to set this up.

Pushing the latest changes now.

token.attrJoin('style', `counter-reset: line ${startFromZeroBased};`);
}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's keep unrelated changes to another PR (our custom renderers should probably be moved to entirely separate linted file)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you referring to the whitespace changes here? Looks like WebStorm fixed it out automatically for some reason. Let's see if I can re-add these back

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yup

+ hljs.highlight(lang, token.content, true).value
+ '</code>';
} else {
token.attrSet('class', `${inlineClass}`);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

inlineClass

@@ -0,0 +1 @@
.hljs{display:block;overflow-x:auto;padding:.5em;color:#333;background:#f8f8ff}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:700}.hljs-literal,.hljs-number,.hljs-tag .hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:700}.hljs-subst{font-weight:400}.hljs-class .hljs-title,.hljs-type{color:#458;font-weight:700}.hljs-attribute,.hljs-name,.hljs-tag{color:navy;font-weight:400}.hljs-link,.hljs-regexp{color:#009926}.hljs-bullet,.hljs-symbol{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:700}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}.hljs>span.highlighted{background:#e6e6fa}.hljs.inline{background:#f8f8f8}.hljs.inline.no-lang{color:#e83e8c}.hljs:not(.inline){border:1px solid #c8c8c8;border:1px solid rgba(200,200,200,.3)}.code-block-heading{background:#f2f2ff;color:#8787a5}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok looks good functional wise

let's clealy break off our custom styles as well to facilitate future changes

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I think I'll break it off to another line (but still in minified form), and add a short comment to indicate these are MarkBind-customized styles

@ang-zeyu ang-zeyu added this to the v2.17.0 milestone Oct 4, 2020
Copy link
Contributor

@ang-zeyu ang-zeyu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok looks good, thanks for implementing this staple : )


edited your commit message a little to reflect the expanded scope

@ang-zeyu ang-zeyu merged commit 9dc0a44 into MarkBind:master Oct 4, 2020
wxwxwxwx9 pushed a commit to wxwxwxwx9/markbind that referenced this pull request Nov 1, 2020
Markdown code is always presented on a light background.

Let's provide a dark style for this, and provide user configuration to
specify which styles to use.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Code fences / inline code: provide a 'dark' mode

3 participants