Org-mode

Org-Mode

Overview

Org-Mode is a mode built-in to Emacs that allows to store structured data, information in text format - org-mode markdown that can be exported to html, pdf, latex, markdown, github flavoured markdown and more file formats.

Features:

Everything stored in text format: The most portable format.
Todo List.
It can be used as a personal Wiki.
Table editing, formating, built-in spreadsheet.
Tags, Headlines
Literate programming, Run code blocks, Create Interactive and reproducible software documentation.
Display and export Latex Formulas
Display Pictures
Many link formats
- Link to files, web, IRC, Usenet News groups
- Link to shell commands
- Links to trigger Emacs Functions
Usefulness
- Authoring
- Write Software documentation with embedded snippets
- Literate Programming
- Reproducible Research
- Wiki
- Markdown

Example: this document is now written in org-mode and the exported to html and github flavoured markdown.

file:images/document_in_org_mode1.png

It also supports inline code blocks that can be evaluated and the result printed in the document or displayed in the minibuffer.

file:images/document_in_org_mode2.png

Key bindings and commands for org-mode

Useful Commands

Command	Description

Display
M-x org-toggle-inline-images	Toggle images display
M-x org-toggle-latex-fragment	Toggle latex formulas display
M-x org-toggle-link-display	Toggle hyperlink display

Export
M-x org-html-export-to-html	Export buffer to html file.
M-x org-latex-export-to-pdf	Export buffer to pdf file.

Search
heml-occur	Useful quick search and navigation.
helm-org-in-buffer-headings	Filter org-mode files by headlines.

Hyperlink

Key binding	Description
C-c C-l	Insert hyperlink at point
C-c C-o	Open hyperlink at point

Move within headlines

Key Binding	Description
M - <return>	Insert headline at same level as the previous one.
C-c C-p	Move to previous headline
C-c C-n	Move to next headline
C-c C-u	Move to higher headline
M-[up]	Move headline, list row or table row up
M-[down]	Move headline, list item or table row down
M-[left]	Demote list item or headline
M-[right]	Promote list item or headline

Buffer Subtree

Key Binding	Description
shift-tab	Fold / Unfold headlines
C-x n s	Narrow the buffer subtree to current headline
C-c n w	Widen the view back

Table

Key Binding	Description
C-c-!	Convert region into a table

Hyperlinks

Key Binding	Description
C-c-C-o	Open a link
C-c-C-l	Insert/ Edit a link

Markdown Summary

Text Formatting

Example	Code
bold	`bold`
italics	`/italics/`
/very strong/	`/very strong/`
underline	`_underline_`
`verbatim`	`~verbatim~`
~~strike through~~	`+strike through+`
`inline code`	==inline code==

Hyperlinks

Description	Formatting	Output
Link to a file	`file:/etc/fstab`	file:/etc/fstab
Link to a web page	`http://www.httpbing.org/get`	http://www.httpbing.org/get
Email	`mailto:dummy@gmail.com`	mailto:dummy@gmail.com
Usenet Link	`news:comp.emacs`	news:comp.emacs
Info - Documentation	`info:gcc`	info:gcc
Shell Command	`shell:uname%20-a`	shell:uname%20-a
Elisp code	`elisp:(info%20"gcc")`	elisp:(info%20”gcc”)
Doi - Digital object identifier	`doi:10.1000/182`	doi:10.1000/182

Hyperlinks from org-contrib:

Description	Example
Link to manpage	`man:sed`	(require ‘org-man)

Code Blocks

Summary

Description	Shortcut	Code
Soource code block	<s	`#+BEGIN_SRC ... #+END_SRC`
Example	<e	`#+BEGIN_EXAMPLE ... #+END_EXAMPLE`
Quote	<q	`#+BEGIN_QUOTE ... #+END_QUOTE`
Verse	<v	`#+BEGIN_VERSE ... #+END_VERSE`
Center	<c	`#+BEGIN_CENTER ... #+END_CENTER`
Latex	<l	`#+BEGIN_LaTeX ... #+END_LaTeX`
Html	<h	`#+BEGIN_HTML ... #+END_HTML`
Ascii	<a	`#+BEGIN_ASCII ... #+END_ASCII`

Quote Block

Literal:

#+BEGIN_QUOTE
This block encloses text that you want to appear as a quotation.
#+END_QUOTE

Output:

This block encloses text that you want to appear as a quotation.

Text Position

Center

Output:

This text is centered!

Literal:

#+begin_center
This text is  
centered!
#+end_center

Left

Output:

Literal:

#+begin_left
This text is \\
aligned to the left!
#+end_left

Right

Output:

Literal:

#+begin_right
This text is 
aligned to the right!
#+end_right

Latex Code Block

Example1

\begin{equation}
\begin{align}
\mbox{Union: }  A\cup B = \{x\mid x\in A \mbox{ or } x\in B\} \newline
\mbox{Concatenation: } A\circ B  = \{xy\mid x\in A \mbox{ and } y\in B\} \\
\mbox{Star: } A^\star  = \{x_1x_2\ldots x_k \mid  k\geq 0 \mbox{ and each } x_i\in A\} \\
\end{align}
\end{equation}

Output:

\begin{equation} \begin{align} \mbox{Union: } A∪ B = \{x\mid x∈ A \mbox{ or } x∈ B\} \newline \mbox{Concatenation: } Aˆ B = \{xy\mid x∈ A \mbox{ and } y∈ B\}
\mbox{Star: } A^* = \{x_1x_2\ldots x_k \mid k\geq 0 \mbox{ and each } x_i∈ A\} \ \end{align} \end{equation}

Example2

Literate Programming Recipes

See: Org-mode-recipes.org

Resources

References

Manual:

The Org Manual orgmode.org
Org Mode Manual
Org Glossary: An Explanation of Basic Org-Mode Concepts
Editing
- http://orgmode.org/manual/Structure-editing.html

Examples:

Emacs org-mode examples and cookbook

Many examples about literate programming in Org-mode with Python, R, java and C. Shows integration of org-mode tables and Python, R … and code blocks.

http://gitwiki.org/Tests/org-mode.org
My Org-mode journey – Chapter 1 | chop-mode

Reference Cards and Cheat Sheets:

The Compact Org-Mode Guide
Org-Mode Reference Card
Markup Cheat sheet for Org-mode

Books:

Org Mode - Organize Your Life In Plain Text!

Hacking and Tweaking:

Embedding Youtube videos with org-mode links
Paste an image on clipboard to Emacs Org mode file without saving it
Org-mode Frequently Asked Questions
My org-protocol setup, part 1.
Batch export of org-mode files from the command line
Org ad hoc code, quick hacks and workarounds

Cases:

What we are using org-mode for
Org-mode tricks for team management

Literate Programming:

Literate DevOps - www.howardism.org
Emacs Org Mode: Executing simple python code
R and Emacs with org mode
Org-mode and R: An Introduction Introduction
Babel: Introduction
Results of evaluation / Org-Mode Manual

Non Categorized:

Gareth’s Org-Mode Config

Videos

Tutorials

Org Mode in Depth - by Rick Dillon

Hack Emacs - Org Mode In Depth: Managing Structure - YouTube

Description: “Part of the Org Mode In Depth series. In this episode, we examine methods for exploiting the structure of an Org Mode file to focus on specific subtrees, control visibility by folding and unfolding headlines, navigate among headlines efficiently and reorganize headlines my moving and/or promoting and demoting them.”

Org Mode In Depth: Tables - YouTube

Description: “Actually recorded a few months back, I never got around to uploading this. I give a brief demo of some of the functionality Org Mode tables offer, and an explanation of some of the commands that enable it.”

Hack Emacs - Org Mode in Depth: Markup and Links - YouTube

Description: “Part of the Org Mode in Depth series. In this episode, I examine ways of marking up text in Org Mode, as well as various link types that connect Org headlines and files, as well as links that can execute code.”

NOn-Programmer’s Emacs: Studying in Emacs pt 3: Annotation with Orgmode by Tory S. Anderson

Non-Programmer’s Emacs: Studying in Emacs pt 3: Annotation with Orgmode

- -

Presentations

Emacs Org-Mode - A system for note-taking and project planning - Talk given by Carsten Dominik.
Embedding Code Snippets In Org Mode
Emacs Tutorial - Overview of Init Files Using Org-Mode and Use-Package (Part 1 of 2)
Org mode is awesome
Emacs Org-mode - a system for note-taking and project planning
Hack-Emacs an Overview of Org-Mode
Teaching with Emacs+org-mode - YouTube

Org-mode Elisp Snippets and Org-mode API

Org-mode API documentation

To access org-mode API documentation inside Emacs, copy the code below to the scratch buffer, then place the cursor at the end of any of those s-expressions and type C-x C-e or type M-x eval-last-sexp.

(info "(org)Library of Babel") 

(info "(org)Previewing LaTeX fragments")

(info "(org)Exporting code blocks") 

(info "(org)The export dispatcher") 

(info "(org)noweb")

Code Block Templates

When the user writes ‘<p’in org-mode and hits tab key it expands to a python source code block like this:

#+BEGIN_SRC python :results value

#+END_SRC

Elisp code:

(add-to-list 'org-structure-template-alist
	     '("p" "#+BEGIN_SRC python :results ?value\n\n#+END_SRC"))

Code Blocks API

Overview

To test this the code block API divide the window in two parts, one cointaining a org buffer with some org-mode file and other one the emacs shell, IELM, that can be invoked with M-x ielm.
At the org-mode buffer position the cursor at the code block.
Go to the IELM buffer and run C-c C-b or type M-x ielm-change-working-buffer and change the working buffer to the org-mode buffer by typing its name and hitting tab to complete it.
Run the commands at the IELM shell. If it was done the command
- (buffer-name) will return the name of the org-mode buffer instead of *ielm*.

In this section, it is supposed that the org-buffer has this code block:

#+BEGIN_SRC scala :tangle /tmp/scalatest.scala
  import java.awt.BorderLayout
  import javax.swing.{JFrame, JPanel, JButton, JTextArea}

  val frame = new JFrame("Border Layout")
  val btn1  = new JButton("North")
  val btn2  = new JButton("South")
  val btn3  = new JButton("Center")
  val btn4  = new JButton("West")
  val btn5  = new JButton("East")

  frame.setLayout(new BorderLayout())
  frame.add(btn1, BorderLayout.NORTH)
  frame.add(btn2, BorderLayout.SOUTH)
  frame.add(btn3, BorderLayout.CENTER)
  frame.add(btn4, BorderLayout.WEST)
  frame.add(btn5, BorderLayout.EAST)

  frame.setSize(300, 400)
  frame.setVisible(true)
#+END_SRC

It would be rendered as:

import java.awt.BorderLayout
import javax.swing.{JFrame, JPanel, JButton, JTextArea}

val frame = new JFrame("Border Layout")
val btn1  = new JButton("North")
val btn2  = new JButton("South")
val btn3  = new JButton("Center")
val btn4  = new JButton("West")
val btn5  = new JButton("East")

frame.setLayout(new BorderLayout())
frame.add(btn1, BorderLayout.NORTH)
frame.add(btn2, BorderLayout.SOUTH)
frame.add(btn3, BorderLayout.CENTER)
frame.add(btn4, BorderLayout.WEST)
frame.add(btn5, BorderLayout.EAST)

frame.setSize(300, 400)
frame.setVisible(true)

Get information about code block

ELISP> (org-babel-get-src-block-info)
("scala" "import java.awt.BorderLayout\nimport javax.swing.{JFrame, JPanel, JButton, JTextArea}\n\nval frame = new JFrame(\"Border Layout\")\nval btn1  = new JButton(\"North\")\nval btn2  = new JButton(\"South\")\nval btn3  = new JButton(\"Center\")\nval btn4  = new JButton(\"West\")\nval btn5  = new JButton(\"East\")\n\nframe.setLayout(new BorderLayout())\nframe.add(btn1, BorderLayout.NORTH)\nframe.add(btn2, BorderLayout.SOUTH)\nframe.add(btn3, BorderLayout.CENTER)\nframe.add(btn4, BorderLayout.WEST)\nframe.add(btn5, BorderLayout.EAST)\n\nframe.setSize(300, 400)\nframe.setVisible(true)"
 ((:colname-names)
  (:rowname-names)
  (:result-params "replace")
  (:result-type . value)
  (:comments . "")
  (:shebang . "")
  (:cache . "no")
  (:padline . "")
  (:noweb . "no")
  (:tangle . "/tmp/scalatest.scala")
  (:exports . "code")
  (:results . "replace")
  (:hlines . "no")
  (:session . "none"))
 "" nil 0 2257)

ELISP>

Getting the programming language of the code block

ELISP> (car (org-babel-get-src-block-info))
"scala"
ELISP>

Getting the source code of the code block

ELISP> (cadr (org-babel-get-src-block-info))
"import java.awt.BorderLayout\nimport javax.swing.{JFrame, JPanel, JButton, JTextArea}\n\nval frame = ..."
ELISP>

ELISP> (print (cadr (org-babel-get-src-block-info)))

"import java.awt.BorderLayout
import javax.swing.{JFrame, JPanel, JButton, JTextArea}

val frame = new JFrame(\"Border Layout\")
val btn1  = new JButton(\"North\")
val btn2  = new JButton(\"South\")
val btn3  = new JButton(\"Center\")
val btn4  = new JButton(\"West\")
val btn5  = new JButton(\"East\")

frame.setLayout(new BorderLayout())
frame.add(btn1, BorderLayout.NORTH)
frame.add(btn2, BorderLayout.SOUTH)
frame.add(btn3, BorderLayout.CENTER)
frame.add(btn4, BorderLayout.WEST)
frame.add(btn5, BorderLayout.EAST)

frame.setSize(300, 400)
frame.setVisible(true)"

Getting code block attributes

ELISP> (caddr (org-babel-get-src-block-info))
((:colname-names)
 (:rowname-names)
 (:result-params "replace")
 (:result-type . value)
 (:comments . "")
 (:shebang . "")
 (:cache . "no")
 (:padline . "")
 (:noweb . "no")
 (:tangle . "/tmp/scalatest.scala")
 (:exports . "code")
 (:results . "replace")
 (:hlines . "no")
 (:session . "none"))

ELISP> (assoc :exports (caddr (org-babel-get-src-block-info)))
(:exports . "code")

ELISP> (cdr (assoc :exports (caddr (org-babel-get-src-block-info))))
"code"
ELISP>

ELISP> (assoc :tangle (caddr (org-babel-get-src-block-info)))
(:tangle . "/tmp/scalatest.scala")

ELISP> (cdr (assoc :tangle (caddr (org-babel-get-src-block-info))))
"/tmp/scalatest.scala"
ELISP>

Run a Scala code block

This example is specific for the Scala language, but can be easily adapated to other languages.

Usage:

Place the cursos at the some scala code block
run M-x org/run-scala-block

It will run save the code block content to the file /tmp/scala-snippet.scala and run the command $ scala /tmp/scala-snippet.scala in the compiling mode.

(defun org/run-scala-block ()
  (interactive)
         ;; Org-mode block contents 
  (let* ((content (cadr (org-babel-get-src-block-info)))
         ;; File in that the contents will be saved.
         (file    "/tmp/scala-snippet.scala"))
    ;; Execute the commands inside this special form
    ;; in a temporary buffer 
    (with-temp-buffer
      ;; Delete file if it exists
      (if (file-exists-p file) (delete-file file))
      ;; Insert the code block contents in the temporary buffer 
      (insert content)
      ;; Write the buffer contents to fil.
      (append-to-file (point-min) (point-max) file))    
    ;; Run the compilation command 
    (compile (format "scala %s" file))))

Custom Protocols

Open directory with dired mode

Org-mode already provides the protocol file:<filename> to open a directory or file. The motivation to implement this protocol is that it is unambiguous like file protocol and easy to search.

Hyperlink syntax: dir:<file-path>

(add-hook 'org-mode-hook
          (lambda ()
	      (org-add-link-type "dir" #'dired nil)))

Org-mode file example:

Log directory      -  dir:/var/log  -  [[dir:/var/log][Log directory]]

System cofiguration - dir:/etc

Open directory with system file manager

Hyperlink format: dire:<directory-path>

(defvar default-file-manager-app "pcmanfm-qt")

(defun org/protocol-dire (input)
  (start-process  "proc" ;; Process name
		  nil    ;; Buffer name

		  default-file-manager
		  input
		  ))

(add-hook 'org-mode-hook
          (lambda ()
	      (org-add-link-type "dire" #'org/protocol-dire nil)))

Example:

To open the directory file:/var/log in the system file
manager click on the hyperlink bellow.


 - Hyperlink1:   dire:/var/log

 - Hyperlink2:   [[dire:/var/log][System Log directory]]

Man page

Provides a hyperlink that displays a man page when clicked.

(add-hook 'org-mode-hook
          (lambda ()
	         (org-add-link-type  "man" #'woman nil)))

Example:

file test.org

Click on the hyperlinks bellow to open the man pages:

Gcc Man Page:

 - man:gcc

C-function cbrt Man Page

 - man:cbrt

 - [[man:cbrt][C-function cbrt Man Page]]

Elisp Documentation

Provides clickable link that shows the the Elisp documentation.

A link of format elisp-doc:add-hook will show the add-hook documentation when clicked.

Hyperlink format: elisp-doc:<function-name> or [elisp-doc:<function-name>]

(defun org/protocol-elisp-doc (function-symbol)
  (princ function-symbol)
  (describe-function (intern-soft function-symbol)))


(defun org/protocol-elisp-doc-html (path desc backend)
   (cl-case backend
     (html (format
            "<a href='' title='%s'>%s</a>"
            (documentation (intern-soft path))
            (or desc path)))))

(add-hook 'org-mode-hook
      (lambda ()
        (org-add-link-type "elisp-doc"
                           #'org/protocol-elisp-doc
                           #'org/protocol-elisp-doc-html)))

Example:

file: /tmp/test.org

Elisp documentation protocol:

[[elisp-doc:add-hook][Function Add hook]]

The function elisp-doc:start-process is used to start an asynchronous process.

This screenshot show what happens when the user clicks in the hyperlink.

Exported to html with: M-x org-html-export-to-html

Settings

General Settings

Syntax highlight for code blocks #+BEGIN_SRC .. #+END_SRC

;; Syntax highlight for code blocks  #+BEGIN_SRC .. #+END_SRC
;;
(setq org-src-fontify-natively t)

Syntax highlight for latex fragments

(setq org-highlight-latex-and-related '(latex script entities))

Code Block - Org-babel

Enable source code block in org files

(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (sh . t)
   (python . t)
   (scheme . t)
   (lisp . t)
   (clojure . t)
   (R . t)
   (latex . t)
   (ruby . t)
   (C . t)
   ;;; (C++ . t)
   (ditaa . t)
   (haskell . t)
 ;;  (fsharp . t)
 ;;  (java . t)
 ;;  (scala . t)
;;   (javascript . t)
   (maxima . t)
  ))

Disable Security confirmation:

;; Disable security confirmations
;;

(setq   ;; Confirmation for running coide blocks
        org-confirm-babel-evaluate      nil
        ;; Confirmation for elisp links
        org-confirm-elisp-link-function nil
        ;; Confirmation for shell links
        org-confirm-shell-link-function nil

        org-export-babel-evaluate       nil
        )

Files

Org-Mode.org

Latest commit

History

Org-Mode.org

File metadata and controls

Org-mode

Org-Mode

Overview

Key bindings and commands for org-mode

Useful Commands

Hyperlink

Move within headlines

Buffer Subtree

Table

Hyperlinks

Markdown Summary

Text Formatting

Hyperlinks

Code Blocks

Summary

Quote Block

Text Position

Center

Left

Right

Latex Code Block

Literate Programming Recipes

Resources

References

Videos

Tutorials

Presentations

Org-mode Elisp Snippets and Org-mode API

Org-mode API documentation

Code Block Templates

Code Blocks API

Overview

Get information about code block

Getting the programming language of the code block

Getting the source code of the code block

Getting code block attributes

Run a Scala code block

Custom Protocols

Open directory with dired mode

Open directory with system file manager

Man page

Elisp Documentation

Settings

General Settings

Code Block - Org-babel