Syntax Reference

This reference covers the syntax the current Android app can parse, render, highlight, or assist with in the hybrid editor.

Otter supports standard Markdown plus several Otter-specific and markdown-it-style extras.

Reading this reference

• "Toolbar" means there is a dedicated button in the current editor toolbar.
• "Manual" means the syntax works when typed, even if there is no dedicated button for it in the current toolbar.
• Inside inline code or fenced code blocks, Otter intentionally keeps the raw text untouched.

Quick syntax map

Feature	Syntax	Current input path
Heading 1	# Title	Toolbar + manual
Heading 2	## Title	Toolbar + manual
Heading 3-6	### to ######	Manual
Bold	**text**	Toolbar + manual
Italic	_text_ or *text*	Toolbar inserts _; manual also works
Strikethrough	~~text~~	Manual
Highlight	==text==	Manual
Underline	~text~	Manual
Superscript	x^2^	Manual
Subscript	H~2~O	Manual
Inserted text	++text++	Manual
Inline code	`code`	Toolbar + manual
Markdown link	[label](https://example.com)	Toolbar + manual
Wiki link	[[Note title]]	Toolbar + manual
Bare URL	https://example.com	Manual
Angle-bracket autolink	<https://example.com>	Manual
Bullet list	- item	Toolbar + manual
Ordered list	1. item or 1) item	Manual
Task list	- [ ] item / - [x] item	Toolbar + manual
Block quote	> quote	Toolbar + manual
Horizontal rule	---	Manual
Fenced code block	triple backticks	Manual
Table	pipe table syntax	Manual
Footnote reference	[^1] plus [^1]: definition	Manual
Inline footnote	^[Footnote text]	Manual
Image		Manual
Definition list	Term then : Definition or ~ Definition	Manual
Container block	::: warning ... :::	Manual
Abbreviation	*[HTML]: HyperText Markup Language	Manual
Emoji alias	:smile:	Manual
Emoticon	:)	Manual
Tag	#work/project-a	Manual

Titles and body text

Otter stores a separate title field and a Markdown body.

• If the title field is blank, Otter derives the saved display title from the first non-blank line of the body.
• If both are blank, the note displays as Untitled.

Inline formatting

Bold

**bold**

• Toolbar button: Bold
• The toggle wraps the current selection with **.

Italic

_italic_
*italic*

• Toolbar button: Italic
• The current toolbar inserts _..._.
• Standard Markdown emphasis with *...* also works.

Strikethrough

~~done~~

• Manual only in the current toolbar.

Highlight

==important==

• Renders as highlighted text.
• Otter implements this as a custom extension on top of standard Markdown.

Underline

~underlined~

• Manual only.
• Uses single tildes.
• It cannot span a newline.
• ~~double tildes~~ are reserved for strikethrough, not underline.

Superscript

x^2^
19^th^

• Manual only.

Subscript

H~2~O
C~6~H~12~O~6~

• Manual only.
• Numeric single-tilde spans inside a word are treated as subscript.
• This is why H~2~O becomes subscript instead of underline.

Inserted text

++fresh++

• Manual only.
• Renders as inserted text.

Inline code

Use `render()` here.

• Toolbar button: Code
• Inline code suppresses nested styling inside the backticks.

Links

Markdown links

[Otter](https://otter.snyders.xyz)
[Docs](https://example.com "Optional title")

• Toolbar button: Link
• If text is selected, the toolbar wraps the selection and selects the URL placeholder.
• If no text is selected, the toolbar inserts [title](https://).

Bare URLs

https://commonmark.org

• Manual only.
• Otter linkifies bare URLs in prose.

Angle-bracket autolinks

<https://commonmark.org>

• Manual only.

Reference-style links

[Guide][guide]

[guide]: https://example.com/guide "Optional title"

• Manual only.
• The reference-definition line is hidden in the hybrid presentation when Otter can resolve it.

Wiki links

[[Release plan]]
[[Project Alpha]]

• Toolbar button: Wiki
• If you type [[ and then start entering a note title, Otter shows note-title suggestions.
• Picking a suggestion inserts the full title and closes ]].

Important rules:

• wiki links cannot span a newline
• the raw label inside [[...]] is stored exactly as typed
• on save, Otter resolves a wiki link to an existing note only if the label matches a note title exactly, ignoring case
• manually typed wiki links still remain in the note even if no current note matches

Tags

Tags are plain text in the body.

#journal
#work/project-a
#release_2026
#personal-weekend

Supported tag grammar in the current parser:

• tag starts with #
• first character after # must be a letter or number
• remaining characters may include letters, numbers, _, -, and /
• spaces are not supported
• nested tags use /

Examples that work:

#work
#work/project-a
#release_2026

Examples that do not fit the current parser:

#project alpha
#/leading-slash
#tag.with.dot

Otter extracts tags automatically when the note saves.

Lists

Bullet lists

- one
- two

Also accepted manually:

* one
+ two

• Toolbar button: Bullet

Ordered lists

1. Draft
2. Review

Also accepted by the current command/parser shape:

1) Draft
2) Review

• Manual only in the current toolbar.

Task lists

- [ ] Todo
- [x] Done
- [X] Also done

• Toolbar button: Todo
• Toolbar toggle inserts - [ ].
• Checked state is case-insensitive for x or X.

Quotes and separators

Block quote

> Keep it calm.
> Keep it portable.

• Toolbar button: Quote

Horizontal rule

---

• Manual only in the current toolbar.
• The internal editor command inserts ---.

Code blocks

Fenced code blocks

```kotlin
data class Note(
    val bodyMarkdown: String,
)
```

• Manual only in the current toolbar.
• Triple backticks are supported.
• An optional language label after the opening fence is supported and used for syntax highlighting.

Tables

| Feature | Status | Note |
|:--|:--:|--:|
| Hybrid editor | Ready | Calm |
| Backlinks | Later | V1.5 |

• Manual only.
• Alignment markers are supported in the divider row.

Footnotes

Referenced footnotes

Support careful references[^1].

[^1]: The detail lives here.

• Manual only in the current toolbar.
• The current editor command implementation can insert the next numeric label automatically, even though the toolbar does not currently expose a footnote button.

Inline footnotes

Otter keeps notes calm^[This is an inline footnote].

• Manual only.

Images

Inline Markdown images

![Otter notebook](https://example.com/otter.png)
![Stormtroopocat](https://example.com/stormtroopocat.jpg "Optional title")

Reference-style images

![Otter notebook][hero]

[hero]: https://example.com/otter.png "Warm cover"

Collapsed and shortcut reference image forms are also supported:

![Otter notebook][]

[otter notebook]: https://example.com/otter.png

![Otter notebook]

[otter notebook]: https://example.com/otter.png 'Warm cover'

HTML image tag

<img src="https://example.com/otter.png" alt="Otter notebook" title="Warm cover">

Notes:

• standalone image syntax is rendered as an image block in the hybrid editor
• inline images inside a sentence stay inline
• image syntax is supported even though the app does not yet expose a full attachment-management UI

Definition lists

Otter supports markdown-it-style definition lists.

Colon form

Calm
: Writing with focus

Tilde form

Term
~ Definition

You can also use multiple entries and continuation paragraphs:

Term 1

:   Definition 1
with lazy continuation.

Term 2
  ~ Definition 2a
  ~ Definition 2b

Container blocks

Otter supports fenced container blocks with :::.

Basic form

::: warning
Heads up.
:::

With explicit title

::: warning Heads up
Keep nested tags tidy.
:::

Notes:

• container kind must start with a letter
• the current parser accepts letters, numbers, _, and - in the kind after the first letter
• nesting is supported

Abbreviations

Use markdown-it-style abbreviation definitions:

*[HTML]: HyperText Markup Language

Use HTML for docs.

Otter hides the definition line in the hybrid presentation and replaces matching standalone uses with an abbreviation render.

Emoji aliases and emoticons

Supported alias form

:smile:
:rocket:
:white_check_mark:

Current built-in aliases:

• :+1:
• :-1:
• :blush:
• :bug:
• :clap:
• :coffee:
• :confused:
• :cry:
• :fire:
• :grin:
• :heart:
• :heart_eyes:
• :joy:
• :laughing:
• :memo:
• :neutral_face:
• :pray:
• :rocket:
• :scream:
• :slightly_frowning_face:
• :slightly_smiling_face:
• :smile:
• :sob:
• :sparkles:
• :sunglasses:
• :thinking:
• :tada:
• :thumbsdown:
• :thumbsup:
• :warning:
• :wave:
• :white_check_mark:
• :wink:
• :x:
• :yum:

Supported emoticons

• :-D
• :D
• :-)
• :)
• 8-)
• B-)
• ;-)
• ;)
• :-P
• :P
• :-(
• :(
• :'(
• :-/
• :/
• :-|
• :|
• <3
• X-)
• x-)

Boundary rules:

• aliases and emoticons are only replaced when they sit on sensible token boundaries
• Otter does not replace them inside code spans or fenced code blocks

Smart typography

Otter also performs typography substitutions on visible text outside code:

• straight quotes -> curly quotes
• apostrophes -> typographic apostrophes
• ... -> ellipsis
• -- -> en dash in valid contexts
• --- -> em dash in valid contexts
• (c) -> ©
• (tm) -> ™
• (r) -> ®
• (p) -> ℗
• +- -> ±

Examples:

"Otter's hybrid editor"
Wait.... alpha -- beta
(c) (TM) (r) (p) +-

Becomes visually:

“Otter’s hybrid editor”
Wait… alpha – beta
© ™ ® ℗ ±

Otter skips these typography conversions inside inline code, fenced code blocks, and protected autolinks.

Nested syntax

Otter supports nesting across many inline constructs.

Example:

==**_~quiet focus~_**==

The hybrid editor is designed to:

• let the closed result read as one calm span
• reveal the raw markers again when the caret moves back into that region

What the current toolbar does not expose

These syntax forms work when typed, but do not currently have their own dedicated toolbar button in the active editor toolbar:

• strikethrough
• highlight
• underline
• superscript
• subscript
• ordered lists
• horizontal rules
• fenced code blocks
• footnotes
• tables
• images
• definition lists
• container blocks
• abbreviations
• emoji aliases and emoticons

Safe habits

• Use the toolbar for the common flows you use every day.
• Type advanced syntax manually when you need it.
• Use wiki-link suggestions when possible so links resolve to existing note titles.
• Use tags without spaces so they are extracted correctly.
• If you want the cleanest reading surface, keep Hide completed Markdown markers enabled in Settings.