Multi-file Documents
Marked allows several different syntaxes for including one file within another.
Contents
Marked Syntax
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.
You can use the metadata headers “Include Base” or “Transclude Base” to change the base location for included files, e.g.:
Transclude Base: ~/Desktop
Note that when viewing documents with included files, you can type “I” (shift-i) to see which included file is in the visible area. Pressing return while the included file path is displayed will open the included file in the default editor.
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.
MultiMarkdown Transclude Syntax
You can also use {{filename}} syntax based on the newer MultiMarkdown spec. Marked will recognize Transclude Base: path in MMD metadata and use it as the base for file transclusion.
Transclude Base will only be recognized in the parent document, not in additional included documents. All nested includes must have paths based on the initial Transclude Base, or from the location of the parent document.
The fenced code syntax that MultiMarkdown provides for including files without processing will not work in Marked. To do this, please use the <<(file) (code block) or <<{file} (raw) syntax.
IA Writer Block syntax
Marked 2.5.11+ supports the IA Writer Content Block syntax. This is a reference beginning with a forward slash (/) on its own line. It can be a code sample, an image, a markdown file, or a CSV file. All will be handled appropriately based on the extension of the included file, and CSVs will be converted into Markdown tables if possible.
In IA writer, included files are brought into the iCloud container and don’t always require “actual” paths. In Marked, unless included files already exist in the same folder as the file being previewed, this syntax should be used with a path, either absolute or relative. The first slash will be ignored, so if it’s an absolute path, start with two slashes.
A code snippet in the same folder as the document being previewed:
/snippet.h
Relative path to a subdirectory called “images”:
/images/image.png "optional title"
Absolute path to the Documents folder:
//Users/username/Documents/content.csv
Book Formats
Marked also supports index files in formats like Leanpub, GitBook and mmd_merge (MultiMarkdown). Files included in book format indexes will be watched for changes and the result is a complete preview of your compiled document, just like the “Index.md” example above.
Leanpub
If you enable the option in the under Leanpub/GitBook support, files named “Book.txt” will be treated as Leanpub index files automatically. The older “frontmatter:” format is also recognized.
Leanpub Book.txt example:
frontmatter:
Acknowledgments.txt
Preface.txt
Introduction.txt
mainmatter:
Markdown.txt
Sample Books.txt
Inserting Images.txt
mmd_merge
For mmd_merge, Marked require that the first line be “#merge” (a special Marked trigger for mmd_merge, treated as a comment and ignored by other processors).
mmd_merge example:
#merge
metadata.txt
Chapter-1.md
sub-chapter-1-1.md
sub-chapter-1-2.md
Chapter-2.md
sub-chapter-2-1.md
sub-chapter-2-2.md
FAQ.md
Acknowledgments.md
GitBook
GitBook formatting uses a Markdown list to create the structure and Table of Contents. If GitBook support is enabled in the under Leanpub/GitBook support, a file named SUMMARY.md will be read and automatically converted to mmd_merge format, allowing a full preview of your GitBook document.
GitBook SUMMARY.md example:
# Summary
* [Part I](part1/README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)
GitBook allows for anchors to be used in SUMMARY.md table of contents, but Marked will ignore these and only include the base document one time.
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.
Next up: Fountain for Screenwriters ▶
Search | Support Site | Knowledgebase | Legal | Privacy | Twitter