Markdown 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 live previewing of tables, images, links, and MathJax equations. This displays these items in the source code, similar to how it will be rendered in the preview. An example of this is shown in the image at the top of this section, where you can see a WYSIWYG image, link, and table. 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 still can edit these live elements in the source. Some even support click-to-edit, so you click, make a change, then the element dynamically renders again when you click away from it. Here are the current methods:

• Image: Control-click and choose Edit Image. Modify or remove the caption, change the image by modifying the URL, or add optional parameters, e.g., width=250px.
• Link: Click next to the link to display and edit the raw Markdown link's text or URL. Alternatively, Control-click and choose Edit Link or select the text and use Format > Edit Link to modify the URL but not the link's text.
• Tables: Click in a cell to edit the contents. Click directly under the rendered table and you can add another row. Or Control-click anywhere in the table and choose Edit Table. The raw Markdown table is shown.
• MathJax: Click an equation in the text to display and edit the raw MathJax/LaTeX Math equation.

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.

LaTeX Exports: LaTeX is a typesetting engine very commonly used in scientific and academic circles for creating documents in a very precise and controlled manner. With a Markdown document selected, choose File > Export > as LaTeX Document to create a .tex file, the native LaTeX format, to be used elsewhere. Links are preserved, any linked images are exported to the same location as the document, and metadata such as title, author, and date are retained.

If you need to create a finished document, export as PDF Document (LaTeX). The document includes images and active hyperlinks, ready for submission. Exporting multiple Markdown documents yields a combined final PDF document. Note you will need to have pdflatex installed in order to export to PDF. A local installation of MacTeX will put the required pieces together to effectively use this export option.

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.