Markdown

Trilium has always supported Markdown through its import feature, however the file was either transformed to a Text note (converted to Trilium's internal HTML format) or saved as a Code note with only syntax highlight.

This note type is a split view, meaning that both the source code and a preview of the document are displayed side-by-side. See Note types with split view for more information.

Rationale#

The goal of this note type is to fill a gap: rendering Markdown but not altering its structure or its whitespace which would inevitably change otherwise through import/export.

Even if Markdown is now specially treated by having a preview mechanism, Trilium remains at its core a WYSWYG editor so Markdown will not replace text notes.

Features#

Source view pane#

• Syntax highlighting for the Markdown syntax.
• Nested syntax highlighting for code inside code blocks.
• When editing larger documents, the preview scrolls along with the source editor.

Preview pane#

The following features are supported by Trilium's Markdown format and will show up in the preview pane:

• All standard and GitHub-flavored syntax (basic formatting, tables, blockquotes).

• Basic HTML is also supported (e.g. collapsible blocks using <details> and <summary>).

• Code blocks with syntax highlight.

  • The language must be specified for syntax highlight to be applied (e.g. ```js).
  • Code blocks will respect the text wrapping from the Text section in Options.

• Block quotes & admonitions

• Math Equations (both inline and block)

• Mermaid Diagrams using ```mermaid

• Include Note (no built-in Markdown syntax, but HTML syntax works just fine):

  <section class="include-note" data-note-id="vJDjQm0VK8Na" data-box-size="expandable">
      &nbsp;
  </section>

  • These can also be quickly created via the /include command or via a dedicated keyboard shortcut (not assigned by default).

• Internal (reference) links via its HTML syntax, or through a Wikilinks-like format (only Note ID):

  [[Hg8TS5ZOxti6]]

• Footnotes are also supported via the corresponding Markdown syntax:

  This is [^1], while this is [^2].
  
  [^1]: the first footnote
  [^2]: the second footnote

  • These can also be quickly created using the /footnote command.

Links#

Multiple types of links are supported:

• Web URLs can be written with the standard Markdown syntax:

  [Wikipedia](https://www.wikipedia.org)

• Reference link to other notes with dynamic title, either by manually entering the note ID or via the Add link dialog:

  [[B9oMG6rFvvfq]]

• Reference link to other notes with a custom text:

  [This is a link](#root/LhtnZxtVsUMp)

To create a link, either:

• Type it manually using the syntax described above.
• Use the Add link dialog by pressing Ctrl+L or typing the /link command.

Keyboard shortcuts#

The Markdown notes share some of the keyboard shortcuts from Text notes:

• Cut to note (Ctrl+X) which cuts the selection into a new child note.
• Add link (Ctrl+L) which shows the dialog to create external or reference links.
• Insert date/time (Alt+T) which respects the same formatting as text notes.
• Include note (not assigned by default), which triggers the same dialog to insert notes as the one for text notes.

In addition, the following formatting keyboard shortcuts are available:

• Ctrl+B to toggle bold.
• Ctrl+I to toggle italic.
• Ctrl+M to wrap the current selection in an inline math ($).
• Ctrl+Shift+X to toggle strikethrough.

Images & attachments#

Images can be inserted into the document in four different methods:

• Drag & drop directly into the editor area.
• Pasting an image from clipboard.
• Pasting a reference to another attachment (e.g. Copy reference to clipboard button).
• Use the /image slash command.

An image reference to an attachment looks like this:

![Name.jpeg](api/attachments/z50RceuHXe9J/image/image)

Slash commands#

Just like Text notes, Markdown notes support a selection of slash commands:

• Creating admonitions (e.g. /tip)
• Uploading images (/image).
• Inserting the current date & time (/date).

Note that slash commands only work outside of inline 

Other features#

• The Table of contents will be displayed in the Right Sidebar based on the Markdown-level headings.
  • This feature is available only on the New Layout.

Shared notes#

When a Markdown note is shared publicly, it will be rendered with extended formatting just like Text notes.

Most of the features described previously should be supported. If you face any issues, feel free to report it alongside a sample Markdown file.

Creating Markdown notes#

There are two ways to create a Markdown note:

1. Create a new note (e.g. in the Note Tree) and select the type Markdown, just like all the other note types.
2. Create a note of type Code and select as the language either Markdown or GitHub-Flavored Markdown. This maintains compatibility with your existing notes prior to the introduction of this feature.

Import/export#

Import#

By default, when importing a single Markdown file it automatically gets converted to a Text note. To avoid that and have it imported as a Markdown note instead:

• Right click the Note Tree and select Import into note.
• Select the file normally.
• Uncheck Import HTML, Markdown and TXT as text notes if it's unclear from the metadata.

When importing a Trilium ZIP, it will preserve the Markdown type without converting to text notes thanks to the meta-information in it.

Exporting#

When exporting Markdown files, the extension is preserved and the content remains the same as in the source view (with some small exceptions such as handling of attachments).

When exporting Markdown files as ZIP, choosing HTML or Markdown as the export format makes no difference as that only affects Text notes.

If the Markdown note contains attachments, a ZIP export will rewrite the links to attachments so that they are replaced with a relative path to the attachment. On import, the links are re-written back.

Conversion between text notes and Markdown notes#

Currently there is no built-in functionality to convert a Text note into a Markdown note or vice-versa. We do have plans to address this in the future.

This can be achieved manually, for a single note:

1. Export the file as Markdown, with single format.
2. Import the file again, but unchecking Import HTML, Markdown and TXT as text notes if it's unclear from the metadata.

For multiple notes, the process is slightly more involved:

1. Export the file as Markdown, ZIP.
2. Extract the archive.
3. Remove the !!!meta.json file.
4. Compress the extracted files back into an archive.
5. Import the newly create archive, but unchecking Import HTML, Markdown and TXT as text notes if it's unclear from the metadata.

Sync-scrolling & block highlight#

When scrolling through the editing pane, the preview pane will attempt to synchronize its position to make it easier to see the preview.

In addition, the block in the preview matching the position of the cursor in the source view will appear slightly highlighted.

The sync is currently one-way only, scrolling the preview will not synchronize the position of the editor.

This feature cannot be disabled as of now; if the scrolling feels distracting, consider temporarily switching to the editor mode and then switching to preview mode when ready.