Home | Appendix

Quick links: |  | Linking Styling Markdown Extensions Interface Item Linking

|  |  | Markdown Documents

Markdown is a simple formatting language invented by John Gruber that has gained in popularity over the past few years. It allows you to write in plain text, using some easily learned control characters, to produce nicely rendered HTML output. With some styling and ingenuity, you can create a wide variety of documents. Markdown files can be imported or created via Data > New > Markdown text. As you're writing you can switch easily between a plain text editor and the rendered view or even view both simultaneously using the side-by-side view via the View > Document Display commands. If there is a view you prefer, you can choose it in the Settings > Files > Markdown > Markdown Display dropdown. Elements: As Markdown at its core is just plain text, you can create a new document and just start typing. However, you may need more than paragraphs in your composition. Below is a list of parts of a document you may need in your writing. Section Header: `# Header`. Prefix each header with the appropriate number of hashtag symbols. Supports header levels 1 through 6. Link: `[Link Text](URL)` or `<URL>`. Blockquote: `>` preceding each line in the quote. Code block: ``code terms``. This inserts inline code, e.g., in the sentence. Note: Those are backticks, found on the tilde (~) key. Fenced code block: ````` - triple backticks on a line above and below the code. For syntax coloring of code, see the Prism.js extension described in the Markdown Extensions section below. Metadata headers: `attribute:` . Used to add arbitrary metadata to the document. This also supports YAML metadata. Some common attributes, e.g., an `Author` attribute will be added to the same field in the Properties inspector. As noted below, these must be the first lines in the document. Lists are often used in a variety of ways. As an example, to create an unordered list (often called a bulleted list), type a hyphen or asterisk followed by a space, then your text. When you press the ↩ Return key, the next line will have the control character to continue the list. If you're finished with the list, add one more return. For sublists, after adding a line item and pressing the ↩ Return key, type two to four spaces or press the ⇥ Tab key and type after the control-character. To outdent a list, put the cursor before the control character and press the ⌦ Delete key. Here are the supported lists and their control characters: Ordered (Numbered) List: `1. Manufacturers` Unordered (Bulleted) List: `* Smart rules are powerful` or `- AppleScript is versatile`. To Do List: `-[ ] Call insurance company.` Remember to leave a space between the square brackets. To mark an item as complete, put an `x` between them. Formatting: Markdown has a simple syntax for creating and styling text. Here are the control characters used for common styles, including CriticMarkup (see below): Bold: `**bold**`. Italic: `*italic*` or `_italic_`. Bold-Italic: `***bold-italic***`. Subscript: `~subscript~`. Superscript: `^superscript^`. Highlight: `{==highlight==}`. Underscore: `{++underscore++}`. Strikethrough: `{--strikethrough--}`. 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 see no 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 in the Markdown settings to be used in all Markdown documents or by selecting Format > WYSIWYG Editing on a document-by-document basis. However, syntax highlighting must be enabled in the application settings to use this feature. If you need to edit the attributes of a rendered image, Control-click it and choose Edit Image. You can 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, you can 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. Metadata: One of the features of MultiMarkdown is metadata headers. These allow you to add non-displaying information about the document, like authors, dates, and even linked stylesheets. To use the feature, format the first line of the document with a colon, e.g., Author: DEVONtechnologies. Add as many metadata fields as you wish but they must be in a block at the top of the document. If you would like the first line of your document to contain a colon, perhaps adding notes like Developer: A. Edwards and Re: OCR, just add a single blank line at the top of the document and the subsequent lines will be treated as normal paragraphs. You can learn more about Markdown and its syntax on Gruber's Markdown pages or the MultiMarkdown syntax guide. Linking You can reference local images, scripts, and other resources using item links, downward-relative (traveling subgroups; it's not possible to travel up with '..' as documents can have multiple parents) or absolute (start with a forward slash) paths. Here are examples of linking an image: `![link](item.png)`: Use this when linking to an item in the same group as the Markdown document. `![link](group/item.png)`: Use this when linking to an item in a sub-group of the group containing the Markdown document. `![link](/group/item)`: Use this when you are linking to an item in a group outside the group containing the Markdown document. For example, if you have common resources in a specific group, you can link to them using this format. Linking Images: Regarding keeping track of your linked images, if you drag or paste images into a Markdown document, they will be imported into a group in the document's location if Preference > Files > Markdown > Import images to group is enabled. The group name is also assigned in the preferences, with the default name being Assets. This group will also contain images from web content clipped as Markdown documents if the above option is enabled. If you enter a name in the preferences mentioned above, this will create a subgroup in the location of the Markdown document and a relative link will be created in the Markdown document. If you add a name preceded by a forward slash, e.g., `/Markdown`, this will create a group in the root of the database and an item link placed into the Markdown text. You can even set a more precise location, e.g., `/Inbox/Markdown/Images`. Drag and Drop/Copy and Paste: Drag and drop or copy and paste items into a Markdown document to add the appropriate links. Drag and drop documents while holding ⌘-⌥ will create a URL with an item link. Dropping an image will create a properly formatted Markdown image link. Drop `.mp3` or `.mp4` files to insert a playable multimedia link. You can also copy and paste files into the document. The type of link that's inserted, relative or an item link, is controlled by the Image Reference setting. WikiLinking: If you have enabled automatic WikiLinks, links to documents can be detected as you write. If you have enabled Names & Aliases, links will appear as matches are detected. If you enabled Square Brackets, type `[[` and continue typing, suggestions will be made via autocompletion. Selecting one inserts the link or type something new to begin a new Wiki document. These WikiLinks are active when editing and previewing the file and are also preserved in a website export or conversion to other formats. Inserting Item Links: Another option for inserting links into Markdown documents, Control-click while editing and choose Insert > Item Link. Search for an item's name and insert a Markdown formatted link directly into the document. For images, just add an exclamation point before the link if you want it to display in the rendered document. File Transclusion: A special feature of DEVONthink's Markdown handling is support for file transclusion. This provides the capability of displaying the contents of one file inside the contents of a Markdown file. This supports displaying the contents of: plain text, rich text, HTML, formatted notes, sheet, or more commonly, other Markdown files. For example, you may have several chapters of a book written in individual Markdown files. Use transclusion to view them all as one document with out the need to merge or copy and paste the content between files, similar to some popular writing applications. If you examine the image at the top of this section, you will notice the table isn't a Markdown table at all. It's a transcluded sheet. 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]]`. Styling Styling your Markdown documents can be done with internal styling or externally referenced stylesheets. If you have a specific stylesheet you'd like to use globally, you can specify one in the Files > Markdown > Style Sheet. settings. If you're working on styling or creating different kinds of documents, here are options for in-document styling: Internal styling: You can add styling directly to your document, often placed at the end, inside a styling block, `<style type="text/css"> … </style>`. Do not include spaces between elements you're styling. HTML Link: When using an external stylesheet, whether in a database, on your Mac, or online, you can add this style link to your document: `<link rel="stylesheet" type="text/css" href="css/styles.css" />` XHTML Link: Another option to use with an external stylesheet is using a metadata XHTML link, e.g., `CSS: css/styles.css`. This needs to be at the very top of the document.
Note: If no specific styling is applied, the Editing > Format > Markdown Font will be used in both the source and preview of Markdown documents.
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 Settings > Files > Markdown, if desired. Highlighting, strikethrough, …: Text notations, e.g., for noting changes are sometimes necessary in documents. DEVONthink supports the features of the CriticMarkup extension of Markdown. It also supports a few alternate highlighting syntaxes, like ==text== and ^^text^^, found in some other Markdown-enabled applications. MathJax: Markdown is often used in academic situations, many using mathematical equations in their writing. DEVONthink supports the Mathjax extension that will beautifully render LaTeX coded equations in your Markdown documents. For more information on how MultiMarkdown handles equations, please see: Math support in MultiMarkdown. Mermaid: Diagrams can be created in Markdown documents using the Mermaid extension. Add a line of three backticks as shown````mermaid`. Add the diagram code as needed and close the diagram with another line of three backticks. There are several diagram types available and discussed on the Mermaid.js website. Prism: For those writing code in their Markdown, DEVONthink supports Lea Verou's Prism extension. Just add a line of three backticks ````language-` and the language you're writing about. For example, ````language-applescript`. Remember to add a line of three backticks under the code to close it. This displays syntax highlighting of code blocks in the rendered output. Note it does not affect the Markdown source as you're writing, only the rendered output.
Note: Not all languages supported by Prism are available. Additional languages may be added in the future if there's sufficient interest in them.
Emoji: For a little extra personality, you can type Slack-style emoji, like `:grinning:`, directly in the Markdown document. 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.