13.4 Include Files ¶

During export, you can include the content of another file. For example, to include your ‘.emacs’ file, you could use:

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

There are three positional arguments after the include keyword, they are:

1. The file name, this is the sole mandatory argument. Org neither checks for correctness or validates the content in any way.
2. The block name to wrap the file content in. When this is ‘example’, ‘export’, or ‘src’ the content is escaped by org-escape-code-in-string. Arbitrary block names may be given, however block names starting with ‘:’ must be quoted, i.e. ‘":name"’.
3. The source code language to use for formatting the contents. This is relevant to both ‘export’ and ‘src’ block types.

If an included 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 Creating Footnotes) in the included file local to that file. The contents of the included file belong to the same structure—headline, item—containing the ‘INCLUDE’ keyword. In particular, headlines within the file 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.

Inclusions may specify a file-link to extract an object matched by org-link-search¹³⁰ (see Search Options in File Links). The ranges for ‘:lines’ keyword are relative to the requested element. Therefore,

#+INCLUDE: "./paper.org::*conclusion" :lines "1-20"

includes the first 20 lines of the headline named ‘conclusion’.

To extract only the contents of the matched object, set ‘:only-contents’ property to non-nil. This omits any planning lines or property drawers. For example, to include the body of the heading with the custom ID ‘theory’, you can use

#+INCLUDE: "./paper.org::#theory" :only-contents t

The following command allows navigating to the included document:

C-c ' (org-edit-special) ¶

Visit the included file at point.