Skip to main content

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

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 included file is specified as having a markup language, Org neither checks for valid syntax nor changes the contents in any way. For example and source blocks, Org code-escapes the contents before inclusion.

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.

‘#+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-search1 (see Search Options). 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.

  1. Note that org-link-search-must-match-exact-headline is locally bound to non-nil. Therefore, org-link-search only matches headlines and named elements.↩