Wikilinks, callouts and extended markdown syntax, explained

Extended markdown syntax is CommonMark plus GitHub Flavored Markdown plus a handful of plain-text conventions: wikilinks, embeds, callouts, highlights, comments and block ids. Obsidian made most of them popular, and today several apps read them, Jotura among them. All of it is plain text in a .md file, so an app that lacks a convention shows the characters you typed.

A wikilink is a note’s name in double square brackets, [[Project Atlas]]. The app finds the file with that name anywhere in your vault, the folder that holds your notes. There is no path and no .md to type, which is the practical difference from a standard markdown link like [Project Atlas](work/Project%20Atlas.md).

Cheat sheet

Jotura and Obsidian render most rows. The other columns show what happens to the same file in tools built around standard markdown.

Syntax	What it does	Jotura	Obsidian	GitHub	VS Code preview	Plain CommonMark
[[Note]]	Link to a note by name	Link	Link	Raw text	Raw text	Raw text
![[file]]	Embed a note, image or file	Images inline, others as a chip	Content shown inline	Raw text	Raw text	Raw text
> [!tip] Title	Callout with a title	Callout	Callout	Blockquote	Blockquote	Blockquote
> [!NOTE] alone	Callout without a title	Callout	Callout	Alert	Blockquote	Blockquote
==text==	Highlight	Highlight	Highlight	Raw text	Raw text	Raw text
%%text%%	Comment for the writer	Muted, left out of HTML export	Hidden in reading view	Raw text	Raw text	Raw text
[^1] and [^1]:	Footnote	Styled marker and definition	Footnote	Footnote	Raw text	Raw text
^[text]	Inline footnote	Raw text	Footnote in reading view	Raw text	Raw text	Raw text
^block-id	Names a block for linking	Kept in the file	Link target	Raw text	Raw text	Raw text
$x$ and $$x$$	Math in TeX	KaTeX on desktop	MathJax	MathJax	KaTeX	Raw text
#tag	Tag	Tag, click to search	Tag	Raw text	Raw text	Raw text
- [ ] and - [x]	Task list	Checkboxes	Checkboxes	Checkboxes	List items	List items
- [/], - [-]	Custom task state	Six states drawn, others kept	Ticked box	List items	List items	List items
```mermaid	Diagram	Diagram	Diagram	Diagram	Diagram	Code block

“Plain CommonMark” means a renderer with no extensions switched on, and many static site generators add plugins for footnotes, math and task lists. We checked the GitHub column against GitHub’s markdown API in October 2026. Properties, the YAML block at the top of a note, have their own section below.

Links and wikilinks

You type	It points at
[[Project Atlas]]	The note Project Atlas.md, in whatever folder it sits
[[Project Atlas.md]]	The same note, with the extension written out
[[work/Project Atlas]]	That path, counted from the vault root
[[Project Atlas|the Atlas work]]	The same note, displayed as “the Atlas work”
[[Project Atlas#Risks]]	The heading “Risks” inside that note
[[Project Atlas#^risk1]]	The block tagged ^risk1 inside that note
[[#Risks]]	A heading in the note you are reading
[[diagram.png]]	A file that is not a note, where the extension is required

Inside a table cell, write the pipe as \|, since a bare pipe ends the cell in GitHub Flavored Markdown tables. Markdown tables covers the rest of that syntax. Keep # | ^ : %% [[ ]] out of file names you plan to link to, because those characters already mean something inside a wikilink. Obsidian’s help gives the same warning.

The syntax comes from wiki software: Wikipedia and other MediaWiki sites write internal links as [[Page]], and GitHub wikis accept it. In a README or any other repository file, GitHub prints [[Note]] as literal brackets.

How a wikilink finds its note

The rules below come from Jotura’s resolver, which is documented in full and follows the same rules as Obsidian. Obsidian does not publish its full resolution order:

1. Case is ignored. [[project atlas]] finds Project Atlas.md.
2. The anchor comes off first. #Risks and #^risk1 are dropped before the lookup. An empty name, as in [[#Risks]], means the current note.
3. An exact path wins. [[work/Project Atlas]] finds work/Project Atlas.md even when archive/work/Project Atlas.md exists. A standard markdown link is tried relative to the note holding it, then from the vault root.
4. A bare name takes the shortest path. [[today]] opens inbox/today.md when no today.md sits at the root. Jotura breaks a tie at equal depth alphabetically.
5. An extension decides what can match. [[diagram.png]] matches files only, and [[diagram]] matches notes only. Among attachments sharing a name, the one in the attachment folder set in .obsidian/app.json wins, then the one beside the linking note.
6. Aliases come last. A name that matches no file is checked against each note’s frontmatter aliases.

There is no fuzzy fallback, so a link that matches no file stays unresolved. Clicking one in Jotura asks before creating the note at the path the link names, counted from the vault root. Obsidian creates it at that path, or in its default location for new notes when the link names no folder.

Duplicate names are the usual cause of a link opening the wrong note. Adding the folder, as in [[work/Project Atlas]], settles which one you mean. Obsidian’s New link format setting can add the folder for you, only when a bare name would match two notes.

Wikilinks vs markdown links

	Wikilink	Markdown link
Example	[[Project Atlas]]	[Project Atlas](work/Project%20Atlas.md)
Part of CommonMark	No	Yes
Needs the folder path	No	Yes, relative to the note or from the root
Spaces in the name	Typed as spaces	%20, or the whole path in angle brackets: (<work/Project Atlas.md>)
Survives the target moving folder	Yes, when written as a bare name	Only if the app rewrites the link
On GitHub	Raw brackets in repository files, a link in wikis	A link
In VS Code’s preview	Raw brackets, links with the Foam extension	A link
Display text	After a pipe	Inside the square brackets

Wikilinks are shorter to type and keep working through folder moves, so they suit links between notes that a notes app reads. A file published elsewhere, such as a README or a docs page built by a static site generator, needs markdown links to stay clickable. Mixing both styles in one vault is fine, and Jotura and Obsidian resolve both.

Aliases

An alias is an extra name a note answers to, declared in its frontmatter:

---
aliases:
  - Atlas
  - The Atlas work
---

With that block in Project Atlas.md, [[Atlas]] resolves to it. Write aliases as a YAML list, which every app that reads them accepts. Picking an alias from the link picker in Jotura or Obsidian inserts [[Project Atlas|Atlas]], which keeps the file name as the target, so the link still works in apps that ignore aliases. Aliases suit acronyms, nicknames and a note’s old name after a rename.

Embeds

An embed is a wikilink with a leading !. An app that supports embeds shows the target inside the current note:

![[Project Atlas]]
![[Project Atlas#Risks]]
![[Project Atlas#^risk1]]
![[diagram.png|300]]
![[diagram.png|640x480]]
![[contract.pdf#page=3]]

An image takes a width, or a width and height, after the pipe. Jotura draws embedded images inline and shows every other embed as a chip that opens the target. Obsidian also draws the text of an embedded note, heading or block, updating as the source changes, along with PDFs at a given page, audio files and canvases.

Callouts

A callout is a blockquote whose first line names a type in square brackets after an exclamation mark. Text after the type becomes the title, and with no text the type name is the title.

> [!warning] Back up first
> The steps below rewrite files in place.

> [!tip]- Folded by default
> A minus after the type collapses the callout. A plus expands it.

> [!info] A title-only callout has no body

> [!question] Outer
> > [!note] Inner
> > Nest a callout by adding another `>`.

The body takes any markdown, including lists, code blocks, wikilinks and embeds. Type names are case-insensitive, and an unknown type renders with the note style. The common set of types, as Obsidian defines them, with the aliases that share their look:

Type	Aliases
note, info, todo, bug, example	none
abstract	summary, tldr
tip	hint, important
success	check, done
question	help, faq
warning	caution, attention
failure	fail, missing
danger	error
quote	cite

Any word works as a type, and Jotura draws a type it does not know with the default look. In Obsidian a custom type takes its color and icon from a CSS snippet. The data-callout value is the type you will write, and the icon is a Lucide icon id:

.callout[data-callout="decision"] {
  --callout-color: #2e7d32;
  --callout-icon: lucide-alert-circle;
}

Callouts that also render on GitHub

GitHub calls the same idea “alerts” and supports five types: NOTE, TIP, IMPORTANT, WARNING and CAUTION. Our test through GitHub’s markdown API found the type case-insensitive. A title on the first line, a - or + fold marker, or any other type turns the alert into a plain blockquote, and alerts cannot be nested.

For one file that renders everywhere, put one of the five types alone on the first line. Jotura draws all five as callouts, and Obsidian treats important as tip and caution as warning.

> [!warning]
> Back up the vault first.

Highlights

Wrap text in double equals signs:

The deadline is ==Friday 16 October==, a week earlier than planned.

Obsidian supports six highlight colors, chosen by typing a color emoji such as the red circle straight after the opening ==. Apps that lack the color feature, Jotura included, show the emoji inside a plain highlight.

Comments

Text between double percent signs is a note to yourself:

Shipping on Friday. %% confirm with legal first %%

%%
A block comment starts with %% at the beginning of a line
and runs to the next %%.
%%

Jotura shows comments in a muted color and leaves them out when you export a note to HTML. Obsidian shows them in editing view and hides them in reading view, where an unclosed block comment hides the rest of the note. Other renderers print comments as text, so keep anything private out of them. An HTML comment, <!-- like this -->, stays hidden on GitHub too, though Jotura shows it as text.

Footnotes

A footnote is a marker plus a matching definition anywhere in the note:

The figure is from the annual report.[^1] The audit disagreed.[^audit]

[^1]: Annual report, page 12.
[^audit]: Audit letter, section 3.
  An indented second line continues the footnote.

Labels can be numbers or words without spaces, and Obsidian displays named footnotes as numbers. GitHub gathers footnotes at the bottom of the page with links back to each marker, though GitHub wikis do not support them.

Inline footnotes, ^[The text of the note.], put the caret outside the brackets. They render only in Obsidian’s reading view and nowhere else in the cheat sheet, so prefer the labeled form.

Block ids

A block id names one paragraph so other notes can link to it. Add a space, a caret and the id at the end of the paragraph:

The budget review moves to March. ^budget-move

A list, quote, callout or table takes its id on a separate line after the block, with a blank line on each side. Ids use Latin letters, numbers and dashes. Link with [[Project Atlas#^budget-move]], or embed with ![[Project Atlas#^budget-move]], and expect other renderers to show the caret and id as text.

Math

Write TeX between dollar signs, one pair inline and two for a block:

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

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

Jotura’s desktop app typesets both forms with KaTeX, and Obsidian and GitHub use MathJax. GitHub also accepts $`...`$ inline and a fenced block tagged math, useful when the TeX contains markdown characters. VS Code’s built-in preview uses KaTeX, switched by the markdown.math.enabled setting.

Tags

A tag is a # followed by a word, anywhere in the body: #meeting. Clicking one in Jotura searches the vault for it. A slash nests tags, so #inbox/to-read sits under #inbox, and searching Obsidian for tag:inbox finds both. Tags are case-insensitive and cannot contain spaces. Obsidian allows letters, numbers, _, -, / and most Unicode characters, and a tag needs at least one character that is not a digit, so #1984 is not a tag.

Properties

Properties are the YAML block at the very top of a note, between two --- lines:

---
tags:
  - recipe
  - cooking
aliases:
  - Weeknight pasta
due: 2026-10-30
draft: true
---

Obsidian types each property as text, list, number, checkbox, date or date and time. It treats three names specially: tags, aliases and cssclasses, the last for styling one note with a CSS snippet. Its help asks for tags and aliases as lists, and it does not support nested properties or markdown inside a property. Static site generators and scripts read the same YAML front matter.

Task lists and task states

A task is a list item starting with a checkbox:

- [ ] Draft the release notes
- [x] Book the meeting room
- [/] Review the budget
- [-] Order new laptops

GitHub draws checkboxes for [ ] and [x] only and shows the other two lines as plain list items. Jotura draws [/] as in progress and [-] as cancelled. Obsidian treats any character between the brackets as done, so both count as completed tasks there.

Mermaid diagrams

A fenced code block tagged mermaid draws a Mermaid diagram:

```mermaid
flowchart LR
  Meeting --> Decision --> Task
```

Jotura, Obsidian, GitHub and VS Code’s built-in preview all draw it. Anywhere else it stays a readable code block.

Line breaks

Standard markdown joins two lines separated by a single return into one paragraph. A line break inside a paragraph needs two trailing spaces, which Obsidian inserts when you press Shift+Enter, and a blank line starts a new paragraph. Obsidian’s Strict line breaks setting under Settings > Editor follows that rule; turn it off and single returns show as line breaks in reading view.

Backlinks

A backlink is a link read from the other end. When your Monday meeting note contains [[Project Atlas]], the meeting note is a backlink of Project Atlas. No file records it: apps work backlinks out from the links in your notes, so the list matches the files.

Jotura has no backlinks panel, and its command-line tool prints them, as the Jotura section below shows. Obsidian’s Backlinks core plugin lists them in the right sidebar, with Unlinked mentions for places where the note’s name appears as plain text. In VS Code, the Foam extension shows them in its Connections panel. With no app at all, grep gives a rough list from inside the vault:

grep -rniE '\[\[Project Atlas(\||#|\]\])' --include='*.md' .

That catches bare, piped and anchored wikilinks. It misses folder-qualified links, links through an alias and markdown links, and it cannot tell you which links are dead.

Renaming without breaking links

Renaming a note breaks every wikilink that used the old name, unless the tool doing the renaming updates them. Jotura’s file tree, jotura rename and Obsidian all rewrite links on rename. A file manager, git mv or a script changes the name and leaves the links pointing at nothing.

After a rename outside the app, add the old name as an alias and every old link resolves again with no other edits:

---
aliases:
  - Project Atlas
---

Edit the block in any text editor, keeping the list format. An alias only applies when no file has that name, so a leftover archive/Project Atlas.md would still win [[Project Atlas]].

Writing this syntax in Jotura

Jotura is a notes app for a folder of plain markdown files, on desktop and Android. It reads every construct on this page and keeps each one byte for byte through an edit, which a round-trip test suite enforces. A vault written in Obsidian opens as it is, and Coming from Obsidian covers what carries over.

To insert	Do this
A link	Type [[ or press Mod+L, then pick a note. Aliases match too
An embed	Type ![[ or press Mod+Shift+L
A callout, block math, comment block or footnote	Pick it from the / slash menu
A highlight	Select text, press Mod+Shift+H
Inline math	Mod+Shift+M
An inline comment	Mod+Shift+/
A task state	Right-click the checkbox

Mod is Command on macOS and Control elsewhere. A callout’s chevron writes the fold marker into the file.

Right-clicking a checkbox offers Todo, Done, In progress, Cancelled, Forwarded and Question, and any other character between the brackets stays as typed. The editor docs list the rest.

Renaming a note in Jotura’s file tree, or with jotura rename, rewrites every link that pointed at it. In a test vault, [[Project Atlas#Risks|the risks]] became [[Atlas Program#Risks|the risks]] and [plan](../work/Project%20Atlas.md) became [plan](../work/Atlas%20Program.md). Links through an alias and copies inside code were left alone.

The jotura command-line tool that ships with the app prints a note’s backlinks and its outgoing links:

jotura backlinks "work/Project Atlas.md"
jotura links "meetings/2026-10-06.md"

The CLI reference covers what they count, including that a markdown link in angle brackets is not counted. To add an alias from the CLI, jotura frontmatter set handles single-line values only, so use it when aliases is missing or written inline as [Atlas]. For a block list, edit in source mode (Mod+Shift+E).

Jotura has no graph view and no plugins. Note embeds show as chips without their content, highlight colors and inline footnotes are not drawn, a custom callout type gets the default look, and HTML comments show as text. The Android app shows math as TeX. Stay with Obsidian when you rely on its plugins, its graph view or embeds that show a note’s text, and the Obsidian comparison sets the two side by side.

Frequently asked questions

Do wikilinks work on GitHub?

In GitHub wikis, yes. In repository files such as a README, GitHub shows [[Note]] as literal brackets with no link. Write [Note](Note.md) there, with spaces as %20 or the path wrapped in angle brackets.

What is the difference between a wikilink and a backlink?

A wikilink is the link you type in one note, such as [[Project Atlas]] inside a meeting note. A backlink is that same link seen from the target, so the meeting note appears among Project Atlas’s backlinks. Apps compute backlinks from the links in your files, and no file stores them.

Why does my callout show as a plain quote on GitHub?

GitHub renders only five alert types (note, tip, important, warning and caution), and only when the type sits alone on the first line. A title, a - or + fold marker, or a type such as info turns it back into a blockquote. Write > [!warning] on its own line for a callout that works on GitHub and in notes apps alike.