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

I keep a list of projects I found that let you include things with a preprocessing step to produce the final markdown file: realazthat/snipinator: Related Projects.

Disclosure: I wrote snipinator.

Not complete, and not necessarily up to date. Make a PR to README.md.jinja, (see realazthat/snipinator/Contributions) to insert/modify the table, and edit this answer.

Project	Stars	Last Update	Language	Platform	Similarity X Obviousness
mdx-js / mdx	16.8k	2024/04/17	JS	N/A	⭐⭐⭐⭐⭐
fletcher / MultiMarkdown-6	599	2023/12/30	C	CLI	⭐⭐⭐⭐⭐
gajus / gitdown	448	2022/03/01	JS	CLI	⭐⭐⭐⭐⭐
gpoore / codebraid	362	2023/10/17	Python	CLI	⭐⭐⭐⭐⭐
amyreese / markdown-pp (archived)	307	2021/09/02	Python	CLI	⭐⭐⭐⭐⭐
zakhenry / embedme	222	2023/11/08	JS	CLI	⭐⭐⭐⭐⭐
DCsunset / pandoc-include	62	2024/04/30	Python	Pandoc / CLI	⭐⭐⭐⭐⭐
BurdetteLamar / markdown_helper	38	2020/03/16	Ruby	CLI	⭐⭐⭐⭐⭐
SimonCropp / MarkdownSnippets	23	2024/04/23	.NET	CLI	⭐⭐⭐⭐⭐
endocode / snippetextractor	4	2014/08/16	C++	CLI	⭐⭐⭐⭐⭐
polywrap / doc-snippets	3	2023/09/26	JS	CLI	⭐⭐⭐⭐⭐
hxtmike / markdown_include	2	2024/05/09	Python	CLI	⭐⭐⭐⭐⭐
JulianCataldo / remark-embed	2	2022/09/22	JS	JS / library	⭐⭐⭐⭐⭐
xrd / oreilly-snippets	2	2015/10/15	Ruby	Ruby / library	⭐⭐⭐⭐⭐
DamonOehlman / injectcode	1	2021/08/01	JS	CLI	⭐⭐⭐⭐⭐
electrovir / markdown-code-example-inserter	1	2024/02/19	JS	CLI	⭐⭐⭐⭐⭐
andersfischernielsen / Simple-Embedded-Markdown-Code-Snippets	1	2021/02/12	JS	CLI	⭐⭐⭐⭐⭐
ildar-shaimordanov / git-markdown-snippet	0	2021/09/14	Perl	CLI	⭐⭐⭐⭐⭐
teyc / markdown-snippet	0	2024/01/22	Powershell	Powershell / function	⭐⭐⭐⭐
marc-bouvier-graveyard / baldir_markdown	0	2020/06/15	Python	CLI	⭐⭐⭐⭐⭐
facelessuser / pymdown-extensions (snippets)	903	2024/05/05	Python	Python / PyMarkdown	⭐⭐⭐⭐
dineshsonachalam / markdown-autodocs	176	2022/09/19	JS	GH Action	⭐⭐⭐⭐
sethen / markdown-include	148	2017/10/26	JS	CLI+config	⭐⭐⭐⭐
cmacmackin / markdown-include	95	2023/02/07	Python	Python / library	⭐⭐⭐⭐
tokusumi / markdown-embed-code	28	2022/01/05	Python	GH Action	⭐⭐⭐⭐
sammndhr / gridsome-remark-embed-snippet	2	2021/06/14	JS	Gridsome	⭐⭐⭐⭐
NativeScript / markdown-snippet-injector	4	2019/01/24	JS	CLI	⭐⭐⭐⭐
fossunited/markdown-macros	0	2021/06/10	Python	Python / Python-Markdown	⭐⭐⭐⭐
fuxingloh / remark-code-import-replace	0	2022/12/21	JS	Remark?	⭐⭐⭐⭐
szkiba / mdcode	15	2014/02/12	Go	CLI	⭐⭐⭐
devincornell/pymddoc	0	2023/12/01	Python	Python	⭐⭐⭐
shiftkey / scribble (docs)	40	2013/08/08	.NET	CLI	⭐⭐
calebpeterson / jest-transformer-test-md	2	2020/08/21	JS	Jest Tests	⭐⭐
tjstankus / commitate	0	2014/05/29	Ruby	CLI	⭐
GitHub Docs: Creating a permanent link to a code snippet	N/A	N/A	N/A	GitHub	⭐
javierfernandes / markdown-exercises	1	2017/05/01	JS	N/A	⭐
gatsby-remark-embed-snippet	N/A (55k)	2024/01/23	JS	Gatsby	⭐
ARMmbed / snippet (docs)	6	2021/08/05	Python	CLI	⭐
drewavis / markdowninclude	1	2024/04/06	JS	VSCode Extension	?
romnn / embedme	0	2024/04/18	Go	N/A	⭐

Answer 2

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

Answer 3

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.

Answer 4

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

Answer 5

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.

Answer 6

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.

Answer 7

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.