14.1 Structure of code blocks
Org offers two ways to structure source code in Org documents: in a
‘src’ block, and directly inline. Both specifications are shown below.
A ‘src’ block conforms to this structure:
#+BEGIN_SRC <language> <switches> <header arguments>
Org mode's templates system (see Easy templates) speeds up creating
‘src’ code blocks with just three keystrokes. Do not be put-off by
having to remember the source block syntax. Org also works with other
completion systems in Emacs, some of which predate Org and have custom
domain-specific languages for defining templates. Regular use of templates
reduces errors, increases accuracy, and maintains consistency.
An inline code block conforms to this structure:
- Optional. Names the ‘src’ block so it can be called, like a function,
from other ‘src’ blocks or inline blocks to evaluate or to capture the
results. Code from other blocks, other files, and from table formulas
(see The spreadsheet) can use the name to reference a ‘src’ block.
This naming serves the same purpose as naming Org tables. Org mode requires
unique names. For duplicate names, Org mode's behavior is undefined.
- Mandatory. They mark the start and end of a block that Org requires. The
#+BEGIN_SRC line takes additional arguments, as described next.
- Mandatory for live code blocks. It is the identifier of the source code
language in the block. See Languages, for identifiers of supported
- Optional. Switches provide finer control of the code execution, export, and
format (see the discussion of switches in Literal examples)
- Optional. Heading arguments control many aspects of evaluation, export and
tangling of code blocks (see Header arguments). Using Org's properties
feature, header arguments can be selectively applied to the entire buffer or
specific sub-trees of the Org document.
source code, header arguments
- Source code in the dialect of the specified language identifier.