Org Mode

Table of Contents

A GNU Emacs major mode for keeping notes, authoring documents, computational notebooks, literate programming, maintaining to-do lists, planning projects, and more — in a fast and effective plain text system.

1. Metadata

2. Markup

2.1. Heading

  • * ** ***, …
  • Promoting without heading is not allowed due to the need for simplicity and compatibility with LaTeX, DocBook and traditional book/article structures.(??, ????)
  • M-<right>, M-<left> demote and promote current heading or list item
  • C-M-<right>, C-M-<left> demote and promote current subtree
  • M-<up>, M-<down> swap up and down
  • M-RET new item, M-S-RET new checklist item

2.2. Tags

  • C-c C-q (org-set-tags-command) add tag to a topic.
  • C-c C-c does the same thing in a headline
  • @ and _ can be used within tag names.
  • #+TAGS: <tag>(<fast access key>) ... is used to set tags for a file
  • org-tag-alist defines the tags, with the second argument ?<fast access key>.

2.3. Format

Face

  • *bold*, /italic/, _underline_, +strikethrough+
  • ~code~, =verbatim=, : at the start of a line

List

  • + , - , * (nested) unordered list
    =term
    description= description list
    (no term)
    [ ] [-] [X] checkbox
  • 1. , 1) , A. , A) ordered list
    • [@N] start the number at N

2.4. Todo

  • C-c C-t or S-<right>, S-<left> org-todo, change the todo state

2.5. Link

[[target]] or [[target][desc]] where target can be type:target if no type is provided, org looks for the headings. <<target>> creates target point. Link to it with [[target]].

#+name: target match the exact name of an element. See External Links (The Org Manual), Internal Links (The Org Manual)

  • http:, https:
  • file:
    • it can be nested such as file:...::#id or file:...::*heading
    • The id is set by the CUSTOM_ID property.
  • org-link-set-parameters create custom link type
    • :follow <func> on open
    • :export <func>
    • :store <func>
    • :image-data-fun <func>
  • C-c C-l org-insert-link
  • C-c C-o org-open-at-point
  • The URL is hidden if org-link-descriptive is t

2.6. Footnote

  • [fn:Name], [fn:: inline], [fn:NAME: inline definition]
  • C-c C-x f footnote action. jump to the definition, or create a new footnote, and more
  • C-c C-c jump to the definition or jump back to the reference
  • C-c C-o or <mouse-1>, <mouse-2> follow the link, same as C-c C-c

2.7. Citation

The format is 

[cite/<style>/<variant>:<prefix> @<key> <suffix>; ...]

The bib source file can be added locally with #+bibliography: <BibTeX file> or globally with org-cite-global-bibliography variable.

  • C-c C-x @ (org-cite-insert)
    • select with RET
    • finish with M-RET (or C-M-j in some cases).

2.8. Image

  • Image is inserted as a link to the image file.
  • C-c C-x C-v to render image without description inline.
  • C-u C-c C-x C-v to render image with description inline.
  • Instead of manually rendering inline images for every buffer, the variable org-startup-with-inline-images can be set to t globally, or the directive #+STARTUP: inlineimages can be used per file.
  • #+caption: TEXT, #+name: NAME can be preceded to the image.
  • #+attr_org, #+attr_latex, #+attr_html: :TAG VALUE are used to set the display format.
  • When using TRAMP, change org-display-remote-inline-images to somthing other than skip

2.9. Block

A block 

#+begin_TYPE
#+end_TYPE

Block types include

  • center <c
  • comment
  • dynamic
  • example <e
  • export <ex
  • quote <q
  • special
  • verse <v
  • src <src

2.10. Comment

Line commnet # comment

Inline commnet @@comment: comment@@

Block comment 

#+begin_comment
#+end_comment

Section comment * COMMENT

3. Macro

  • #+macro: f ...$1... define macro
  • {{{f(1,...)}}} use macro

4. Commands

  • C-c C-j (org-goto) show outline in a new buffer and select from it
  • C-c C-q add tag to a topic
  • C-c C-, or C-c C-x s (org-insert-structure-template) insert org block at point or around a region
  • C-c C-x C-v (org-toggle-inline-images)
  • C-c C-x
    • Properties
      • p (org-set-property)
      • P (org-set-property-and-value)
    • Timer
      • ; (org-timer-set-timer) countdown timer, 0 (org-timer-start) countup timer
      • , (org-timer-pause-or-continue), _ (org-timer-stop)
      • . (org-timer) start a timer if there's none, and insert current elapsed time
    • Text
      • C-f (org-emphasize) choose bold, italic, and others.
    • ! reload all lisp files related to org.

5. LaTeX

  • org-cdlatex-mode enables the cdlatex bindings

5.1. LaTeX Preview

  • org-latex-preview is now being worked on to include live preview and support in other major modes.
  • The divpng did not work sometimes with the error .dvi was not found. Changing the relative path %f to absolute path %F fixed the issue.
    • It is not supported on the Karthink's branch
  • #+startup: latexpreview renders the LaTeX expressions on startup.
    • org-startup-with-latex-preview can be also be set to t
  • <C-c> <C-x> <C-l> preview the LaTeX fragment at the cursor, if no fragment for every fragment in the current entry.

6. Tasks

  • S-<rightarrow>, S-<leftarrow> to change the TODO status of a heading.
  • C-c , set or remove priority
  • C-c C-s schedule a heading, C-c C-d set a deadline
    • The datetime is delimited with <> or [].
    • S-<arrow> within the brackets alters the time.
  • [/] at the end of the parent heading indicate the number of completed tasks
  • Clock

7. Org Table   builtin

Each table cell is separated by | 

,| example | table |
,|---------+-------|
,|       1 |     2 |
  • C-c C-c align table
  • M-a, M-e beginning and end of a field.
  • M-<arrow> move a row or column
  • M-S-<right> insert column left (at point), M-S-<down> insert row above (at point)
  • M-S-<left> delete column at point, M-S-<up> delete row at point.
  • S-<arrow> move a cell
  • C-c - insert hline below
  • C-c RET insert hline below and move below the hline
  • S-RET first non-empty field above and insert copy of it below.
    • integer, time stamp, whole number prefixed/suffixed is incremented when org-table-copy-increment is set.
  • C-c TAB shrink or show specified columns.

7.1. Table Formula

7.1.1. Execution

  • C-c * (org-table-recalculate) apply column formulas left to right, and field/range formulas in the current row.
  • C-u C-c * or C-u C-c C-c recomputer the entire table, line by line, with the lines before the first hline is ignored.
  • C-u C-u C-c * or C-u C-u C-c C-c iteratatively recompute the entire table until no changes occur.
  • org-table-recalculate-buffer-tables
  • C-c <=> edit or create formula at the current cell.

7.1.2. Field Reference

  • Row
    • @0 Current Row
    • @1 Absolute, @+1 Relative, @< @> @>>> Relative to the top/bottom
    • @II Absolute hline, @+I @-II Relative hline, @II+2 Relative dataline relative to the absolute hline
  • Column
    • $0 Current Column
    • $1 Absolute, $-1 Relative, $> Relative to the left/right
  • Range
    • $1..$3 @-1$-2..@-1 @I..II (@I..@II)
  • Coordinate
    • @#, $# row or column number of the field for

7.1.3. Syntax

The calc expression is directly allowed.

  • if(COND, IF_TRUE, IF_FALSE)
  • string(STR)
  • vsum(RANGE)
  • vmean(RANGE)

Emacs lisp can be used. The expression needs to be quoted.

  • ;N at the end of an expression let emacs treats the result as a numerical value.

There are reference function as well

  • remote(TBL_NAME, REF)

7.2. Features

  • The content in the first column can create a special row
    • ! name definition of columns
    • ^, _ name definition of fields in the row above (or below)
    • # make the row recalculate automatically
    • * make the row selected for global recalculation
    • / the row is not exported
  • Any one of the fields in a column can be used to specify the width and alignment of the column.
    • <N> fixed width of N,with the ability to be expanded with C-c TAB.
    • <r>, <c>, <l> to align the contents
    • <rN> is also allowed

8. Org Babel   builtin

#+begin_src LANG OPTIONS
  SOURCE
#+end_src

The source code is only executable if the language is properly installed on the system and the language is loaded by Babel

Org Babel evaluates and manage code blocks. The language listed by org-babel-load-languages is loaded.

  • C-c C-c evaluate

8.1. Header

#+HEADER: can be used to specify the header right before the source block.

:var

  • VARIABLE=VALUE Give parameter to the script

:results

  • Collection
    • value return value, output standard output
  • Type: Result Type
    • table, vector, list, scalar, verbatim
    • file output to file set by :file <filename>.
  • Format: Result Format
    • raw, code, drawer
    • html Use BEGIN_EXPORT html
    • latex Use BEGIN_EXPORT latex
    • link, graphics Link to the file specified in :file header argument The code block output is not written to the disk
    • org Use BEGIN_SRC org block
    • pp Pretty-Print Source Code
  • Handling
    • replace
    • silent echo in the minibuffer
    • none compute the result without displaying them, but it can be used by other code blocks
    • discard The result is ignored. The value of the code block will be nil
    • append append to the buffer at the bottom
    • prepend Prepend to the buffer at the top

:tangle FILE

  • C-c C-v t tangle current file
  • C-u C-c C-v t tangle current block
  • C-c C-v f choose file to tangle
  • org-babel-tangle to process every block with :tangle tag
  • #+auto_tangle t global option is provided by org-auto-tangle package.

:exports

  • code
  • results
  • both
  • none

8.2. Dot

  • The Graphviz language
  • It generates graphs
    • title:
    • type:(2d|3d|radar|grid)
      • org-plot/preset-plot-types customize
    • with:
    • min: max:
    • labels:
    • set:

Plot the table with <C-c> " g or <M-x> org-plot/gnuplot

8.3. Asymptote

Vector graphics language

ob-asymptote only recognizes asymptote as the language. Asymptote package provides asym-mode.el in /usr/share/asymptote directory.

9. Org Agenda   builtin

  • C-c [ (org-agenda-file-to-front) adds current file to org-agenda-files, C-c ] removes current file.

9.1. Todo

  • C-c C-t (org-todo), or S-<left>, S-<right> rotate the state of TODO
  • C-u C-c C-t record timestamp and a note
  • C-u N C-c C-t changes to N th state.
  • org-todo-keywords can be configured. See
    • Format: (<fast access key><entering log>[/<leaving log>])
    • The fast access key becomes available after C-c C-t
    • ! log timestamp, @ log note and timestamp
    • the leaving log only works when the target keywords does not have logging enabled.
    • | within the sequence indicates that the keywords after it are DONE state.
    • The logging is enabled when the destination is set by the org-log-into-drawer variable.
  • [ / ] can be added at the end of a TODO heading to count the task done.
    • C-c C-c (org-toggle-checkbox)
    • C-c , (org-priority), S-<up>, S-<down> to change priorit
  • S-M-RET (org-insert-todo-heading)
  • Schedule and Deadline
    • C-c C-s to schedule a heading. C-c C-d to set a deadline
    • <DATETIME REPEATER WARNING> date can be repeated with +N[ymwdh], and warned with -N[ymwdh]
    • .+ is for repeat after done, ++ for repeat periodically.
  • habit module has to be enabled in org-modules to use :STYLE: habit.

9.2. Agenda View

  • g D (org-agenda-view-mode-dispatch) select the view format
  • A add agendas to view
  • D toggle diary
  • g j, g k next, previous item
  • g d goto date
  • * mark all
  • U, M, unmark all
  • u undo, r redo
  • Q quit
  • a add note to an agenda
  • m toggle mark
    • x bulk action
  • S-<left>, S-<right>, H, L shift the scheduled date
    • p change date with prompt
  • S-<up>, S-<down>, J, K shift the priority

10. Org Capture   builtin

10.1. Template

Capture templates are stored in org-capture-templates variable as a list of template.

A template has format of (KEY DESC TYPE TARGET TEMPLATE PROPS).

Type

  • entry org heading
  • item list item
  • checkitem
  • table-line new line in the first table
  • plain text

Target

  • (file PATH) at the beginning or end of the file
  • (id ID) child or body of the entry
  • (file+headline FILENAME HEADLINE) under the headline
  • (file+olp FILENAME HEADING SUBHEADING ...) full path to the heading
  • (file+regexp FILENAME REGEXP) regexp to the position
  • (file+function FILENAME FUNCTION) function to find the position
  • (function FUNCTION) function to visit the file and move the point
    • Use (set-buffer (find-file-noselect FILE)) in order to not show the buffer.
    • (org-capture-put :new-buffer t) is not set by default, which is responsible for killing the buffer with :kill-buffer t option.

Template Template can be given as a string, or as a file with (file PATH), or as an output of a function (function FUNCTION).

Following expansions can be used:

  • %[FILE] insert the content of FILE
  • %(EXP) evaluate elisp EXP
  • %<FORMAT> format-time-string of FORMAT
  • %:KEYWORD specific keywords depending on it is captured
  • %t date, %T date and time, %u and %U inactive timestamp
  • %i content of the selected region
  • %a annotation, nomally from org-store-link
  • %^{PROMPT} prompt the user and replace this
  • %^{PROP}p prompt the user for the property PROP
  • %? move point here

Properties

  • :kill-buffer t kill the capture target buffer after capture completion
  • :unnarrowed t do not narrow
  • :empty-lines N insert N newlines before and after the capture

11. Org Roam

Wrapper of Org Capture with more convenience.

The files are hashed into SQL database, stored in ~/.emacs.d/org-roam.db.

  • org-roam-db-sync and org-roam-db-autosync-mode to update the database

11.1. Template

The templates are defined in the variable org-roam-capture-templates.

A template looks like (KEY DESC TYPE TEMPLATE :target TARGET PROPS)

Templates The org-capture template syntax can be used. It can also be (file FILEPATH) to externally load the content.

A new expansion is added which can work within the filename.

  • ${foo} expansion dispatcher
    1. call the function foo with the current node as its argument
    2. call org-roam-node-foo with the current node as its argument
    3. look up org-roam-capture--info for foo
    4. read a string using completion-read. Default value can be provided with ${foo=default}

Properties The org-capture properties can be used.

  • :target specifies the target
    • (file+head FILE HEADING) replaces the file+headline in org capture

11.2. Keybindings

  • C-c n d daily note for today
  • C-c n c capture node
  • C-c n i insert node

12. Org Journal

  • org-journal-dir directory to store the journal files
  • org-journal-new-entry insert new entry under the daily heading

org-journal-file-type other than daily seems to be broken, as it does not recognize the CREATED property of the daily heading.

13. Org Drill

The org topic with :drill: tag will be used as a drill item.

14. Org Cliplink

Automatic insertion of title of the hyperlink

It provides org-cliplink and org-cliplink-capture, which is recommended to be bound to <C-x> p i.

15. org-special-block-extras

Enable the definition of custom blocks and links

16. Export and Publish

  • C-c C-e to export.
  • Use org-publish-project-alist to publish project-wise.

17. Configuration

  • org-startup-folded can be set to control how much the org document is folded
  • org-indent-mode pretty indent the headings
  • number each heading
    • org-startup-numerated can be set to t

18. References

Author: Jeemin Kim

Created: 2026-07-12 Sun 14:28