33

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

Tahnoon Pasha
  • 5,196
  • 12
  • 42
  • 71

3 Answers3

16

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.

Oliver Matthews
  • 6,755
  • 3
  • 27
  • 32
  • Perfect thanks @OliverMatthews. I may use python instead of perl but a pre-process sounds like a good idea. – Tahnoon Pasha Aug 29 '13 at 22:45
  • After tens of hours invested to searching a viable and fast method for implementing includes in Pandoc this is finally what works. Thank you! – certainlyakey Feb 08 '14 at 21:50
  • Here's how my perl statement looks like now - it's a little bit modified so it could embrace file paths with spaces and be compatible with path-searching ST plugins like AutoFileName. Also it's escaped to work inside a ST build system. The syntax is `#(path/to/file)`: `perl -ne 's/^#\\((.+)\\).*/`cat \"\\$1\"`/e;print' ${file_base_name}.md > result.md` – certainlyakey Feb 09 '14 at 00:41
4

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.

Community
  • 1
  • 1
Sebastian
  • 1,733
  • 11
  • 16
  • Thanks @Sebastian. A very useful link too. – Tahnoon Pasha Aug 29 '13 at 22:46
  • I thought about using cpp (and using #include), but figured it would be a pain as the headers also start with #s. For those who like things a little more esoteric, there is always funnelweb (which is probably what I would have personally used, but I did try to limit it to things you would have installed). – Oliver Matthews Aug 29 '13 at 23:03
0

I've been reading these posts recently though they're a little old now, as well as the ones at Markdown and including multiple files. I am relatively green at all this, so I haven't been able to get Sethen's markdown-include function to work since I don't know javascript.

But it seems to me that you could write a simple recursive function in Python pretty easily. It would take a .md file as its argument and parse it, looking for characteristic syntax indicating that/where the argument file is calling another .md file. The parsing would not only look for the characteristic syntax, but also build a single long string of all the markdown it has checked along the way. If the function hits a reference to a .md file, it calls itself, using the .md file it's just found. When it gets to the bottom, it pops back up through the recursive levels, returning all the markdown it has passed through its dive(s). The final result would be to return a single .md file with all markdown inside it.

It's then easy to feed this larger, returned, 100% standard markdown .md file to pandoc.

Colin Wilder
  • 11
  • 2