CSS for Markdown, write your own

This is the third part of some posts on using CSS in and with DT/DTTG. Though I wrote it as a single piece, I broke it up in smaller installments to keep the posts (barely) managable. Please let me know (preferably by a PM) if you find errors of any kind or are missing details. I’ll correct the first ones and try to help with the second ones.

Previous post | Next post

Delving deeper into CSS

CSS is a complicated beast, and it’s getting more so every day (no thanks to Google inventing and implementing new exciting stuff). The only authoritative documentation is the one at the W3C. However, that’s unwieldy stuff not meant for mere mortals. There are numerous websites out there providing easier to digest examples and reference material, notably CSS tricks and the Mozilla Developer Network.

Structure of HTML generated from Markdown

The good news is that the HTML generated from Markdown is fairly simple. It contains only HTML elements without any classes or IDs. Also, the number of elements is quite small, so you won’t see the fancier stuff like aside, nav, section and the like, nor any divs wrapping elements. Basically, a HTML document generated from Markdown, has this structure:

  other elements

where other elements can be lists or tables. All elements except head and body can repeat any number of times. Links and images are just rendered as shown above inside a p element. This simple structure makes styling HTML generated from Markdown quite easy, at least compared to a full-fledged HTML document.

Lay out the foundation

To start from scratch, I suggest to set all relevant values to reasonable defaults on the body element. This is sometimes referred to as a CSS reset. Of course, it is up to you what you consider “reasonable”. Something like this might be a starting point:

body {
  margin-left: 2em;
  font-family: "Century Schoolbook", Times, serif;
  font-size: 1em;
  color: black;
  background-color: white;
  padding: 0;
  max-width: 55ch;

The choice of the font-family is very much a metter of taste (more so then everything else, probably). Here, I went for a serif font: “Century Schoolbook” is used if it’s available. Otherwise, “Times”, and if that’s also missing, the default serif font. Also, I specified a font-size of 1em, which is exactly the same as the font size specified for the user agent (aka “browser”) used to render the HTML. This is not strictly necessary, but it makes sure that the default text size in your HTML is the same the user specified in their browser settings.

To make the text easier to read, the maximum width of the body element (and all its children!) is set to 55ch, that is 55 average characters (loosely speaking). padding is the inner margin of an element that will remain blank, whereas margin is the space between the current element and its parent. Here, I specify a left margin of 2em so that the text does start flush left.

Fine-tune HTML elements

These styles for body define a baseline. Now you can specify differing styles for other elements to your heart’s content. For example, if you’d like the first line of every paragraph to be indented by an em space, you could use

p {
  text-indent: 1em;

or if you’d want all first level headlines to have a red underline

h1 {
  text-decoration: underline red;

or if you’d want all third level headings to appear in uppercase

h2 {
  text-transform: uppercase;

The latter, though, is probably not a very good idea – firstly, all uppercase letters are more difficult to read, secondly many readers will think that you’re screaming at them. And thirdly, the text looks fundamentally different than what you see in your Markdown document.