Skip to main content

Markdown to Org Mode: Moving Notes into Emacs

A practical guide to converting Markdown to Emacs Org mode: star headlines, slash italics, link syntax, and migrating notes, TODOs, and timestamps.

Published By Li Lei
#markdown #org-mode #emacs #converter #note-taking

Markdown to Org Mode: Moving Notes into Emacs

I spent three years writing notes in Markdown before I gave Emacs a real try. The first week was rough. I pasted a Markdown README straight into a .org file, hit TAB to fold a section, and nothing folded. My headings stayed flat, my **bold** words showed up as raw asterisks, and every link printed as visible [text](url) text on the page. Org mode is not Markdown with a different file extension. It is a different format with different rules, and a paste that ignores those rules produces a mess.

This guide walks through what actually changes when you go from Markdown to Org, so your notes land in Emacs the way you meant them. If you just want the conversion done, the Markdown to Org converter handles every rule below in one paste. But understanding the mapping makes you faster at editing the result.

Headings use stars, counted by level

The single biggest difference is headings. Markdown uses one to six hash marks. Org uses leading asterisks, one star per level, with a space after the stars. There is no hash, and there is no underline row.

The rule is literal: count the stars to read the level. A line that starts with one star is a top-level headline. Two stars is a child of the headline above it. Three stars is a grandchild. This is what makes Org fold so cleanly: when you press TAB on ** Getting started, every *** Install steps beneath it tucks away, because Org knows three stars sits under two.

Here is a small Markdown document and the Org it should become:

# Project notes
## Setup
### Install steps
Run the build.

becomes:

* Project notes
** Setup
*** Install steps
Run the build.

Notice # Heading turns into * Heading, ## Setup into ** Setup, and ### Install steps into *** Install steps. The hash count and the star count are the same number, so a level-three Markdown heading is always three stars in Org. Get this one mapping right and the outline folds correctly on the first try.

Emphasis: bold is one star, italic is a slash

Markdown emphasis collides with Org in a way that bites everyone once. Markdown uses doubled asterisks for bold and single asterisks for italic. Org uses single markers for everything:

  • *bold* — a single asterisk, not two
  • /italic/ — forward slashes, not asterisks
  • +strikethrough+ — plus signs
  • ~code~ or =verbatim= — inline fixed-width text

So Markdown **strong** becomes Org *strong*, Markdown *emphasis* becomes /emphasis/, and ~~struck~~ becomes +struck+. The trap is italic: if you leave a Markdown *italic* in an Org file, Org reads the single asterisk as bold and flips the meaning. Pasting raw Markdown emphasis into Org is the fastest way to a page full of literal asterisks.

Code blocks become source blocks

A fenced Markdown block turns into an Org source block. The three backticks and language tag become a #+BEGIN_SRC line, the code stays verbatim, and a #+END_SRC line closes it:

print("hi")

becomes:

#+BEGIN_SRC python
print("hi")
#+END_SRC

A fence with no language becomes a bare #+BEGIN_SRC. These are not cosmetic. Org source blocks get syntax highlighting, and with Babel you can execute the block right inside Emacs and capture its output below it. Inline code converts too: Markdown ` value with single backticks becomes ~value~` with tildes, which Org renders as fixed-width verbatim on the page.

Links and images flip their order

Org links are the construct people forget most, because the order is reversed. Markdown puts the description first, then the URL: [docs](https://example.com). Org puts the target first, then the description, both inside double square brackets: [[https://example.com][docs]].

A bare link with no text, [](url), becomes a plain [[url]]. An image is the same form without a description: ![logo](https://x.com/a.png) becomes [[https://x.com/a.png]], which is exactly how Org embeds an inline image. Toggle inline images in Emacs with C-c C-x C-v and the picture appears in the buffer. If you paste Markdown link syntax into Org unchanged, the link never resolves and the brackets show up as plain characters.

Migrating a whole notebook to Org-roam

The reason I converted at all was Org-roam, which turns a folder of .org files into a linked knowledge base with backlinks and a daily journal. Migration is mechanical once you have the mapping right:

  1. Convert each Markdown note so headings, emphasis, code, and links match Org syntax.
  2. Paste the Org output under a top-level headline, or save it as its own .org file in your roam directory.
  3. Run org-roam-db-sync so the new file gets indexed and its links become backlinks.

Lists carry over as-is — bullet and numbered lists work in both formats — and a Markdown block quote becomes a #+BEGIN_QUOTE block. What does not carry over automatically is structure that Markdown simply does not have: TODO states and timestamps. Those you add after conversion.

TODOs and timestamps are Org's home turf

Markdown has no native task state, so action items usually live as checkbox lines like - [ ] Ship the build. In Org, a headline can carry a TODO keyword and an agenda picks it up automatically. After converting, promote a list line to a headline and prefix it:

* TODO Ship the build
  DEADLINE: <2026-06-20 Sat>
* DONE Write the migration notes
  CLOSED: [2026-06-13 Sat]

The keyword is the first word after the stars; cycle it with C-c C-t. Timestamps go in angle brackets for active dates that show in the agenda, or square brackets for inactive ones that do not. A SCHEDULED: or DEADLINE: line under the headline is what makes the item appear in M-x org-agenda. This is the payoff of moving to Org: a flat Markdown checklist becomes a live, queryable agenda once the headings and keywords are in place.

A note on what stays in your browser

The conversion is plain JavaScript that runs in your browser tab — star headlines, source blocks, link rewriting, every regex pass. Nothing is uploaded, so a private journal never leaves the page. The one caveat is the shareable link: it encodes your input in the URL, so for a private note, use the copy button and paste the Org output directly instead of sharing the link.

If your target is a different markup language entirely, the same paste-and-convert approach works for Markdown to reStructuredText when you are feeding Sphinx instead of Emacs. But for an Org notebook, get the stars, the slashes, and the double-bracket links right, and your old Markdown archive folds, links, and schedules like it was born in Emacs.

Made by Toolora · Updated 2026-06-13