Markdown Reference · Syntax & Dialects
The definitive Markdown reference for macOS.
Master CommonMark, GitHub Flavored Markdown (GFM), and Obsidian extensions. Learn how standard formatting renders on disk and inside Oyma.
Every guide includes raw syntax snippets, specification differences across dialects, edge case behavior, and native live-preview rendering in Oyma.
Basic syntax
12 syntaxesHeadings
Structure documents clearly using ATX and Setext heading syntax across CommonMark and Obsidian.
# Heading 1
## Heading 2
### Heading 3View syntax guide →
Bold & Italic Emphasis
Format bold, italic, and combined emphasis cleanly with asterisks and underscores in CommonMark.
**bold text**
*italic text*
***bold and italic***View syntax guide →
Blockquotes
Format clean quotes, callouts, and indented citations using standard CommonMark blockquote syntax.
> Single blockquote
>
> > Nested blockquoteView syntax guide →
Ordered Lists
Structure sequential instructions, numbered steps, and nested lists using CommonMark ordered lists.
1. First step
2. Second step
1. Sub-step A
3. Third stepView syntax guide →
Unordered Lists
Create clean bullet lists, nested outlines, and structured notes using CommonMark unordered lists.
- First item
- Second item
- Sub-item A
- Sub-item B
- Third itemView syntax guide →
Links & Hyperlinks
Create clean web links, reference links, and autolinks using standard CommonMark hyperlink syntax.
[Anchor text](https://example.com)
[Reference text][ref]
<https://example.com>View syntax guide →
Images & Media
Embed local and remote images with alt text, captions, and sizing dimensions in CommonMark.
![[image.png|300]]View syntax guide →
Inline Code
Format functions, shell commands, and code variables cleanly using CommonMark backtick syntax.
`const apiKey = process.env.KEY;`
``Use a literal `backtick` inside``View syntax guide →
Fenced Code Blocks
Format multi-line code, scripts, and terminal commands with syntax highlighting in CommonMark.
```typescript
interface Note {
id: string;
content: string;
}
```View syntax guide →
Horizontal Rules & Dividers
Separate sections and chapters with elegant thematic divider lines using CommonMark horizontal rules.
---
***
___View syntax guide →
Line Breaks & Paragraphs
Control paragraph flow, hard line breaks, and poetic verse with CommonMark line break rules.
First line with two spaces
Second line directly beneath
New paragraph separated by blank lineView syntax guide →
Escaping Characters
Prevent accidental formatting and display literal symbols using CommonMark backslash escaping.
\*Not italic\*
\[Not a link\]
\# Not a headingView syntax guide →
Extended syntax
9 syntaxesTask Lists & Checkboxes
Track action items and project tasks with interactive GitHub Flavored Markdown checkboxes.
- [ ] Incomplete task item
- [x] Completed task item
- [ ] Nested sub-taskView syntax guide →
Tables & Alignment
Format structured data, matrices, and comparisons using GitHub Flavored Markdown pipe tables.
| Feature | Status | Notes |
| :--- | :---: | ---: |
| Offline | Clean | 100% on Mac |View syntax guide →
Strikethrough Text
Mark deleted, deprecated, or completed text with GitHub Flavored Markdown double tildes.
~~Strikethrough text~~
**~~Bold and struck through~~**View syntax guide →
Footnotes & Citations
Cite external references, annotate legal text, and add scholarly footnotes in Extended Markdown.
Here is a statement.[^1]
[^1]: Here is the corresponding footnote.View syntax guide →
Definition Lists
Structure glossaries, vocabulary indexes, and term definitions with Extended Markdown syntax.
Term Name
: Definition of the specified term.
: Second definition.View syntax guide →
Subscript & Superscript
Format chemical formulas, ordinal dates, and exponents using subscript and superscript in Markdown.
H~2~O (Chemical formula)
E = mc^2^ (Mathematical exponent)
10<sup>th</sup> anniversaryView syntax guide →
Keyboard Key Tags (<kbd>)
Format keyboard shortcuts and interactive keycaps cleanly using HTML kbd tags in Markdown.
<kbd>⌘</kbd> + <kbd>O</kbd> (Open palette)
<kbd>Ctrl</kbd> + <kbd>C</kbd> (Copy)View syntax guide →
HTML in Markdown
Embed semantic HTML tags, audio players, and details disclosures directly inside Markdown.
<details>
<summary>Click to reveal</summary>
Hidden content
</details>View syntax guide →
Emojis & Symbols
Incorporate expressive Unicode symbols and colon shortcodes seamlessly into Markdown documents.
:rocket: (Shortcode)
🚀 (Native Unicode)
:white_check_mark: (Verified badge)View syntax guide →
Advanced & Obsidian
9 syntaxesMath & LaTeX (KaTeX)
Typeset mathematical formulas and scientific notation using LaTeX and KaTeX in Markdown.
$E = mc^2$
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$View syntax guide →
YAML Frontmatter
Attach structured metadata, tags, and document properties to Markdown notes using YAML frontmatter.
---
title: "Note Title"
tags: [research, ai]
status: in-progress
updated: 2026-10-09
---View syntax guide →
Bidirectional [[WikiLinks]]
Connect notes into an interactive knowledge graph using double-bracket [[WikiLinks]] and aliases.
[[Target Note]]
[[Target Note|Custom Display Text]]
[[Target Note#Specific Heading]]View syntax guide →
Callouts & Admonitions
Create visually distinct callout boxes, warning alerts, and tips using Obsidian callout syntax.
> [!NOTE]
> Useful context and informational background.
> [!WARNING]
> Critical operational caveat.View syntax guide →
Text Highlights
Highlight critical passages and phrases using double equal signs in Obsidian and Extended Markdown.
==Highlighted text phrase==
**==Bold and highlighted text==**View syntax guide →
Comments & Hidden Notes
Embed private author notes, drafting comments, and hidden annotations in Markdown.
%%This is a private inline comment%%
%%
Multi-line private drafting comment
%%View syntax guide →
Mermaid Diagrams & Flowcharts
Generate interactive flowcharts, sequence diagrams, and architecture charts using plain-text Mermaid.
```mermaid
graph TD;
A[Audio Input] --> B[Whisper VAD];
B --> C[Markdown Note];
```View syntax guide →
Internal Anchors & Section Links
Navigate deeply within documents using heading anchors and block reference links.
[Jump to Summary](#executive-summary)
[[Document Name#Target Heading]]
[[Note#^block-id]]View syntax guide →
Media & File Embeds
Transclude notes, embed PDF documents, and display audio clips using Markdown embed syntax.
![[Target Note]]
![[document.pdf]]
![[meeting-audio.m4a]]
![[Target Note#Specific Section]]View syntax guide →
The evolution of Markdown dialects: CommonMark, GFM, and Obsidian
Created by John Gruber in 2004 with input from Aaron Swartz, Markdown revolutionized digital writing by introducing a lightweight markup syntax that translates plain text into semantically correct HTML while remaining effortlessly human-readable in its raw source form.
Over two decades of widespread adoption across open-source communities, software engineering platforms, and personal knowledge management applications, three distinct standards emerged:
- CommonMark: The rigorous, unambiguous specification designed by John MacFarlane, Jeff Atwood, and the CommonMark working group. CommonMark standardizes edge-case parsing rules for headings, lists, blockquotes, and paragraph breaks.
- GitHub Flavored Markdown (GFM): GitHub's formal extension to CommonMark, standardizing tables, task list checkboxes (
- [ ]and- [x]), autolinks, and strikethrough (~~text~~). - Obsidian Flavored Markdown: The knowledge management extension layer popularized by Obsidian and adopted by Oyma, adding bidirectional
[[WikiLinks]], callout admonitions (> [!NOTE]), math blocks ($...$), highlights (==text==), and YAML frontmatter.
How Oyma renders Markdown on macOS
In Oyma, your notes are never locked inside a proprietary database or encrypted binary blob. Every file is a standard CommonMark document stored directly on your Mac's filesystem in a folder you choose.
Our live-preview editor conceals complex Markdown syntax when your cursor moves away while keeping the raw characters untouched on disk. You get the fluid typographic elegance of a finished document alongside the permanent data sovereignty of pure plain text.
Explore related resources: check our live-preview editor guide, learn about spreadsheet-like tables, discover bidirectional [[WikiLinks]], inspect your notes with our Vault Health Inspector, or read Markdown basics in docs.
Your notes, in plain Markdown.
Experience lightning-fast writing on Apple Silicon. Open your vault and write without distractions.