12.4 Include files

Include other files during export. For example, to include your .emacs file, you could use:

#+INCLUDE: "~/.emacs" src emacs-lisp

The first parameter is the file name to include. The optional second parameter specifies the block type: ‘example’, ‘export’ or ‘src’. The optional third parameter specifies the source code language to use for formatting the contents. This is relevant to both ‘export’ and ‘src’ block types.

If an include file is specified as having a markup language, Org neither checks for valid syntax nor changes the contents in any way. For ‘example’ and ‘src’ blocks, Org code-escapes the contents before inclusion.

If an include file is not specified as having any markup language, Org assumes it be in Org format and proceeds as usual with a few exceptions. Org makes the footnote labels (see Footnotes) in the included file local to that file. The contents of the included file will belong to the same structure—headline, item—containing the INCLUDE keyword. In particular, headlines within the file will become children of the current section. That behavior can be changed by providing an additional keyword parameter, :minlevel. It shifts the headlines in the included file to become the lowest level. For example, this syntax makes the included file a sibling of the current top-level headline:

#+INCLUDE: "~/my-book/chapter2.org" :minlevel 1

Inclusion of only portions of files are specified using ranges parameter with :lines keyword. The line at the upper end of the range will not be included. The start and/or the end of the range may be omitted to use the obvious defaults.

#+INCLUDE: "~/.emacs" :lines "5-10"   Include lines 5 to 10, 10 excluded
#+INCLUDE: "~/.emacs" :lines "-10"    Include lines 1 to 10, 10 excluded
#+INCLUDE: "~/.emacs" :lines "10-"    Include lines from 10 to EOF

Inclusions may specify a file-link to extract an object matched by org-link-search¹²⁷ (see Search options).

To extract only the contents of the matched object, set :only-contents property to non-nil. This will omit any planning lines or property drawers. The ranges for :lines keyword are relative to the requested element. Some examples:

#+INCLUDE: "./paper.org::#theory" :only-contents t
   Include the body of the heading with the custom id ‘theory’
#+INCLUDE: "./paper.org::mytable"  Include named element.
#+INCLUDE: "./paper.org::*conclusion" :lines 1-20
   Include the first 20 lines of the headline named ‘conclusion’.

C-c '

Visit the include file at point.