← Back to Marked

Marked Help

• Full Index
• Changelog

# Multi-file Documents

You can include external files in a single preview document by using the syntax <<[path/file] at the beginning of a line. The line should have blank lines above and below it, and the path is assumed to be relative to the main document unless it begins with a slash (/) or a tilde (~). Slash (root directory) and tilde (home directory) may be used to define absolute paths to files. No path is needed if the external files are in the same folder as the main document, just put the filename (case sensitive and including extension) in the square brackets.

Note that when viewing documents with included files, you can type “I” (shift-i) to see which included file is in the visible area.

Using this feature you can build large documents/books using multiple files (e.g. a file for each chapter) and then specify the document order in a single index file. It doesn’t matter how any of the files are named or how the folders are organized; the file you open in Marked will be considered the index and the files listed inside it will be included. An example of an index file for a three-part document:

Folder structure:

Index.md:

# Document title

## Section 1

<<[sections/section1.md]

## Section 2

<<[sections/section2.md]

## Section 3

<<[sections/section3.md]


Opening Index.md in Marked will display its contents with all three included files expanded inside. All included files will be watched for changes. Unlike the open document in Marked, included file tracking depends on Spotlight to obtain updates and must exist in a Spotlight-indexed folder on your disk.

You can also include code snippets and raw html or text using variations of this syntax.

The final HTML export of a document containing includes will have HTML comments containing the relative path of the included file at the beginning and end of the imported text.

Note: the more files included in a document, the slower the overall compile time of the preview will be. Marked tries to optimize and cache the process, but expect some rendering delays as your document size increases.

## Book Formats

Marked also supports index files in formats like Leanpub and mmd_merge (MultiMarkdown). If you enable the option in Behavior Preferences, files named “Book.txt” will be treated as Leanpub index files automatically. The older “frontmatter:” format is also recognized. For mmd_merge, Marked require that the first line be “#merge” (special Marked trigger for mmd_merge, treated as a comment and ignored by other processors).

Included files will be watched for changes and the result is a complete preview of your compiled document, just like the “Index.md” example above.

## Multi-file Document Preview Features

When viewing a document containing included files, you can use two features to help figure out which file you’re looking at.

• Keyboard: Pressing ⇧I will briefly display a popup showing the title of the file currently visible at the scroll position of the preview.
• Pressing Return following I will edit the displayed file with your external editor.
• Mouse: Selecting “Show Boundaries of Included Files” from the Gear menu (^⌘B) will add a colored bar to the left side of the preview, segmented to show the beginning and end of included files. It also shows nested includes. Hovering over a section of this bar will show the name of the file it represents, and clicking it will open that file in your chosen editor.