Next: , Previous: , Up: Markup   [Contents][Index]

11.5 Literal examples

You can include literal examples that should not be subjected to markup. Such examples will be typeset in monospace, so this is well suited for source code and similar examples.

Some example from a text file.

Note that such blocks may be indented in order to align nicely with indented text and in particular with plain list structure (see Plain lists). For simplicity when using small examples, you can also start the example lines with a colon followed by a space. There may also be additional whitespace before the colon:

Here is an example
   : Some example from a text file.

If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to look like the fontified Emacs buffer114. This is done with the ‘src’ block, where you also need to specify the name of the major mode that should be used to fontify the example115, see Easy templates for shortcuts to easily insert code blocks.

#+BEGIN_SRC emacs-lisp
  (defun org-xor (a b)
     "Exclusive or."
     (if a (not b) b))

Both in example and in src snippets, you can add a -n switch to the end of the BEGIN line, to get the lines of the example numbered. The -n takes an optional numeric argument specifying the starting line number of the block. If you use a +n switch, the numbering from the previous numbered snippet will be continued in the current one. The +n can also take a numeric argument. The value of the argument will be added to the last line of the previous block to determine the starting line number.

#+BEGIN_SRC emacs-lisp -n 20
 ;; this will export with line number 20
 (message "This is line 21")
#+BEGIN_SRC emacs-lisp +n 10
 ;; This will be listed as line 31
 (message "This is line 32")

In literal examples, Org will interpret strings like ‘(ref:name)’ as labels, and use them as targets for special hyperlinks like [[(name)]] (i.e., the reference name enclosed in single parenthesis). In HTML, hovering the mouse over such a link will remote-highlight the corresponding code line, which is kind of cool.

You can also add a -r switch which removes the labels from the source code116. With the -n switch, links to these references will be labeled by the line numbers from the code listing, otherwise links will use the labels with no parentheses. Here is an example:

#+BEGIN_SRC emacs-lisp -n -r
(save-excursion                  (ref:sc)
   (goto-char (point-min)))      (ref:jump)
In line [[(sc)]] we remember the current position.  [[(jump)][Line (jump)]]
jumps to point-min.

Finally, you can use -i to preserve the indentation of a specific code block (see Editing source code).

If the syntax for the label format conflicts with the language syntax, use a -l switch to change the format, for example ‘#+BEGIN_SRC pascal -n -r -l "((%s))"’. See also the variable org-coderef-label-format.

HTML export also allows examples to be published as text areas (see Text areas in HTML export).

Because the #+BEGIN_... and #+END_... patterns need to be added so often, shortcuts are provided using the Easy templates facility (see Easy templates).

C-c '

Edit the source code example at point in its native mode. This works by switching to a temporary buffer with the source code. You need to exit by pressing C-c ' again117. The edited version will then replace the old version in the Org buffer. Fixed-width regions (where each line starts with a colon followed by a space) will be edited using artist-mode118 to allow creating ASCII drawings easily. Using this command in an empty line will create a new fixed-width region.

C-c l

Calling org-store-link while editing a source code example in a temporary buffer created with C-c ' will prompt for a label. Make sure that it is unique in the current buffer, and insert it with the proper formatting like ‘(ref:label)’ at the end of the current line. Then the label is stored as a link ‘(label)’, for retrieval with C-c C-l.



This works automatically for the HTML back-end (it requires version 1.34 of the htmlize.el package, which you need to install). Fontified code chunks in LaTeX can be achieved using either the listings or the minted package. If you use minted or listing, you must load the packages manually, for example by adding the desired package to org-latex-packages-alist. Refer to org-latex-listings for details.


Code in ‘src’ blocks may also be evaluated either interactively or on export. See Working with source code, for more information on evaluating code blocks.


Adding -k to -n -r will keep the labels in the source code while using line numbers for the links, which might be useful to explain those in an Org mode example code.


Upon exit, lines starting with ‘*’, ‘,*’, ‘#+’ and ‘,#+’ will get a comma prepended, to keep them from being interpreted by Org as outline nodes or special syntax. These commas will be stripped for editing with C-c ', and also for export.


You may select a different-mode with the variable org-edit-fixed-width-region-mode.

Next: , Previous: , Up: Markup   [Contents][Index]