Jekyll on GitHub Pages: include markdown in another markdown file

Question

I'm using kramdown with Jekyll on GitHub Pages. I have a piece of markdown that I want to use twice, and don't want to maintain two versions of it. How can I include this in other markdown files?

For example, I want to type something like

{: include otherFile.md }

and have the contents of otherFile.md rendered directly where this command is. Note that the parent file is also a markdown file, and not an HTML template.

Additional consideration: it would be great to be able to do this with the default GitHub pages workflow, and not have to use a plugin that is disabled by GH pages and have to push compiled versions of the site manually.

Answer 1

The way to go seems to be include_relative. I found this answer by user geraldb on the old Jekyll forums:

Yes, there's a simple way. It works "out-of-the-box" in Jekyll (and GitHub Pages). Just tried it. See the Vienna.html test page e.g.:

---
layout: default
---

some text here

{% include_relative test_header.md %}

some more text here

{% include_relative test_footer.md %}

See the source -> test.md and the live page.

The "trick" if you want to call it so - is to use include_relative if you want to have the building block texts (e.g. intro.md, explanation.md, conclusion.md, etc.) along with your page (in the same folder). Cheers. Happy Jekylling.

---

Since I've first written this answer, the original forum post seems to be completely gone and I haven't found it archived on archive.org. The answer link on the old forum was this (now points to an unrelated post), and the profile of geraldb in the new forum is here.

The first link in the quoted answer has been updated to point to the correct file in the repo as it exists today,¹ and the second link is dead but left unchanged as I'm quoting the original author here.

---

¹Thanks to Ben Leggiero for finding it!

Answer 2

For me, the problem couldn't be solved with importing by include_relative and using the normal include does not render the included Markdown files.

But capturing the include and then piping it through markdownify is a pretty good workaround:

{% capture my_include %}{% include a_markdown_file.md %}{% endcapture %}
{{ my_include | markdownify }}

I found this in GH:/jekyll/jekyll#1303 (comment). That's a feature request for avoiding the capturing. It's closed, unfortunately.

Answer 3

There's a Ruby gem markdown_helper that supports include files.