How to use Markdown Extensions offline

How to use Markdown Extensions offline

For all using Markdown, Math and Code in Devonthink (ToGo) 3.

What you get

Offline updatable and customizable markdown theming, Mathjax, and Prism.js code highlighting and theming (again).

Motivation

  • DT 3 added an option for an app-wide Stylesheet, and online Mathjax, Prism support. But this does not work in DTTG 3
  • Also if you use the Mathjax option in the settings, some font stretching may occur
  • So if you use your own script html (which allows you to set Mathjax options) in the beginning of every markdown document, this can get long and if it needs to be updated – well – good luck I guess
  • Meanwhile this all still needs the internet to work and so your research field trip may suffer some inconveniences
  • Same goes for Prism.js

Solution
Thanks to file transclusions we can now do the following:

  1. Create a folder at any location in Devonthink (you can move it around later, so don’t worry too much about the perfect location)
  2. Create a Plain Text document in the previously created folder and name it MyMdStyle.css (name it like you want, only the .css extension is important)
    • In this document you can paste or write your custom css style theme
  3. Next create a new Plain Text file and name it MdHeader.txt
  4. Write this in the first line of the MdHeader.txt file:
    • <link rel="stylesheet" type="text/css" href="ABCD">
  5. Right-Click your MyMdStyle.css file and select Copy Item Link
  6. Select the ABCD and press CMD + V to replace it with the unique item link
  7. Up next: Mathjax
  8. Go to Mathjax on Github and download the repository
  9. Unzip it and move the es5 folder into the folder created in step 1 in Devonthink
  10. Now same as for the style sheet, put the following in the next line of the MdHeader.txt file:
    • <script type="text/javascript" src="ABCD"></script>
  11. Again replace the ABCD with the item link of any of the tex-abcd.js files
    • I use text-svg-full.js to prevent the stretching of the math fonts (see the sum symbol in the image above)
    • More info on the Mathjax options can be found in the doku
  12. Last but not least: Prism code highlighting
  13. Go to the Prism website, select your languages, your plugins (can be tricky) and your theme and download them (at the bottom of the page are links for the prism.js file and the theme prism.css)
  14. Put both in your trusty folder in Devonthink
  15. You know the drill by now, …
    • add <script type="text/javascript" src="ABCD"></script> for the prism.js to your MdHeader.txt file and replace ABCD with the item link
    • do the same with <link rel="stylesheet" type="text/css" href="ABCD"> and the prism.css file
  16. The order of the lines can matter so if something does not look right, you can change them any time
    • for me works first line: Prism style sheet, followed by the Prism script, then Mathjax script, and the regular style sheet at last
  17. Finally, copy the item link of our trusty MdHeader.txt file and put {{ABCD}} (ABCD is the item link) in the beginning of your markdown files (you can create a template for that, so future .md files have it already)
    • Now you can customize and update your stylesheet, Prism and the Prism stylesheet, and Mathjax at any time by just replacing the item links in the MdHeader.txt file
    • This will work with DTTG 3 too (remember you need to install your favorite fonts on the iPad / iPhone through certificates [there is maybe a way to include them and load them with item links too])
    • Remember to not delete the MdHeader.txt file or the item link will change and you have to update them in all your markdown files manually! (but you can move / rename the folder / files any time)

Your result should look like this:

You can get Mermaid support too:

  1. Go the Mermaid Github page and download the repo
  2. Find the mermaid.min.js file in the dist folder
  3. Add it as a script like shown above for Mathjax

I hope this helps and happy note taking!

4 Likes

Aren’t your questionable and happy face examples switched? The questionable summation symbol, to me, is the proper one, the happy face one is stretched.

Stretched was maybe the wrong word, it tries to use an installed font in the middle example, while the last one is a svg of the nicer looking latex fonts (you can see this on the ‘n’). Typora and other editors show it like in the bottom example. Still depending on the font size there can be distortion. In the end it is a taste thing I guess :slight_smile: .

Thanks for the post. Incidentally, support for the Markdown extensions are coming to DEVONthink To Go.

3 Likes

I’m ignorant of css and it’s uses in and out of DT but I was wondering if the above method could be used to get the highlighting in the Fountain film/TV script writing extension of Markdown?

I use Atom to write in Fountain format and to generate PDFs in the acceptable format. 95% of this I do on a laptop within reach of a printer.

I can write in the markdown in DT and paste it into any number of Fountain translators to make a PDF when I am on the road and only have a phone or iPad at hand. If it were possible to at least see the format highlighting/colours that Atom shows you in DTTG that would make the few times I have to make changes on the road a little easier.

Fountain is an extension in itself, not just some CSS styling.
DEVONthink supports MultiMarkdown.

OK. I am not sure if this is any different than an extension but is Fountain Syntax Highlighting as described here
https://github.com/poritsky/fountain-sublime-text something that could be done in DT?
I am not looking for the PDF generation or the formatting of Fountain, just the syntax colouring based on the Fountain scheme. I am guessing this isn’t

  1. possible or
  2. a priority

but I’ve been reading tons of posts about Markdown (and a bunch of Devonthink stuff I didn’t know about, i.e. Imprinting/Stamps, WTF, Devonthink is DEEP!) and trying to understand how all this technology works.

This is fantastic. Thank you for posting this detailed explanation.

1 Like

Just a note about DEVONthink 3 on a Mac: I discovered that in order for this method to work, I had to turn off the MathJax support setting in DEVONthink preferences (in the Media tab, in the Markdown section).

Prism didn’t seem to be affected either way; it worked with my custom Prism css/js whether I enabled it in DEVONthink or not. But not so for MathJax: it didn’t work at all until I turned off DEVONthink’s MathJax checkbox in the preferences.

Yes, DTs markdown extensions should be disabled in the settings.

My guess is that DTs extensions do their magic before the other scripts can be executed. Maybe MathJax strips the math-code so the second MathJax run has nothing to find otherwise it would lead to every math blocks doubled while the second prism run just overwrites the previous ones theming.

This tutorial is really confusing me. I’m having a hard time with your writing style. I created an empty plain text file called MyMdStyle.css. I’m confused about what content I should add to that file.

Could you please upload a ZIP with the documents configured in the manner you described?

I can’t speak for the OP, of course. But a CSS file should contain styles. So you’d put something like

h1: {
  font-size: 1.2em;
  font-weight: bold;
}

blockquote: {
  margin-left: 1em;
}

ul: {
  padding: none;
}

in it. Whatever you’d want the HTML rendering of your Markdown file to look like.

What the OP had wanted to explain, I think, is this: You can put HTML elements in every MD file. These HTML elements can be, for example, style, link and script, too. Which permits you to add a CSS to your MD file as well as JavaScript script(s) which (can) influence how the MD rendered as HTML looks. I’d probably have gone with a more concise approach, but …

If and how it is really necessary to do all this stuff to simply have Prism/Mathjax support, I don’t know. Also, it might be easier to convert the MD files to HTML on the Mac just before synchronizing them. That way you’ll have the HTML version on your mobile devices.

This however is so general that it is plain wrong. You can always go with freely available fonts (like the ones offered by Google) and refer to them by URL. No need to install anything.

Thank you for answering @chrillek. As DT evolves many things in this guide are now obsolete for most users (DTTG has Mathjax support, etc).

Sadly posts are locked ofter some time so I can not update or improve them.

The main reason for this guide was show how to use Markdown extensions offline and have control over their parameters or change the source code if needed.