1. 16

I cannot find a satisfying solution for how to cleanly present blocks of code on a personal website. Over the weekend I read two books about typography and then some, but found nothing that talks about presenting code.

Maybe people here have advice on how to make code look both distinct from the body of text, and not jump out too much at the same time? Or examples of websites that in your opinion do it well?


  2. 7

    If you’re talking about code blocks, I always set them like my block quotes. If it’s inline code, try and find a code font that has around the same x-height as your body text. If the family you’re using had a monospace variation, that’s probably your best bet as it will have been have designed to look good with the rest of the family.

    Aside from general advice, could you share some screenshots? The x/y problem exists in design too. 😅

    1. 2

      Oh I am still experimenting, HERE is the current version, and HERE is the same for a trickier situation where the output is displayed below the code. But it is “work in progress” and the design will probably be changed again. I tried too many things this weekend, will need to take a break before revisiting this question later.

      But I am interested in the general principles too. The thing is - I have several example websites which look lovely in terms of text typography. But I don’t know of any actual website where I would say “yeah, this one has code display figured out”.

      1. 7

        I think it looks fine. You can play around with this forever, but IMHO you quickly get diminishing returns and just gets a distraction from actually writing content.

        For me, the biggest issue I try to avoid is horizontal scrolling, as I find that’s just annoying.

        1. 5

          I wrote an essay with a bunch of code-blocks in it, and I think they turned out alright. Unfortunately for typesetting code, there’s a bunch of conventions that collide:

          • Prose text wants to run about 60 characters per line
          • Code is typically formatted about 80 characters per line (since there’s often significant indenting and short lines)
          • Your code typeface should be about the same size and shape as your text typeface

          Personally, if I’m writing code for an article, I compromise on the second one and wrap my code at 40-60 columns. It feels a bit cramped, but I can present individual code-chunks and provide context in prose, rather than having to present a big lump of code that provides context through indentation (and thus requires wider output).

          For the absolute details of formatting, it looks like you’re going minimalist for your text formatting, and so the complexity of your code formatting (background colours, borders, and occasionally horizontal scroll bars) feels distracting. For the examples you’ve posted, I think just removing the borders makes them look much better.

          1. 1

            The style of code blocks in your essay look very well and even original. Very nice. Thank you for the comment as well, I found your opinion about conventions that collide to be true. The way I try to solve it is by reducing the font size of code blocks.

            And yes, I am trying to be very minimalist but when I just indent code it doesn’t stand out as much as I want it to.

          2. 2

            CSS Tricks, possibly?

            Looks like you’re using a different size for your code. Even if it’s the same pixel value it’s perceptually different. Adjusting it until the Bowls of the lowercase o are about the same actual size might be a good way to go. It also looks like there is some margin around your inline snippets—that may look more jarring because it is literally offset from the flow of the text.

            1. 1

              In fact yes, CSS Tricks is pretty good. https://css-tricks.com/almanac/properties/f/flex/

              The inlines are separate but flow well

              1. 1

                CSS Tricks work for their case. I tried dark background similar to what they have in this example. However it only works when your syntax has a lot of colors. If you use one color for text it doesn’t look good against the dark background.

                Regarding margins - the margins in the example should be consistent between paragraphs as well as paragraph and border of the code block. It looks off in the example I gave because all the paragraphs are one line in length :) I think it will not look too jarring with normal blocks of text like HERE

        2. 6

          This isn’t specifically related to typesetting code, however I highly recommend checking out Matthew Butterick’s Practical Typography, an incredible online resource. It goes into more detail about typesetting in software and for screens compared to “traditional” typography resources.

          Here’s some advice I pulled from thin air just now. Try using a type family that has both a proportional and a monospaced variant, this is the easiest way to get them to match since it’s already been done for you. Some open source ones I quite like are IBM Plex and Fira Sans/Mono.

          If using a consistent type family isn’t an option, then the usual rules for mixing and matching fonts apply. The weights should be largely the same, and you might need to adjust your text size so that the x-height of letterforms matches up. This makes the transition from one font to another less jarring.

          Another common piece of advice is to avoid mixing fonts that look too similar since the end result can look off, but this is probably not an issue here since there’s inherent contrast between a proportional and a monospaced font. Often you might want to choose fonts that have similar letterforms though, both double-storey and single-story a’s on the same page can look jarring as well and affect readability.

          1. 2

            So I managed to find one page where Matthew Butterick used code himself: HERE. However it is hard to imagine it working in general: his examples are all very small and less than 40 characters long. Anything above 40 would not fit in this example.

            1. 4

              Check out his book “Beautiful Racket”, which is full of code.

              1. 3

                Very interesting that he is doing a very similar thing that I am currently doing - light background with top and bottom borders. Looks like I was influenced by the ideas in his typography book and somehow came up with the same decision he did without seeing it..

                1. 2
            2. 2

              I just started reading a few pages of that Practical Typography, and it does strike me as sort of an incredible book. As I say that, I balk and think that perhaps “incredible” is too extreme a term, but yet, it’s the term that came to mind. Anyway: thanks for sharing it.

              1. 1

                Thank you for a long reply. I read the book you recommended during the weekend, but it didn’t talk about presenting code at all. Which was a bit strange, since the author seems to have an IT background and he talked about various little details, like presenting lists, headers, tables, block quotes. Seems everything BUT code.

                Regarding fonts - the advice is taken. Big thank you for that. But I am also interested in other aspects of it, like: indent or don’t indent. Should it have a distinct background color? Does font size and line height need to be the same or smaller, etc.

              2. 4

                One thing to avoid is to switch between light and dark backgrounds. I guess programmers are tempted to do it if they are used to coding in a dark terminal. It is more tiresome for the eyes though.

                1. 3

                  You ought to write the code to suit its purpose. Normally code is written to be run, but in your case you’re writing code to be read in a fairly narrow context. Adapt your line length to that. If you insist that the code have very long lines you make your problem more difficult than it needs to be.

                  You have to use a pair of fonts that work. The code font should be different enough from the text font, but not too different. This is difficult, really difficult. Courier IMO never works with any other font. If your code and text fonts are very close in appearance (e.g. from the same font family), you can increase the contrast a little by reducing the code font size by 5%.

                  If your design is lively, you can use a different background colour for the code, but if you only have one background colour that won’t work, again in my opinion. Look at Stack Overflow, which uses five different background colours, one of them for code. That works. If code is important, you might even consider using a little more background colour for other elements, so you can use it for code without skewing the design. It’s also possible to use just a border around the code blocks.

                  Some people add line numbers for the code, which gives you additional contrast. I find that using e.g. Documenta for the text and Documenta Sans for code works if you have line numbers. (I’ve used that combination on paper, never on the web.)

                  1. 1

                    Thank you for a reply, exactly what I was asking for.

                    In particular the comment about background working only in cases where there are other colors, like stack overflow, is, I think, right to the point. I tried removing the background entirely in my case, it looks somewhat better, but with longer code blocks it becomes harder to track where code starts and where it ends.

                    And I hadn’t considered adding line numbers, good point.

                    1. 1

                      I didn’t mention box shadows, but they are another possibility, onscreen at least. And I’ve never seen it used for code, but of course animation exists and could be used. For example by using a discreet box shadow, and making the box shadow a little more pronounced when the cursor hovers over the code.

                      1. 2

                        It’s been a few days now, and I took your advice in the first sentence to heart:

                        You ought to write the code to suit its purpose

                        I think it has to be said that for some types of problems, to make it more readable, content has to be changed instead of style. If you are curious HERE is how it looks now. I no longer use code block to mean exactly runnable code. The code blocks on that page for example often have two distinct commands displayed side by side for comparison. Found this to be much more readable compared with them coming one after the other. And it serves the purpose of the article really well.

                        So thanks a lot for your reply, it really helped.

                        1. 1

                          No, thank you.

                          It’s so rare that someone a) pays attention when I speechify about code and writing and documentation and blah b) acts on it c) achieves a good result (I think your output is now exemplary) and d) says thanks. You made my day.