Is there a way to create a `README.md` file for GitHub that compiles from other `.md` files?

Question

Is there a way to create a README.md file for GitHub that compiles from other .md files? For instance, let's say I have three files: repo/1.md, repo/2.md, and repo/3.md. I want to combine the files in this order to create repo/README.md.

This SO question gives some help, but it's more than 2 years old and I'm thinking (hoping) there might be new ideas out there now. One answer suggests using Pandoc to compile .md files into outputting to html:

pandoc *.md > markdown_book.html

I tried this with my files. My .md files take the form:

# Page 1
testing

Once in repo/, I ran:

pandoc *.md > README.html

which created:

<h1 id="page-1">Page 1</h1>
<p>testing # Page 2 testing # Page 3 testing</p>

This is not looking right, but I went ahead and ran the following to get back to a .md file:

pandoc -o README.md README.html

which produced:

Page 1
======

testing \# Page 2 testing \# Page 3 testing

I expected:

# Page 1
testing

# Page 2 
testing

# Page 3
testing

So to wrap up:

1. Is Pandoc the best tool for the job, or is there an easier approach to combining .md files together? The Marked app has syntax for including external files, <<[path/file], but I don't think there is an option to "export" the compiled document to .md.

2. If not, what is the right way to do this with Pandoc? I'd like to combine markdown files without having to go to another format first.

Answer 1

Pandoc 1.11.1 works for me on Ubuntu, going straight from Markdown to Markdown, although it converts # headings into underlined headings:

pandoc -o README.md 1.md 2.md 3.md

Make sure your files include a final newline in each of your source files; omitting this is the only way that I was able to reproduce your error.