6 ms·
I spent some time exploring how to improve the UX of code blocks on the web
- milliams 5y agoI wish the "Click a highlighted word to navigate to a different page" was just an <a> tag rather than a JavaScript onclick handler.
- uberswe 5y agoI agree, I like to see where I'm going
- lovelydrop 5y agogreat idea! implemented, and updated the article. thank you.
- carlosperate 5y agoIt's also not easy to quickly identify it's a link, as the word highlight is the same as the previous examples. Maybe adding an underlines or something to make it slightly different might help with that.
- SamBam 5y agoRight, or a small "outgoing link" symbol (usually a box with an arrow coming out the top-right corner) next to it.
- extra88 5y agoYes, don't disable link underlines within the code blocks, let the default be. It's not like there's a competing convention for underlining within code blocks.
- Silhouette 5y agoIt might also be worth having those links opening in new tabs as an option. Right now, at least on iOS, following a link and then going back leaves you at the top of the original page again, not where you were up to before you clicked the link.
- extra88 5y agoIn general, it's better for sites to not take away from the user the choice of opening a link in a new tab or not. When I follow a link on my iPhone, when I use the Back button, the page is still scrolled to where it was before, which is my typical experience in mobile Safari.
- Silhouette 5y agoIn general, I agree. But if the link is a surprise because the styling isn't obvious and it might easily be tapped while trying to scroll content on a small touchscreen and it breaks normal back button behaviour, I disagree in this specific instance. All of those things were true in iOS Safari on my iPhone at the time I wrote that comment.
- macando 5y agoThe date on this article is June 02, 2021 Other than that, a great write-up.
- lovelydrop 5y agoloool, ooops. fixed, thank you
- AlexeyMK 5y agoThis is super well done & polished. Will try out for future blog posts. Thank you!
- lovelydrop 5y agothank you <3
- randomfool 5y agoDoes anyone know if there's a trick to avoid the trailing newline when double-clicking a line to copy/paste it elsewhere? This always annoys me for single-line commands. I'd love a CSS solution but can only think of some ugly JS approaches.
- alpaca128 5y agoI hate that too, and it seems to be a very common default behaviour of text selection. Even Vim does it when you copy a whole line. It's one of those little UI annoyances that refuse to disappear. Just like blinking cursors in unfocused input fields & windows.
- arthur2e5 5y agoIt probably ties into the whole “line ending not newline” philosophy of requiring files to end with an EOL character.
- Someone 5y agoI think that’s because, if you follow selection of a full line by a backspace/delete/cut, you expect the new line to disappear. Apart from undo state, you also want cut to be equivalent to copy; backspace.
- contravariant 5y agoI mean you can probably fix this with autohotkey. Whether this is a good idea is a whole different matter.
- carlosperate 5y agoThis is pretty good! One thing I wasn't able to trigger (or understand) was the "hover me" part from the "Interact with the content" section.
- coldtea 5y agoThere's not much to it. Ignore the "hover me" label, and just hover over the highlighted parts of the code. They change color on hover.
- blunte 5y agoViewer attention is increasingly limited these days, so avoiding small mistakes which limit your audience is recommended. Dark mode content such as TFA is practically unreadable outside in bright light. Your reader will need to remember to return to your page some other time when they can see it, but chances are they will not return.
- marcusbuffett 5y agoLooks great! I'd add a Copy to Clipboard button somewhere, since that's such a common use case when showing code
- metalrain 5y agoIt's looks great. I think for me biggest problem with code snippets is that I encounter them with mobile device. Lines are quite long, like who uses 80 character line limits these days, more like 160. This combined with reality that most websites don't allow mobile device to zoom out. I wish I could read full lines of code instead of trying to scroll back and forth.
- sneak 5y agoI hard wrap at <=80 columns, and enforce those standards in codebases and in CI. Prettier's default is 80, and I don't change it. I have three huge monitors, but long lines just makes most of the right-hand side of an editor window wasted. Text files (source) are documents, and documents are much taller than they are wide: portrait orientation, like letter or A4. My two side monitors and oriented in portrait mode for this reason, and their quadrants (also portrait) are where I put editors. I made this comment not to show my age, but to overcome the loudness bias of trends. There are plenty of us out here who still do it the old way, because the new way isn't better.
- manigandham 5y agoThe new way is to make the lines as long as a human needs it to be, and use the computer to automatically wrap them when you need a narrower view.
- sneak 5y agoThe Linux kernel style guide expresses a different rationale.
- jraph 5y agoEven 80 characters could be too long for some screens / font size. Long lines could be broken (like white-space: pre-wrap does), with an indicator that the line has been broken at the beginning of the continued lines. This is what Kate does and I think it is a good default, better than having to scroll horizontally.
- 5y ago
- jraph 5y agoThe best feature for me is that it works well without JavaScript. The document is still a document. Except for collapsed code blocks. I would suggest collapsing them using JavaScript, so they are fully readable without. They are currently unavailable to someone who does not run JavaScript.
- sergkop 5y agoNice! Here is another collection of ideas on improving code blocks https://co-pilot.dev/docs-code-block https://co-pilot.dev/docs-code-block
- zalo 5y agoWould be nice to see Intellisense-style hover tooltips on code-blocks someday (via referencing a `.d.ts` or `.ts` file). There might be some minimalist way to get Monaco into read-only mode for it...
- eyelidlessness 5y agoThis exists! But with a slightly different set of libraries than the highlighter used by the post author: remark-shiki-twoslash[1]. Shiki tokenizes using the same language definitions as VSCode, Twoslash uses the same language service. 1: https://www.npmjs.com/package/remark-shiki-twoslash https://www.npmjs.com/package/remark-shiki-twoslash
- l0b0 5y agoExcellent work, although the "hover me" doesn't do anything in Firefox 88 on Linux.
- lsiebert 5y agoor on FF 88 on Mac
- Groxx 5y agoPossible bug? The `hover me` seems to be implying that hovering that text should highlight something in the code sample, but nothing is happening. I assume that's the goal anyway - mouse over sections of explaining-text to see the highlighted-code that's relevant. (both "highlight word" and "highlight lines" could be handy here. tbh I'd probably use "highlight lines" more often) Ignoring that: this is pretty nice looking, both the explanation (clear and with good examples) and the component itself. Good work!
- chrismorgan 5y agoFor the highlighted code, you’ve made unhighlighted lines look more like comments than merely deemphasised lines. One alternative style that I’ve found effective in such situations is to reduce the opacity and partially desaturate: -.sx5jq50 .highlight-line[data-highlighted="false"], .sx5jq50 .highlight-line[data-highlighted="false"] * { - color: var(---fadedLines); -} +.sx5jq50 .highlight-line[data-highlighted="false"] { + opacity: 0.5; + filter: grayscale(0.6); +} But I have always found adding a yellow background to the line to be by far the most effective (that is, the most likely to be read and understood correctly without explanation), most likely combined with opacity reduction and/or desaturation. And yes, specifically yellow will normally yield the best results. (There may be cultural factors to weigh against this recommendation, but there’s also some actual colour science supporting it. I’d definitely avoid red and green for normal highlighting in western culture, though it’s great for removed and added lines in diffs—but do remember the colourblind and not make colour the only indication.)
- ahurle 5y agoAgreed on highlighting with a different background color. Unfortunately, it can be difficult to find a background color that is different-enough from the usual background while maintaining a high enough contrast with the text sitting on top of it. This is especially true if your syntax highlighting color palette covers all the hues you could use. So here's another protip: Make the highlight pop with a brighter left-border, so your background color doesn't have to pop so much on its own and you have more wiggle room to maintain contrast. Something like what mdx-prism has in their readme image [1], though I don't like the specific blue-on-blue colors. This blog article [2] has an example in the middle with nicer colors. [1]: https://github.com/j0lv3r4/mdx-prism https://github.com/j0lv3r4/mdx-prism [2]: https://leerob.io/blog/mdx https://leerob.io/blog/mdx
- o_____________o 5y agoGreat job! Would be nice to see a docusaurus plugin for this.
- yuchi 5y agoAnd this is the power of MDX (and some great focus from the author of course). I’m having a hard time trying to understand why some people seem to dislike MDX, it is the holy grail of web authoring imho.
- spankalee 5y agoIt's because "standard" Markdown and many other formats already support HTML. If these kind of components were vended as standard web components, they could work in existing Markdown files and workflows. My team is also working on code sample editor and preview components, but as web components for this reason: https://polymerlabs.github.io/playground-elements/ https://polymerlabs.github.io/playground-elements/
- ahurle 5y agoI'm curious why you avoided using mdx-prism in favor of re-implementing much of it yourself. If only because I just used it in my own project and spent time patching a minor Firefox-specific bug, and now I have FOMO because I like your implementation here :) Were your features impossible without huge changes? I do like that you use the `line=1-3` syntax for highlighting instead of mdx-prism's `lang{1-3}`. Do you have any appetite for upstreaming that change?
- cryptonector 5y agoTIL I like turquoise themes.