Dev In The Mountain Header
A Developer In The mountains having fun

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_src instead 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

WhatMarkdownOrg
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 breaktwo 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

WhatMarkdownOrg
Bullet list- item or * item- item or + item
Numbered list1. item1. 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

WhatMarkdownOrg
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![alt](cat.png)[[file:cat.png]]
Image with caption(none)#+caption: My cat on the line above
Footnotetext[^1] + [^1]: notetext[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
WhatMarkdownOrg
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

  1. # is not a heading. # Notes at the start of a line is a comment and won't show up in exports. This is the first mistake everybody makes.

  2. Asterisks at the start of a line are always headings. In Markdown, * item is a bullet. In Org it's a top-level heading. Use - for bullets.

  3. 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.

  4. Underscores become subscripts on export. snake_case_name exports as "snake" with "case" in subscript. Wrap it in ~code~, or add this line to the top of the file so only a_{b} with braces makes a subscript:

    #+options: ^:{}
  5. Emphasis needs a space or punctuation around it. *bold* works, but un*bold*ed doesn't. In Markdown that's allowed.

  6. 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.

  7. 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.)

  8. 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 p and SPC m q add 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;%.2f

Edit 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-generic

This 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:

sh
# 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"; done

Basic 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:

  1. Day 1: just write. Make ~/org/notes.org. Use * headings, - lists, and TAB to fold. That's it.
  2. Day 2: links and markup. SPC m l l to insert links, *bold*, /italic/, ~code~.
  3. Day 3: tasks. Turn headings into tasks with SPC m t. Mark them done.
  4. Day 4: dates and the agenda. Schedule a few tasks with SPC m d s and open the agenda with SPC o a a.
  5. Day 5: capture. Use SPC X to grab a task from anywhere without leaving what you're working on.
  6. 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.


Links

More places to find me
Mental Health
follow me on Mastodon