A visual reference · Org-mode
From a first paragraph to a reproducible report. Complete source. A small change. Its actual result.
Edition 3 - original example edition: 10 October 2026. Prepared for Lukas C. Bossert. Native export and editor results.
The Org file is the canonical source. Read the HTML guide beside your work, or download its PDF and source for offline reading.
Last changes: 2026-10-11. Unified tour–chapter–example IDs, numbered chapter anchors and updated direct links, downloads and comparisons. Reader pages now omit publishing instructions and highlight PDF downloads.
Reading the tour
Document
Org source becomes exported content: HTML fragments or real PDF pages.
Editor
Source, cursor and command produce actual buffer text, not a simulated editor.
Code and data
A source block produces a result or file. Babel evaluates; tangling extracts.
Read from the beginning or jump to a stable example ID. Each example includes its complete input and captured result. Copy link preserves the address of the guide you are reading, including its current domain and path.
Scope. This edition focuses on Doom Emacs without Evil. Standard Org / Emacs
keys are shown on every example; the keyboard reference explains non-Evil Doom
prefixes and contextual bindings. Command names remain usable through M-x.
C means Control, M Meta (usually Alt/Option), and S Shift. Cursor position
matters: commands may behave differently inside a table, a list or a heading.
Shared defaults. Examples start with no contents list, section numbers, author,
date or HTML postamble. Displayed options override these settings. Full-document
examples enable explicit metadata. Agenda examples use 12 October 2026. Task
completion logging is off. Each example has its own file, working directory and
Org buffer; Emacs starts with -Q.
Comparisons. A teal stripe marks source lines changed from the named comparison. HTML Before / After buttons switch both source and result; the PDF shows the After state. Some examples change a command rather than the source, and some refactorings deliberately produce the same output.
This tour assumes Doom's evil module is disabled, with :lang org enabled. Standard Org / Emacs keys appear on every example. Doom's non-Evil leader is C-c and its localleader is C-c l; these are configurable through doom-leader-alt-key and doom-localleader-alt-key. No modal editing is required. Press C-h k before a sequence to inspect the binding in your actual buffer. The computed examples run in plain Emacs -Q; Doom-specific aliases are documented separately and are not execution tests of your configuration.
| Keys | Command / prefix | Use |
|---|---|---|
Keys | Command / prefix | Use |
C-c | Doom leader | Global Doom command prefix; wait to see the available menu. |
C-c l | Doom localleader | Mode-specific Doom commands in an Org buffer. |
M-x command RET | execute-extended-command | Run any interactive command by name. |
C-h k, then keys | describe-key | Inspect the current binding; Doom may use a richer help frontend. |
C-h f | describe-function | Read a command's documentation. |
C-h m | describe-mode | Inspect active modes and their bindings. |
C-x C-f / C-x C-s | find-file / save-buffer | Open / save your .org file. |
C-SPC | set-mark-command | Start a region; move point to select text. |
C-_ or C-x u | undo | Undo an edit. |
Keyboard reference continued. Commands are available by name through M-x; context-specific keys require the indicated buffer.
| Keys | Command / prefix | Use |
|---|---|---|
C-g | keyboard-quit | Cancel a prompt or unfinished key sequence. |
C-u | universal-argument | Prefix the next command; its meaning depends on that command. |
M-: expression RET | eval-expression | Evaluate a Lisp expression shown by an inspect example. |
These aliases use Doom's standard non-Evil prefixes and the :lang org module. They are read from Doom's current module source (10 October 2026); your configured keys may differ. C-c l introduces the local menu: the letters after it are ordinary sequential keypresses. The spreadsheet examples include the recalculation prefix explicitly, because the unprefixed command updates only the current row.
| Keys | Command / prefix | Use |
|---|---|---|
Keys | Command | Use |
C-c l e | org-export-dispatch | Export menu; continue with h h for HTML or l p for PDF. |
C-c l ' | org-edit-special | Formula editor in a table; source editor inside a block. |
C-c l b f | org-table-edit-formulas | Open table formulas directly. |
C-c l b r / C-u C-c l b r | org-table-recalculate | Current row / whole table. |
C-c l b R | org-table-recalculate-buffer-tables | Recalculate every table in the buffer once. |
C-c l b t f / C-c l b t o | org-table-toggle-formula-debugger / org-table-toggle-coordinate-overlays | Formula debugger / coordinate grid. |
C-c l b a | org-table-align | Align the current table. |
C-c l t / C-c l x | org-todo / org-toggle-checkbox | Change task state / checkbox state. |
C-c l q / C-c l o | org-set-tags-command / org-set-property | Edit tags / a property. |
Keyboard reference continued. Commands are available by name through M-x; context-specific keys require the indicated buffer.
| Keys | Command / prefix | Use |
|---|---|---|
C-c l d s / C-c l d d | org-schedule / org-deadline | Schedule / deadline. |
C-c l d t / C-c l d T | org-time-stamp / org-time-stamp-inactive | Active / inactive timestamp. |
C-c l l l / C-c n l | org-insert-link / org-store-link | Insert / store a link. |
C-c n a a / C-c n t | org-agenda / org-todo-list | Agenda view / unfinished tasks. |
C-c l # | org-update-statistics-cookies | Refresh completion statistics. |
C-c l s n / C-c l s N | org-narrow-to-subtree / widen | Focus on a subtree / show the full buffer. |
C-c l s s m | org-sparse-tree | Interactive tag/property match. |
C means Control, M means Meta (usually Alt/Option), S means Shift. RET is Return; arrow names refer to arrow keys. A sequence such as C-c C-e h h is pressed in order. Org's editing commands depend on point: the same arrow shortcut can edit a heading, list item or table. On keyboards where C-SPC or modifier-arrow combinations are intercepted, use M-x with the command name.
| Keys | Command / prefix | Use |
|---|---|---|
Keys | Command | Use |
TAB / S-TAB | org-cycle / org-shifttab | Fold current heading / cycle the whole outline. |
M-RET | org-meta-return | Insert a heading or list item. |
M-LEFT / M-RIGHT | org-metaleft / org-metaright | Promote / demote heading or item at point. |
M-S-LEFT / M-S-RIGHT | org-shiftmetaleft / org-shiftmetaright | Change the level of an entire subtree. |
M-UP / M-DOWN | org-metaup / org-metadown | Move the current subtree or item. |
C-c C-n / C-c C-p | org-next-visible-heading / org-previous-visible-heading | Navigate visible headings. |
C-c C-u | outline-up-heading | Go to the parent heading. |
C-c ^, then a | org-sort | Sort sibling headings alphabetically at a heading. |
C-x n s / C-x n w | org-narrow-to-subtree / widen | Focus on a subtree / restore the whole buffer. |
Keyboard reference continued. Commands are available by name through M-x; context-specific keys require the indicated buffer.
| Keys | Command / prefix | Use |
|---|---|---|
C-c C-x C-f | org-emphasize | Add an emphasis marker to selected text; choose *, /, ~, = or +. |
C-c C-l / C-c C-o | org-insert-link / org-open-at-point | Insert or edit / follow a link. |
C-c C-x f | org-footnote-action | Create a footnote or jump between reference and definition. |
C-c C-x C-v | org-toggle-inline-images | Show or hide inline image previews. |
Inside a table, C-c C-c aligns it. On a #+TBLFM line, the same keys apply that formula set. Use C-c ' to edit formulas in a separate buffer: each assignment gets its own line, so long formulas remain manageable. If you see #ERROR, toggle the debugger with C-c {, then recalculate and inspect the substitutions. Arrow shortcuts act on whole rows or columns only when point is inside the table.
| Keys | Command / prefix | Use |
|---|---|---|
Keys | Command | Use |
TAB / S-TAB / RET | org-table-next-field / org-table-previous-field / org-table-next-row | Align and move through fields. |
C-c C-c | org-ctrl-c-ctrl-c | Align table; on #+TBLFM, apply that formula line. |
M-LEFT / M-RIGHT | org-table-move-column-left / org-table-move-column-right | Move the current column. |
M-UP / M-DOWN | org-table-move-row-up / org-table-move-row-down | Move the current row. |
M-S-RIGHT / M-S-LEFT | org-table-insert-column / org-table-delete-column | Insert / delete a column. |
M-S-DOWN / M-S-UP | org-table-insert-row / org-table-kill-row | Insert / delete a row. |
C-c - | org-table-insert-hline | Insert a horizontal separator below the row. |
C-c = / C-u C-c = | org-table-eval-formula | Edit a column / field formula. |
C-c * / C-u C-c * | org-table-recalculate | Recalculate current row / whole table. |
Keyboard reference continued. Commands are available by name through M-x; context-specific keys require the indicated buffer.
| Keys | Command / prefix | Use |
|---|---|---|
C-u C-u C-c * | org-table-iterate | Recalculate repeatedly until stable or the limit is reached. |
C-c ' | org-table-edit-formulas | Open the formula editor when point is inside a table. |
C-c C-c / C-u C-c C-c | org-table-fedit-finish | In formula editor: save / save and recalculate. |
C-c C-q | org-table-fedit-abort | In formula editor: leave without applying changes. |
C-c ? / C-c } | org-table-field-info / org-table-toggle-coordinate-overlays | Show current field coordinates / coordinate grid. |
C-c { | org-table-toggle-formula-debugger | Toggle formula debugging, then recalculate. |
Agenda commands read org-agenda-files. To include your current file temporarily, use C-c [; use C-c ] to remove it. Day-view keys below apply inside the agenda buffer. The guide fixes its agenda examples to 12 October 2026; your interactive agenda normally opens at the current date. M-x entry points work even if you have customized Doom's global menu.
| Keys | Command / prefix | Use |
|---|---|---|
Keys | Command | Use |
C-c C-t | org-todo | Change the TODO keyword of a heading. |
C-c , | org-priority | Set a heading's priority. |
M-S-RET | org-insert-todo-heading | New TODO heading; in a list, a checkbox item. |
C-c C-c | org-ctrl-c-ctrl-c | Toggle checkbox at point / refresh statistics cookie. |
C-c . / C-c ! | org-time-stamp / org-time-stamp-inactive | Insert active / inactive timestamp. |
C-c C-s / C-c C-d | org-schedule / org-deadline | Set scheduled date / deadline. |
C-c [ / C-c ] | org-agenda-file-to-front / org-remove-file | Add / remove current file from agenda files. |
M-x org-agenda RET a | org-agenda | Open the agenda view. |
d / w / j | org-agenda-day-view / org-agenda-week-view / org-agenda-goto-date | In agenda: day / week / chosen date. |
Keyboard reference continued. Commands are available by name through M-x; context-specific keys require the indicated buffer.
| Keys | Command / prefix | Use |
|---|---|---|
n / p / RET / q | org-agenda-next-line / org-agenda-previous-line / org-agenda-switch-to / org-agenda-quit | Navigate / visit item / quit agenda. |
M-x org-agenda RET t | org-todo-list | Show unfinished tasks across agenda files. |
C-c C-q | org-set-tags-command | Add or remove heading tags. |
C-c C-x p | org-set-property | Set a named property on the current heading. |
C-c / m | org-sparse-tree | Show entries matching a tag/property expression. |
Use the export dispatcher from the Org buffer. For a body-only HTML fragment like the guide previews, enable C-b in that dispatcher before h h; for a complete document, leave body-only off. The PDF examples require a working LaTeX installation. In Doom, enable the required Babel language support through its Org module/configuration. Execute only code you intend to run; tangling writes source files without running them.
| Keys | Command / prefix | Use |
|---|---|---|
Keys | Command | Use |
C-c C-e | org-export-dispatch | Open the export menu. |
C-c C-e h h / h o | org-html-export-to-html | From dispatcher: HTML file / HTML file and browser. |
C-c C-e l l / l p / l o | org-latex-export-to-latex / org-latex-export-to-pdf | LaTeX source / PDF / PDF and viewer. |
C-b / C-s | Export dispatcher toggles | Body-only / current subtree; press within the dispatcher. |
C-c C-, s | org-insert-structure-template | Insert a source block; enter the language. |
C-c ' | org-edit-special | Edit a source block in its language mode. |
C-c ' / C-c C-k | org-edit-src-exit / org-edit-src-abort | In source editor: accept changes / abort editing. |
C-c C-c | org-babel-execute-src-block (contextual dispatch) | Evaluate the source block at point. |
C-c C-v b | org-babel-execute-buffer | Evaluate source blocks throughout the current buffer. |
Keyboard reference continued. Commands are available by name through M-x; context-specific keys require the indicated buffer.
| Keys | Command / prefix | Use |
|---|---|---|
C-c C-v t | org-babel-tangle | Extract tangled files from the buffer. |
C-c C-v v | org-babel-expand-src-block | Inspect an expanded source block without executing it. |
C-c C-v g | org-babel-goto-named-src-block | Jump to a named source block. |
C-c C-v r | org-babel-goto-named-result | Jump to a named result. |
Begin with text. Introduce structure and metadata only when they change the result.
Official Org manual ↗An ordinary line of text is already a valid Org document.
Research begins with a question.Research begins with a question.
| Plain text | No wrapper or document environment is required. |
A blank line starts a new paragraph.
Research begins with a question.Research begins with a question.
Research begins with a question. Write down what you observe.Research begins with a question.
Write down what you observe.
| Blank line | Separates paragraphs; a single source newline normally does not. |
A star followed by a space introduces a top-level heading.
Research begins with a question. Write down what you observe.Research begins with a question.
Write down what you observe.
* Research notesResearch begins with a question.Research begins with a question.
| * | Level-one heading; the space after the star matters. |
Add a second star to make a child heading.
* Research notesResearch begins with a question.Research begins with a question.
* Research notesResearch begins with a question. ** ObservationsWrite down what you observe.Research begins with a question.
Write down what you observe.
| ** | Level-two heading inside the preceding level-one section. |
The title is document metadata, separate from the outline. This example uses a full HTML document so its title is visible.
* Research notesResearch begins with a question. ** ObservationsWrite down what you observe.Research begins with a question.
Write down what you observe.
#+TITLE: Field notebook* Research notesResearch begins with a question.Research begins with a question.
| #+TITLE: | Document title; the guide normally previews only the document body. |
Add an author to the same document. The full HTML export puts author metadata in its postamble.
#+TITLE: Field notebook* Research notesResearch begins with a question.Research begins with a question.
#+TITLE: Field notebook#+AUTHOR: Alex Researcher* Research notesResearch begins with a question.Research begins with a question.
| #+AUTHOR: | Author string used by the exporter. |
An explicit date makes the document independent of the export day.
#+TITLE: Field notebook#+AUTHOR: Alex Researcher* Research notesResearch begins with a question.Research begins with a question.
#+TITLE: Field notebook#+AUTHOR: Alex Researcher#+DATE: 12 October 2026* Research notesResearch begins with a question.Research begins with a question.
Date: 12 October 2026
| #+DATE: | Literal document date; an empty value suppresses the date. |
An abstract block identifies introductory summary content.
#+TITLE: Field notebook#+BEGIN_ABSTRACTA compact record of a small study.#+END_ABSTRACT* Research notesResearch begins with a question.A compact record of a small study.
Research begins with a question.
| #+BEGIN_ABSTRACT | Starts a special block named abstract. |
| #+END_ABSTRACT | Closes the block; HTML exports a container, while LaTeX uses an environment. |
Change a small piece of syntax and inspect the rendered text beside it.
Official Org manual ↗Use paired asterisks around a word.
A *reliable* workflow.A reliable workflow.
| *text* | Emphasis exported as strong text. |
Replace the emphasis markers.
A /reliable/ workflow.A reliable workflow.
| /text/ | Emphasis exported as italic text. |
Mark short pieces of code inside a sentence.
Run ~make~ to rebuild.
Run make to rebuild.
| ~text~ | Inline code; internal markup is not interpreted. |
Protect syntax that would otherwise be interpreted.
Keep =*this*= literal.
Keep *this* literal.
| =text= | Verbatim text; the stars remain visible. |
Mark a superseded phrase.
The result is +final+ provisional.
The result is final provisional.
| +text+ | Strike-through formatting. |
Start each item with a hyphen and a space.
Materials:- Notebook- PencilMaterials:
| - | Unordered list item. |
Indent an item beneath its parent.
Materials:- Notebook - Blank pages- PencilMaterials:
| Indentation | Keeps the child item inside the preceding list item. |
Use ordered markers when sequence matters.
1. Collect2. Check3. Publish| 1. | Starts an ordered list; Org can renumber it while editing. |
Associate terms with definitions.
- Input :: Raw observations- Output :: Checked observations| term :: definition | Description-list syntax. |
A verse block preserves intentional line breaks and indentation.
#+BEGIN_VERSEFirst line Second lineThird line#+END_VERSE
First line
Second line
Third line
| verse block | For text whose line structure matters. |
These are real buffer transformations. A command operates at the stated cursor location.
Official Org manual ↗Make Methods one level deeper. Its child is not demoted with it.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-do-demote)* StudyIntroduction.*** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.| org-do-demote | Moves the current heading one level down. |
| M-RIGHT | Standard Emacs binding; command names also work through M-x. |
Move Methods and its descendants together.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-do-demote)* StudyIntroduction.*** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-demote-subtree)* StudyIntroduction.*** MethodsCollect data.**** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.| org-demote-subtree | Preserves relative depths inside the subtree. |
| M-S-RIGHT | Meta + Shift + Right in standard bindings. |
Move Methods and its child one level up.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-demote-subtree)* StudyIntroduction.*** MethodsCollect data.**** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-promote-subtree)* StudyIntroduction.* MethodsCollect data.** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.| org-promote-subtree | Promotes the heading and every descendant. |
| M-S-LEFT | Standard binding. |
Swap Methods with the next sibling, Results. The Instruments child moves with Methods.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-move-subtree-down)* StudyIntroduction.** ResultsChecked data.** MethodsCollect data.*** InstrumentsA sensor.* AppendixDetails.| org-move-subtree-down | Moves across one sibling without losing child content. |
Sort the direct children of Study alphabetically.
* Study** ZebraLast alphabetically.** AlphaFirst alphabetically.** BetaIn the middle.(org-sort-entries nil ?a)* Study** AlphaFirst alphabetically.** BetaIn the middle.** ZebraLast alphabetically.| org-sort-entries | Sorts sibling entries. |
| ?a | The Lisp character a requests ascending alphabetical order. |
Narrow the buffer to Methods. The other text still exists but is outside the accessible region.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-narrow-to-subtree)** MethodsCollect data.*** InstrumentsA sensor.| org-narrow-to-subtree | Restricts the accessible buffer region. |
| C-x n s | Standard binding; C-x n w widens again. |
First narrow to Methods, then widen. The full buffer becomes accessible again.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-narrow-to-subtree)** MethodsCollect data.*** InstrumentsA sensor.* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-narrow-to-subtree)
(widen)* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.| widen | Removes narrowing without editing the document. |
Hide the body and descendants of Methods. The preview serializes visible buffer text and uses an ellipsis for each hidden region.
* StudyIntroduction.** MethodsCollect data.*** InstrumentsA sensor.** ResultsChecked data.* AppendixDetails.(org-fold-show-all)
(org-cycle)* StudyIntroduction.** Methods …** ResultsChecked data.* AppendixDetails.| org-cycle | Cycles the visibility of a heading. |
| TAB | With point on a heading, cycle its visibility. |
Make destinations explicit and keep internal references stable when headings change.
Official Org manual ↗A bracket link can display its destination directly.
[[https://orgmode.org/]]| [[URL]] | A link without a separate description. |
Add a description while keeping the same destination.
[[https://orgmode.org/][Org website]]| [[URL][description]] | The description is shown; the URL remains the destination. |
A star inside the link targets a heading by its text.
See [[*Results][the findings]]. * MethodsCollect data.* ResultsThe findings are ready.| [[*Heading]] | A fuzzy link to a heading in the same file. |
The link survives a change to the displayed heading text.
See [[#findings][the findings]]. * Results:PROPERTIES::CUSTOM_ID: findings:END:The findings are ready.See the findings.
The findings are ready.
| CUSTOM_ID | Explicit local target for this heading. |
| [[#findings]] | Links to that custom target. |
An explicit target can sit inside ordinary document content.
See [[sampling][the sampling step]]. <<sampling>>Take three readings.See the sampling step.
| <<sampling>> | Creates a named target. |
| [[sampling][...]] | References that target. |
Separate supporting detail from the main sentence.
| [fn:sample] | Named footnote reference and definition marker. |
Put the definition directly beside its reference.
| [fn::text] | Anonymous inline footnote; the exporter assigns a number. |
Use a relative path to keep the project portable. The HTML contains the small sample file as an embedded download.
Download [[file:assets/readings.csv][the readings]].Download the readings.
| file: | Local-file link. |
| Relative path | Resolved relative to the Org file; the ZIP includes the asset. |
Edit and recalculate real Org tables. Source formulas remain visible beside their evaluated buffer.
Official Org manual ↗ORG-05-001Export a small tableORG-05-002Align the source columnsORG-05-003Move a data row downORG-05-004Insert a columnORG-05-005Calculate a whole columnORG-05-006Change the multiplierORG-05-007Format decimal placesORG-05-008Calculate one specific fieldORG-05-009Sum a rangeORG-05-010Use an Emacs Lisp formulaORG-05-011Refer to a named tableORG-05-012Add a caption and a referenceA horizontal separator distinguishes the header from the data.
| Item | Count ||------+-------|| A | 2 || B | 5 || Item | Count |
|---|---|
| A | 2 |
| B | 5 |
| vertical bar | Separates cells. |
| vertical bar---+---vertical bar | Horizontal rule; exporter treats the preceding row as a header. |
Align the table in the Org buffer without changing its data.
| Item | Count ||------+-------|| A | 2 || B | 5 |(org-table-align)| Item | Count ||------+-------|| A | 2 || B | 5 || org-table-align | Pads cells so the pipe characters line up. |
| TAB | Also aligns while moving between table fields. |
Move the A row below B.
| Item | Count ||------+-------|| A | 2 || B | 5 |(org-table-align)
(org-table-move-row-down)| Item | Count ||------+-------|| B | 5 || A | 2 || org-table-move-row-down | Moves the current table row down one position. |
Insert an empty column at the Count field.
| Item | Count ||------+-------|| A | 2 || B | 5 |(org-table-align)
(org-table-insert-column)| Item | | Count ||------+---+-------|| A | | 2 || B | | 5 || org-table-insert-column | Inserts before the current column. |
| M-S-RIGHT | Standard binding inside a table. |
Compute the second column from the first.
| x | twice ||---+-------|| 2 | || 5 | |#+TBLFM: $2=2*$1(org-table-recalculate t)| x | twice ||---+-------|| 2 | 4 || 5 | 10 |#+TBLFM: $2=2*$1| $2 | Destination column. |
| $1 | Value from the first column in the same row. |
| 2*$1 | Multiply by two. |
Change only the multiplier; the second row now produces 15.
| x | twice ||---+-------|| 2 | || 5 | |#+TBLFM: $2=2*$1(org-table-recalculate t)| x | twice ||---+-------|| 2 | 4 || 5 | 10 |#+TBLFM: $2=2*$1| x | twice ||---+-------|| 2 | || 5 | |#+TBLFM: $2=3*$1(org-table-recalculate t)| x | twice ||---+-------|| 2 | 6 || 5 | 15 |#+TBLFM: $2=3*$1| 3*$1 | Multiply the current row's first field by three. |
Show the quotient with exactly two decimal places.
| x | twice ||---+-------|| 2 | || 5 | |#+TBLFM: $2=3*$1(org-table-recalculate t)| x | twice ||---+-------|| 2 | 6 || 5 | 15 |#+TBLFM: $2=3*$1| x | twice ||---+-------|| 2 | || 5 | |#+TBLFM: $2=$1/3;%.2f(org-table-recalculate t)| x | twice ||---+-------|| 2 | 0.67 || 5 | 1.67 |#+TBLFM: $2=$1/3;%.2f| ;%.2f | Calc formula output format: floating-point, two decimal places. |
Use row and column coordinates to fill the Total field.
| Label | Value ||-------+-------|| A | 2 || B | 5 || Total | |#+TBLFM: @4$2=@2$2+@3$2(org-table-recalculate t)| Label | Value ||-------+-------|| A | 2 || B | 5 || Total | 7 |#+TBLFM: @4$2=@2$2+@3$2| @4$2 | Fourth non-rule row, second column; the header counts as row 1. |
| @2$2+@3$2 | Add the values at the two explicit coordinates. |
Replace individual additions with a vector sum.
| Label | Value ||-------+-------|| A | 2 || B | 5 || Total | |#+TBLFM: @4$2=@2$2+@3$2(org-table-recalculate t)| Label | Value ||-------+-------|| A | 2 || B | 5 || Total | 7 |#+TBLFM: @4$2=@2$2+@3$2| Label | Value ||-------+-------|| A | 2 || B | 5 || C | 8 || Total | |#+TBLFM: @5$2=vsum(@2$2..@4$2)(org-table-recalculate t)| Label | Value ||-------+-------|| A | 2 || B | 5 || C | 8 || Total | 15 |#+TBLFM: @5$2=vsum(@2$2..@4$2)| vsum(...) | Sum the cells in a range. |
| .. | Inclusive range between two coordinates. |
Use Lisp instead of Calc for the same numerical transformation.
| x | twice ||---+-------|| 2 | || 5 | |#+TBLFM: $2='(* 2 $1);N(org-table-recalculate t)| x | twice ||---+-------|| 2 | 4 || 5 | 10 |#+TBLFM: $2='(* 2 $1);N| ' | Selects an Emacs Lisp formula. |
| ;N | Convert referenced fields to numbers before evaluating. |
Read a value from another table in the same document.
#+NAME: inputs| Item | Count ||------+-------|| A | 2 || B | 5 | | Summary | Value ||---------+-------|| First | |#+TBLFM: @2$2=remote(inputs,@2$2)(org-table-recalculate t)#+NAME: inputs| Item | Count ||------+-------|| A | 2 || B | 5 | | Summary | Value ||---------+-------|| First | 2 |#+TBLFM: @2$2=remote(inputs,@2$2)| #+NAME: inputs | Names the source table. |
| remote(inputs,@2$2) | Reads its row 2, column 2. |
Give the exported table a caption and a named reference.
See [[tab:counts]]. #+NAME: tab:counts#+CAPTION: Observations by group| Item | Count ||------+-------|| A | 2 || B | 5 |See 1.
| Item | Count |
|---|---|
| A | 2 |
| B | 5 |
| #+CAPTION: | Caption for the next element. |
| #+NAME: | Named export target; references use the exported label/number. |
Cell references, aggregates, conditions and dependencies: start with a calculated column, then change one formula or one recalculation command at a time. Every result is computed by Org. Use the keyboard reference for formula editing and debugging.
Official Org manual ↗ORG-06-001Multiply two columnsORG-06-002Target one cellORG-06-003Target a rectangular rangeORG-06-004Keep a parameter cell fixedORG-06-005Refer to nearby columnsORG-06-006Put a total in the last rowORG-06-007Use separators as range boundariesORG-06-008Sum across a rowORG-06-009Calculate a row averageORG-06-010Calculate a weighted meanORG-06-011Show a share as a percentageORG-06-012Build a running totalORG-06-013Compare with the previous rowORG-06-014Choose between two valuesORG-06-015Guard against division by zeroORG-06-016Ignore empty cells in a meanORG-06-017Treat empty cells as zeroORG-06-018Format fixed decimal placesCell references, aggregates, conditions and dependencies: start with a calculated column, then change one formula or one recalculation command at a time. Every result is computed by Org. Use the keyboard reference for formula editing and debugging.
Official Org manual ↗ORG-06-019Use scientific notationORG-06-020Keep exact fractionsORG-06-021Use degrees in trigonometryORG-06-022Switch to radiansORG-06-023Name a file-level constantORG-06-024Give columns meaningful namesORG-06-025Keep a parameter beside the dataORG-06-026Read a heading propertyORG-06-027Chain formulas from left to rightORG-06-028See a dependency that needs another passORG-06-029Iterate until values stabilizeORG-06-030Recalculate only the current rowORG-06-031Aggregate a different tableORG-06-032Look up a row by its keyORG-06-033Transform text with Emacs LispORG-06-034Use numeric Lisp argumentsORG-06-035Add durationsORG-06-036Convert a duration to decimal hoursCell references, aggregates, conditions and dependencies: start with a calculated column, then change one formula or one recalculation command at a time. Every result is computed by Org. Use the keyboard reference for formula editing and debugging.
Official Org manual ↗A column formula fills the data rows below the first separator. Edit the inputs, then recalculate: ordinary Org tables do not update continuously.
| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: $4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | 20 |#+TBLFM: $4=$2*$3| $4 | Destination: column 4. |
| $2*$3 | Multiply quantity by price in the current row. |
| C-c = | Edit a column formula while the cursor is in that column. |
Replace the column destination with an explicit row and column. The second item is left untouched. Row numbers count the header but skip separator lines.
| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: $4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | 20 |#+TBLFM: $4=$2*$3| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: @2$4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | |#+TBLFM: @2$4=$2*$3| @2$4 | Row 2, column 4: the first data row. |
| C-u C-c = | Edit a field formula at the destination cell. |
A range on the left applies the formula to each destination. Here the range has one column and two rows; the final row stays blank.
| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: @2$4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | |#+TBLFM: @2$4=$2*$3| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | || Ink | 1 | 8 | |#+TBLFM: @2$4..@3$4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | 20 || Ink | 1 | 8 | |#+TBLFM: @2$4..@3$4=$2*$3| @2$4..@3$4 | Inclusive destination range. |
| C-c } | Show row and column coordinates over the table. |
Both data rows read the same parameter cell. Absolute references keep the row and column explicit when the formula is applied elsewhere.
| Item | Value | Scaled || Gain | 3 | ||------+-------+--------|| A | 2 | || B | 5 | |#+TBLFM: $3=$2*@2$2(org-table-recalculate t)| Item | Value | Scaled || Gain | 3 | ||------+-------+--------|| A | 2 | 6 || B | 5 | 15 |#+TBLFM: $3=$2*@2$2| @2$2 | Fixed cell containing the gain. |
| First separator | Column formulas skip the two header rows above it. |
Relative column references are measured from the destination. This is the same multiplication as example 001, expressed as two steps and one step to the left.
| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: $4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | 20 |#+TBLFM: $4=$2*$3| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: $4=$-2*$-1(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | 20 |#+TBLFM: $4=$-2*$-1| $-2 | Two columns left of the current destination. |
| $-1 | One column left of the current destination. |
The destination follows the final row. The sum stops one row before it, avoiding a self-reference when you add more data rows.
| Item | Amount ||-------+--------|| Pen | 6 || Pad | 20 ||-------+--------|| Total | |#+TBLFM: @>$2=vsum(@2$2..@-1$2)(org-table-recalculate t)| Item | Amount ||-------+--------|| Pen | 6 || Pad | 20 ||-------+--------|| Total | 26 |#+TBLFM: @>$2=vsum(@2$2..@-1$2)| @> | Last row; @< would mean the first row. |
| @-1 | Row immediately before the destination. |
| vsum(...) | Sum the values in a range. |
Horizontal rules can define a data region. Only the values between the first and second separator enter the sum.
| Item | Amount ||-------+--------|| Pen | 6 || Pad | 20 ||-------+--------|| Total | |#+TBLFM: @>$2=vsum(@2$2..@-1$2)(org-table-recalculate t)| Item | Amount ||-------+--------|| Pen | 6 || Pad | 20 ||-------+--------|| Total | 26 |#+TBLFM: @>$2=vsum(@2$2..@-1$2)| Item | Amount ||-------+--------|| Pen | 6 || Pad | 20 ||-------+--------|| Total | |#+TBLFM: @>$2=vsum(@I$2..@II$2)(org-table-recalculate t)| Item | Amount ||-------+--------|| Pen | 6 || Pad | 20 ||-------+--------|| Total | 26 |#+TBLFM: @>$2=vsum(@I$2..@II$2)| @I / @II | First / second horizontal separator. |
| Range endpoints | The separator lines themselves contain no values. |
Ranges work horizontally as well as vertically. The current row is implicit when only columns are specified.
| Team | Jan | Feb | Mar | Total ||------+-----+-----+-----+-------|| A | 2 | 3 | 4 | || B | 5 | 1 | 6 | |#+TBLFM: $5=vsum($2..$4)(org-table-recalculate t)| Team | Jan | Feb | Mar | Total ||------+-----+-----+-----+-------|| A | 2 | 3 | 4 | 9 || B | 5 | 1 | 6 | 12 |#+TBLFM: $5=vsum($2..$4)| $2..$4 | Columns 2 through 4 of the current row. |
| $5 | Store each row total in column 5. |
Changing only the aggregate turns the total into a mean. The three numeric readings contribute equally.
| Team | Jan | Feb | Mar | Total ||------+-----+-----+-----+-------|| A | 2 | 3 | 4 | || B | 5 | 1 | 6 | |#+TBLFM: $5=vsum($2..$4)(org-table-recalculate t)| Team | Jan | Feb | Mar | Total ||------+-----+-----+-----+-------|| A | 2 | 3 | 4 | 9 || B | 5 | 1 | 6 | 12 |#+TBLFM: $5=vsum($2..$4)| Team | Jan | Feb | Mar | Mean ||------+-----+-----+-----+------|| A | 2 | 3 | 4 | || B | 5 | 1 | 6 | |#+TBLFM: $5=vmean($2..$4)(org-table-recalculate t)| Team | Jan | Feb | Mar | Mean ||------+-----+-----+-----+------|| A | 2 | 3 | 4 | 3 || B | 5 | 1 | 6 | 4 |#+TBLFM: $5=vmean($2..$4)| vmean(...) | Arithmetic mean of a vector or range. |
Multiply each reading by its weight, add the products and divide by the sum of the weights. Parentheses make the intended grouping explicit.
| Value | Weight ||-------+--------|| 10 | 1 || 20 | 3 ||-------+--------|| Mean | |#+TBLFM: @>$2=(@2$1*@2$2+@3$1*@3$2)/vsum(@2$2..@3$2)(org-table-recalculate t)| Value | Weight ||-------+--------|| 10 | 1 || 20 | 3 ||-------+--------|| Mean | 17.5 |#+TBLFM: @>$2=(@2$1*@2$2+@3$1*@3$2)/vsum(@2$2..@3$2)| Numerator | 10 x 1 + 20 x 3 = 70. |
| Denominator | 1 + 3 = 4; weighted mean = 17.5. |
Each amount is divided by the same total. Multiply the ratio by 100 and give the output column an explicit percent label.
| Item | Amount | Share % ||------+--------+---------|| A | 20 | || B | 30 | || C | 50 | |#+TBLFM: $3=100*($2/vsum(@2$2..@4$2));%.1f(org-table-recalculate t)| Item | Amount | Share % ||------+--------+---------|| A | 20 | 20.0 || B | 30 | 30.0 || C | 50 | 50.0 |#+TBLFM: $3=100*($2/vsum(@2$2..@4$2));%.1f| Fixed total range | The denominator stays the same for all rows. |
| ;%.1f | Format each displayed result with one decimal place. |
The beginning of the range stays fixed while its end follows the current row. This avoids depending on a previously calculated total.
| Day | Amount | Running ||-----+--------+---------|| Mon | 2 | || Tue | 3 | || Wed | 4 | |#+TBLFM: $3=vsum(@2$2..@0$2)(org-table-recalculate t)| Day | Amount | Running ||-----+--------+---------|| Mon | 2 | 2 || Tue | 3 | 5 || Wed | 4 | 9 |#+TBLFM: $3=vsum(@2$2..@0$2)| @0 | Current destination row. |
| @2$2..@0$2 | From the first amount through the current amount. |
Start the formula on the second data row, because the first has no earlier reading. The relative reference follows each destination.
| Day | Reading | Change ||-----+---------+--------|| Mon | 10 | || Tue | 14 | || Wed | 11 | |#+TBLFM: @3$3..@4$3=$2-@-1$2(org-table-recalculate t)| Day | Reading | Change ||-----+---------+--------|| Mon | 10 | || Tue | 14 | 4 || Wed | 11 | -3 |#+TBLFM: @3$3..@4$3=$2-@-1$2| @-1$2 | Column 2 of the preceding row. |
| Destination range | Exclude the first reading from the calculation. |
Use a condition to assign a numeric band. The threshold is inclusive: a score of exactly 50 receives 1.
| Name | Score | Passed ||------+-------+--------|| Ada | 70 | || Bea | 40 | || Cy | 50 | |#+TBLFM: $3=if($2>=50,1,0)(org-table-recalculate t)| Name | Score | Passed ||------+-------+--------|| Ada | 70 | 1 || Bea | 40 | 0 || Cy | 50 | 1 |#+TBLFM: $3=if($2>=50,1,0)| if(test,yes,no) | Evaluate the branch selected by the condition. |
| >= | Greater than or equal to. |
Choose a defined fallback before dividing. Zero here means the chosen fallback, so use a separate status column if it must be distinguished from a measured zero.
| Total | Count | Per item ||-------+-------+----------|| 12 | 3 | || 8 | 0 | |#+TBLFM: $3=if($2==0,0,$1/$2)(org-table-recalculate t)| Total | Count | Per item ||-------+-------+----------|| 12 | 3 | 4 || 8 | 0 | 0 |#+TBLFM: $3=if($2==0,0,$1/$2)| == | Equality test in a Calc formula. |
| if($2==0,0,...) | Skip the division when the count is zero. |
By default, range references drop empty fields. The mean is therefore (10 + 20) / 2, not a mean over three measurements.
| A | B | C | Mean ||---+---+----+------||10 | | 20 | |#+TBLFM: $4=vmean($1..$3)(org-table-recalculate t)| A | B | C | Mean ||----+---+----+------|| 10 | | 20 | 15 |#+TBLFM: $4=vmean($1..$3)| Empty range fields | Omitted by default; a blank is not automatically a measured zero. |
The formula is unchanged; the EN flags change how its input range is interpreted. Now all three positions contribute to the denominator.
| A | B | C | Mean ||---+---+----+------||10 | | 20 | |#+TBLFM: $4=vmean($1..$3)(org-table-recalculate t)| A | B | C | Mean ||----+---+----+------|| 10 | | 20 | 15 |#+TBLFM: $4=vmean($1..$3)| A | B | C | Mean ||---+---+----+------||10 | | 20 | |#+TBLFM: $4=vmean($1..$3);EN(org-table-recalculate t)| A | B | C | Mean ||----+---+----+------|| 10 | | 20 | 10 |#+TBLFM: $4=vmean($1..$3);EN| E | Keep empty cells in range references. |
| N | Treat nonnumeric fields as zero; combined with E, blanks become zero. |
A printf-style format controls the displayed result. Org stores that formatted text in the cell, so later formulas can read an already rounded value.
| Value | Third ||-------+-------|| 1 | || 2 | |#+TBLFM: $2=$1/3;%.2f(org-table-recalculate t)| Value | Third ||-------+-------|| 1 | 0.33 || 2 | 0.67 |#+TBLFM: $2=$1/3;%.2f| ;%.2f | Exactly two digits after the decimal point. |
| Rounding | Keep additional digits in intermediate cells when precision matters. |
Only the output format changes. Scientific notation gives a compact view of values across very different scales.
| Value | Copy ||---------+------|| 1234000 | || 0.00123 | |#+TBLFM: $2=$1;%.2e(org-table-recalculate t)| Value | Copy ||---------+----------|| 1234000 | 1.23e+06 || 0.00123 | 1.23e-03 |#+TBLFM: $2=$1;%.2e| ;%.2e | Scientific notation with two decimal places in the mantissa. |
Fraction mode keeps rational arithmetic exact. The result remains a fraction instead of a rounded decimal approximation.
| Value | Third ||-------+-------|| 1 | || 2 | |#+TBLFM: $2=$1/3;%.2f(org-table-recalculate t)| Value | Third ||-------+-------|| 1 | 0.33 || 2 | 0.67 |#+TBLFM: $2=$1/3;%.2f| Value | Third ||-------+-------|| 1 | || 2 | |#+TBLFM: $2=$1/3;F(org-table-recalculate t)| Value | Third ||-------+-------|| 1 | 1:3 || 2 | 2:3 |#+TBLFM: $2=$1/3;F| ;F | Calc fraction mode. |
| 1:3 | Calc notation for one third. |
Declare the angle unit explicitly. A numeric angle without a unit would otherwise depend on the calculation mode.
| Angle | Sine ||-------+------|| 30 | || 90 | |#+TBLFM: $2=sin($1);D%.3f(org-table-recalculate t)| Angle | Sine ||-------+-------|| 30 | 0.500 || 90 | 1.000 |#+TBLFM: $2=sin($1);D%.3f| D | Interpret trigonometric input in degrees. |
| %.3f | Display three decimal places. |
Change the flag and the input values together. The inputs below are numeric radian values; approximately 1.57079632679 radians is a right angle.
| Angle | Sine ||-------+------|| 30 | || 90 | |#+TBLFM: $2=sin($1);D%.3f(org-table-recalculate t)| Angle | Sine ||-------+-------|| 30 | 0.500 || 90 | 1.000 |#+TBLFM: $2=sin($1);D%.3f| Angle | Sine ||-------+------|| 0.523598775598 | || 1.57079632679 | |#+TBLFM: $2=sin($1);R%.3f(org-table-recalculate t)| Angle | Sine ||----------------+-------|| 0.523598775598 | 0.500 || 1.57079632679 | 1.000 |#+TBLFM: $2=sin($1);R%.3f| R | Interpret trigonometric input in radians. |
| Numeric input | Approximately pi/6 and pi/2 radians. |
A named constant removes a repeated magic number. Recalculate after changing the constant; the stored result cells are not live views.
#+CONSTANTS: gain=3| Value | Scaled ||-------+--------|| 2 | || 5 | |#+TBLFM: $2=$1*$gain(org-table-recalculate t)#+CONSTANTS: gain=3| Value | Scaled ||-------+--------|| 2 | 6 || 5 | 15 |#+TBLFM: $2=$1*$gain| #+CONSTANTS: | File-level values available to table formulas. |
| $gain | Reference the named constant. |
A special ! row names columns. Reserve the first column for control markers and mark data rows with # so whole-table recalculation includes them.
| ! | qty | price | cost ||---+-----+-------+------|| # | 2 | 3 | || # | 4 | 5 | |#+TBLFM: $4=$qty*$price(org-table-recalculate t)| ! | qty | price | cost ||---+-----+-------+------|| # | 2 | 3 | 6 || # | 4 | 5 | 20 |#+TBLFM: $4=$qty*$price| ! | Column names are defined in this special row. |
| # | A marked data row; it also supports automatic recalculation on TAB/RET. |
| $4 | Destination column; named columns are used on the right-hand side. |
A special $ row holds a named parameter inside the table. As with named columns, the first column is reserved for markers.
#+CONSTANTS: gain=3| Value | Scaled ||-------+--------|| 2 | || 5 | |#+TBLFM: $2=$1*$gain(org-table-recalculate t)#+CONSTANTS: gain=3| Value | Scaled ||-------+--------|| 2 | 6 || 5 | 15 |#+TBLFM: $2=$1*$gain| $ | gain=3 | ||---+--------+--------|| ! | value | scaled ||---+--------+--------|| # | 2 | || # | 5 | |#+TBLFM: $3=$value*$gain(org-table-recalculate t)| $ | gain=3 | ||---+--------+--------|| ! | value | scaled ||---+--------+--------|| # | 2 | 6 || # | 5 | 15 |#+TBLFM: $3=$value*$gain| $ marker | Defines parameters in fields such as gain=3. |
| $gain | Read the table parameter in a formula. |
A table can use a property from its enclosing heading. The PROP_ prefix distinguishes property values from other constants.
* Budget:PROPERTIES::RATE: 0.2:END: | Net | Gross ||-----+-------|| 100 | || 50 | |#+TBLFM: $2=$1*(1+$PROP_RATE);%.0f(org-table-recalculate t)* Budget:PROPERTIES::RATE: 0.2:END: | Net | Gross ||-----+-------|| 100 | 120 || 50 | 60 |#+TBLFM: $2=$1*(1+$PROP_RATE);%.0f| $PROP_RATE | Value of the RATE property, with inheritance supported. |
| C-c C-x p | Set the property interactively at the heading. |
Separate assignments with two colons. Org calculates column formulas from left to right within each row, so the third column can use the freshly calculated second one.
| Input | Double | Plus one ||-------+--------+----------|| 2 | 0 | 0 || 5 | 0 | 0 |#+TBLFM: $2=2*$1::$3=$2+1(org-table-recalculate t)| Input | Double | Plus one ||-------+--------+----------|| 2 | 4 | 5 || 5 | 10 | 11 |#+TBLFM: $2=2*$1::$3=$2+1| :: | Separates independent assignments. |
| Calculation order | Column 2 is updated before column 3. |
Move the dependency to the right and run one pass. Column 2 reads the old zero in column 3; the visibly stale result is intentional.
| Input | Double | Plus one ||-------+--------+----------|| 2 | 0 | 0 || 5 | 0 | 0 |#+TBLFM: $2=2*$1::$3=$2+1(org-table-recalculate t)| Input | Double | Plus one ||-------+--------+----------|| 2 | 4 | 5 || 5 | 10 | 11 |#+TBLFM: $2=2*$1::$3=$2+1| Input | Plus one | Double ||-------+----------+--------|| 2 | 0 | 0 || 5 | 0 | 0 |#+TBLFM: $2=$3+1::$3=2*$1(org-table-recalculate t)| Input | Plus one | Double ||-------+----------+--------|| 2 | 1 | 4 || 5 | 1 | 10 |#+TBLFM: $2=$3+1::$3=2*$1| $2=$3+1 | Reads column 3 before its update in this pass. |
| Result 1 | Demonstrates the dependency, not the final desired answer. |
Keep the same source and change only the command. Iteration repeats recalculation until the table stops changing or reaches its iteration limit; circular formulas need not converge.
| Input | Plus one | Double ||-------+----------+--------|| 2 | 0 | 0 || 5 | 0 | 0 |#+TBLFM: $2=$3+1::$3=2*$1(org-table-recalculate t)| Input | Plus one | Double ||-------+----------+--------|| 2 | 1 | 4 || 5 | 1 | 10 |#+TBLFM: $2=$3+1::$3=2*$1| Input | Plus one | Double ||-------+----------+--------|| 2 | 0 | 0 || 5 | 0 | 0 |#+TBLFM: $2=$3+1::$3=2*$1(org-table-iterate)| Input | Plus one | Double ||-------+----------+--------|| 2 | 5 | 4 || 5 | 11 | 10 |#+TBLFM: $2=$3+1::$3=2*$1| C-u C-u C-c * | Iterate the table rather than run one pass. |
| org-table-iterate | Command for repeatedly recalculating the current table. |
Omit the prefix argument to recalculate just the row at point. The second data row remains blank, even though the formula applies to its column.
| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: $4=$2*$3(org-table-recalculate t)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | 20 |#+TBLFM: $4=$2*$3| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | || Pad | 4 | 5 | |#+TBLFM: $4=$2*$3(org-table-recalculate)| Item | Qty | Price | Cost ||------+-----+-------+------|| Pen | 2 | 3 | 6 || Pad | 4 | 5 | |#+TBLFM: $4=$2*$3| C-c * | Recalculate the current row. |
| C-u C-c * | Recalculate all applicable rows in the table. |
Give the input table a name and pass an absolute range to remote. The Summary table reads those cells without copying the data.
#+NAME: sales| Item | Amount ||------+--------|| A | 20 || B | 30 | | Summary | Value ||---------+-------|| Total | |#+TBLFM: @2$2=vsum(remote(sales,@2$2..@3$2))(org-table-recalculate t)#+NAME: sales| Item | Amount ||------+--------|| A | 20 || B | 30 | | Summary | Value ||---------+-------|| Total | 50 |#+TBLFM: @2$2=vsum(remote(sales,@2$2..@3$2))| remote(sales,...) | Read cells from the named table. |
| Dependencies | Recalculate the source table first if it also contains formulas. |
An Emacs Lisp formula can match a key in one table and return a value from the corresponding row. Reordering the input rows will not change these matches.
#+NAME: prices| Code | Price ||------+-------|| pen | 3 || pad | 5 | | Code | Price ||------+-------|| pad | || pen | |#+TBLFM: $2='(org-lookup-first $1 '(remote(prices,@2$1..@3$1)) '(remote(prices,@2$2..@3$2)));E(org-table-recalculate t)#+NAME: prices| Code | Price ||------+-------|| pen | 3 || pad | 5 | | Code | Price ||------+-------|| pad | 5 || pen | 3 |#+TBLFM: $2='(org-lookup-first $1 '(remote(prices,@2$1..@3$1)) '(remote(prices,@2$2..@3$2)));E| org-lookup-first | Return the first corresponding result for an equal key. |
| ;E | Preserve empty fields so the two lookup ranges stay aligned. |
| Leading apostrophe | Select Emacs Lisp rather than Calc. |
Calc is not the only formula engine. In an Emacs Lisp formula, ordinary field references are substituted as strings unless numeric mode is requested.
| Name | Upper ||------+-------|| ada | || bea | |#+TBLFM: $2='(upcase $1)(org-table-recalculate t)| Name | Upper ||------+-------|| ada | ADA || bea | BEA |#+TBLFM: $2='(upcase $1)| '(upcase $1) | Call the Lisp upcase function on the field text. |
| No N flag | Keep the text as a string. |
The N flag supplies numeric values to a Lisp formula. Without it, these field references would be strings and + would reject them.
| A | B | Sum ||---+---+-----|| 2 | 3 | || 5 | 8 | |#+TBLFM: $3='(+ $1 $2);N(org-table-recalculate t)| A | B | Sum ||---+---+-----|| 2 | 3 | 5 || 5 | 8 | 13 |#+TBLFM: $3='(+ $1 $2);N| ;N | Read numeric fields as numbers for Lisp arithmetic. |
| + | The Emacs Lisp addition function. |
The duration flag lets Calc read hours and minutes and format the sum as a duration. These cells are elapsed times, not clock times or dates.
| Work | Break | Total ||------+-------+-------|| 1:30 | 0:45 | || 2:10 | 0:20 | |#+TBLFM: $3=$1+$2;U(org-table-recalculate t)| Work | Break | Total ||------+-------+-------|| 1:30 | 0:45 | 02:15 || 2:10 | 0:20 | 02:30 |#+TBLFM: $3=$1+$2;U| ;U | Interpret durations and display hours:minutes. |
| ;T | Use hours:minutes:seconds instead. |
Keep the same duration arithmetic and switch the output flag. Lowercase t uses the configurable duration format, whose default is fractional hours.
| Work | Break | Total ||------+-------+-------|| 1:30 | 0:45 | || 2:10 | 0:20 | |#+TBLFM: $3=$1+$2;U(org-table-recalculate t)| Work | Break | Total ||------+-------+-------|| 1:30 | 0:45 | 02:15 || 2:10 | 0:20 | 02:30 |#+TBLFM: $3=$1+$2;U| Work | Break | Hours ||------+-------+-------|| 1:30 | 0:45 | || 2:10 | 0:20 | |#+TBLFM: $3=$1+$2;t(org-table-recalculate t)| Work | Break | Hours ||------+-------+-------|| 1:30 | 0:45 | 2.25 || 2:10 | 0:20 | 2.50 |#+TBLFM: $3=$1+$2;t| ;t | Format using org-table-duration-custom-format. |
| Default format | Fractional hours with two decimal places in this tested environment. |
Keep two alternative formula lines under the table. A normal table recalculation uses the first line; it does not apply both alternatives in sequence.
| Value | Result ||-------+--------|| 2 | || 5 | |#+TBLFM: $2=2*$1#+TBLFM: $2=3*$1(org-table-recalculate t)| Value | Result ||-------+--------|| 2 | 4 || 5 | 10 |#+TBLFM: $2=2*$1#+TBLFM: $2=3*$1| First #+TBLFM line | Default formula set used by table recalculation. |
| :: on one line | Use this when both assignments belong to the same formula set. |
Move point to the second formula line and use C-c C-c. Org applies that selected line for this calculation; the first line remains the default for later table recalculation.
| Value | Result ||-------+--------|| 2 | || 5 | |#+TBLFM: $2=2*$1#+TBLFM: $2=3*$1(org-table-recalculate t)| Value | Result ||-------+--------|| 2 | 4 || 5 | 10 |#+TBLFM: $2=2*$1#+TBLFM: $2=3*$1| Value | Result ||-------+--------|| 2 | || 5 | |#+TBLFM: $2=2*$1#+TBLFM: $2=3*$1(org-ctrl-c-ctrl-c)| Value | Result ||-------+--------|| 2 | 6 || 5 | 15 |#+TBLFM: $2=2*$1#+TBLFM: $2=3*$1| C-c C-c on #+TBLFM | Apply the formula set on that particular line. |
| Cursor position | Distinguishes this action from C-c C-c inside a table cell. |
The @# token is the numeric row index of the destination. Subtract one because the header occupies the first row.
| No | Item ||----+------|| | Pen || | Pad || | Ink |#+TBLFM: $1=@#-1(org-table-recalculate t)| No | Item ||----+------|| 1 | Pen || 2 | Pad || 3 | Ink |#+TBLFM: $1=@#-1| @# | Numeric row index of the current destination. |
| $# | The corresponding token for the column index. |
Calc gives multiplication special precedence after division. Parenthesize the intended quotient before multiplying; the three result columns make the difference visible.
| a | b | c | a/b*c | (a/b)*c | a/(b*c) ||---+---+---+-------+---------+---------||12 | 2 | 3 | | | |#+TBLFM: $4=$1/$2*$3::$5=($1/$2)*$3::$6=$1/($2*$3)(org-table-recalculate t)| a | b | c | a/b*c | (a/b)*c | a/(b*c) ||----+---+---+-------+---------+---------|| 12 | 2 | 3 | 2 | 18 | 2 |#+TBLFM: $4=$1/$2*$3::$5=($1/$2)*$3::$6=$1/($2*$3)| Calc parsing | a/b*c is parsed as a/(b*c). |
| (a/b)*c | Use parentheses when the intended result is 18. |
Separate task state, checklist progress, scheduled work and deadlines. Agenda examples use a fixed date.
Official Org manual ↗ORG-07-001Mark a heading as a taskORG-07-002Complete a taskORG-07-003Define a workflowORG-07-004Set a priorityORG-07-005Start a checklistORG-07-006Check one itemORG-07-007Count completed itemsORG-07-008Show percentage progressORG-07-009See one day in the agendaORG-07-010Move the scheduled taskORG-07-011Show all unfinished tasksORG-07-012Add a repeating dateTODO is a recognized keyword at the start of a heading.
* TODO Review the report| TODO | Default unfinished task state. |
Change the task state at the heading. This build disables completion timestamps to keep the example focused.
* TODO Review the report* TODO Review the report(org-todo "DONE")* DONE Review the report| org-todo | Changes the current task state. |
| DONE | Default completed state. |
Define additional states locally, then select NEXT.
#+TODO: TODO NEXT WAIT | DONE* TODO Review the report(org-todo "NEXT")#+TODO: TODO NEXT WAIT | DONE* NEXT Review the report| #+TODO: | File-local keyword sequence. |
| TODO NEXT WAIT | Unfinished states. |
| vertical bar | Separates unfinished from completed states. |
Add a priority cookie to the heading.
* TODO [#A] Review the report| [#A] | Highest default priority; default priorities run from A to C. |
Checkboxes belong to list items and are independent of heading TODO states.
* Packing- [ ] Notebook- [ ] Pencil[ ] Notebook[ ] Pencil| [ ] | Unchecked checkbox; [X] is checked; [-] is partial. |
Toggle the checkbox at Notebook.
* Packing- [ ] Notebook- [ ] Pencil[ ] Notebook[ ] Pencil* Packing- [ ] Notebook- [ ] Pencil(org-toggle-checkbox)* Packing- [X] Notebook- [ ] Pencil| org-toggle-checkbox | Changes checkbox state at point. |
Refresh the fraction in the heading from the checklist below it.
* Packing- [ ] Notebook- [ ] Pencil(org-toggle-checkbox)* Packing- [X] Notebook- [ ] Pencil* Packing [0/2]- [X] Notebook- [ ] Pencil(org-update-statistics-cookies t)* Packing [1/2]- [X] Notebook- [ ] Pencil| [0/2] | Statistics cookie showing completed / total items. |
| org-update-statistics-cookies | Recomputes task and checkbox statistics. |
Use a percentage cookie for the same checklist.
* Packing [0/2]- [X] Notebook- [ ] Pencil(org-update-statistics-cookies t)* Packing [1/2]- [X] Notebook- [ ] Pencil* Packing [0%]- [X] Notebook- [ ] Pencil(org-update-statistics-cookies t)* Packing [50%]- [X] Notebook- [ ] Pencil| [0%] | Percentage form of the statistics cookie. |
Collect scheduled work, deadline warnings and an appointment into one day view. The reference day is 12 October 2026.
* TODO Analyse readingsSCHEDULED: <2026-10-12 Mon>* TODO Send reportDEADLINE: <2026-10-14 Wed>* Meeting<2026-10-12 Mon 14:00>(org-agenda-list nil "2026-10-12" 1)Day-agenda (W42):Monday 12 October 2026 W42 14:00...... Meeting Scheduled: TODO Analyse readings In 2 d.: TODO Send report| SCHEDULED: | Date on which work should start. |
| DEADLINE: | Due date; warnings may appear before it. |
| <... 14:00> | Active timestamp with appointment time. |
Move the scheduled date one day forward. It no longer appears as scheduled work on Monday.
* TODO Analyse readingsSCHEDULED: <2026-10-12 Mon>* TODO Send reportDEADLINE: <2026-10-14 Wed>* Meeting<2026-10-12 Mon 14:00>(org-agenda-list nil "2026-10-12" 1)Day-agenda (W42):Monday 12 October 2026 W42 14:00...... Meeting Scheduled: TODO Analyse readings In 2 d.: TODO Send report* TODO Analyse readingsSCHEDULED: <2026-10-13 Tue>* TODO Send reportDEADLINE: <2026-10-14 Wed>* Meeting<2026-10-12 Mon 14:00>(org-agenda-list nil "2026-10-12" 1)Day-agenda (W42):Monday 12 October 2026 W42 14:00...... Meeting In 2 d.: TODO Send report| 2026-10-13 Tue | The new start date; the displayed agenda day is unchanged. |
A global TODO list collects unfinished headings even if they have no appointment today.
* TODO Analyse readingsSCHEDULED: <2026-10-12 Mon>* TODO Send reportDEADLINE: <2026-10-14 Wed>* Meeting<2026-10-12 Mon 14:00>(org-todo-list)Global list of TODO items of type: ALLPress ‘N r’ (e.g. ‘0 r’) to search again: (0)[ALL] (1)DONE (2)TODO TODO Analyse readings TODO Send report| org-todo-list | Builds the global TODO view from org-agenda-files. |
A repeater records how to advance the date when the task is completed. The preview shows the source because repeater behavior is an editor operation.
* TODO Check backupsSCHEDULED: <2026-10-12 Mon +1w>* TODO Check backupsSCHEDULED: <2026-10-12 Mon +1w>| +1w | Advance from the previous scheduled date by one week on completion. |
| ++1w / .+1w | Respectively catch up into the future / repeat relative to completion. |
Attach machine-readable context to headings. Inspect metadata and simple filtered views.
Official Org manual ↗Tags classify headings without changing their titles.
* TODO Review report :writing:projectA:* TODO Review report :writing:projectA:| :writing:projectA: | Colon-separated tags at the end of the heading. |
A drawer stores named values below a heading.
* Study:PROPERTIES::OWNER: Alex:STATUS: draft:END:Notes.* Study:PROPERTIES::OWNER: Alex:STATUS: draft:END:Notes.| :PROPERTIES: / :END: | Drawer delimiters. |
| :OWNER: Alex | Property name and value. |
Read OWNER programmatically at the current heading.
* Study:PROPERTIES::OWNER: Alex:END:Notes.(org-entry-get nil "OWNER")"Alex"| org-entry-get | Gets a named property from the entry at point. |
| nil | Use the current point as the location. |
Read OWNER at the child heading, explicitly enabling inheritance for this lookup.
* Study:PROPERTIES::OWNER: Alex:END:Notes.(org-entry-get nil "OWNER")"Alex"* Study:PROPERTIES::OWNER: Alex:END:** AnalysisNotes.(org-entry-get nil "OWNER" t)"Alex"| Third argument t | Search ancestors if the current entry has no value. |
A property on the child takes precedence over the parent value.
* Study:PROPERTIES::OWNER: Alex:END:** AnalysisNotes.(org-entry-get nil "OWNER" t)"Alex"* Study:PROPERTIES::OWNER: Alex:END:** Analysis:PROPERTIES::OWNER: Sam:END:Notes.(org-entry-get nil "OWNER" t)"Sam"| Local OWNER | Overrides the value found in ancestors. |
Create the drawer and property through Org instead of typing the syntax.
* StudyNotes.(org-set-property "OWNER" "Alex")* Study:PROPERTIES::OWNER: Alex:END:Notes.| org-set-property | Writes a property on the current entry. |
Map a function over headings matching the review tag. The result is a list of heading titles.
* TODO Check data :review:* TODO Write text :writing:* TODO Check text :review:(org-map-entries (lambda () (org-get-heading t t t t)) "review" 'file)("Check data" "Check text")| org-map-entries | Calls a function on each matching entry. |
| "review" | Tag matcher. |
| 'file | Restrict the search to this file. |
Use a property matcher to select Study A.
* Study A:PROPERTIES::OWNER: Alex:END:* Study B:PROPERTIES::OWNER: Sam:END:(org-map-entries (lambda () (org-get-heading t t t t)) "OWNER=\"Alex\"" 'file)("Study A")| OWNER="Alex" | Matches the exact property value Alex. |
Keep content portable; make format-specific presentation choices explicit.
Official Org manual ↗An image-only link is exported as an inline image. This asset is a small, reproducibly generated SVG.
[[file:assets/curve.svg]]
| Image file link | Org recognizes supported image extensions. |
Set the image width in the HTML backend.
[[file:assets/curve.svg]]
#+ATTR_HTML: :width 240[[file:assets/curve.svg]]
| #+ATTR_HTML: | Attributes for the next exported element. |
| :width 240 | Requested width in CSS pixels; this does not set LaTeX width. |
Attach a caption to the same image.
#+ATTR_HTML: :width 240[[file:assets/curve.svg]]
#+CAPTION: A tiny signal#+ATTR_HTML: :width 240[[file:assets/curve.svg]]
Figure 1: A tiny signal
| #+CAPTION: | Text exported with the figure. |
A quote block gives the paragraph quotation semantics.
#+BEGIN_QUOTEA clear record makes a result easier to check.#+END_QUOTEA clear record makes a result easier to check.
| quote | Exports as blockquote in HTML and a quotation environment in LaTeX. |
An example block displays Org-looking content without interpreting it.
#+BEGIN_EXAMPLE* This is literal text#+TITLE: Also literal#+END_EXAMPLE#+BEGINEXAMPLE
#+ENDEXAMPLE
| example block | Preserves literal lines in a fixed-width block. |
HTML exports an arbitrary special block as a named container. Styling that class is a separate step; LaTeX would need a matching environment.
#+begin_noteKeep the original observations.#+end_noteKeep the original observations.
| note | Becomes a div with class note in HTML. |
| Backend support | An arbitrary block name is not automatically a predefined LaTeX environment. |
Vary one export setting at a time. HTML fragments and native LaTeX/PDF previews are clearly labelled.
Official Org manual ↗ORG-10-001Hide numbers and the contents listORG-10-002Number the headingsORG-10-003Add a shallow contents listORG-10-004Include child headings in the contentsORG-10-005Number only the main headingsORG-10-006Move the contents listORG-10-007Exclude a sectionORG-10-008Select sections explicitlyORG-10-009Hide TODO keywords in exportORG-10-010Remove tasks from exportORG-10-011Require braces for subscriptsORG-10-012Change the PDF marginsORG-10-013Use larger PDF typeORG-10-014Insert an explicit PDF page breakStart with the simplest outline presentation.
#+OPTIONS: num:nil toc:nil* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
| #+OPTIONS: | num:nil disables heading numbers; toc:nil disables the table of contents. |
Turn on section numbers without adding a contents list.
#+OPTIONS: num:nil toc:nil* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
#+OPTIONS: num:t toc:nil* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
| #+OPTIONS: | num:t enables heading numbering. |
List only level-one headings in the contents.
#+OPTIONS: num:t toc:nil* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
#+OPTIONS: num:t toc:1* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
| #+OPTIONS: | toc:1 limits the contents list to one level. |
Include Instruments in the contents list.
#+OPTIONS: num:t toc:1* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
#+OPTIONS: num:t toc:2* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
| #+OPTIONS: | toc:2 includes two outline levels. |
Keep the deep contents list but number only the first heading level.
#+OPTIONS: num:t toc:2* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
#+OPTIONS: num:1 toc:2* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
| #+OPTIONS: | num:1 limits numbering to level one. |
Disable the default contents location and insert one after the introduction.
#+OPTIONS: num:1 toc:2* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.A short description.
The equipment used.
The main findings.
#+OPTIONS: num:t toc:nilAn introductory paragraph. #+TOC: headlines 2 * MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.An introductory paragraph.
A short description.
The equipment used.
The main findings.
| #+TOC: headlines 2 | Insert a two-level heading contents list at this position. |
The noexport tag excludes the entire subtree from the exported document.
* Public findingsThese may be shared.* Internal notes :noexport:Keep these out of the export.These may be shared.
| :noexport: | Default exclusion tag; it does not remove the source text. |
Export only tagged sections and their subtrees.
#+SELECT_TAGS: publish* Findings :publish:Publish this section.* Working notesDo not publish this section.Publish this section.
| #+SELECT_TAGS: publish | Use publish as the selection tag. |
Keep the task heading but remove its TODO keyword from the exported text.
#+OPTIONS: todo:nil* TODO Review reportA useful reminder.A useful reminder.
| todo:nil | Hides the keyword; tasks:nil would exclude task entries altogether. |
Exclude task entries, preserving ordinary headings.
#+OPTIONS: todo:nil* TODO Review reportA useful reminder.A useful reminder.
#+OPTIONS: tasks:nil* TODO Review reportA useful reminder.* ResultsReady for readers.Ready for readers.
| tasks:nil | Removes task headings and their contents from the export. |
Require braces for subscript and superscript markup so common identifiers remain intact.
#+OPTIONS: ^:{}Keep sample_A literal; write CO_{2} with a subscript.Keep sample_A literal; write CO2 with a subscript.
| ^:{} | Interpret sub/superscripts only when the argument is braced. |
Export through the native Org LaTeX backend and compile with pdfLaTeX. This preview is a real PDF page.
#+LATEX_CLASS: article#+LATEX_HEADER: \usepackage[margin=25mm]{geometry}#+TITLE: Research note#+AUTHOR: Alex Researcher#+DATE:* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.
| #+LATEX_CLASS: article | Choose the article document class. |
| geometry / margin=25mm | Set all four page margins to 25 mm. |
Change the base font size while keeping margins and content unchanged.
#+LATEX_CLASS: article#+LATEX_HEADER: \usepackage[margin=25mm]{geometry}#+TITLE: Research note#+AUTHOR: Alex Researcher#+DATE:* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.#+LATEX_CLASS: article#+LATEX_CLASS_OPTIONS: [12pt]#+LATEX_HEADER: \usepackage[margin=25mm]{geometry}#+TITLE: Research note#+AUTHOR: Alex Researcher#+DATE:* MethodsA short description.** InstrumentsThe equipment used.* ResultsThe main findings.
| #+LATEX_CLASS_OPTIONS: [12pt] | Pass the 12pt option to the LaTeX document class. |
Place Results on a new PDF page. The guide previews every generated page.
#+LATEX_CLASS: article#+LATEX_HEADER: \usepackage[margin=25mm]{geometry}#+TITLE: Research note#+AUTHOR: Alex Researcher#+DATE:* MethodsA short description.#+LATEX: \newpage* ResultsThe main findings.
| #+LATEX: | Emit a backend-specific LaTeX line. |
| \newpage | End the current page. |
Distinguish execution, stored results and export. Header arguments control each of these separately.
Official Org manual ↗ORG-11-001Display a source blockORG-11-002Run a Bash blockORG-11-003Return multiple output linesORG-11-004Return an Emacs Lisp valueORG-11-005Return a tableORG-11-006Supply an input variableORG-11-007Change only the inputORG-11-008Read a named table as inputORG-11-009Run Python with a value resultORG-11-010Export only the codeORG-11-011Export only the resultORG-11-012Export code and resultORG-11-013Append a new resultORG-11-014Set defaults for a whole fileORG-11-015Create a plot from a named tableORG-11-016Change the plot styleExport code without running it.
#+BEGIN_SRC bash :eval neverprintf "hello\n"#+END_SRCprintf "hello\n"
| :eval never | Prevents Babel evaluation of this block. |
| bash | Language identifier for execution and highlighting. |
Execute the block and insert captured standard output below it.
#+BEGIN_SRC bash :results outputprintf "hello\n"#+END_SRC#+BEGIN_SRC bash :results outputprintf "hello\n"#+END_SRC #+RESULTS:: hello| :results output | Capture stdout rather than a language-specific return value. |
| #+RESULTS: | Marker inserted by Babel above the stored result. |
The output result preserves both lines.
#+BEGIN_SRC bash :results outputprintf "hello\n"#+END_SRC#+BEGIN_SRC bash :results outputprintf "hello\n"#+END_SRC #+RESULTS:: hello#+BEGIN_SRC bash :results outputprintf "alpha\nbeta\n"#+END_SRC#+BEGIN_SRC bash :results outputprintf "alpha\nbeta\n"#+END_SRC #+RESULTS:: alpha: beta| \n | A newline escape interpreted by printf. |
Capture the value of the final Lisp expression.
#+BEGIN_SRC emacs-lisp :results value(+ 2 3)#+END_SRC#+BEGIN_SRC emacs-lisp :results value(+ 2 3)#+END_SRC #+RESULTS:: 5| :results value | Use the language backend's return value. |
| (+ 2 3) | Lisp addition; produces 5. |
A list of rows can become an Org table.
#+BEGIN_SRC emacs-lisp :results value table'(("A" 2) ("B" 5))#+END_SRC#+BEGIN_SRC emacs-lisp :results value table'(("A" 2) ("B" 5))#+END_SRC #+RESULTS:| A | 2 || B | 5 || :results value table | Format the returned rows as a table. |
| '(...) | A literal Lisp list; inner lists are rows. |
Pass a named input through a header argument.
#+BEGIN_SRC emacs-lisp :var n=4 :results value(* n n)#+END_SRC#+BEGIN_SRC emacs-lisp :var n=4 :results value(* n n)#+END_SRC #+RESULTS:: 16| :var n=4 | Bind n to the number 4. |
| (* n n) | Square the input. |
Keep the code unchanged and change the parameter to seven.
#+BEGIN_SRC emacs-lisp :var n=4 :results value(* n n)#+END_SRC#+BEGIN_SRC emacs-lisp :var n=4 :results value(* n n)#+END_SRC #+RESULTS:: 16#+BEGIN_SRC emacs-lisp :var n=7 :results value(* n n)#+END_SRC#+BEGIN_SRC emacs-lisp :var n=7 :results value(* n n)#+END_SRC #+RESULTS:: 49| :var n=7 | The changed input produces 49. |
Use the table as a list of rows and sum the first field of each row.
#+NAME: measurements| 2 || 5 || 8 | #+BEGIN_SRC emacs-lisp :var data=measurements :results value(apply #'+ (mapcar #'car data))#+END_SRC#+NAME: measurements| 2 || 5 || 8 | #+BEGIN_SRC emacs-lisp :var data=measurements :results value(apply #'+ (mapcar #'car data))#+END_SRC #+RESULTS:: 15| :var data=measurements | Resolve the named table and bind its data. |
| mapcar / car | Extract the first item from each row. |
| apply | Call addition with all extracted values. |
For a non-session Python value block, use an explicit return statement.
#+BEGIN_SRC python :results valuereturn sum([2, 5, 8])#+END_SRC#+BEGIN_SRC python :results valuereturn sum([2, 5, 8])#+END_SRC #+RESULTS:: 15| python | Requires a Python interpreter and ob-python. |
| return | Returns the value from Babel's generated function wrapper. |
Execute first, then export only the source. The result remains stored in the working Org buffer.
#+BEGIN_SRC emacs-lisp :results value :exports code(+ 2 3)#+END_SRC(+ 2 3)
| :exports code | Include source, omit the result in export. |
Use the same computation but hide the source in the rendered document.
#+BEGIN_SRC emacs-lisp :results value :exports code(+ 2 3)#+END_SRC(+ 2 3)
#+BEGIN_SRC emacs-lisp :results value :exports results(+ 2 3)#+END_SRC5
| :exports results | Include the stored result, omit source. |
Show both sides of the computation.
#+BEGIN_SRC emacs-lisp :results value :exports results(+ 2 3)#+END_SRC5
#+BEGIN_SRC emacs-lisp :results value :exports both(+ 2 3)#+END_SRC(+ 2 3)
5
| :exports both | Include source and result. |
Keep the existing result and append the new one. Re-running this example starts from the same source each time.
#+BEGIN_SRC emacs-lisp :results value append(+ 2 3)#+END_SRC #+RESULTS:: 2#+BEGIN_SRC emacs-lisp :results value append(+ 2 3)#+END_SRC #+RESULTS:: 2: 5| :results append | Append to the current result instead of replacing it. |
Move shared header arguments to a language-specific property.
#+PROPERTY: header-args:emacs-lisp :results value :exports both #+BEGIN_SRC emacs-lisp (+ 2 3)#+END_SRC(+ 2 3)
5
| #+PROPERTY: header-args:emacs-lisp | Default arguments for Emacs Lisp blocks in this file. |
| Local block arguments | More specific block arguments override these defaults. |
Pass the table to gnuplot and insert a link to the generated SVG.
#+NAME: readings| 1 | 2 || 2 | 5 || 3 | 3 | #+BEGIN_SRC gnuplot :var data=readings :file plot.svg :results file graphics :exports resultsset title "Three readings"set xlabel "Sample"set ylabel "Value"plot data using 1:2 with linespoints title "Reading"#+END_SRC| 1 | 2 |
| 2 | 5 |
| 3 | 3 |
| :var data=readings | Pass the named table to the gnuplot backend. |
| :file plot.svg | Output file, relative to this isolated example directory. |
| :results file graphics | Insert a file result recognized as graphics. |
Change only linespoints to boxes. The Org data flow and output settings stay the same.
#+NAME: readings| 1 | 2 || 2 | 5 || 3 | 3 | #+BEGIN_SRC gnuplot :var data=readings :file plot.svg :results file graphics :exports resultsset title "Three readings"set xlabel "Sample"set ylabel "Value"plot data using 1:2 with linespoints title "Reading"#+END_SRC| 1 | 2 |
| 2 | 5 |
| 3 | 3 |
#+NAME: readings| 1 | 2 || 2 | 5 || 3 | 3 | #+BEGIN_SRC gnuplot :var data=readings :file plot.svg :results file graphics :exports resultsset title "Three readings"set xlabel "Sample"set ylabel "Value"plot data using 1:2 with boxes title "Reading"#+END_SRC| 1 | 2 |
| 2 | 5 |
| 3 | 3 |
| with boxes | Draw a bar at each x value instead of connecting points. |
Reusable text, arguments, metadata and computed replacements. Macro expansion is part of document export; a Babel call is a separate execution mechanism.
Official Org manual ↗Define reusable wording once, then place it in prose. The source keeps the macro call; the exported sentence contains the replacement.
#+MACRO: project Signal studyWelcome to {{{project}}}.Welcome to Signal study.
#+MACRO: project Open LabThe {{{project}}} report is ready.The Open Lab report is ready.
| #+MACRO: | Define the name and replacement text. |
| {{{project}}} | Call a text macro without parameters. |
A placeholder inserts the supplied text. This example changes the reusable label without changing the surrounding sentence.
#+MACRO: project Open LabThe {{{project}}} report is ready.The Open Lab report is ready.
#+MACRO: status Status: $1{{{status(ready)}}}.Status: ready.
| $1 | First argument, passed as text. |
| {{{status(ready)}}} | One argument in parentheses. |
Use separate placeholders for a value and its unit. The same definition produces both inline measurements.
#+MACRO: status Status: $1{{{status(ready)}}}.Status: ready.
#+MACRO: quantity $1 $2Length: {{{quantity(12,cm)}}}.Time: {{{quantity(5,s)}}}.Length: 12 cm. Time: 5 s.
| $1 / $2 | First / second argument. |
| , | Separates macro arguments. |
Escape a comma that belongs to the text. Without that escape, Org would interpret it as an argument separator.
#+MACRO: quantity $1 $2Length: {{{quantity(12,cm)}}}.Time: {{{quantity(5,s)}}}.Length: 12 cm. Time: 5 s.
#+MACRO: location $1 — $2{{{location(Aachen\, Germany,home)}}}Aachen, Germany — home
| \, | A literal comma inside one argument. |
| Expansion | The first argument contains the complete location. |
A macro can produce Org markup that is then rendered by the exporter. Both labels become emphasized text.
#+MACRO: label *$1*{{{label(Ready)}}} for review. {{{label(Approved)}}} for publication.Ready for review.
Approved for publication.
| *$1* | Bold markup surrounds the argument. |
| Export order | Macro expansion happens before the resulting Org markup is rendered. |
An eval macro runs an Emacs Lisp expression while exporting. Its argument arrives as a string, so this expression converts it to a number first.
#+MACRO: twice (eval (* 2 (string-to-number $1)))Twice seven is {{{twice(7)}}}.Twice seven is 14.
| (eval ...) | Compute the replacement during export. |
| string-to-number | Convert the textual argument before arithmetic. |
| Trusted source | Exporting this document evaluates the macro expression. |
Built-in macros can read document keywords. Keep the title and author in metadata and reuse them in a sentence.
#+TITLE: Small report#+AUTHOR: Alex ResearcherThis is {{{title}}}, prepared by {{{author}}}.This is Small report, prepared by Alex Researcher.
| {{{title}}} | Read the TITLE keyword. |
| {{{author}}} | Read the AUTHOR keyword. |
A setup file can hold shared definitions. The companion file is bundled with this example and shown in the companion-inputs appendix.
#+MACRO: quantity $1 $2Length: {{{quantity(12,cm)}}}.Time: {{{quantity(5,s)}}}.Length: 12 cm. Time: 5 s.
#+SETUPFILE: assets/macros.org{{{project}}}: {{{quantity(12,cm)}}}.Open Lab: 12 cm.
| #+SETUPFILE: | Load document configuration, including macro definitions. |
| assets/macros.org | Bundled source; changing it affects every document that loads it. |
Reuse text, include files, expand named code and generate standalone scripts. These mechanisms solve different problems.
Official Org manual ↗ORG-13-001Define a text macroORG-13-002Pass a macro argumentORG-13-003Include another Org fileORG-13-004Include a file as source codeORG-13-005Tangle one Bash scriptORG-13-006Add an executable shebangORG-13-007Combine blocks into one fileORG-13-008Expand a named code fragmentORG-13-009Expand Noweb only when tanglingORG-13-010Tangle to two destinationsAn export macro replaces a marker with text.
#+MACRO: project Signal studyWelcome to {{{project}}}.Welcome to Signal study.
| #+MACRO: name text | Defines an export-time text replacement. |
| {{{project}}} | Calls the macro. |
Use an argument to generate consistent labels.
#+MACRO: project Signal studyWelcome to {{{project}}}.Welcome to Signal study.
#+MACRO: sample Sample $1Compare {{{sample(A)}}} with {{{sample(B)}}}.Compare Sample A with Sample B.
| $1 | First macro argument. |
| {{{sample(A)}}} | Calls sample with argument A. |
Include reusable text from a companion file. The asset is supplied in the ZIP.
* Study#+INCLUDE: "assets/methods.org"Calibrate the sensor before collecting three readings.
| #+INCLUDE: | Expands another file during export. |
| Quoted path | Relative to this Org document. |
Display a file as code without evaluating it.
#+INCLUDE: "assets/analyse.py" src pythonreadings = [2, 5, 8]
print(sum(readings) / len(readings))
| src python | Wrap included file content as a Python source block. |
Extract the code into hello.sh. Tangling writes source files; it does not run the extracted script.
#+BEGIN_SRC bash :tangle hello.shprintf "hello\n"#+END_SRCFILE: hello.shprintf "hello\n"| :tangle hello.sh | Destination filename. |
| C-c C-v t | Run org-babel-tangle. |
Write a shebang before the extracted code. Org also makes a shebang-bearing tangled file executable.
#+BEGIN_SRC bash :tangle hello.shprintf "hello\n"#+END_SRCFILE: hello.shprintf "hello\n"#+BEGIN_SRC bash :tangle hello.sh :shebang "#!/usr/bin/env bash"printf "hello\n"#+END_SRCFILE: hello.sh#!/usr/bin/env bashprintf "hello\n"| :shebang | First line identifying the interpreter. |
Blocks targeting the same file are concatenated in document order.
#+BEGIN_SRC bash :tangle run.shprintf "first\n"#+END_SRC #+BEGIN_SRC bash :tangle run.shprintf "second\n"#+END_SRCFILE: run.shprintf "first\n" printf "second\n"| Repeated :tangle target | Both block bodies contribute to run.sh. |
Insert the named fragment into the tangled script.
#+NAME: greeting#+BEGIN_SRC bash :tangle noprintf "hello\n"#+END_SRC #+BEGIN_SRC bash :tangle run.sh :noweb yes<<greeting>>printf "done\n"#+END_SRCFILE: run.shprintf "hello\n"printf "done\n"| #+NAME: greeting | Names a reusable block. |
| <<greeting>> | Noweb reference to that block. |
| :noweb yes | Expand references during evaluation and tangling. |
| :tangle no | Do not write this fragment to a separate file. |
Generate the same script while restricting expansion to tangling.
#+NAME: greeting#+BEGIN_SRC bash :tangle noprintf "hello\n"#+END_SRC #+BEGIN_SRC bash :tangle run.sh :noweb yes<<greeting>>printf "done\n"#+END_SRCFILE: run.shprintf "hello\n"printf "done\n"#+NAME: greeting#+BEGIN_SRC bash :tangle noprintf "hello\n"#+END_SRC #+BEGIN_SRC bash :tangle run.sh :noweb tangle<<greeting>>printf "done\n"#+END_SRCFILE: run.shprintf "hello\n"printf "done\n"| :noweb tangle | Expand for tangling only; leave the source reference visible during export. |
One Org document can produce scripts in multiple languages and files.
#+BEGIN_SRC bash :tangle analyse.shprintf "analysis\n"#+END_SRC #+BEGIN_SRC python :tangle analyse.pyprint(sum([2, 5, 8]))#+END_SRCFILE: analyse.pyprint(sum([2, 5, 8])) FILE: analyse.shprintf "analysis\n"| Distinct :tangle targets | Each target collects only the blocks assigned to it. |
Call named Babel blocks without arguments, override defaults, pass data and compute values inside prose. Each action evaluates the indicated call or block in isolation.
Official Org manual ↗ORG-14-001Call a block without parametersORG-14-002Call a function with a default inputORG-14-003Override one function parameterORG-14-004Pass two named parametersORG-14-005Keep an omitted parameter at its defaultORG-14-006Pass a string to a functionORG-14-007Pass a named table to a functionORG-14-008Collect a function return valueORG-14-009Override how the function collects resultsORG-14-010Format a call result as a tableORG-14-011Call a function inline without parametersORG-14-012Pass a parameter in an inline callORG-14-013Export prose containing an inline resultORG-14-014Evaluate code directly inside a sentenceORG-14-015Call a function from another Org fileORG-14-016Feed one function result into anotherORG-14-017Export an inline result as plain textORG-14-018Ingest a reusable function libraryA named block behaves like a callable unit. Evaluate the CALL line to insert its result beneath that line; the block definition is left intact.
#+NAME: greeting#+BEGIN_SRC emacs-lisp :results value"Hello from Org"#+END_SRC #+CALL: greeting()(org-babel-lob-execute-maybe)#+NAME: greeting#+BEGIN_SRC emacs-lisp :results value"Hello from Org"#+END_SRC #+CALL: greeting() #+RESULTS:: Hello from Org| #+NAME: greeting | Give the code block a unique name. |
| greeting() | The empty argument list is still written with parentheses. |
The function declares a default input. Calling it without arguments uses that value.
#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+CALL: double()(org-babel-lob-execute-maybe)#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+CALL: double() #+RESULTS:: 6| :var n=3 | Default argument declared on the block. |
| double() | Use the default n=3. |
Override the default at the call site. The function body and default remain unchanged.
#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+CALL: double()(org-babel-lob-execute-maybe)#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+CALL: double() #+RESULTS:: 6#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+CALL: double(n=7)(org-babel-lob-execute-maybe)#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+CALL: double(n=7) #+RESULTS:: 14| n=7 | Named argument passed by this call. |
| Argument syntax | Use n=7 inside parentheses, not :var n=7. |
Both parameters are explicit at the call site. Their names connect the inputs to the variables used by the block.
#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRC #+CALL: scale(x=7,factor=4)(org-babel-lob-execute-maybe)#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRC #+CALL: scale(x=7,factor=4) #+RESULTS:: 28| :var x=3 factor=2 | Declare two default inputs. |
| x=7,factor=4 | Override both arguments; commas separate them. |
Override only x. The omitted factor keeps its default value of 2.
#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRC #+CALL: scale(x=7,factor=4)(org-babel-lob-execute-maybe)#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRC #+CALL: scale(x=7,factor=4) #+RESULTS:: 28#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRC #+CALL: scale(x=7)(org-babel-lob-execute-maybe)#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRC #+CALL: scale(x=7) #+RESULTS:: 14| Partial override | Explicit arguments replace defaults individually. |
Quote a string parameter at the call site. Numeric parameters do not need those quotes.
#+NAME: greet#+BEGIN_SRC emacs-lisp :var name="reader" :results value(concat "Hello, " name "!")#+END_SRC #+CALL: greet(name="Ada")(org-babel-lob-execute-maybe)#+NAME: greet#+BEGIN_SRC emacs-lisp :var name="reader" :results value(concat "Hello, " name "!")#+END_SRC #+CALL: greet(name="Ada") #+RESULTS:: Hello, Ada!| name="Ada" | A string argument. |
| concat | Combine the greeting and name. |
The call supplies a table as a list of rows. This example adds the first cell of each row.
#+NAME: readings| 2 || 5 || 8 | #+NAME: total#+BEGIN_SRC emacs-lisp :var data=readings :results value(apply #'+ (mapcar #'car data))#+END_SRC #+CALL: total(data=readings)(org-babel-lob-execute-maybe)#+NAME: readings| 2 || 5 || 8 | #+NAME: total#+BEGIN_SRC emacs-lisp :var data=readings :results value(apply #'+ (mapcar #'car data))#+END_SRC #+CALL: total(data=readings) #+RESULTS:: 15| data=readings | Resolve the named table and pass its values. |
| mapcar / car | Select the first cell from each row. |
The block prints one string and returns another. Value collection keeps the returned value.
#+NAME: demo#+BEGIN_SRC emacs-lisp :results value(princ "printed")"returned"#+END_SRC #+CALL: demo()(org-babel-lob-execute-maybe)#+NAME: demo#+BEGIN_SRC emacs-lisp :results value(princ "printed")"returned"#+END_SRC #+CALL: demo() #+RESULTS:: returned| :results value | Collect the final Lisp value. |
| princ | Produces printed output, which is not the chosen result here. |
Move a collection override inside the brackets before the argument list. The result now comes from printed output.
#+NAME: demo#+BEGIN_SRC emacs-lisp :results value(princ "printed")"returned"#+END_SRC #+CALL: demo()(org-babel-lob-execute-maybe)#+NAME: demo#+BEGIN_SRC emacs-lisp :results value(princ "printed")"returned"#+END_SRC #+CALL: demo() #+RESULTS:: returned#+NAME: demo#+BEGIN_SRC emacs-lisp :results value(princ "printed")"returned"#+END_SRC #+CALL: demo[:results output]()(org-babel-lob-execute-maybe)#+NAME: demo#+BEGIN_SRC emacs-lisp :results value(princ "printed")"returned"#+END_SRC #+CALL: demo[:results output]() #+RESULTS:: printed| [:results output] | Inside headers alter execution of the called block. |
| () | The function still takes no arguments. |
End headers describe how the returned value is inserted at the call site. This list of rows becomes an Org table.
#+NAME: items#+BEGIN_SRC emacs-lisp :results value'(("Ada" 3) ("Bea" 5))#+END_SRC #+CALL: items() :results value table(org-babel-lob-execute-maybe)#+NAME: items#+BEGIN_SRC emacs-lisp :results value'(("Ada" 3) ("Bea" 5))#+END_SRC #+CALL: items() :results value table #+RESULTS:| Ada | 3 || Bea | 5 || After () | End headers apply to the result at the call site. |
| :results value table | Insert the returned rows as an Org table. |
An inline call evaluates the same kind of named block inside a sentence. The inserted results macro records the value in the Org buffer.
#+NAME: greeting#+BEGIN_SRC emacs-lisp :results value :exports none"Hello from Org"#+END_SRC Message: call_greeting().(org-babel-lob-execute-maybe)#+NAME: greeting#+BEGIN_SRC emacs-lisp :results value :exports none"Hello from Org"#+END_SRC Message: call_greeting() {{{results(=Hello from Org=)}}}.| call_greeting() | Inline call syntax: no #+CALL keyword. |
| {{{results(...)}}} | The stored inline result, produced by Babel. |
Pass a parameter from prose. The function is evaluated at the inline call position.
#+NAME: greeting#+BEGIN_SRC emacs-lisp :results value :exports none"Hello from Org"#+END_SRC Message: call_greeting().(org-babel-lob-execute-maybe)#+NAME: greeting#+BEGIN_SRC emacs-lisp :results value :exports none"Hello from Org"#+END_SRC Message: call_greeting() {{{results(=Hello from Org=)}}}.#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7).(org-babel-lob-execute-maybe)#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7) {{{results(=14=)}}}.| call_double(n=7) | Inline call with a named argument. |
| :exports none | Hide the function definition in document export. |
Evaluate the inline call, then export the document. The stored result appears in the sentence; the hidden function definition does not.
#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7).(org-babel-lob-execute-maybe)#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7) {{{results(=14=)}}}.#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7).(org-babel-lob-execute-maybe)
The result is 14.
| Evaluation first | C-c C-c on the inline call stores the result. |
| Export second | C-c C-e h h publishes the sentence. |
Inline source syntax contains code itself. Inline call syntax instead refers to a separately named block.
The mean is src_emacs-lisp{(/ (+ 2 5 8) 3.0)}.(org-babel-execute-src-block)
The mean is 5.0.
| src_emacs-lisp{...} | An inline source block with a Lisp expression. |
| call_name(...) | Use this when calling a named block instead. |
The file path and block name identify the function. The companion file is included in the ZIP and in the HTML companion-inputs section.
#+CALL: assets/functions.org:scale(x=7,factor=4)(org-babel-lob-execute-maybe)#+CALL: assets/functions.org:scale(x=7,factor=4) #+RESULTS:: 28| file.org:name(...) | Call a named block in another file. |
| assets/functions.org | Contains the scale block with x and factor parameters. |
A header argument can call a named block to obtain its input. This evaluates the dependency before the consumer block.
#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+BEGIN_SRC emacs-lisp :var x=double(n=7) :results value(+ x 1)#+END_SRC(org-babel-execute-src-block)#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value(* 2 n)#+END_SRC #+BEGIN_SRC emacs-lisp :var x=double(n=7) :results value(+ x 1)#+END_SRC #+RESULTS:: 15| :var x=double(n=7) | Run double with n=7; bind its result to x. |
| Consumer result | 14 + 1 = 15. |
End headers on an inline call can change its result format. Raw output removes the default verbatim styling from this number.
#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7).(org-babel-lob-execute-maybe)
The result is 14.
#+NAME: double#+BEGIN_SRC emacs-lisp :var n=3 :results value :exports none(* 2 n)#+END_SRC The result is call_double(n=7)[:results raw].(org-babel-lob-execute-maybe)The result is 14.
| [:results raw] after () | Inline end headers format the returned result. |
| Plain text | The number uses the surrounding paragraph style. |
Ingest the companion file into the Library of Babel, then call its block by name. This registration belongs to the Emacs session; another session must ingest the file again.
#+CALL: assets/functions.org:scale(x=7,factor=4)(org-babel-lob-execute-maybe)#+CALL: assets/functions.org:scale(x=7,factor=4) #+RESULTS:: 28# First ingest assets/functions.org with C-c C-v i.#+CALL: scale(x=7,factor=4)(let ((org-babel-library-of-babel nil))
(org-babel-lob-ingest "assets/functions.org")
(org-babel-lob-execute-maybe))# First ingest assets/functions.org with C-c C-v i.#+CALL: scale(x=7,factor=4) #+RESULTS:: 28| org-babel-lob-ingest | Read named code blocks into the session's Library of Babel. |
| Local let binding | Isolate this demonstration from other examples in the build. |
Choose how to collect a result, represent it and insert it. A return value, printed output, result format and export policy answer different questions.
Official Org manual ↗ORG-15-001Return a plain scalarORG-15-002Preserve a string literallyORG-15-003Render the same string as Org markupORG-15-004Return a tableORG-15-005Return a bullet listORG-15-006Wrap output in a results drawerORG-15-007Return HTML markupORG-15-008Return LaTeX markupORG-15-009Write a text file as the resultORG-15-010Export a downloadable file linkORG-15-011Replace an earlier resultORG-15-012Append to earlier resultsORG-15-013Prepend to earlier resultsORG-15-014Evaluate without inserting a resultStart with one returned value. Babel records it as a fixed-width result line.
#+BEGIN_SRC emacs-lisp :results value(+ 2 5)#+END_SRC#+BEGIN_SRC emacs-lisp :results value(+ 2 5)#+END_SRC #+RESULTS:: 7| :results value | Collect the returned value. |
| : 7 | Org fixed-width text representation. |
Verbatim collection keeps the asterisks as text. They do not become bold markup in this exported result.
#+BEGIN_SRC emacs-lisp :results value verbatim :exports results"*Ready*"#+END_SRC"*Ready*"
| verbatim | Keep the result literal. |
| :exports results | Publish the result without the source block. |
Changing verbatim to raw makes the result ordinary Org content. The same asterisks now mark bold text.
#+BEGIN_SRC emacs-lisp :results value verbatim :exports results"*Ready*"#+END_SRC"*Ready*"
#+BEGIN_SRC emacs-lisp :results value raw :exports results"*Ready*"#+END_SRCReady
| raw | Insert the returned string as Org markup. |
A nested list gives Org rows and columns. The stored table remains editable like any other Org table.
#+BEGIN_SRC emacs-lisp :results value table'(("Ada" 3) ("Bea" 5))#+END_SRC#+BEGIN_SRC emacs-lisp :results value table'(("Ada" 3) ("Bea" 5))#+END_SRC #+RESULTS:| Ada | 3 || Bea | 5 || Outer list | Table rows. |
| Inner list | Cells in one row. |
A flat list can be inserted as ordinary Org list items.
#+BEGIN_SRC emacs-lisp :results value table'(("Ada" 3) ("Bea" 5))#+END_SRC#+BEGIN_SRC emacs-lisp :results value table'(("Ada" 3) ("Bea" 5))#+END_SRC #+RESULTS:| Ada | 3 || Bea | 5 |#+BEGIN_SRC emacs-lisp :results value list'("Collect" "Check" "Publish")#+END_SRC#+BEGIN_SRC emacs-lisp :results value list'("Collect" "Check" "Publish")#+END_SRC #+RESULTS:- Collect- Check- Publish| :results list | One list item for each returned element. |
A drawer makes multiline output collapsible. The result remains visible here as actual buffer text.
#+BEGIN_SRC emacs-lisp :results output drawer(princ "first line\nsecond line")#+END_SRC#+BEGIN_SRC emacs-lisp :results output drawer(princ "first line\nsecond line")#+END_SRC #+RESULTS::results:first linesecond line:end:| drawer | Wrap inserted text in a RESULTS drawer. |
| TAB at drawer | Collapse or expand it in the editor. |
The html format inserts an HTML export block. This preview comes from the native HTML exporter.
#+BEGIN_SRC emacs-lisp :results value html :exports results"<p><strong>Ready</strong> for review.</p>"#+END_SRCReady for review.
| html | Wrap the result in #+BEGIN_EXPORT html. |
| Backend-specific | This markup targets HTML output. |
Use latex for content intended for the LaTeX exporter. The preview shows the compiled PDF.
#+LATEX_HEADER: \usepackage[a6paper,landscape,margin=12mm]{geometry}#+BEGIN_SRC emacs-lisp :results value latex :exports results"\\textbf{Ready} for review."#+END_SRC
| latex | Wrap the result in #+BEGIN_EXPORT latex. |
| Native PDF | The build exports LaTeX and runs pdfLaTeX. |
With file results, Babel writes the returned text to the named file and inserts a link. The build checks the file contents as well.
#+BEGIN_SRC emacs-lisp :results value file :file message.txt :file-desc "Download message""Ready for review."#+END_SRC#+BEGIN_SRC emacs-lisp :results value file :file message.txt :file-desc "Download message""Ready for review."#+END_SRC #+RESULTS:[[file:message.txt][Download message]]| :file message.txt | Output path relative to this example. |
| :file-desc | Readable text for the inserted link. |
Keep the same file result and export it. In the self-contained HTML guide, the download embeds the generated file.
#+BEGIN_SRC emacs-lisp :results value file :file message.txt :file-desc "Download message""Ready for review."#+END_SRC#+BEGIN_SRC emacs-lisp :results value file :file message.txt :file-desc "Download message""Ready for review."#+END_SRC #+RESULTS:[[file:message.txt][Download message]]#+BEGIN_SRC emacs-lisp :results value file :file message.txt :file-desc "Download message" :exports results"Ready for review."#+END_SRC| :exports results | The exported content is the download link. |
| Generated file | Contains the exact text returned by the block. |
Replace is the default insertion policy. The new result takes the place of the stored old one.
#+BEGIN_SRC emacs-lisp :results value replace"new"#+END_SRC #+RESULTS:: old#+BEGIN_SRC emacs-lisp :results value replace"new"#+END_SRC #+RESULTS:: new| replace | Keep only the latest inserted result. |
Change only the insertion policy. The old result is retained and the new result is added below it.
#+BEGIN_SRC emacs-lisp :results value replace"new"#+END_SRC #+RESULTS:: old#+BEGIN_SRC emacs-lisp :results value replace"new"#+END_SRC #+RESULTS:: new#+BEGIN_SRC emacs-lisp :results value append"new"#+END_SRC #+RESULTS:: old#+BEGIN_SRC emacs-lisp :results value append"new"#+END_SRC #+RESULTS:: old: new| append | Keep history with the newest result at the bottom. |
Prepend preserves the old result but places the newest result above it.
#+BEGIN_SRC emacs-lisp :results value append"new"#+END_SRC #+RESULTS:: old#+BEGIN_SRC emacs-lisp :results value append"new"#+END_SRC #+RESULTS:: old: new#+BEGIN_SRC emacs-lisp :results value prepend"new"#+END_SRC #+RESULTS:: old#+BEGIN_SRC emacs-lisp :results value prepend"new"#+END_SRC #+RESULTS:: new: old| prepend | Keep history with the newest result at the top. |
Silent execution leaves the Org buffer unchanged. Emacs reports the result in its echo area; this panel deliberately shows the unchanged buffer.
#+BEGIN_SRC emacs-lisp :results value(+ 2 5)#+END_SRC#+BEGIN_SRC emacs-lisp :results value(+ 2 5)#+END_SRC #+RESULTS:: 7#+BEGIN_SRC emacs-lisp :results value silent(+ 2 5)#+END_SRC#+BEGIN_SRC emacs-lisp :results value silent(+ 2 5)#+END_SRC| silent | Return the value without inserting #+RESULTS. |
| Editor view | No result line is added below the block. |
Publication keys, in-text citations and printed bibliographies. The executed examples use Org-cite with its built-in basic processor and a bundled bibliography. The citation setup reference explains Citar, CSL and BibLaTeX.
Official Org manual ↗ORG-16-001Cite a publication and print its referenceORG-16-002Cite two publications togetherORG-16-003Make the author part of the sentenceORG-16-004Show author and year separatelyORG-16-005Add a prefix and page locatorORG-16-006Add context around a citation groupORG-16-007Switch to numeric referencesORG-16-008Include an uncited publicationORG-16-009Put a citation in a footnoteORG-16-010Export author–year references to PDFORG-16-011Export numeric references to PDFORG-16-012Inspect the publication metadataThe citation key resolves to a record in the bundled bibliography. The citation and the printed reference are separate elements.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. #+PRINT_BIBLIOGRAPHY:Literate programming (Knuth, Donald E., 1984) joins explanation and code.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
| @knuth1984 | Key in assets/references.bib. |
| #+BIBLIOGRAPHY: | Bibliographic input file. |
| #+PRINT_BIBLIOGRAPHY: | Print the cited references here. |
Semicolons separate keys inside one citation group. Both cited publications appear in the reference list.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. #+PRINT_BIBLIOGRAPHY:Literate programming (Knuth, Donald E., 1984) joins explanation and code.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Related approaches [cite:@knuth1984;@schulte2012] support this report. #+PRINT_BIBLIOGRAPHY:Related approaches (Knuth, Donald E., 1984, Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten, 2012) support this report.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten (2012). A Multi-Language Computing Environment for Literate Programming and Reproducible Research, Journal of Statistical Software.
| ; | Separate reference keys within one citation. |
The text style makes the citation fit a narrative sentence.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. #+PRINT_BIBLIOGRAPHY:Literate programming (Knuth, Donald E., 1984) joins explanation and code.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year [cite/text:@knuth1984] introduced literate programming. #+PRINT_BIBLIOGRAPHY:Knuth, Donald E. (1984) introduced literate programming.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
| /text | Narrative citation style. |
| Same key | Formatting changes while the bibliographic record stays the same. |
Author-only and noauthor styles expose different parts of the same reference.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year [cite/text:@knuth1984] introduced literate programming. #+PRINT_BIBLIOGRAPHY:Knuth, Donald E. (1984) introduced literate programming.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Author: [cite/author:@knuth1984] Year: [cite/noauthor:@knuth1984]. #+PRINT_BIBLIOGRAPHY:Author: Knuth, Donald E.
Year: (1984).
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
| /author | Author-only citation. |
| /noauthor | Omit the author from the citation, leaving the year here. |
Text before and after a key supplies context for that reference. The page locator points into the cited publication.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. #+PRINT_BIBLIOGRAPHY:Literate programming (Knuth, Donald E., 1984) joins explanation and code.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Background [cite:see @knuth1984 p. 97]. #+PRINT_BIBLIOGRAPHY:Background (see Knuth, Donald E., 1984 p. 97).
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
| see | Prefix attached to this reference. |
| p. 97 | Suffix giving a page locator. |
The text before the first semicolon and after the last semicolon belongs to the whole citation.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Related approaches [cite:@knuth1984;@schulte2012] support this report. #+PRINT_BIBLIOGRAPHY:Related approaches (Knuth, Donald E., 1984, Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten, 2012) support this report.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten (2012). A Multi-Language Computing Environment for Literate Programming and Reproducible Research, Journal of Statistical Software.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Background [cite:compare ;@knuth1984;@schulte2012; for two approaches]. #+PRINT_BIBLIOGRAPHY:Background (compare Knuth, Donald E., 1984, Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten, 2012 for two approaches).
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten (2012). A Multi-Language Computing Environment for Literate Programming and Reproducible Research, Journal of Statistical Software.
| Group prefix / suffix | Placed outside the individual reference entries. |
| Semicolons | Separate affixes and reference items. |
Change the processor options while keeping the same two publications. Numeric citation markers correspond to numbered bibliography entries.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Related approaches [cite:@knuth1984;@schulte2012] support this report. #+PRINT_BIBLIOGRAPHY:Related approaches (Knuth, Donald E., 1984, Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten, 2012) support this report.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten (2012). A Multi-Language Computing Environment for Literate Programming and Reproducible Research, Journal of Statistical Software.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic numeric numeric Related approaches [cite:@knuth1984;@schulte2012] support this report. #+PRINT_BIBLIOGRAPHY:Related approaches (1, 2) support this report.
[1] Knuth, Donald E., Literate Programming, The Computer Journal, 1984.
[2] Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten, A Multi-Language Computing Environment for Literate Programming and Reproducible Research, Journal of Statistical Software, 2012.
| basic numeric numeric | Numeric bibliography labels and default numeric citation style. |
| basic | Built-in processor; no CSL or BibTeX installation needed. |
Nocite includes a reference in the bibliography without printing a normal citation at that position.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year The Org workflow is described in [cite:@schulte2012]. [cite/nocite:@knuth1984] #+PRINT_BIBLIOGRAPHY:The Org workflow is described in (Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten, 2012).
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten (2012). A Multi-Language Computing Environment for Literate Programming and Reproducible Research, Journal of Statistical Software.
| /nocite | Include the keyed record without a visible citation marker. |
| Reference list | Contains both the cited and the additional publication. |
The note style moves the citation into a footnote. The bibliography still lists the publication.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. #+PRINT_BIBLIOGRAPHY:Literate programming (Knuth, Donald E., 1984) joins explanation and code.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year This report follows a literate approach[cite/note:@knuth1984]. #+PRINT_BIBLIOGRAPHY:| /note | Footnote citation with the basic processor. |
| Bibliography | Independent of the citation position. |
The same basic processor also supports LaTeX output. Add a heading explicitly, because basic does not supply the bibliography heading.
#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. #+PRINT_BIBLIOGRAPHY:Literate programming (Knuth, Donald E., 1984) joins explanation and code.
Knuth, Donald E. (1984). Literate Programming, The Computer Journal.
#+LATEX_HEADER: \usepackage[a6paper,landscape,margin=12mm]{geometry}#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. * References#+PRINT_BIBLIOGRAPHY:
| basic | Produces the reference text directly for LaTeX. |
| No biber step | This example compiles with pdfLaTeX alone. |
Only the citation configuration changes from the preceding PDF example.
#+LATEX_HEADER: \usepackage[a6paper,landscape,margin=12mm]{geometry}#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic author-year Literate programming [cite:@knuth1984] joins explanation and code. * References#+PRINT_BIBLIOGRAPHY:#+LATEX_HEADER: \usepackage[a6paper,landscape,margin=12mm]{geometry}#+BIBLIOGRAPHY: assets/references.bib#+CITE_EXPORT: basic numeric numeric Literate programming [cite:@knuth1984] joins explanation and code. * References#+PRINT_BIBLIOGRAPHY:
| Numeric mode | Changes citation markers and bibliography labels together. |
The companion file contains two real journal articles. Stable citation keys connect the Org text to these records; a DOI identifies the publication itself.
#+INCLUDE: "assets/references.bib" src bibtex@article{knuth1984,
author = {Knuth, Donald E.},
title = {Literate Programming},
journal = {The Computer Journal},
year = {1984}, volume = {27}, number = {2},
pages = {97--111},
doi = {10.1093/comjnl/27.2.97}
}
@article{schulte2012,
author = {Schulte, Eric and Davison, Dan and Dye, Thomas and Dominik, Carsten},
title = {A Multi-Language Computing Environment for Literate Programming and Reproducible Research},
journal = {Journal of Statistical Software},
year = {2012}, volume = {46}, number = {3},
pages = {1--24},
doi = {10.18637/jss.v046.i03}
}
| Citation key | Local identifier, such as knuth1984; keep it stable. |
| DOI | Persistent publication identifier; different from an Org CUSTOM_ID. |
| Metadata sources | Publisher pages for the two article DOIs. |
Combine familiar pieces into a report. These integration examples deliberately change more than one detail.
Official Org manual ↗Keep the question, input data, executable analysis and interpretation together.
#+TITLE: Three readings#+OPTIONS: toc:nil num:nil* QuestionHow large is the average reading?* Data#+NAME: observations| 2 || 5 || 8 |* Analysis#+BEGIN_SRC emacs-lisp :var data=observations :results value :exports both(/ (apply #'+ (mapcar #'car data)) (float (length data)))#+END_SRC* InterpretationThe arithmetic mean summarizes these three illustrative readings.How large is the average reading?
| 2 |
| 5 |
| 8 |
(/ (apply #'+ (mapcar #'car data)) (float (length data)))
5.0
The arithmetic mean summarizes these three illustrative readings.
| :exports both | Make the computation visible to readers. |
| float | Force floating-point division. |
| length | Count observations. |
Change only the export policy. The calculation stays in the Org source.
#+TITLE: Three readings#+OPTIONS: toc:nil num:nil* QuestionHow large is the average reading?* Data#+NAME: observations| 2 || 5 || 8 |* Analysis#+BEGIN_SRC emacs-lisp :var data=observations :results value :exports both(/ (apply #'+ (mapcar #'car data)) (float (length data)))#+END_SRC* InterpretationThe arithmetic mean summarizes these three illustrative readings.How large is the average reading?
| 2 |
| 5 |
| 8 |
(/ (apply #'+ (mapcar #'car data)) (float (length data)))
5.0
The arithmetic mean summarizes these three illustrative readings.
#+TITLE: Three readings#+OPTIONS: toc:nil num:nil* QuestionHow large is the average reading?* Data#+NAME: observations| 2 || 5 || 8 |* Analysis#+BEGIN_SRC emacs-lisp :var data=observations :results value :exports results(/ (apply #'+ (mapcar #'car data)) (float (length data)))#+END_SRC* InterpretationThe arithmetic mean summarizes these three illustrative readings.How large is the average reading?
| 2 |
| 5 |
| 8 |
5.0
The arithmetic mean summarizes these three illustrative readings.
| :exports results | Hide the implementation in the published edition. |
Change the last observation from 8 to 11 and re-run the calculation. The mean changes to 6.0.
#+TITLE: Three readings#+OPTIONS: toc:nil num:nil* QuestionHow large is the average reading?* Data#+NAME: observations| 2 || 5 || 11 |* Analysis#+BEGIN_SRC emacs-lisp :var data=observations :results value :exports both(/ (apply #'+ (mapcar #'car data)) (float (length data)))#+END_SRC* InterpretationThe arithmetic mean summarizes these three illustrative readings.How large is the average reading?
| 2 |
| 5 |
| 11 |
(/ (apply #'+ (mapcar #'car data)) (float (length data)))
6.0
The arithmetic mean summarizes these three illustrative readings.
| Named data table | A single changed input flows into the calculation. |
Evaluate the same Org report and compile its LaTeX export. The preview shows the actual PDF page.
#+TITLE: Three readings#+AUTHOR: Alex Researcher#+DATE:#+LATEX_HEADER: \usepackage[margin=25mm]{geometry}#+OPTIONS: toc:nil num:nil* QuestionHow large is the average reading?* Data#+NAME: observations| 2 || 5 || 8 |* Analysis#+BEGIN_SRC emacs-lisp :var data=observations :results value :exports results(/ (apply #'+ (mapcar #'car data)) (float (length data)))#+END_SRC* InterpretationThe arithmetic mean summarizes these three illustrative readings.
| HTML and LaTeX backends | Different renderers consume the same structured source. |
| Evaluation before export | The build stores fresh results before creating either view. |
Use the smallest mechanism that matches the job. Text macros shape exported prose; Babel executes code. A macro name and a Babel block name live in different mechanisms, even if you happen to give them the same spelling. The examples use unique names within each standalone file.
| Mechanism | Syntax | When it runs |
|---|---|---|
| Text macro | {{{name}}} or {{{name(a,b)}}} | During document export. |
| Computed macro | #+MACRO: name (eval ...) | During export; arguments are strings. |
| Named block call | #+CALL: name(x=7) | C-c C-c on the CALL line; export evaluation depends on :eval. |
| Inline function call | call_name(x=7) | C-c C-c at the inline call; result stored in a results macro. |
| Inline source | src_emacs-lisp{(+ 2 5)} | Evaluates the expression directly in the sentence. |
| Code inclusion | <<name>> with :noweb yes | Expands source text; see the REU chapter. |
Result collection, representation, insertion and export are independent choices. These controls let one computation serve an editable notebook and a clean publication. The build evaluates the examples explicitly and uses :eval never-export to keep export from running them again.
| Question | Header argument | Examples |
|---|---|---|
| What is captured? | :results value or output | Return value versus printed output. |
| How is it represented? | :results table, list, verbatim, raw, html, latex, drawer | Structured values or backend-specific markup. |
| Where does it go? | :results replace, append, prepend, silent | Update, retain history or leave the buffer unchanged. |
| What is published? | :exports code, results, both, none | See ORG-11-010 through ORG-11-012 and the FUN inline cases. |
| Is a file produced? | :results file :file message.txt | Write the result and insert a file link. |
| Is evaluation permitted? | :eval never-export | Allow explicit evaluation; suppress execution during export. |
Within a CALL, inside headers precede the argument list and control the named block. End headers follow the argument list and control insertion of its returned result. Inline calls put the end headers in brackets.
#+CALL: demo[:results output]() :results verbatimInline: call_double(n=7)[:results raw].Enable :lang org, :tools biblio and :completion vertico in Doom's module selection, then run doom sync after changing modules. Citar provides selection and actions for bibliographic records. Org-cite stores the citation syntax; the export processor formats the final citations and bibliography. This setup recipe is not a simulated Citar UI or an executed example.
;; In your Doom config.el; replace the path with your bibliography.(after! citar (setq citar-bibliography '("~/bib/references.bib")))(after! org (setq org-cite-global-bibliography '("~/bib/references.bib") org-cite-insert-processor 'citar org-cite-follow-processor 'citar org-cite-activate-processor 'citar))| Keys / command | Action | Context |
|---|---|---|
| C-c C-x @ / C-c l @ | org-cite-insert | Insert a citation or edit the one at point. |
| C-c C-o | org-open-at-point | Follow the citation through the configured processor. |
| M-x citar-open-entry | Open bibliographic metadata | Requires Citar; choose a reference. |
| M-x citar-open | Open a resource for a publication | Available PDFs, notes and links depend on your Citar setup. |
| C-h k, then keys | Inspect active binding | Useful if local Doom customizations change a shortcut. |
The executed CIT examples use basic so HTML and native PDF need no extra citation engine. Its intentionally simple formatting includes literal author names and a limited set of bibliographic fields. A publisher-specific style needs CSL or a LaTeX bibliography processor. Citar is a selection frontend, not the export processor.
| Processor | Output | Additional requirements |
|---|---|---|
| basic | HTML, LaTeX/PDF and other backends | Built into Org; used by all executed citation examples. |
| csl | HTML, LaTeX/PDF and other backends | citeproc-el, a CSL style file and locale data. |
| biblatex | LaTeX/PDF | BibLaTeX package and a matching biber or BibTeX build step. |
| natbib / bibtex | LaTeX/PDF | Matching LaTeX package/style and BibTeX build step. |
These are alternative setup recipes, not additional executed cases. Use one CITE_EXPORT setting in a document. Keep your chosen CSL style and bibliography with the project for reproducible output.
# Cross-format CSL output, after installing citeproc-el:#+CITE_EXPORT: csl styles/apa.csl # LaTeX-only alternative, with biber in the compilation pipeline:#+CITE_EXPORT: biblatex authoryear,backend=biber # Shared citation input and bibliography placement:#+BIBLIOGRAPHY: references.bib[cite:@knuth1984]#+PRINT_BIBLIOGRAPHY:These files are bundled in assets/ and copied beside each standalone example. They are also embedded in the canonical Org source. Publication records are shown in ORG-16-012.
#+MACRO: project Open Lab#+MACRO: quantity $1 $2#+NAME: scale#+BEGIN_SRC emacs-lisp :var x=3 factor=2 :results value(* x factor)#+END_SRCThe Org source and example index are attached to the PDF. The HTML and PDF show the same captured results, with complete source beside each example.
Captured environment: Emacs 31.1 and Org 9.8.7. Native PDF previews show actual exported pages; editor examples show captured buffer text.
Checks: All 208 examples passed their declared expectations. Native PDF examples were compiled twice.
Stable references: An ID such as ORG-01-001 identifies the tour, chapter and example. Chapter numbers have two digits; example numbers have three and start at 001 in each chapter. The 000 entry identifies the chapter. IDs are independent of PDF pages.
Reading the results: Editor results show text rather than your Emacs theme or window chrome. Folded text is shown with ellipses. HTML and LaTeX styling can differ. Capture templates, clock reports, publishing projects and external packages are useful further topics.
| Command / action | Example | Purpose |
|---|---|---|
| M-RIGHT · org-do-demote | ORG-03-001 | Demote one heading |
| M-S-RIGHT · org-demote-subtree | ORG-03-002 | Demote a whole subtree |
| M-S-LEFT · org-promote-subtree | ORG-03-003 | Promote a whole subtree |
| M-DOWN · org-move-subtree-down | ORG-03-004 | Move a subtree down |
| C-c ^, then a · org-sort-entries | ORG-03-005 | Sort sibling headings |
| C-x n s · org-narrow-to-subtree | ORG-03-006 | Focus on one subtree |
| C-x n s, then C-x n w | ORG-03-007 | Widen the buffer again |
| TAB · org-cycle | ORG-03-008 | Fold a subtree |
| C-c C-c · org-table-align | ORG-05-002 | Align the source columns |
| M-DOWN · org-table-move-row-down | ORG-05-003 | Move a data row down |
| M-S-RIGHT · org-table-insert-column | ORG-05-004 | Insert a column |
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-005 | Calculate a whole column |
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-006 | Change the multiplier |
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-007 | Format decimal places |
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-008 | Calculate one specific field |
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-009 | Sum a range |
| Command / action | Example | Purpose |
|---|---|---|
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-010 | Use an Emacs Lisp formula |
| C-u C-c * · org-table-recalculate (whole table) | ORG-05-011 | Refer to a named table |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-001 | Multiply two columns |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-002 | Target one cell |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-003 | Target a rectangular range |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-004 | Keep a parameter cell fixed |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-005 | Refer to nearby columns |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-006 | Put a total in the last row |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-007 | Use separators as range boundaries |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-008 | Sum across a row |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-009 | Calculate a row average |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-010 | Calculate a weighted mean |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-011 | Show a share as a percentage |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-012 | Build a running total |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-013 | Compare with the previous row |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-014 | Choose between two values |
| Command / action | Example | Purpose |
|---|---|---|
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-015 | Guard against division by zero |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-016 | Ignore empty cells in a mean |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-017 | Treat empty cells as zero |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-018 | Format fixed decimal places |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-019 | Use scientific notation |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-020 | Keep exact fractions |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-021 | Use degrees in trigonometry |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-022 | Switch to radians |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-023 | Name a file-level constant |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-024 | Give columns meaningful names |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-025 | Keep a parameter beside the data |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-026 | Read a heading property |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-027 | Chain formulas from left to right |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-028 | See a dependency that needs another pass |
| C-u C-u C-c * · org-table-iterate | ORG-06-029 | Iterate until values stabilize |
| C-c * · org-table-recalculate (current row) | ORG-06-030 | Recalculate only the current row |
| Command / action | Example | Purpose |
|---|---|---|
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-031 | Aggregate a different table |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-032 | Look up a row by its key |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-033 | Transform text with Emacs Lisp |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-034 | Use numeric Lisp arguments |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-035 | Add durations |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-036 | Convert a duration to decimal hours |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-037 | Understand multiple formula lines |
| C-c C-c on the second #+TBLFM line · org-ctrl-c-ctrl-c | ORG-06-038 | Apply a different formula line |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-039 | Generate row numbers |
| C-u C-c * · org-table-recalculate (whole table) | ORG-06-040 | Make arithmetic grouping explicit |
| C-c C-t · choose DONE | ORG-07-002 | Complete a task |
| C-c C-t · choose NEXT | ORG-07-003 | Define a workflow |
| C-c C-c · toggle checkbox | ORG-07-006 | Check one item |
| C-c C-c on the cookie | ORG-07-007 | Count completed items |
| C-c C-c on the cookie | ORG-07-008 | Show percentage progress |
| M-x org-agenda-list · one day | ORG-07-009 | See one day in the agenda |
| Command / action | Example | Purpose |
|---|---|---|
| Agenda for 12 October 2026 | ORG-07-010 | Move the scheduled task |
| M-x org-todo-list | ORG-07-011 | Show all unfinished tasks |
| Source inspection · no command | ORG-07-012 | Add a repeating date |
| (org-entry-get nil "OWNER") | ORG-08-003 | Read a property |
| (org-entry-get nil "OWNER" t) | ORG-08-004 | Inherit a parent property |
| (org-entry-get nil "OWNER" t) | ORG-08-005 | Override an inherited value |
| C-c C-x p · OWNER · Alex | ORG-08-006 | Set a property with a command |
| org-map-entries · tag match | ORG-08-007 | Find headings with a tag |
| org-map-entries · property match | ORG-08-008 | Filter by a property value |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-001 | Call a block without parameters |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-002 | Call a function with a default input |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-003 | Override one function parameter |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-004 | Pass two named parameters |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-005 | Keep an omitted parameter at its default |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-006 | Pass a string to a function |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-007 | Pass a named table to a function |
| Command / action | Example | Purpose |
|---|---|---|
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-008 | Collect a function return value |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-009 | Override how the function collects results |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-010 | Format a call result as a table |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-011 | Call a function inline without parameters |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-012 | Pass a parameter in an inline call |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-013 | Export prose containing an inline result |
| C-c C-c · org-babel-execute-src-block | ORG-14-014 | Evaluate code directly inside a sentence |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-015 | Call a function from another Org file |
| C-c C-c · org-babel-execute-src-block | ORG-14-016 | Feed one function result into another |
| C-c C-c · org-babel-lob-execute-maybe | ORG-14-017 | Export an inline result as plain text |
| C-c C-v i · org-babel-lob-ingest; then C-c C-c on CALL | ORG-14-018 | Ingest a reusable function library |
Original demonstrations executed with the installed Org version. The manual is the reference for syntax; inspect your local version with M-x org-version.
| Topic | Official manual chapter |
|---|---|
| First document | https://orgmode.org/manual/Document-Structure.html |
| Text and lists | https://orgmode.org/manual/Markup-for-Rich-Contents.html |
| Outline and navigation | https://orgmode.org/manual/Structure-Editing.html |
| Links and references | https://orgmode.org/manual/Hyperlinks.html |
| Tables and calculations | https://orgmode.org/manual/Tables.html |
| Spreadsheets and formulas | https://orgmode.org/manual/The-Spreadsheet.html |
| Tasks and planning | https://orgmode.org/manual/TODO-Items.html |
| Tags and properties | https://orgmode.org/manual/Properties-and-Columns.html |
| Images and blocks | https://orgmode.org/manual/Images.html |
| Export and layout | https://orgmode.org/manual/Export-Settings.html |
Original demonstrations executed with the installed Org version. The manual is the reference for syntax; inspect your local version with M-x org-version.
| Topic | Official manual chapter |
|---|---|
| Source blocks and Babel | https://orgmode.org/manual/Working-with-Source-Code.html |
| Text macros | https://orgmode.org/manual/Macro-Replacement.html |
| Reuse and tangling | https://orgmode.org/manual/Extracting-Source-Code.html |
| Functions and inline calls | https://orgmode.org/manual/Evaluating-Code-Blocks.html |
| Result formats and files | https://orgmode.org/manual/Results-of-Evaluation.html |
| Citations and publications | https://orgmode.org/manual/Citation-handling.html |
| A small reproducible report | https://orgmode.org/manual/Working-with-Source-Code.html |
Standard bindings were checked in Emacs 29.3 / Org 9.6.15. Doom aliases were checked against its module source on 10 October 2026. A full Doom session and your personal configuration were not run by this build. Use C-h k to check the active binding locally.
| Reference | Source |
|---|---|
| Doom non-Evil global bindings | Doom modules · config/default/+emacs-bindings.el |
| Doom Org localleader bindings | Doom modules · lang/org/config.el · +org-init-keybinds-h |
| Disabling the Evil module | Doom modules · editor/evil · How do I remove evil? |
| Table editing | Org manual · Built-in Table Editor |
| Formula editor and debugger | Org manual · Editing and debugging formulas |
| Recalculation and iteration | Org manual · Updating the table |
| Babel commands | Org manual · Key Bindings and Useful Functions |
| Export menu | Org manual · The Export Dispatcher |
Doom prefix defaults assume its default configuration module. Changes to module selection, local bindings or operating-system shortcuts can change the effective keys. The M-x command names remain the reference entry points.
| Reference | Source |
|---|---|
| Knuth (1984), Literate Programming | doi:10.1093/comjnl/27.2.97 · The Computer Journal 27(2), 97–111. |
| Schulte, Davison, Dye and Dominik (2012) | A Multi-Language Computing Environment for Literate Programming and Reproducible Research · Journal of Statistical Software 46(3), 1–24. doi:10.18637/jss.v046.i03 |
| Citar frontend and Doom integration | Official Citar repository and configuration guide |
| Export processors and bibliography styles | Org manual · Citation export processors |
| Bibliography placement | Org manual · Bibliography printing |
The bundled .bib file contains publication metadata, not full article text. Local citation keys are chosen for the demonstrations. Exported typography and available citation styles depend on the selected processor.
Content: CC0 1.0. Structure and publishing framework: CC BY 4.0 by Lukas C. Bossert. Repository source · Publishing framework source · License scope and third-party notices.