Markdown is a fairly simple "language" to learn. For many people, just typing and using a handful of control characters will be sufficient. However, it has become a very feature-rich format supporting things like outlines, images, tables, linking, etc., perhaps even some things surprising to you.
Over time multiple "flavors" of Markdown have been introduced. DEVONthink Markdown utilizes standard Markdown but also supports features from some other flavors: MultiMarkdown, CommonMark, CriticMarkup, and GitHub Flavored Markdown (GFM). Here you can read about many possible features, but also realize it's not exhaustive. There many be extra features for an element, but we'll leave the deeper investigation to you!
Basic formatting: Get started by simply typing, creating paragraphs. These will usually be your most common element. But as you write, you may want to add some emphasis to certain content. To add formatting, surround the content with control characters showing the Markdown parser the words should be rendered with specific formatting. Here are the three most common styles you'll use:
With these basics, you can quickly capture ideas or write longer-form content in plain text, but with some extra flair. However, the possibilities only increase from here.
Extended Formatting and Elements: Often used in academic or professional writing, some specialized formatting is also supported. The first two are standard Markdown; the remainder are CriticMarkup.
-
Subscript: ~subscript~.
-
Superscript: ^superscript^.
-
Highlight: {==highlight==}.
-
Underscore: {++underscore++}.
-
Strikethrough: {--strikethrough--}.
-
Addition: {++text to add++}
-
Deletion: {--text to delete--}
-
Substitution: {~~replace this~> with this~~}
-
Comment: {>>comment<<}
Lists: Whether for an outline, shopping list, taxonomies, or record your top ten movies, creating lists is easily done. These are the supported types:
-
Ordered (Numbered) List: 1. Manufacturers
-
Unordered (Bulleted) List: * Monday or - Plan.
-
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.
As you type each line item, pressing the ↩ Return key will add a new line item ready to enter the next one. Press the key twice to close the list. Lists can be indented to create nested lists by pressing the ⇥ Tab key or adding one space per-level at the beginning of a line. To outdent a list, remove spaces from the line's beginning.
Tables: Creating tables is supported, even building them in a semi-visual manner. The cells of the table are separated by the pipe | character. (A pipe at the beginning and end is optional.) The top of a table is defined the header line: the number of columns denoted by pipes, usually with column header names, e.g., Name|Location||Age. The next line is the column alignment line: three hyphens, again separated by a pipe, like :---|:---|---|:---:. The colons : control if the cell content is left, right, or center justified. Then you enter each row's cell's content, e.g., Jason|Marana|AZ|48, on separate lines. You can also include an optional table caption in square brackets immediately before or after the table, like [Friends and Family].
|
Example:
Movie | Year | First Week Box Office
:--|:--:|:--:
Star Wars: A New Hope | 1977 | $1,554,475
The Empire Strikes Back | 1980 | $6,400,000
Return of the Jedi | 1983 | $45,311,004
|
Sections: As your content becomes more complex, you may want to split the content into sections. Create a section by typing # followed by a space and the title of the section, e.g., # Milky Way. This creates an "h1" heading. Sections up to six levels deep are made by using the requisite number of hashtag symbols. So your first subsection would be ## Planets, creating an "h2" heading. You can use these headers to navigate the document in the
Table of Contents inspector. Additionally, you can include a table of contents in the document by entering {{TOC}} where you want it to appear. You'll also find more information in the
Cross-Reference Linking section below.
Everyday Extras: Here are a few more common elements you may find useful in your writing:
-
Horizontal Rules: Add a separator line by typing three dashes or asterisks on a line: ***.
-
Blockquote: Enter attributed quotes by preceding each line in the quote with a greater than symbol: >I think, therefore I am.. You can also nest blockquotes with multiple > symbols.
-
Code block: Insert inline code in a sentence: `code terms`. Note: Those are backticks, found on the tilde (~) key.
-
Fenced code block: Create separate blocks of code: ``` - 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.
-
Emoji: For a little extra personality, you can type Slack-style emoji, like :grinning:, directly in a Markdown document.
Advanced Markdown
DEVONthink Markdown also supports some "advanced" features found in some other Markdown flavors. From academia to design to business uses and more, these give you some specialized tools to work with.
Footnotes: Footnotes are supported in our parser and automatically insert a numbered footnote link in the text. These are two of the supported footnote styles:
-
Reference: Uses a label, [^label], pointing to a particular footnote matching the same label, [^label]: Footnote text, typically added at the bottom of the document.
-
Inline: The footnote text is used as the label, automatically creating a numbered footnote, e.g., [^The tax authority responded on the 15th.], and adding the footnote link in the text.
Callouts: A feature found in GitHub Flavored Markdown, a callout or admonition is a specially styled blockquote element to call attention to some text, e.g., a tip or warning. The syntax is >[!Type]Optional Title followed by the message, preceded by the greater than symbol. The supported types are: INFO, NOTE, TIP, IMPORTANT, CAUTION, WARNING, DANGER, QUESTION, EXAMPLE, QUOTE, SUCCESS, FAILURE, and BUG. The callout's text can contain rich content, like formatting, links, lists, etc.
Callouts can be collapsible and have an initial state when the document is viewed., opened or closed. After the closing square bracket, include a plus + for open or a minus - for closed, e.g., >[!INFO]-What is subzero?.
The MkDocs and Python-Markdown callout syntax is also supported.
Abbreviations: Abbreviations are content appearing in tooltips when you hover over words with definitions. To define the abbreviation text, use the syntax: *[Word]: tooltip text. Create the abbreviation *[NASA]: National Aeronautics and Space Administration and the full title will appear when you hover over NASA in the preview.
|
Note:
Abbreviations, footnotes, bibliographic entries, etc. can be defined anywhere in the document but they're most commonly put at the bottom of the document.
|
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. Pre-defined fields in the
Info > Properties inspector can be populated with this metadata, e.g., keywords: support,markdown. If you're not using metadata and want the first line of your document to contain a colon, add a single blank line at the top of the document and the subsequent lines will be treated as normal paragraphs.
Metadata can also be used as variables in the content of the document by entering the attribute's name prefixed with a percent sign, inside square brackets. So if you enter product: widget-002 in the metadata, you would type [%product] in the text and it will render as widget-002 in the preview.
Markdown Extensions
DEVONthink supports some Markdown extensions to provide a few specialized features in the output. These can be toggled in the
Files > Markdown > Extensions settings.
MathJax: Markdown is often used in academic situations, many using mathematical equations in their writing. DEVONthink supports the Mathjax extension that will beautifully render coded equations.
-
Inline Math: Surround the equation with single dollar signs, e.g., $E = mc^2$. The alternate \(…\) syntax can be used.
-
Display Math: Begin and end the equation with lines containing double dollar signs. The alternate, \[ and \] syntax can be used.
-
MathML: Raw MathML elements can be added to the document, both inline and display: What if <math xmlns=“http://www.w3.org/1998/Math/MathML”><mi>A</mi><mo>≠</mo><mi>B</mi></math> ?
|
Note:
If you need to include a rendered dollar sign, escape it: \$.
|
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 the syntax is discussed on their 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 using, 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:
Not all languages supported by Prism are available. Additional languages may be added in the future if there's sufficient interest in them.
|
Linking
Document linking is an important feature for a wide range of purposes, e.g., linking Zettelkasten documents, building a custom bookmarks page, or adding some images to brighten up a page. Markdown has rich support for linking a variety of link types. *External Links* Links to external items, e.g., web pages and documents, are very commonly used in Markdown. The basic forms are:
|
Note:
Be aware, the URL must be URL-encoded, e.g., spaces are represented with %20.
|
Document links will either show a filename, with or without a path, or an item link. Depending on where the linked document is located or how it was created, e.g., pasting an item link.
-
Sibling Link: Links to an item in the same group as the Markdown document: .
-
Relative Downward Link: Links to an item in a sub-group of the group containing the Markdown document: . Upward links are not possible as a document may have multiple parents.
-
Absolute Link: Links to an item outside the Markdown document's parent group: . For example, if you have common resources in a specific group, you can link to them using this format, e.g., .
-
Item Link: Links to a specific item by its UUID, not requiring a location: [link text](x-devonthink-item://…)
While it's good for you to know and understand the link syntax, DEVONthink has ways to make linking easy and more efficient. See the Documents > Markdown documents section for information on linking.
Cross-Reference Linking: If you are using sections in your Markdown, you can create links to jump to those sections. Assume we have a document with sections:
-
Link via name: [Notes][] uses the section's name to jump to the section.
-
Link with text: [some ideas][Notes] hyperlinks text to a section, e.g., "some ideas" to the "Notes" section.
-
Link with custom ID: Define a heading with a custom ID in braces, preceded by a hashtag symbol, # Notes {#lab-01}. Spaces are invalid in the ID. You then reference the section via a link like [findings][lab-01]. This can be useful if you have redundant section headings in a document.
Citations and Bibliographies: For academic writing, support for citations and bibliographic references is built-in. When you first create a citation element, a References section will appear at the bottom of the preview and clicking the citation jumps to that section.
To insert a citation link, in square brackets enter an ampersand @ (Pandoc) or a hashtag #, immediately followed by an abbreviation: [@dt42026,p42]. Now define the bibliographic entry with the link and text, e.g., [#dt42026]: DEVONtech *DEVONthink 4 Manual*(2026), noting you use a hashtag for the definition. If you need to include multiple citations, add see and encompass them all in the square brackets, e.g., [see @dt42026;cf. @west2017].
Styling
There is a default style built into DEVONthink and it's usually good for quick and easy composition. If you want to make some changes, adjust margins, line width and spacing, and choose a specific Markdown font via the Editing > Format settings.
More complex styling is done with CSS (Cascading Style Sheets), using either 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. This will apply the style to all your Markdown documents. If you're creating documents for different purposes or building a style you like, 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.
You can also search online to find thousands of tutorials on CSS, as well as many styles. Do note many of the styles are very complex and often made specifically for certain types of web layouts. It's often better to investigate how to style specific things, e.g., tables, as the need arises.
|
