I’ve been using DEVONthink for some years now and it has become my “go-to-place” for external and internal documents and documentation. Great piece of software!
What I’m struggling a little bit with is own documentation using markdown files. Not on a technical basis, it’s more a readability issue for me or maybe just aesthetics…
Is there any way to apply the theme of “read the docs” to markdown files? An example layout would be
Especially the “Note” and “Important” environments.
I know that you can use CSS as a rendering template but unfortunately re-creating this template in CSS is beyond my capabilities.
One a sidenote - to manage expectations here - I’m not asking anyone to create this for me, but maybe someone knows if anything similar already exists?
and the following html code in the markdown document:
<div class="note">
<div class="title-bar"><span>Note</span></div>
<div class="box-content">
<p>Attempting to run powertop --auto-tune on boot may overwrite TLP's settings (depending on whether Powertop or TLP is invoked first in the boot order).</p>
<p>Furthermore, TLP will overwrite Powertop’s initial settings every time the power source changes.</p>
<p>Refer to How it works for details.</p>
</div>
</div>
<div class="important">
<div class="title-bar"><span>Important</span></div>
<div class="box-content">
<p>TLP applies maximum power savings on battery power only, so unplug AC power before checking with Powertop.</p>
<p>Powertop’s recommendations are quite schematic, they do not take into account frequently occurring problems with certain types of devices. For that reason TLP’s settings deviate from Powertop’s recommendations for a few but important exceptions:</p>
</div>
</div>
While adding divs to a MD document works (of course), it goes a bit against the whole idea of MD, namely to facilitate the production of HTML. If you’re writing HTML in MD, what’s the point of using MD in the first place?
That makes no sense. If you write MD, HTML is a normal citizen. That’s by design. Hiding it would make the MD completely unintelligble (what would you in effect want to see instead of the HTML?).
What we’d need would be block-level attributes like Hugo’s Goldmark renderer provides. Those are not generally available with DT’s MultiMarkdown 6. Therefore, @vinschger’s solution is one of the few possibilities you have. I’d probably go with less markup, though. Something like
<div class="important">
### Important
TLP applies maximum power savings **on** battery power only, so unplug AC power **before** checking with Powertop.
Powertop's recommendations are quite schematic, they to **not** take into account …
</div>
since there’s no point in adding a span inside a div as the only element. Here’s a (very simplistic) CSS for that:
What I meant with “hiding the HTML” was that you do not need to type this into the “unrendered” .md file. In my head I was thinking along the lines of “Prism.js” where you could just write
```language-bash
# some code written in bash
and have it rendered automatically.
So the “lazy way” in this case would be like
```box-important
TLP applies maximum power savings on ...
and have it rendered like in vinschger’s solution.
Does this make more sense?
But I understood form your answer that this will not be possible.
I’m sorry, but that makes no sense either. You’re talking about code fences now, and those are limited to a set of pre-defined languages (like HTML, CSS, JavaScript). And that’s not part of MD per se, but of prism.js (in the case of DT) or another highlighter.
You can’t re-purpose code fences for something like
```box-important
`whatever
```
since box-important is not a pre-defined language. Nor can you define it (without a serious amount of work, that is). And even if you could, it would go against semantic HTML, as code blocks are for code, not for arbitrary information. The best (I think) approach would probably be an aside element (instead of a div), since that is meant to stand out from the normal text flow.
I posted a simpler solution already that avoids all but one HTML element. Just make sure to keep all the empty lines in that example, they are crucial.
I understand that I just have not enough knowledge in this regard, that’s why I was asking for help. And vinschger’s approach and your improvement is already way more than I would have dreamed of getting as a reply on a weekend (or Monday morning - depending on your TZ ;-))
Thanks a lot for your feedback. I have only slightly adjusted the CSS code to my preferences (other padding, color of left margin). Wondering if @ThorstenG is happy with this
One recommendation to @ThorstenG You can use the text replacement feature of macos to enter this in your markdown code, e.g. by typing importantx so that this text block is inserted…
<div class="important">
### Important
text
</div>```
Yeah, that’s visually more appealing. Also better to use relative units for padding than pixels!
I forgot to mention that the choice of h3 (or ### in the markdown) is arbitrary. And from a semantic standpoint, using an aside element might be preferable over a div. That doesn’t change anything with the CSS as long as the class important is set for the aside element.
<div class="important">
### Important
First paragraph
Second paragraph
</div>
use
<aside>
# Important
first paragraph
second paragraph
…
</aside>
<div> has no semantics, so the blocks (“Important”, “Notification”, whatever) are considered to be semantically part of the normal text flow. Which they are not (why else would one want them to stand out this much?). Everything you need to know (as usual in this context) is at MDN:
This is relevant for several reasons:
A h3 element without a preceding h2 is not considered semantically correct
A screen reader might (I don’t know, though) just read out the “Important” div like any other text, which could be irritating
Also, I was wrong in assuming that one could use any heading in an aside element: The W3C examples use an h1 here, so I have modified the MD accordingly. CSS should also be modified to address h1 instead of h3 in this case.
