Beyond the basics: Markdown tables, task lists, math and diagrams

To make a Markdown table, write the column names between pipes (|), put a row of hyphens under them, and then add one line per row: | Day | Plan |, then | --- | --- |, then | Monday | Museum |. Task lists work the same way, with - [ ] for an open item and - [x] for a done one. Both come from GitHub Flavored Markdown and work in most note apps.

This guide collects the Markdown features that go beyond the basics: tables, task lists, footnotes, callouts, highlights, math, Mermaid diagrams, links between notes, front matter and collapsible sections. For each one you get copyable examples and, just as important, which dialect it belongs to, so you know where it will work. If you are new to Markdown, start with the beginner's guide and cheat sheet.

Which Markdown features work where?

Markdown is not one fixed standard. The core is CommonMark. GitHub Flavored Markdown (GFM) adds a handful of well-specified features on top. Everything else is an extension: a convention that one app introduced and others copied, sometimes with small differences.

Here is how three places handle the features in this guide, as of September 2026. GitHub and Obsidian are included because they are among the most common places Markdown notes end up; always check the documentation of the apps you use.

Sources: GitHub's pages on basic formatting, math and diagrams; Obsidian's basic and advanced syntax pages. The Cappa column describes the current editor.

How to make a Markdown table

A Markdown table has three parts: a header row, a delimiter row of hyphens, and the data rows. Cells are separated by pipes. The pipes at the start and end of each line are optional, but they make the table easier to read as text.

| Day | City | Budget |
| --- | --- | --- |
| Monday | Lisbon | €80 |
| Tuesday | Sintra | €45 |

The columns do not need to line up in the source. |a|b| works as well as a neatly padded row; aligned pipes are only for your own eyes. GitHub's documentation asks for at least three hyphens per column in the delimiter row, so --- is the safe habit.

Aligning columns

Colons in the delimiter row set the alignment of a column: :--- for left, :---: for center and ---: for right. Right alignment is handy for numbers.

| Item | Qty | Price |
| :--- | :---: | ---: |
| Coffee | 2 | 3.20 |
| Pastel de nata | 6 | 7.50 |

Pipes, line breaks and formatting inside cells

Cells can hold inline formatting: bold, italic, code, links. They cannot hold block elements such as lists, headings or code blocks. Three situations need care:

• A pipe inside a cell. Write \|, or the pipe starts a new column.
• A line break inside a cell. Markdown has no syntax for it, so the common workaround is the HTML tag <br>. GitHub and many other apps display it as a line break.
• Rows with a different number of cells. In GFM, missing cells are left empty and extra cells are dropped. Some apps are stricter, so keep every row the same length.

| Command | Meaning |
| --- | --- |
| `a \| b` | Send output of a to b |
| Pack | Passport<br>Charger |

Markdown task lists and checkboxes

A task list is an ordinary list whose items start with [ ] (open) or [x] (done). The space inside the brackets matters. Task lists come from GFM, so GitHub, Obsidian, Bear, Cappa and most note apps show them as checkboxes.

- [x] Book flights
- [ ] Reserve a table
    - [x] Pick a restaurant
    - [ ] Call before Friday
- [ ] Download offline maps

In most apps you tick a box by clicking it, and the app changes the character inside the brackets. The note stays plain text, so a search for - [ ] finds every open task across your files, even with a basic text editor.

In Cappa, clicking a checkbox toggles it, /todo at the start of a line inserts a new one, and Enter continues the list with a fresh open box. Completed items are dimmed rather than struck through. An optional setting, Sort completed todos, moves finished items below the open ones in each list.

Markdown footnotes

Footnotes keep side remarks and sources out of the main text. You place a marker such as [^1] where the note belongs and write the footnote text anywhere in the document, usually at the end. The renderer numbers the markers and collects the notes at the bottom.

Lisbon has seven hills.[^hills] The tram line 28 climbs most of them.[^tram]

[^hills]: The number is traditional; locals will argue about it.
[^tram]: Buy a day pass before boarding.

Labels can be numbers or words; [^hills] is easier to keep track of than [^7]. Footnotes are not part of CommonMark or the GFM specification, but GitHub supports them (except in wikis), and so do Obsidian, Bear and most note apps.

In Cappa, /footnote inserts the next free number and adds its definition at the end of the note, with the placeholder text selected so you can type straight away. If the numbers drift out of order after editing, Renumber footnotes in the note's More actions menu renumbers them in order of first use.

Callouts

A callout, which GitHub calls an alert, is a quote whose first line names a type. It renders as a colored box. GitHub supports five types: NOTE, TIP, IMPORTANT, WARNING and CAUTION.

> [!WARNING]
> The museum is closed on Mondays.

Obsidian supports the same syntax with more types and custom titles. Cappa supports the five GitHub types, written in capitals as above; /callout offers them in the block menu. In an app without callouts, the text still appears as an ordinary quote with [!WARNING] on its first line, which is readable enough.

Highlights and colored highlights

Two equals signs on each side highlight text, like a marker pen: ==check the date==. This extension is supported by Obsidian, Bear, iA Writer and Cappa, among others. GitHub does not support it and shows the equals signs. If a note must also look right on GitHub, use bold instead.

Meet at the ==north entrance==.

Cappa adds colors. After the closing ==, an attribute such as {color=red} picks one of five colors: green, red, blue, yellow or purple. Without it, the highlight uses the theme's default color. You do not have to type the attribute: right-click a highlight and choose a color, or Remove highlight.

==Confirmed=={color=green}
==Overdue=={color=red}
==Idea=={color=blue}

Math in Markdown

Most apps that support math use the notation of TeX, the typesetting system mathematicians have used for decades. Put inline math between single dollar signs and a formula on its own lines between double dollar signs. GitHub and Obsidian both render this with MathJax, a library that supports nearly all of TeX's math commands.

The area of a circle is $\pi r^2$.

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

A few conventions help math survive in any app. Leave no space right after the opening $ or before the closing one. Prices such as "$5 and $10" are a classic trap. Cappa follows the rules of Pandoc, a widely used document converter: no space just inside the dollar signs and no digit right after the closing one, so those prices stay text. For block formulas, keep $$ on lines of their own.

Mermaid diagrams in Markdown

Mermaid turns a short text description into a diagram. You write it in a code block whose language is mermaid. In an app without Mermaid support you simply see the text, which is still a readable description of the diagram.

flowchart LR
  A[Inbox] --> B{Actionable?}
  B -->|Yes| C[Project note]
  B -->|No| D[Archive]

The first line names the diagram type. flowchart LR draws left to right; TD draws top down. Square brackets make a box, curly braces a decision diamond, and -->|label| an arrow with a label. A sequence diagram, useful for "who says what to whom", looks like this:

sequenceDiagram
  Anna->>Hotel: Can we check in early?
  Hotel-->>Anna: Yes, after 11:00

GitHub and Obsidian render Mermaid, and so do many other tools, though each ships its own Mermaid version, so newer diagram types may not work everywhere.

In Cappa, Mermaid diagrams are drawn on your device and never sent to a rendering service. The editor supports a subset of diagram types: flowchart (or graph), sequenceDiagram, stateDiagram, classDiagram, erDiagram and xychart-beta (the current Mermaid documentation uses the shorter xychart, which Cappa does not recognize). The type must be on the first line of the block. For safety, a diagram that uses Mermaid directives, clickable links or HTML labels shows a message instead of a preview, and every drawn picture is sanitized before it is displayed. Very large or complex diagrams (for example, over 12,000 characters or 240 lines) also show a message instead of a preview. Type /mermaid to insert a starter diagram, use Edit source to change it, and turn previews off in the settings if you prefer to see only the text.

Links between notes (wikilinks)

A wikilink is a link to another note written with double square brackets: [[Packing list]]. It comes from wiki software and is central to apps like Obsidian. It is not standard Markdown: GitHub shows the brackets as text in regular files.

[[Packing list]]                   link to a note
[[Packing list#Documents]]         link to a heading in that note
[[Packing list#^passport]]         link to a block marked ^passport
[[Packing list|what to bring]]     link with your own text

A block ID is a caret and a short name, such as ^passport, at the end of the line you want to link to. Obsidian's links documentation describes the same forms, which is why notes written this way move between Obsidian and Cappa well.

Cappa supports all four forms. Typing [[ suggests note titles, titles match without regard to capitalization, and clicking a link to a note that does not exist yet offers to create it. When you rename a note from its menu, Cappa updates the wikilinks that point to it in your other notes (locked notes are left untouched). The Links tab in the note details lists the notes that link to the current one.

If a note must also work on GitHub, use a standard link to the file instead, such as [Packing list](packing-list.md). How to combine links, tags and folders is the subject of how to organize notes you can find again.

Front matter: YAML metadata at the top of a note

Front matter is a block of metadata at the very beginning of a file, between two lines of three hyphens. It uses YAML, a simple key: value format. Static site generators, Obsidian (which calls these properties) and many other tools read it.

---
title: Lisbon trip
tags: [travel, portugal]
aliases: [Portugal 2026]
created: 2026-05-02T09:30:00+01:00
---

The note starts here.

Front matter must be the first thing in the file; a --- block anywhere else is just a divider. GitHub shows front matter as a small table above a rendered file.

Cappa keeps front matter as a plain block at the top of the note and does not apply Markdown formatting inside it. /yaml inserts an empty one. When you use Import from Obsidian or Bear, Cappa reads title, tags, aliases and the created and updated dates: the tags are added to the note as regular #tags, aliases help resolve wikilinks during the import, and dates are kept when they include a time zone.

Collapsing sections

Markdown has no syntax for folding. There is a workaround on GitHub: the HTML <details> and <summary> tags create a collapsible block. It is HTML rather than Markdown, though, and many note apps, Cappa included, do not render it.

Note apps usually solve this in the editor instead. In Cappa you can collapse a heading's section, or a list item that has sub-items. Hover over the left margin next to the heading or item and click the control that appears, or press ⌘/Ctrl ' to fold the section that contains the cursor. Fold all sections and Unfold all sections are available from Quick Open (⌘/Ctrl K).

Once you use several of these features, the question becomes how to structure many notes, not one. Zettelkasten and PARA are two methods that pair well with wikilinks, tags and plain Markdown files.

FAQ

How do I add a line break inside a Markdown table cell?

Markdown has no syntax for it, so use the HTML tag <br> where you want the break. GitHub and most note apps display it correctly. In Cappa you can press Enter inside a cell and the editor writes the <br> for you.

Why does my Markdown table not render?

The most common causes are a missing delimiter row, fewer than three hyphens in a column of that row, or a table that starts directly under a line of text. Leave a blank line above the table, check that the header and delimiter rows have the same number of cells, and escape any pipe inside a cell as \|.

Can I use checkboxes in Markdown?

Yes, with task lists: - [ ] for an open item and - [x] for a finished one. They come from GitHub Flavored Markdown, so GitHub and most note apps render them as clickable or display-only checkboxes.

Does GitHub support Mermaid and math?

Yes. GitHub renders mermaid code blocks as diagrams and math between $ or $$ with MathJax. It does not support ==highlights== or [[wikilinks]] in regular Markdown files.

Is a highlight the same in every app?

No. ==text== is an extension. Obsidian, Bear, iA Writer and Cappa support it, while GitHub does not. Colored highlights such as ==text=={color=red} are specific to Cappa and show up as literal text elsewhere.