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.
#+BEGIN_EXAMPLE
Some example from a text file.
#+END_EXAMPLE
For simplicity when using small examples, you can also start the example lines with a colon:
: 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 buffer1. 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 example:
#+BEGIN_SRC emacs-lisp
(defun org-xor (a b)
"Exclusive or."
(if a (not b) b))
#+END_SRC
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. If you use a +n switch, the numbering from the previous
numbered snippet will be continued in the current one. 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, hoovering the mouse over such
a link will remote-highlight the corresponding code line, which is kind of
cool. If the example/src snippet is numbered, you can also add a -r
switch. Then labels will be removed from the source code and the links
will be replaced2 with line numbers from the code listing. Here is
an example:
#+BEGIN_SRC emacs-lisp -n -r
(save-excursion (ref:sc)
(goto-char (point-min)) (ref:jump)
#+END SRC
In line [[(sc)]] we remember the current positon. [[(jump)][Line (jump)]]
jumps to point-min.
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.
artist-mode4 to allow creating
ASCII drawings easily. Using this command in an empty line will create a new
fixed-width region.
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.
[1] Currently this works only for the HTML back-end, and requires the htmlize.el package version 1.34 or later.
[2] If you want to explain the use of such labels
themelves in org-mode example code, you can use the -k switch to make
sure they are not touched.
[3] Upon exit, lines starting with ‘*’ or ‘#’ will get a comma prepended, to keep them from being interpreted by Org as outline nodes or special comments. These commas will be striped for editing with C-c ', and also for export.
[4] You may select a different-mode with
the variable org-edit-fixed-width-region-mode.