3

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.

Community
  • 1
  • 1
Eric Green
  • 6,401
  • 11
  • 41
  • 82

1 Answers1

3

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.

Chris
  • 93,263
  • 50
  • 204
  • 189
  • thanks, @Chris. i'm using 1.12.3 on OSX mavericks. i modified my files to fit your example, but i get different results. `First heading ============= Some content. \# Second heading More content \#\# Second-level headline Content.` – Eric Green Jan 17 '14 at 04:27
  • 1
    @EricGreen, playing with this some more, I was able to reproduce your error by omitting the final newline that my text editor automatically inserts. Try adding a trailing newline to your source files. – Chris Jan 17 '14 at 09:32
  • That's helpful, @Chris. I was able to get it to work with your suggestion. It appears that my [real case](https://github.com/ericpgreen/MCH/tree/master/syllabus) is a bit harder. Outputting to `.md` and `.pdf` looks bad. I might need to compare my markdown syntax to Pandoc's markdown syntax. – Eric Green Jan 17 '14 at 18:23
  • @EricGreen, I built a PDF from your source code. Your HTML tables in `6-format.md` and `9-schedule.md` should probably be converted to something supported by Pandoc, like for instance the tables in `1-introduction.md` (which renders well). Other than that, I don't see any problems. Do you have other complaints? – Chris Jan 17 '14 at 20:49
  • it seems like the table in 6 renders nicely in the compiled `.md`, but not the `pdf`. conversely, the table in 1 renders nicely in the `pdf` but not the `md`. none of the tables looks right in both formats. based on these [guidelines](http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html) the pipe tables should be fine. and i thought the html tables would be ok too because markdown allows html. – Eric Green Jan 18 '14 at 01:05
  • @EricGreen, raw HTML can work *when generating HTML*, because the processor can pass it through untouched. When converting to PDF, though, Pandoc needs to "understand" the table to convert it to LaTeX (on its way to PDF). That's why HTML tables don't work for PDF. – Chris Jan 18 '14 at 13:42