The (maybe) ultimate Guide to Markdown (finally)

The ultimate Guide to Markdown (finally)

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!

1 Like

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.

2 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.