Embedding one markdown document in another

Question

Is there a way to embed one markdown (or its sub-flavors - I'm using PanDoc) document in another except for using a jQuery().load(url)?

I'd like to have a document that has eg. main.md, chapter1.md, chapter2.md, with main.md loading chapter1.md and chapter2.md automatically.

main.md will have text in between the two chapters e.g.

main.md:

Some opening text... ... [chapter1.md]  Some additional text... ... [chapter2.md] ... something else. 

So I can't use a cat *.md > final.md approach

Answer 1

Markdown by itself lacks a notation for including files, which rather screws that.

pandoc has an example on using a custom haskell filter on code blocks to include files but this a. leaves a code block around the text and (more importantly) b. doesn't parse the new file as markdown, and frankly my haskell isn't up to the task of fixing that.

However, you can achieve this by doing a pre-process pass, using perl*. I'm assuming that each include is on a line by itself of the form shown above.

perl -ne 's/^\[(.+)\].*/`cat $1`/e;print' main.md > final.md 

*I dislike having to resort to perl, but sed lacks the ability to read from a file using a match pattern to determine the name.

Answer 2

If you don't want the sub chapters inline, you can simply insert links into the main chapter. This way, you don't need a preprocessing step.

As Oliver Matthews has written, you can write your own preprocessing step with perl.

Or you can use an existing preprocessor, like m4 or cpp (The C PreProcessor) which allows including files. cpp probably doesn't cope nicely with C code sections in the documents, though. Especially when there are more include directives in them.

There are also toolchains available on the internet which combine separate mardown documents into something bigger. Unfortunately, I've got currently problems to access the backup of my bookmarks.

And here's a similar question, with answers: Markdown and including multiple files although the answers don't explain how to insert sub chapters in between other text.