Multiple File Markdown Document

One of the tasks a project manager normally faces is merging lots of pieces of information together into a single document. Markdown has been the primary way I’ve been writing notes and posts for a couple of years now. One of the features I’ve been using more and more is merging multiple Markdown files into a single document.[1] This allows edits to be made to smaller “chapters” and merging them into a single document for publishing. While not as elaborate as Dr. Drang’s workflow, this process allows me to better manage field reports or technical documents in smaller chunks.

Main Document Format

The key to setting up a multiple file Markdown file is the main document.


So an example main document would look like this:

Chapter Documents

The multi-file system is based on linking the “chapter” files to the main document. As shown above, because the chapter files are just links to the other files they don’t have to reside in the same folder as the main document.

The is just a simple Markdown file.

Pulling it all together

Once all the documents are in place, I normally use MarkedApp to publish the main document into whatever format I need - PDF, DOCX, HTML, etc. Again, since I used reference links to the chapter files, parsing the main document in Marked pulls the text from the chapter files into the render of the main document.[2]

Previewing the main document example from above allows me to proof the document and look for any formatting or file errors.

In this case, it shows I have an issue with the file. Either the files does not exist or is not in the path I specified in the main document. I can go back, make any needed corrections, and then publish the document.

  1. Markedapp has a great reference on multi-file document usage, so this post is mainly for my easy personal reference.  ↩
  2. Not all Markdown editors can parse multi-file documents. At the time of this post, two popular editors, Byword and MultiMarkdown Composer, would not parse multi-file documents.  ↩