Home | Appendix

Quick links: |  | Editing Interface Item Linking

|  |  | Markdown Documents

Markdown is a simple formatting language invented by John Gruber and has only gained in popularity. It allows you to write in plain text, using some easily learned control characters, to produce nicely rendered HTML output. Created via Data > New > Markdown text or added from external sources, with some styling and ingenuity, you can create many kinds of documents. Editing While there are many Markdown applications available, DEVONthink's editor is full-featured enough for many peoples' needs. Here are some modern functions to make your writing more pleasant and efficient. As you're writing you can switch easily between three views, all chosen in the View > Document Display submenu. Source displays a plain text view for editing. Preview shows the rendered view of the page. And Side-by-Side displays the source and preview in two connected panes. If there is a view you prefer, you can set it as the default in the Files > Markdown > Markdown Display dropdown. Syntax Highlighting: When editing the source of the Markdown, DEVONthink's hybrid source rendering will display many types of formatting or elements as you type. For example, typing `**important**` will display the plain text in bold; ``{"name":"Audrey Hepburn"}`` will display as a code block, etc. If you'd prefer to never see formatting in the source code, you can disable Syntax Highlighting in the Files > Markdown settings. WYSIWYG Editing: Another feature of syntax highlighting is WYSIWYG images & links. This renders links as active hyperlinks and image links as the linked image. An example of this is shown in the image at the top of this section. You can enable this globally in the Files > Markdown settings or toggle Format > WYSIWYG Editing on a document-by-document basis. Note this feature requires syntax highlighting to be enabled in the application settings. In WYSIWYG mode, you can edit the attributes of a rendered image. Control-click it and choose Edit Image. Modify or remove the caption, change the image by modifying the URL, or add an optional parameter, e.g., `width=250px`. For a rendered non-image link, Control-click it and choose Edit Link or select the text and use Format > Edit Link. This change does not affect the link's text. Typewriter-like Scrolling: A feature used by some other writing applications is typewriter-like scrolling. This keeps the current line you're editing in the middle of the page. Linking Documents: To create links in your Markdown documents, you can use linking methods described in the Document Linking section, e.g., WikiLinks, cross-links, etc. But there are also special behaviors when you drag and drop or copy and paste documents in your database into Markdown: Adding an image automatically inserts a valid Markdown link, e.g., `![piglet](piglet.png)`, depending on your application settings or the location of the image. Copy a document in your database. Pasting it into your document yields a valid Markdown link with an item link. Drop MP3, MP4, or PDF documents to insert a playable multimedia link via a special transclusion link, discussed below.. Organizing Your Linked Images: If you are including images in your Markdown documents, keeping them organized can require creating groups to contain them. There is a function in the settings to help make this easier and more automatic. In the Files > Markdown settings, enable Import images to group. Below that is a text field with Assets as the name. Now images you drag and drop or copy and paste images into the document will be automatically filed in an Assets subgroup in the same group as your documents, all properly linked. (For many years, this has been a tried-and-true filing method for web content.) If you clip documents as Markdown, downloaded images will also be filed in this group. You can change the name in the settings, as needed. And if you want to create the group in a different location, you can read about the link syntax in the Appendix > Markdown Explored > Linking section. File Transclusion: A special feature of DEVONthink Markdown is file transclusion. This creates a special link to display the contents of one file inside the contents of a Markdown document. This supports displaying the contents of: plain text, rich text, HTML, formatted notes, sheet, or more commonly, other Markdown files. For example, imagine you wrote several chapters of a book in individual Markdown files. Using transclusion you can view and arrange them as if they're one document, all without needing to merge or copy and paste content between files. To use transclusion, just enter the desired document's name or item link between double braces, e.g., `{{Chapter 1}}`. Transclusion supports filenames with and without extensions, relative and absolute links, as well as item links. It also supports the Obsidian syntax, e.g., `![[Chapter 2.md]]`. Markdown Extensions: To support some features in Markdown that aren't built in, DEVONthink supports a handful of known and widely used extensions. The first option below requires no user interaction. The following three can be enabled in the Files > Markdown settings: Mathjax for rendering equations and formulae, Mermaid for creating diagrams, and Lea Verou's Prism for syntax highlighting code. If you're interested in composing in Markdown, including the supported extensions, the Appendix > Markdown Explored section will help you get started. While not exhaustive it covers a wide range of elements supported in DEVONthink Markdown. Interface Navigation Bar: When working with Markdown documents, you can switch between Preview and Source modes. There also is a special icon present in the navigation bar. This switches to Side-by-Side mode, allowing you to edit and preview the current document in two side-by-side panes. Editing Bar: The Editing bar is only available when editing the source. It has a subset of the tools used in rich text editing, e.g., Highlight, Bold, etc. Inspectors: These inspectors provide navigation or a view into the resources in Markdown documents: Table of Contents: You can view and navigate your Markdown sections in the Table of Contents inspector. Annotations: Markdown highlighting, underlining, strikethrough, etc. are shown in the Document > Annotations inspector. Links: Excluding WikiLinks, many types of outgoing links are shown in the Document > Links inspector, including item links, web URLs, other URL schemes like `mailto:`, etc. Attachments: Images added to the Markdown document are listed in the Document > Attachments inspector. Context Menu: Markdown documents support the same context menu items available with text selections in the document source. But there are a few special commands available both in the source and preview: Copy/Reveal/Edit…: Copies or reveals a linked document or opens it for editing. Set as Thumbnail: Use a Control-clicked image as the document's thumbnail. Item Linking In addition to the document's standard item link, Markdown documents support this alternative item link: Section Link: Links to the section, e.g., an `h1` header, of the selected text. Alternate item links are available in the context menu in the view/edit pane or when holding the Shift key while viewing the Edit menu.