CSS for Markdown, the beginning

DEVONthink Tips
1

This is the second 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

What does CSS look like?

A style sheet is a sequence of definitions of the form

selector: {
  attribute1: value1;
  attribute2: value2;
  ...
}

where selector specifies the HTML elements to which the following definitions are applied. Note that there must be a colon between the attribute and its value, and that there must be a semicolon after the value.

All that selector and attribute stuff might sound overly complicated, so let’s consider a simple example:

body {
  color: black;
  background-color: white;
}

These lines make sure that the body element of an HTML document appears black (color) on white (background-color). As styles are “cascading” (the C in CSS), this simple definition ensures that all text in your rendered Markdown appears black on white – all elements are children of the body element and by default inherit its style definitions.

With these definitions, you will not notice any difference in the appearance of your document:

Kein-Stil
Kein-Stil1042×1030 109 KB

So what would you do if you wanted to make quotes appear indented and with a different background color? You’d have to define these attributes for the element blockquote:

blockquote {
  background-color: lightgrey;
  margin-left: 2em;
}

The background-color should be obvious. left-margin defines the distance of the left edge of the element from the left edge of its parent element. So here, this distance is 2em, which means “two em spaces”. An em space is a typographical unit that is as wide as the font’s height.

Refrain from absolute units!

In many CSS examples, you’ll still find units like px, for example something like margin-left: 10px. While it might be tempting to use these absolute units, you should in most cases not do that. Instead, employ relative units like em or % or ch (number of characters) or vw (percentage of the viewport width). These allow for a “responsive” layout, i.e. one that works well with different screen sizes and orientations. Pixel sizes vary widely from one device to the next and do not work well if the user zooms in or out.

Note that % values always refer to the enclosing element’s (i.e. the parent’s) dimensions. In the case of font-size, a percentage value also refers to the font size of the parent element.

You might have wondered where the blockquote element came from in the second example above. There is a fairly simple relationship between Markdown markers and HTML elements as shown in the following table (click on the :arrow_right: to reveal it).

Relationship between Markdown and HTML elements
Markdown HTML element
Newline separated text <p>text</p>
# <h1>...</h1>
## <h2>...</h2>
### <h3>...</h3>
and so on until ###### <h6>...</h6>
- <li> as children of an <ul>, content of the li is wrapped in p elements.
1. <li> as children of an <ol>, content of the li is wrapped in p elements.
> <blockquote>...</blockquote>, content wrapped in pelements.
[text](URL) <a href="URL">text</a>
![text](URL) <img src="URL" alt="text"/>
|…| <table>...</table> with all appropriate child elements

Debugging CSS and playing with It

While it is possible to change an external CSS, switch the view in DEVONthink and then go back editing the CSS until the results please you, that is a bit tedious. A simpler approach is this:

  • convert your Markdown document to HTML in DEVONthink
  • open this new HTML document your favourite browser
  • right click somewhere in the document and select “Inspect element”.

That will open the developer tools of your browser (you might have to enable developer mode in Safari first, though). There, you’ll find a “style” tab in which you can easily modify the styles for all elements individually or change the definitions in your CSS and see the changes immediately in HTML.

6 Likes