CSS for Markdown, the basics

[chrillek]

This is the first 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.

Next post

Why would you care about CSS?

CSS stands for Cascading Style Sheets. It is a text format that allows you to describe the visual appearance of HTML documents. In DEVONthink, CSS is used to determine the visual appearance of Markdown documents when they are rendered as HTML. Whenever you select the preview mode to look at a Markdown document, you’ll see it rendered as HTML in some kind of “style”: Foreground and background colors are set as are the fonts and their sizes, indentation and linespacing and so on. Unless you do anything about it, this will be the style that is built into DEVONthink (and the HTML engine it uses). If you’re happy with that, you can stop reading here.

How can you tell DEVONthink to use your own CSS?

As of the time of this writing (DEVONthink Pro Version 3.8 and DEVONthink To Go 3.5.1), there are four methods to specify your own CSS in DEVONthink:

1. In the global preferences. In DEVONthink, you’d provide the x-devonthink-item URL to a record stored somewhere in your database(s) and containing your CSS. In DEVONthink To Go, you do the same in the settings for Markdown documents. A globally defined CSS will influence all Markdown documents in DEVONthink.

2. Add css: URL as the first line of your Markdown document(s). The URL can be any valid URL as well as an x-devonthink-item://... one or an absolute address of a record containing your CSS defintions like /Inbox/myCss.txt.

3. Add a HTML script element somewhere in your Markdown document, i.e. a piece of code looking like that
   <style> Style definitions go here</style> If you go for this option, make sure that you do not have any empty lines in the style element. Those will break everything.

4. Add a HTML link element to the top of your Markdown document like so <link rel="steylsheet" href="URL"> Again, the URL parameter can be anything from a usual URL to a x-devonthink-item://... one or an absolute location like /Inbox/myCSS.txt.

The last three methods will add CSS only to those Markdown documents where you insert them. So they’re not really useful if you want to make sure that all your Markdown documents look the same.

Caveat: DEVONthink 3 and DEVONthink To Go currently handle global style sheets (i.e. those set in the preferences) slightly differently. While DEVONthink replaces its own pre-defined styles with those of the style sheet, DEVONthink To Go has your styles always uses its pre-defined styles, only overriding those that you define globally. This behavior may (and should, I think) change in the future so that pre-defined styles are preserved unless overwritten.

[Archimedes]

I found this series of posts very useful. I’m quite experienced in using CSS, but this is the first time I’ve used it for markdown.

I modified a CSS file based on A CSS to embellish *MultiMarkdown* rendering, created a ‘Global settings’ database, put the CSS file there, and used the x-devonthink-item link in the DTP preferences.

I also put a copy in my ‘~/Global settings’ folder so it is globally available no matter if DTP is running. The reason for this is that I have a quicklook handler installed which displays a markdown file when you quicklook. This handler is available in a number of ways:

If you use macports, type ‘sudo port install QLMarkdown’ in a terminal window.
If you use homebrew, type ‘brew install --cask qlmarkdown’, or copy the zip file from GitHub - toland/qlmarkdown: QuickLook generator for Markdown files. and put the result in /Library/QuickLook (or ~/Library/QuickLook if you want to make this change limited to a single user).

Once it is installed, you can go to /Library/QuickLook/QLMarkdown.qlgenerator/Contents/Resources and replace ‘styles.css’ with a soft link to wherever you put your modified css file (you will have to choose ‘Show package contents’ from the context menu when you get to QLMarkdown.qlgenerator). If you don’t want to use a soft link, you can simply replace styles.css with your new CSS file.

Now getting a quicklook for a markdown file will use your new CSS rules, and the appearance matches what you get in DTP.

[BLUEFROG]

Nice! Thanks for sharing your process and the handy tip.