Tuesday Tip: Make plain text pretty with Markdown

markdownAs we talked about last week, plain text is amazing. It’s an incredibly flexible format, offering many benefits, with next to no downside. On the other hand, plain text is… well, ‘plain’. No font changes. No bold or italic. No images. It’s like a world with no picture books!

“See! That’s why I need Microsoft Word!”, you might say. Well, actually I’d like to offer a better alternative… plain text, yet again. Specifically, plain text written in a style called Markdown. It was developed by John Gruber (of Daring Fireball fame) and is a way of writing plain text so it can be converted to and displayed as HTML.

Now you may think: “Wait! I’m not making web pages! I’m writing notes!” Markdown is being used, more and more, for all kinds of writing. A simple search for Markdown on a site like MacUpdate will yield many options for Markdown editors. In fact, DEVONthink supports creating and editing Markdown documents* natively. I am currently using Markdown in over half my customer support work.

Instead of using formatting, like bold and italics, you type simple characters to specify the formatting and other features. The resulting text is both easily readable for humans and applications that support Markdown can display (‘render’) your writing graphically.

Here are a few examples of the syntax:

  • Use two asterisks around words to make them bold.
    “DEVONthink is an **information** manager” will display as: “DEVONthink is an information manager”
  • An underscore around words will make italics.
    “That _is_ the best option.” displays as “That is the best option.”
  • Or combine the two.
    “Save your database locally _(but **not** in a cloud-synced folder!)_”, will appear as “Save your database locally (but not in a cloud-synced folder!)

As far as what the formatting looks like, if you want some control over the fonts, colors, etc., you can link to Cascading Style Sheets (CSS) or add styling in the Markdown to customize the look. This isn’t necessary but gives you more options. Many apps have options to export to different formats like HTML or PDF. And because the files are simply plain text, you have the option of switching to other applications without having to change the files.

For more info, check out the MultiMarkdown Guide. And Macdown is a nice free Markdown editor with a live preview to see the formatting as you type.

* There are many flavors of Markdown being created. DEVONthink currently supports Fletcher Penney’s MultiMarkdown, as a more standard flavor.

24 Responses to “Tuesday Tip: Make plain text pretty with Markdown”

  1. mrkwnzl says:

    Can I change the CSS used for rendering in DEVONthink, or is that only possible with third-party editors/viewers?


  2. Mio says:

    Good article.
    However, I’d like to know what’s the advantage(s) of markdown over RTF file? In RTF I can immediately format textnin any way I want. For instance, I use quite a bit of highlighting and, correct me if I’m wrong, Cascading Style Sheets (CSS) looks a bit difficult to implement.

  3. @ mrkwnzl: Currently no we’re afraid.

  4. @ Mio: Markdown can be read on any computer system and even with the most primitive readers. RTF may or may not render correctly on other operating systems. And e.g. iOS does not come with a proper RTF editor at all.

  5. Nancy Hildebrandt says:

    I’ve spent a half hour searching documentation and give up. When you say ” In fact, DEVONthink supports creating and editing Markdown documents* natively. ” what exactly do you mean? I took a text document and surrounded a word with a couple asterisks on each side. The result is a word with a couple asterisks on each side. Does DevonThink render that in some view that I don’t know about? When I look at the Data > Convert menu, I sure don’t see Markdown as a choice.

  6. Mr. E says:

    I use markdown for almost al of my notes, and am a new (and satisfied) user of DT.

    But one feature I would *love* to have, is customization of the CSS file used to render to HTML. Or some other form of making the current markdown preview somewhat more pleasant to the eye.

    Please consider this a request, DT devs!
    I’d love to be able to skim through my markdown notes and see them in a more legible fashion (without converting them to HTML first, and giving up the versatility of markdown).

  7. Jim Neumann says:

    Have you considered using internal CSS in the Markdown file? I use this all the time.
    You can also use a linked styleSheet using “file:///“ in the href.
    You could even make a Markdown file with a styling option like those and save it as a Template via File > Export > as Template.

  8. Mr. E says:

    Oh wow, thanks so much Jim! Never knew I could do that!

  9. Jim Neumann says:

    My pleasure. Cheers!

  10. M0ll3art says:

    @Jim Could you please explain how to do it, since this could solve my day ? The CSS in the preferences solve this BUT also reformats all websites I’m visiting through DT ..


  11. Jim Neumann says:

    @M0ll3art: In order to best serve you and have a record of this issue, please start a Support Ticket at http://helpdesk.devontechnologies.com. Thank you.

  12. T. McTester says:

    On a web hosting server account, create a folder dedicated to Markdown .css files (i.e. “_library_mdcss”). In DevonThink, at the top of your markdown document, place a link referencing the desired .css (i.e. “dttemp.css”). Example:

    You can try the aforementioned to test (temporarily). There are a variety of Markdown .css files available on the interwebs; simply use a text editor to create/modify them. The advantages are: (a) easy to insert into your dt workflow; (b) variety of styles available to suit a particular md document’s visual needs; (c) a change in the .css file will update across all your md documents; (d) the md document can be transferred to your server, or another application, and the .css link will not break. The disadvantages are: (a) need a web host/server; (b) must be sure that the server’s library folder never gets moved/renamed; (c) need internet access while using dt.

  13. T. McTester says:

    My “Example” did not render due to syntax. Let’s try this (just drop the quote marks when you paste it into your markdown document):


  14. T. McTester says:

    The “Example” still did not render. Let’s do this. Replace “(lessthan)” and “(greaterthan)” with the actual symbols after pasting into the top of your markdown document:

    (lessthan)link rel=”stylesheet” href=”http://gfupt.com/_library_mdcss/dttemp.css”(greaterthan)

  15. M0ll3art says:

    @ T.McTester thanks for your help. This is what I tried (with an href=”file//” instead) and this is also the solution provided by Jim but I must say that DT is not using the provided CSS for rendering the markdown text. it uses the one provided by DT I supposed or my many experiments messed up the setup somehow :-/

  16. T. McTester says:

    @M0ll3art : Try it using the link to my .css on the server. This will confirm if the rendering issue is native to you DT install, or just an issue with “file:///” (not “file//” as you stated). Good luck.

  17. M0ll3art says:

    @T. McTester I used your link indeed and it is somehow not really rendering differently as the internal CSS. And yes I confirmed that I used the “file://” protocol, what was written is a typo ..

    thanks anyway

  18. Victor Gutierrez says:

    @MOLL3art, I believe that you are having problems with spaces. Remember that you need to change the spaces to something like “%20”. The easiest way to get everything formatted just right is to open the file in Safari (type file:///yourfile_location in the address bar). Safari will change all spaces to something that can be processed. Also, remember to format that link markup reference correctly (Open and close, etc).

  19. jdm says:

    I use markdown files in many apps, and I don’t want to hack all my markdown files just to work around a missing feature in DT, which I certainly hope will be fixed ASAP. It isn’t really Markdown if you can’t config css, IMHO.

    Please add me to the list of DT users who wish to be notified when you have CSS for in-place Markdown rendering.

    FWIW, I use Macdown, along with Jekyll and Github pages.

  20. midas says:

    If one has a Text document, but wants it to be identified as a Markdown, there is no option to Convert > Markdown.

    View > Best Alternative does not fix the problem. I’ll email the support team, but just wanted to flag it here because it seems like an unresolved issue.

  21. Jim Neumann says:

    “View > Best Alternative does not fix the problem.” :: What problem?

    And no, there is no convert to Markdown as they are already plain text. Add .md (.mmd, .markdown) to the end of the filename.

  22. Xu Lin says:

    have the same feature request with @jdm:

    “I use markdown files in many apps, and I don’t want to hack all my markdown files just to work around a missing feature in DT, which I certainly hope will be fixed ASAP. It isn’t really Markdown if you can’t config css, IMHO.
    Please add me to the list of DT users who wish to be notified when you have CSS for in-place Markdown rendering.”

  23. Jim Neumann says:

    Thanks for your input. We will consider this for future releases.