41

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,848
  • 14
  • 49
  • 75

6 Answers6

19

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
  • 7,497
  • 3
  • 33
  • 36
  • 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
  • 1
    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
  • boohoo for _markdown_ on this. but yea you made maybe the least painful workaround – WestCoastProjects Mar 15 '22 at 06:02
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,839
  • 12
  • 16
  • 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
0

Recursive version of @Oliver Matthews' answer but using a wikilinks-like syntax ![[chapter1.md]]

parseMd.sh

#!/usr/bin/env bash
perl -ne 's#^!\[\[(.+?)\]\].*#`'$0' "$1"`#e;print' "$@"

and use it like this

./parseMd.sh main.md > final.md

Using it with pandoc

pandoc <(./parseMd.sh main.md) -o final.pdf
Madacol
  • 3,611
  • 34
  • 33
0

Here's a version of the pandoc-include filter written in Python https://github.com/DCsunset/pandoc-include

I tried it and it works well. It has some useful options, such as indenting and dedenting the included file.

Christian Long
  • 10,385
  • 6
  • 60
  • 58
0

I know this is really old, but just stumbled across it. If you need things like this, checkout asciidoc for documentation. renders basic features on github and provides features/syntax like include. pretty awesome tbh, you can even get into plugins and such- my favorite is Mermaid for rendering diagrams. You can choose a processor to spit out html or pdf from your adoc files as well.

Hope this helps the next person that comes along

Codester
  • 1
  • 1