Org Mode: Syntax, Emacs Keys, Neovim and Markdown Export

November 11, 2026 · 13 min read

Org Mode: Syntax, Emacs Setup, Neovim Plugins and Markdown Conversion

Org mode is a plain-text outlining and markup system built into GNU Emacs. One .org file can hold headlines, TODO items with dates, links, spreadsheet-style tables and runnable code. This reference shows each construct with the Emacs keystroke that makes it, the Vim and Neovim plugins, and what survives conversion to Markdown.

What Does Org Mode Do?

Org is a GNU Emacs major mode for notes, to-do lists, project planning, documents and literate programming, all stored as plain text. Carsten Dominik created it in 2003, and Ihor Radchenko maintains it today, according to the project homepage. Org mode for Emacs ships with the editor itself, so there's nothing extra to install. Like Markdown, it's a lightweight markup language, and our Markdown vs markup explainer covers what that term means.

People use it for five jobs, often in the same file:

  • Outlines you fold and unfold, from a single meeting note to a book draft.
  • Tasks. Any headline that starts with TODO is a task, and the agenda gathers tasks and dated entries from all your files into one view.
  • Tables that realign as you type and calculate like a small spreadsheet.
  • Code blocks that run in place and write their output back into the file.
  • Export to HTML, LaTeX, PDF, ODT, plain text, Markdown and more.

The catch is that the full feature set lives in Emacs. Other editors can read the syntax, but few run the agenda, the formulas or the code. If you're deciding between Org and Markdown for Emacs notes, our Emacs markdown-mode guide covers the Markdown side.

Org Mode Syntax on One Screen: Headlines, Emphasis, Lists and TODOs

Here's a small file that uses most of the everyday syntax:

#+TITLE: Project notes

* Tasks
** TODO Draft the outline :writing:
   SCHEDULED: <2026-11-16 Mon>
** DONE Pick a topic
* Notes
Org has *bold*, /italic/, _underline_, =verbatim=, ~code~ and +strike-through+.
** Shopping list [1/2]
- [X] Coffee
- [ ] Notebook

Read top to bottom, it does this:

  • #+TITLE: is a keyword line. Lines starting with #+ hold settings, and this one sets the title used on export.
  • One star at the left margin, followed by a space, makes a level 1 headline. Two stars make level 2, and so on.
  • TODO or DONE right after the stars turns a headline into a task. :writing: at the end is a tag.
  • SCHEDULED: on the line under a headline attaches a date. DEADLINE: works the same way.
  • The six emphasis markers wrap a word on both sides. Watch the single star: it means bold in Org but italic in Markdown.
  • List items start with -, + or 1., and [ ] or [X] turns an item into a checkbox. The [1/2] cookie on the headline counts ticked boxes for you.

Indenting the SCHEDULED: line is optional, since Org only needs it on the line right after the headline.

How Do You Open .org Files and Start Emacs Org Mode?

In Emacs, open any file ending in .org and it switches into Org automatically. For a file with another extension, run M-x org-mode, or put -*- mode: org; -*- on its first line. Outside Emacs, any text editor opens the file as plain text, and GitHub renders .org files in a repository as formatted pages.

Learn these Org mode Emacs keys first. C-c means hold Control and press c, and S-LEFT means Shift plus the left arrow.

KeysWhat it does
TAB on a headlineFolds or unfolds that subtree
S-TABCycles the whole file: overview, contents, everything
M-RETAdds a headline or list item at the current level
C-c C-tCycles a headline through unmarked, TODO and DONE
S-LEFT, S-RIGHTSteps to the previous or next TODO state
C-c C-c on a checkboxTicks or unticks it
C-c C-s, C-c C-dAdds a SCHEDULED or DEADLINE date
C-c C-qSets tags on the current headline
C-c C-eOpens the export dispatcher

Three handy commands have no default key: org-store-link, org-agenda and org-capture. The manual suggests binding them to C-c l, C-c a and C-c c in your init file. For the agenda, list your files in the org-agenda-files variable first. If the stars feel noisy, M-x org-indent-mode hides the leading ones and indents body text under each headline.

Org Mode Link Syntax: Web, File and Internal Links

An Org mode link wraps a target and an optional description in double square brackets: [[LINK][DESCRIPTION]], or just [[LINK]]. Once both closing brackets are in place, Emacs hides the markup and shows only the description, underlined. The Link Format section of the manual has the full rules.

[[https://orgmode.org/manual/][The Org manual]]
[[file:~/notes/ideas.org][My ideas file]]
[[file:report.pdf]]
[[*Budget][Jump to the Budget heading]]
[[#budget-2026][Budget section by custom ID]]
[[setup]]

The first three point outside the document. C-c C-o follows the link at point: web links open in your browser, text files open in Emacs, and other files such as PDFs go to a suitable app.

The last three are internal. *Budget targets the headline with that exact name. #budget-2026 targets the entry whose CUSTOM_ID property is budget-2026. A plain word like setup looks for a dedicated target written as <<setup>> somewhere in the file.

Use C-c C-l to insert a link, or to edit the one under the cursor. M-x org-store-link remembers your current location, and the next C-c C-l offers it from history. Inside the link part, square brackets need a backslash in front, and so does a backslash before a bracket or at the very end. C-c C-l escapes all of that for you.

In Markdown the order flips: [The Org manual](https://orgmode.org/manual/). On LaTeX export the same link becomes an \href command, which our LaTeX hyperlink guide explains.

Org Mode Tables: The Built-in Table Editor and Spreadsheet Formulas

Org mode tables are plain text that Emacs keeps aligned for you. Any line whose first non-space character is | is a table row, and a line starting with |- is a horizontal rule. Rows above the first rule form the header.

To start one, type |Item|Cost|, press RET, type |- and press TAB. Org draws the rule, pads every column and moves you to the next field. C-c | also works: it creates an empty table, or converts a selected region such as comma-separated lines.

Once you're inside, these keys do the editing:

  • TAB realigns and jumps to the next field, adding a row at the end. S-TAB goes back.
  • RET realigns and moves down a row.
  • M-LEFT and M-RIGHT move the whole column. M-UP and M-DOWN move the row.
  • C-c - inserts a horizontal rule below the current row.

Formulas live on a #+TBLFM: line directly under the table:

| Item    | Cost |
|---------+------|
| Hosting |   12 |
| Domain  |   15 |
|---------+------|
| Total   |   27 |
#+TBLFM: @>$2=vsum(@I..@II)

Read the formula as: in the last row (@>), column 2 ($2), put the sum of the rows between the first and second rules (@I..@II). Recalculation isn't automatic, so press C-c C-c on the #+TBLFM: line, or C-u C-c C-c inside the table. Functions like vsum come from Emacs Calc, which Org uses as its formula engine.

That formula is also the first casualty of conversion. Markdown has no table formulas, so the 27 becomes a plain number that goes stale the moment you edit a cost.

Source Blocks and Literate Programming With Org Babel

Org Babel runs source blocks in place. Write a block, press C-c C-c inside it, and Org inserts the output under a #+RESULTS: line. It asks for confirmation before executing anything, which is a default worth keeping.

#+BEGIN_SRC python :results output
print(6 * 7)
#+END_SRC

#+RESULTS:
: 42

Out of the box, only Emacs Lisp blocks can run. Enable other languages in your init file:

(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (python . t)))

C-c ' opens the block in a separate buffer with that language's own major mode, and C-c ' again brings you back. Tangling writes blocks out to real source files, which is how many people keep an Emacs config as a readable Org document.

Org Mode in Vim and Neovim: nvim-orgmode vs vim-orgmode

Two plugins bring Org files to the Vim family. nvim-orgmode is an Org clone written in Lua for Neovim, and its README requires Neovim 0.12.0 or later at the time of writing. vim-orgmode is an older Vim plugin written mainly in Python, and its README says plainly that it doesn't support all Org features.

Featurenvim-orgmode (Neovim)vim-orgmode (Vim)
Folding, TODO states, tagsYesYes
CheckboxesYes, toggle with <C-space>Yes
AgendaYes, <Leader>oaYes
CaptureYes, <Leader>ocNot implemented, per its guide
TablesAligns them with gqNot implemented, per its guide
Table formulasNot documentedNo
Source blocksEdit in a separate buffer, tangle to filesNot implemented, per its guide
ExportThrough Emacs, pandoc or a custom commandThrough an installed Emacs

A minimal Neovim Org mode setup, using the built-in package manager from the README:

vim.pack.add({ 'https://github.com/nvim-orgmode/orgmode' })
require('orgmode').setup({
  org_agenda_files = '~/orgfiles/**/*',
  org_default_notes_file = '~/orgfiles/refile.org',
})

Be realistic about what you get. Neither plugin's docs describe Babel-style code evaluation or #+TBLFM recalculation, so keep Emacs around for those. For outlines, tasks and an agenda, nvim-orgmode is the stronger pick. For editing Markdown itself, our Neovim Markdown guide covers the plugins.

Converting Org Mode to Markdown: ox-md, Pandoc and What Gets Lost

You have three practical routes from .org to .md. Each keeps the basics and drops different things.

Emacs ox-md. Org loads only the ASCII, HTML, iCalendar, LaTeX and ODT exporters by default. Add (require 'ox-md) to your init file, then press C-c C-e m m to write notes.md next to notes.org, overwriting any old copy without warning. The Markdown Export page explains that it targets John Gruber's original Markdown, so tables come out as HTML.

Pandoc. One command produces GitHub Flavored Markdown:

pandoc -f org -t gfm-raw_html --wrap=none notes.org -o notes.md

The -raw_html part stops pandoc from writing HTML: TODO keywords and tags come out as plain text, and underlines turn into italics. For more flags, see our pandoc conversion commands.

In the browser. Our markup converter turns pasted Org text into Markdown without installing anything. It's a line-by-line scanner, not a full parser like pandoc, so complex constructs aren't fully supported. Check tables, drawers and code blocks in its output.

We ran a test file through pandoc 3.8 and read the ox-md source to build this map:

Orgox-md resultpandoc -t gfm result
* Headline# Headline# Headline
*bold* and /italic/**bold** and *italic*Same
_underline_HTML spanHTML tag, or italic with -raw_html
+strike+HTML del tag~~strike~~
[[url][text]][text](url)[text](url)
[[*Heading]]Link to an HTML anchorPlain text, link lost
- [X] item- [X] item- [x] item
TODO and :tags:Plain text in the headingHTML spans, or plain text
SCHEDULED: and propertiesDroppedDropped
TableHTML tableGFM pipe table
#+TBLFM: formulaDropped, values keptDropped, values kept
#+BEGIN_SRC pythonIndented code, no languageFenced code tagged python
#+RESULTS: outputNot exported by defaultNot exported

We prefer pandoc with -t gfm-raw_html when the file is headed for GitHub. Tables stay pipe tables, code blocks keep their language tag, and checkboxes become task lists. Take this Org snippet:

- [X] Draft the outline
- [ ] Review the tables section

See the [[https://orgmode.org/manual/][Org manual]] for the full syntax.

| Item    | Cost |
|---------+------|
| Hosting |   12 |
| Domain  |   15 |
|---------+------|
| Total   |   27 |
#+TBLFM: @>$2=vsum(@I..@II)

The editor below holds what that pandoc command turns it into, not the Org source. Our editor's preview renders Markdown and doesn't read Org syntax, so convert first and paste the result in.

  • Draft the outline
  • Review the tables section

See the Org manual for the full syntax.

Item Cost
Hosting 12
Domain 15
Total 27
41 words223 characters10 lines
Markdown

The checkboxes show up as task list items, and the link and table render in the preview. Notice what's gone: the rule above Total and the formula. In Org, #+TBLFM computed that 27. In Markdown it's just a number, so update it by hand when a cost changes.

Org mode pays back the time you spend learning Emacs: outlines, tasks, tables and runnable code share one plain-text file. When a note has to leave Emacs, convert it with pandoc and check what came through, because formulas, dates and code results stay behind. Paste the result into the editor to confirm the headings, task lists and tables render correctly before the file goes anywhere else.