A Matter of Style - Markdown

[BLUEFROG]

This is a small discourse on Markdown styling in DEVONthink 3, to help people understand the styling methods and the cascading effect of styling.

This is a simple default stylesheet, chosen in Preferences > Files > Markdown > Style Sheet.

Note it’s setting some basic parameters for paragraph elements, much of what we type in Markdown. A little padding and a colored rounded rectangle around the paragraph.

You should notice there is no font information specified in this stylesheet. This means the default font specified in Preferences > Editing > Rich Text & Note Font will be used in the rendered Markdown.
You can see it’s Times Roman 14 here.

Creating a new Markdown document with no stylesheet specified in the Markdown yields this…

We have the colored rectangle around each paragraph and the font is clearly Times.

---

We can create another stylesheet. This is one I put directly in a DEVONthink database. Here we have specified a different background color and a border.

Notice the new stylesheet has no information about the rounded rectangle, but the rounded rectangles are shown. This is being picked up from the default stylesheet.

---

Lastly, we can add internal styling in the Markdown document…

Notice this is picking up the color from the stylesheet in step 2 above - not from the default stylesheet as we have linked the stylesheet in the top of the Markdown - but we have overridden the font and modified the border.

---

And to show the effect of the default stylesheet, I removed the it from the Media preferences. This is the effect on the last file (and yes, it affected the second file too)…

You should see the padding is gone - as it wasn’t specified anywhere else. However, a background color was specified in the second stylesheet, so it’s present here too. But again, the internal styling gave it a blue dashed border instead of the magenta one specified.
…

There is no requirement to use a default stylesheet. (I personally don’t.) If you’d like to use one, for a generally uniform appearance of your rendered Markdown, go ahead and use one. However, the cascading effect allows you to use override styling on a case-by-case basis.

I hope this helps illustrate the flexibility you have with Markdown styling.

[Hankk2]

Super useful reference – thanks Bill.

[BLUEFROG]

You’re welcome… said Jim

[brookter]

That’s very helpful. Thanks!

[jdharper]

Thanks a lot for this, it’s exactly the info I’ve been looking for as I’m learning about using Markdown in DT.

I have a question about the “CSS: x-devonthink-item” method of linking the stylesheet. I really like this because it allows for moving the stylesheet anywhere I want without breaking the link in the md file.

I played around with this and I’m not sure if this is a bug or intended behavior. I copied a link to the stylesheet and pasted it in the top of the md file then pressed return and it created a clickable link back to the stylesheet as shown below. If I don’t press return, the link is not created.

I can click the link to open the stylesheet (which works), and when I click the back arrow to go back to the md file the link is gone as shown here:

Also just switching between source and preview make the link disappear.

Is this the intended behavior? I really would like the link so I can easily open the stylesheet for editing. I did see that I can highlight the URL, right-click and select “Open URL” to take me there as well but it’s a lot slower.

[BLUEFROG]

Glad it’s helpful!
Development would have to comment on the display and behavior of a link in plain text.

[cgrunenberg]

Did you enable data detection (see Preferences > Editing or menu Edit > Substitutions)? In that case macOS scans the plain text for links, e.g. after editing or pasting, and highlights it. But on 10.14.5 it’s IMHO not that reliable, just like Edit > Substitutions > Text Replacement - sometimes it works, sometimes not. YMMV.

[jdharper]

Just checked and, yes, data detection is enabled. I’m running 10.14.5.

[Demogorgon]

What great news!

Well, “I’ve got a good new workflow going now,” as they say, which includes dumping MD files into DevonThink. I noticed that your blockquote likes to use italics, which I need to remove since I’m using italics as italics inside the blockquote.

So I made a CSS override I told your Preferences where to find it and … well, instead of my simple:

blockquote {
    font-style: normal;
}

just getting rid of the italics, it instead got rid of all your (lovely) CSS styling, 90% of which I’d like to inherit.

Could you please tell me where I might locate DevonThink’s Markdown.CSS file inside the application’s Package Contents? Or is there some other way I can inherit? My plan was just to copy and paste your builtin and just make modifications.

Thanks!

[cgrunenberg]

@Demogorgon

Could you please tell me where I might locate DevonThink’s Markdown.CSS file inside the application’s Package Contents?

There’s none, it’s automatically generated depending on the preferences. But you could convert the file to HTML and check its source.

[chrillek]

I tested with one of my MD files. In the MD preferences, I set a custom style sheet using an x-devonthink-item URL. That works fine within DT, but converting the file to HTML and then opening that in Firefox does not load my style sheet (as probably is to be expected, since FF doesn’t know about x-devonthink-item URLs?).
There are not other styles in the HTML, except for the ones added by Prism.
What I can see in the head element:

• <link rel=“stylesheet” src=“x-devonthink-item…”>
• <style> … Prism code
• <script> … Prism code
• <meta charset=“utf-8”>

What I’d suggest: Put the \<meta charset at the top of the head element. Firefox at least expects the charset declaration in the first 1KB of the page, and it comes a lot later now if Prism is included.

Then add DT’s internal styles followed by an included x-devonthink-item stylesheet, given that browsers probably can’t access them anyway. Then prism.css and prism.js (although I’d include them only if there are codeblocks present, but that is a matter of taste).

That way, a user stylesheet can override DT’s defaults (and only those it wants to override). And using a link element with an x-devonthink-item URL to include a user stylesheet is a bit pointless outside of DT, so just use style and include the styles verbatim (like in the case of prism, btw).

[Demogorgon]

OK. Thanks.

[cgrunenberg]

@chrillek

In the MD preferences, I set a custom style sheet using an x-devonthink-item URL.

My suggestion was only valid if there’s no stylesheet specified by the user in the preferences (as this replaces the internal stylesheet).

[chrillek]

I’d suggest to change that from „replace“ to „augment“. In the spirit of the C in CSS: cascading.

[cgrunenberg]

Actually the internal stylesheet is not used at all if there’s a custom style sheet.

[chrillek]

I got that already and tried to suggest another behavior in the future. The OP wanted to modify only the styling for block quotes, which is bit possible right now. Always loading the default style sheet and loading the user-defined over later would make exactly that possible: override those default styles that one wants to change and leave the rest as it is.