This is the official manual for the latest Org-mode release.

Table of Contents

Next: , Previous: Literal examples, Up: Markup


11.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 names the the file to include. The optional second and third parameter specify the markup (i.e., ‘example’ or ‘src’), and, if the markup is ‘src’, the language for formatting the contents.

If markup is requested, the included content will be placed within an appropriate block1. No changes to the included content are made and it is the responsibility of the user to ensure that the result is valid Org syntax. For markup ‘example’ and ‘src’, which is requesting a literal example, the content will be code-escaped before inclusion.

If no markup is requested, the text will be assumed to be in Org mode format and will be processed normally. However, footnote labels (see Footnotes) in the file will be made local to that file. 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. In that case, all headlines in the included file will be shifted so the one with the lowest level reaches that specified level. For example, to make a file become a sibling of the current top-level headline, use

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

You can also include a portion of a file by specifying a lines range using the :lines keyword parameter. 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

Finally, you may use a file-link to extract an object as matched by org-link-search2 (see Search options). If the :only-contents property is non-nil, only the contents of the requested element will be included, omitting properties drawer and planning-line if present. The :lines keyword operates locally with respect 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.

Footnotes

[1] While you can request paragraphs (‘verse’, ‘quote’, ‘center’), but this places severe restrictions on the type of content that is permissible

[2] 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.