Home → Questions →

CLI uility for merging multi-file documents

• Edit

dhein

22 Dec, 2013 10:07 PM

Is there a utility that will produce a merged markdown file from the command line, in the same way that Marked 2 does on the fly?

I'd like to use the <<[filename.md] inclusion syntax and produce a single file to feed into multimarkdown in a script. I could write this myself, but if something is already available I'd like to use it.

Dave Hein

1. Support Staff 1 Posted by Brett on 22 Dec, 2013 11:11 PM

   

   The only other tool that uses that particular syntax is Leanpub, and
   their processor isn't available to the public. You'd have to script your
   own at this point. I do plan to make such features available for
   automation eventually, but it's not top on my list right now.

   You do have the option of using mmd_merge, available with the
   MultiMarkdown distribution. It lets you just create an indented outline:

   file1.md
   file2.md
       chapter.md
       another_chapter.md
   summary.md
   

   However, it doesn't let you include anything except filenames. It
   can't be interspersed with other markup.

   -Brett

   • Edit

2. 2 Posted by dhein on 15 Mar, 2014 06:04 PM

   

   Brett,

   I've created a utilty that does the muiti-file document merge from the command line. It handles all the file includes and "book" flies that Marked 2 does, as well as handling the MultiMarkdown file transclusion syntax. It's written in Python.

   For a python 2 environment, you can install it via:

   pip install --pre MarkdownTools2

   For a python 3 environment, you can install it via:

   pip install --pre MarkdownTools

   The source is on GitHub at https://github.com/JeNeSuisPasDave/MarkdownTools

   I have a "plug" for Marked in the project descriptions. :-)

   NOTE: the '--pre' is required for the install because the version number is 1.0rc1 (a "non-stable" version number). After a suitable period I'll post a stable verion 1.0 and the --pre will not be necessary).

   If you try it, please let me know if there is anything I can do to improve it.

   Dave Hein

   • Edit

3. 3 Posted by dhein on 15 Mar, 2014 06:55 PM

   

   I forgot to make clear that the MarkdownTools package installs a command, "mdmerge". To use it you do something like:

   $ mdmerge inputfile

   or

   $ mdmerge inputfile -o outputfile

   There's a lot more possible than that, "mdmerge --help" will show the possibilities.

   Dave Hein

   • Edit

4. Support Staff 4 Posted by Brett on 15 Mar, 2014 07:26 PM

   

   Awesome, I'll check it out.

   -Brett

   • Edit

5. 5 Posted by dhein on 16 Mar, 2014 11:17 PM

   

   I put up a blog post about this. http://www.freshthought.com/jenesuispasdave/2014/03/working-with-mu...

   And I just noticed I don't handle the raw includes, <<{filename}. Good thing this is just rc1. :-) I'll address that sometime this week.

   • Edit

6. 6 Posted by dhein on 20 Mar, 2014 05:04 AM

   

   OK, I just posted support for raw includes .... so you can do:

   $ mdmerge root-doc.mmd | multimarkdown | mdmerge --just-raw > doc.html

   That is, you can preprocess the markdown files with mdmerge, then run the assembled Markdown through your favorite processor, and the post process the result to include raw files using mdmerge again but with the --just-raw option.

   OK. I'll stop writing about this now. :-)

   Note: beside the raw include support, 1.0rc2 also includes a bug fix for the Python 2 version; there was a problem with non ascii data in read/write operations with stdin/stdout.

   • Edit

7. Support Staff 7 Posted by Brett on 20 Mar, 2014 11:13 AM

   

   Awesome!

   • Edit