Styling Computer Source Code

Format your code

No matter how nicely you style the code, it won't matter if the code looks sloppy. Make sure it uses a consistent indentation style and is flush-left.

Make sure your "smart punctuation" is smart

Many blog engines rewrite content to improve typography: smart quotes, changing dash to a Unicode minus-sign, etc. This looks great in normal prose, but make sure it's not doing this to code blocks. If someone cut and pastes your code, it won't work. Historically a number of popular platforms destroyed code blocks.

Use a modern monospace system font

On most browsers the default monospace font is something horrible like Courier, or worse Courier New. These are really unsuited for computer code. To fix this you don’t need use a web font, with it’s inherit complexity and performance costs. Your computer and your visitor’s computer already has a number of excellent monospace fonts that are usable in CSS. I’ve written about these native font stacks a few times, but in summary, this is what Bootstrap uses:

code, kbd, var {
  font-family:
    SFMono-Regular,
    Menlo,
    Monaco,
    Consolas,
    "Liberation Mono",
    "Courier New",
    monospace;
}

This will make your code look great, no matter what platform your visitor is using.

Watch out for line breaks

By default HTML will treat white space and the plain dash as a good place to insert a line break. This can cause a mess. For example:

to prevent writes use the flag <code>--dry-run</code>

can render as any of the following:

to prevent writes use the flag --
dry-run
to prevent writes use the flag --dry
-run

Prevent this by setting the CSS property of white-space to nowrap.

/* for inline code */
code, kbd, var {
  white-space: nowrap;
}
/* for large code blocks */
pre>code {
  white-space: pre;
}

Handle embedded tabs

If you do use tabs or if they sneak in by accident, you can control how much space they represent using this ancient CSS property tab-size:

/* set tabs to 2 spaces */
tab-size: 2

If you never use tabs, then consider setting this to large number to intentionally throw off the design so you can find and delete the hidden tabs.

Update 2018-05-01: IE does not support tab-size, according to caniuse.com.

Tone down the syntax colors

There are many reasons to colorize source code when editing. There are far fewer reasons to do so when excerpting 10 or 20 lines for reading. A good use of color is for keyboard session transcripts where you are distinguishing between request and response. Another good use is to distinguish between the code and the code comments. Beyond that, syntax coloring is chartjunk for computer code.

If you must do it, use server-side rendering instead of client-side. It's not worth the cost of loading another JavaScript library and having the style flash in. It's more important that your site load and perform quickly than coloring keywords.

Cleanup GitHub gists

For longer code samples, using GitHub’s gist service can make a lot of sense. A small script tag is all that is needed to embed your source code in HTML and many blog template engines support gist shortcuts to do this as well.

However, the default rendering has lot of chartjunk -- line numbers, excessive coloring, and what’s with that weird GitHub footer? Fortunately, it’s not a science project to clean this up. Will Boyd has written everything you wanted to know about customizing GitHub gists, as well as a number of sample themes.