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/" :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: "./*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: "./" :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.↩