Markdown guide

The Markdown MarkdownMate renders.

Both apps read plain .md files and render GitHub-flavored Markdown, fully offline. Each section shows the syntax and what the apps do with it; where the Mac and Ubuntu apps differ, it says so. Looking for keys instead? See the keyboard shortcuts.

Headings

# Title
## Section
### Subsection

One to six # make a heading. The editor shows headings bigger, with the markers dimmed, and the Outline lists them so you can jump to one.

Paragraphs and line breaks

First line of a paragraph
second line of the same paragraph

A blank line starts a new paragraph.

With Markdown Standard, lines of a paragraph are joined, as Markdown does; a blank line starts a new paragraph. With Every New Line, each single line break starts a new line, as in GitHub comments.

Both apps offer the two options; Markdown Standard is the default. Mac: Settings ▸ Preview ▸ Line breaks. Ubuntu: Preferences ▸ Appearance ▸ Line Breaks. The preview, print and exports follow your choice.

Emphasis

**bold**, *italic*, ~~strikethrough~~, `inline code`
> A quote

The editor styles them inline: real bold and italic, code in a monospace font, markers dimmed. While you type, (, [, {, ` and " get their closing partner, typing the closer steps over it, and Backspace in an empty pair removes both. Turn this auto-pair off in Settings ▸ Editor on Mac or Preferences ▸ Editor on Ubuntu.

Smart punctuation

"Quotes" -- it's done... --- really

With smart punctuation on, the preview, printing, exports and Copy as HTML / Rich Text show “curly quotes”, it’s, – for --, — for --- and … for .... Your note keeps the straight characters you typed, and code, URLs and backslash-escaped characters (\") stay as written.

Mac: on by default, in Settings ▸ Preview; plain-text export keeps the straight characters. Ubuntu: off by default, in Preferences ▸ Preview ▸ Smart Punctuation.

Highlights

Remember to ==book the hotel== before Friday.

Two equals signs on each side mark text as highlighted. Both apps render it with a soft yellow background in the preview, in light and dark, and in print, HTML and PDF exports and Copy as HTML; Copy as Rich Text and the RTF export keep a yellow background. In the editor it gets a light background. Format ▸ Highlight (⇧⌘H on the Mac, Shift+Ctrl+H on Ubuntu) adds or removes it around the selection or the word at the cursor.

Lists and to-dos

- Milk
- Bread
    - Whole grain

1. First
2. Second

- [ ] Write the report
- [x] Send the invoice

Return continues a list, quote or to-do; Tab and Shift-Tab indent. Click a - [ ] checkbox in the preview to tick it in the note (undo works), or use Toggle Task in the editor.

Tables

| Item  | Price |
| :---- | ----: |
| Tea   |  3.50 |
| Cake  |  4.00 |

GFM tables with :--, :-: and --: alignment; write \| for a pipe inside a cell. Insert Table, Format Table, add or delete rows and columns and align a column from the table commands; Tab moves to the next cell and the columns line up again after each change.

Code blocks

```python
def hello():
    print("Hello")
```

Fence code with ``` or ~~~ and a language name for highlighting. Typing the fence and a letter pops up the languages the preview colours, short names such as js, ts, py, sh and yml included. In the preview, hover a block and click Copy to copy its code.

[MarkdownMate](https://markdownmate.homielab.com)
[Plan](Projects/Plan.md)
![Chart](assets/chart.png)

Select text and paste a URL to get [text](url). A relative link to another .md note opens it in the app. Paste or drop an image and it is saved to an assets folder next to the note and linked; hover an image link to preview it.

Web images: the Mac app loads them. The Ubuntu app doesn't download them by default; turn on Preferences ▸ Privacy ▸ Load Images from the Web to show them.

[[Meeting notes]]
[[Meeting notes|last meeting]]
[[Meeting notes#Decisions]]
[[#Summary]]

Link to another note in the open folder by name, in any case; | sets the shown text, #Heading opens the note at that heading and [[#Heading]] jumps within the same note. Click it in the preview to open it; a link to a note that doesn't exist yet creates it. Typing [[ suggests note names, and Backlinks lists the notes linking to the current one.

Tags

Ideas for the trip #travel #work/project

Type #tag, or nested #work/project, anywhere in a note. Tags are coloured in the editor and preview, and the sidebar's Tags section lists them as a tree. The file stays plain Markdown.

Footnotes

Markdown is plain text.[^1]

[^1]: It opens in any editor.

Format ▸ Footnote inserts the next free [^n] and its [^n]: line at the end of the note, with the cursor there.

Math

Inline: $E = mc^2$

$$
\frac{a}{b} = \sqrt{x^2 + y^2}
$$

Both apps typeset math with KaTeX in the preview, offline: $…$ inline, $$…$$ and ```math blocks for display. On Ubuntu a formula with a mistake shows its source in red.

Mermaid diagrams

```mermaid
flowchart LR
    Idea --> Draft --> Publish
```

A mermaid code block shows as a diagram: flowcharts, sequence, class, state, Gantt, pie and more. Mermaid is bundled, so it works offline.

Front matter

---
title: Trip plan
date: 2026-11-01
---

YAML front matter on the first line of a note is rendered, not mixed into the text. Mac: a preview setting for front matter in Settings. Ubuntu: a small dimmed block in the preview, left out of Export, Copy as HTML and Print.

Alerts

> [!NOTE]
> Useful information to read even when skimming.

> [!TIP]
> Advice for doing things better or more easily.

> [!IMPORTANT]
> Key information needed to reach the goal.

> [!WARNING]
> Urgent information that needs attention right away.

> [!CAUTION]
> Risks or bad outcomes of an action.

A quote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] shows as a GitHub-style coloured callout, with the kind's name as its title: Note in blue, Tip in green, Important in purple, Warning in amber and Caution in red. Alerts show in light and dark mode, in brighter shades in dark, and in print and in HTML and PDF exports, and keep their colours with Copy as Rich Text and the RTF export.

There is no need to type the syntax: Format ▸ Callout (the Format menu on Mac, main menu ▸ Format ▸ Callout on Ubuntu) inserts a callout of any kind — above the current line, or turning the selected lines into the callout's body — as one undo step.

Table of contents

# Trip plan

[TOC]

## Flights
## Hotel

Write [TOC] on a line of its own and the preview shows the note's headings there as nested links that jump to each one. It updates as you edit a heading, and print, HTML and PDF exports include it too.

Templates

# {{title}}

Created {{date}}

## To do
- [ ] 

Put notes in a Templates folder inside your folder, then choose New from Template and pick one: a new note starts from it, with {{date}} filled in as today's date and {{title}} as the note's name. Today's Note starts from a Template.md in the daily notes folder when there is one, filling both {{date}} and {{title}} with the day's date. To use another templates folder: Mac: Settings ▸ General. Ubuntu: Preferences ▸ Notes ▸ Templates Folder.

Get MarkdownMate

Mac

Free on the Mac App Store

macOS 15.6 or later

Ubuntu

sudo add-apt-repository ppa:homielab/markdownmate
sudo apt update
sudo apt install markdownmate

Ubuntu 24.04 or later (amd64)

No account, no cloud: notes stay as .md files on your disk.