Org Mode for Markdown Users
If you already write in Markdown, you know most of Org mode already. Both are plain text with light markup for headings, lists, links and code. The differences are mostly which characters you type, plus a set of features Org has that Markdown doesn't: tasks, dates, an agenda, tables that calculate, and code blocks you can run.
This article is the translation guide I wish I'd had: Markdown on one side, Org on the other, then the gotchas that tripped me up, and what Org gives you in return. For the keys to actually do things in Doom Emacs, see the Org mode keybindings cheat sheet. For why I keep most notes in Markdown anyway, see Notes That Outlive the App.
The short version
- Headings use
*, not#. In Org,#at the start of a line is a comment. - Emphasis characters are different.
*bold*,/italic/,~code~. - Links use double square brackets.
[[url][text]]instead of[text](url). - Code blocks use
#+begin_src/#+end_srcinstead of triple backticks. - Front matter is
#+title:lines, not YAML. - Everything else is mostly the same: lists, checkboxes and tables look almost identical.
Syntax side by side
Headings and text
| What | Markdown | Org |
|---|---|---|
| Heading 1 | # Title | * Title |
| Heading 2 | ## Section | ** Section |
| Heading 3 | ### Sub | *** Sub |
| Bold | **bold** | *bold* |
| Italic | *italic* or _italic_ | /italic/ |
| Underline | (none) | _underline_ |
| Strikethrough | ~~strike~~ | +strike+ |
| Inline code | `code` | ~code~ |
| Verbatim text | `text` | =text= |
| Line break | two spaces, or \ at the end | \\ at the end of the line |
| Horizontal rule | --- | ----- (five or more dashes) |
| Comment | <!-- comment --> | # comment (at the start of a line) |
~code~ and =verbatim= look the same in most exports. By convention, use ~code~ for code and =verbatim= for file names, keys and literal text.
Lists and tasks
| What | Markdown | Org |
|---|---|---|
| Bullet list | - item or * item | - item or + item |
| Numbered list | 1. item | 1. item or 1) item |
| Checkbox | - [ ] task | - [ ] task |
| Done checkbox | - [x] task | - [X] task |
| Description list | (none) | - term :: description |
| Progress counter | (none) | - [1/3] Groceries or [33%] on the parent |
Don't use * for bullets in Org. At the start of a line it's a heading, and even indented it's easy to confuse. Stick with -.
Links and images
| What | Markdown | Org |
|---|---|---|
| Link | [text](https://example.com) | [[https://example.com][text]] |
| Bare link | <https://example.com> | https://example.com or [[https://example.com]] |
| Link to a file | [notes](notes.md) | [[file:notes.org][notes]] |
| Link to a heading | [see](#setup) | [[*Setup][see]] |
| Image |  | [[file:cat.png]] |
| Image with caption | (none) | #+caption: My cat on the line above |
| Footnote | text[^1] + [^1]: note | text[fn:1] + [fn:1] note |
In Emacs, a link shows only its description (text), and the brackets disappear. Press SPC m l t to show the raw syntax again, or SPC m l l to insert a link without typing the brackets.
Code blocks and quotes
A Markdown code block:
```python
print("hello")
```The same block in Org:
#+begin_src python
print("hello")
#+end_src| What | Markdown | Org |
|---|---|---|
| Code block | ```lang ... ``` | #+begin_src lang ... #+end_src |
| Plain block (no language) | ``` ... ``` | #+begin_example ... #+end_example |
| Quote | > quoted text | #+begin_quote ... #+end_quote |
| Raw HTML | <b>html</b> | @@html:<b>@@ inline, or #+begin_export html ... #+end_export |
You don't have to type the block markers. Press C-c C-, and pick s for a source block, q for a quote, e for an example.
Tables
Tables look the same, with one difference in the separator line:
| Tool | Format |
|---------|----------|
| Vimwiki | Markdown || Tool | Format |
|---------+----------|
| Vimwiki | Markdown |Org uses + where the lines cross. You never type it by hand, though: type |- and press TAB, and Org draws the line and lines up every column for you. That alone is a nice upgrade from Markdown tables.
Front matter
Markdown usually uses a YAML block. Org uses #+ keyword lines at the top of the file:
---
title: Zellij notes
author: Thomas
date: 2026-11-16
tags: [terminal, tools]
---#+title: Zellij notes
#+author: Thomas
#+date: 2026-11-16
#+filetags: :terminal:tools:Gotchas that catch Markdown users
#is not a heading.# Notesat the start of a line is a comment and won't show up in exports. This is the first mistake everybody makes.Asterisks at the start of a line are always headings. In Markdown,
* itemis a bullet. In Org it's a top-level heading. Use-for bullets.Slashes in paths can turn into italics. Text like
/usr/bin and /etc/may be shown as italic between the slashes. Wrap paths in=verbatim=(=/usr/bin=), which you should do anyway.Underscores become subscripts on export.
snake_case_nameexports as "snake" with "case" in subscript. Wrap it in~code~, or add this line to the top of the file so onlya_{b}with braces makes a subscript:#+options: ^:{}Emphasis needs a space or punctuation around it.
*bold*works, butun*bold*eddoesn't. In Markdown that's allowed.Emphasis can't span many lines. By default, bold or italic stops working if it runs over more than one line break. Keep it to a phrase.
Indentation is just visual. Under a heading, text does not need to be indented, and indenting it doesn't nest it. Only the number of
*decides the structure. (List items are different: there, indentation does matter, the same as Markdown.)Headings carry extra parts in a fixed order. A full heading looks like this, and the order matters:
* TODO [#A] Renew the domain :admin:web:That's the stars, then the TODO keyword, then the priority, then the title, then the tags. You'll rarely type these by hand, because the keys
SPC m t,SPC m p pandSPC m qadd each part in the right place.
What Org gives you that Markdown doesn't
This is why you'd bother learning a second syntax at all.
Tasks with states, dates and priorities
Any heading can be a task. Add a schedule or deadline on the line under it:
* TODO [#B] Write the Org mode article :blog:
SCHEDULED: <2026-11-20 Fri>
* NEXT Renew the domain :admin:
DEADLINE: <2026-11-27 Fri>
* DONE Set up org-roam
CLOSED: [2026-11-10 Tue 14:02]<...> dates are active: they show up in the agenda. [...] dates are inactive: they're just a record and stay out of the agenda. Change the state with SPC m t, and schedule with SPC m d s.
The agenda
The agenda (SPC o a a) reads every file in ~/org/ and shows what's scheduled or due this week, across all of them. Markdown has nothing like this without extra tools. It's the main reason I use Org for tasks.
Folding and moving whole sections
Press TAB on a heading to fold it, S-TAB to fold the whole file down to an outline. M-j and M-k move a heading and everything under it up or down. Restructuring a long document takes seconds.
Properties and tags
Headings can carry tags (:work:urgent:) and a properties drawer with any key-value data:
* Lilex Nerd Font
:PROPERTIES:
:URL: https://github.com/mishamyrt/Lilex
:LICENSE: OFL
:END:You can search and filter by both, in one file or across all your notes.
Tables that calculate
A formula under a table fills in a column for you:
| Item | Qty | Price | Total |
|---------+-----+-------+-------|
| Cable | 2 | 8.50 | 17.00 |
| Adapter | 1 | 12.00 | 12.00 |
#+TBLFM: $4=$2*$3;%.2fEdit a number and press SPC m b r (or C-c C-c on the #+TBLFM line) to recalculate.
Code blocks you can run
With the cursor in a #+begin_src block, press RET (or C-c C-c) and Org runs the code and puts the output underneath:
#+begin_src sh
uname -r
#+end_src
#+RESULTS:
: 7.0.0-43-genericThis is called Org Babel. It's great for notes on shell commands, because the note is the working example.
Going back and forth
You don't have to pick one format forever. Converting is easy.
Export from Emacs: SPC m e opens the export menu. Press m m to write a Markdown file next to the Org file. HTML, PDF (through LaTeX) and ODT are in the same menu.
Convert with pandoc from the command line, in either direction:
# Markdown to Org
pandoc -f markdown -t org notes.md -o notes.org
# Org to GitHub-flavored Markdown
pandoc -f org -t gfm notes.org -o notes.md
# A whole folder of Markdown files
for f in *.md; do pandoc -f markdown -t org "$f" -o "${f%.md}.org"; doneBasic syntax converts cleanly. Org-only features like TODO states, schedules, properties and Babel results either become plain text or are dropped, so convert a copy and check it before deleting anything.
Use both. Emacs is a perfectly good Markdown editor too. Doom's markdown module gives you syntax highlighting, folding with TAB and a preview. That's how I work: long-lived notes in Markdown, tasks and planning in Org.
A first week with Org
Don't try to learn everything at once. This order worked for me:
- Day 1: just write. Make
~/org/notes.org. Use*headings,-lists, andTABto fold. That's it. - Day 2: links and markup.
SPC m l lto insert links,*bold*,/italic/,~code~. - Day 3: tasks. Turn headings into tasks with
SPC m t. Mark them done. - Day 4: dates and the agenda. Schedule a few tasks with
SPC m d sand open the agenda withSPC o a a. - Day 5: capture. Use
SPC Xto grab a task from anywhere without leaving what you're working on. - Later: tables, code blocks, refiling, org-roam. Only when you have a reason to.
When you forget a key, press SPC m and wait for the which-key popup, or keep the keybindings cheat sheet open.

