I developed mdmerge for my own usage. I was tired to update my main README.md file when it contains some codes (all or part of) from an existing file.

When the source file change, your README.md must be manually updated.

So I create my own Node.js application to update my README.md which using other files thanks to a custom instruction which is invisible in the rendered document (also in PDF document).

Currently, the application is not fully finished but the main feature are finished.

The simpliest command line to merge your Markdown is mdmerge <FILE>.md. By default, the command line creates a new file nammed <FILE>.merged.md. I choose to do this to prevent breaks on the source file.

The command line have two implicits options :

• The first one will stands for the input file to merge.
• The second one will stands for the output file to put the result.

Examples with implicits options :

1. mdmerge <INPUT_FILE>.md <OUTPUT_FILE>.md : The merged document from <INPUT_FILE>.md will be place in the output file <OUTPUT_FILE>.md
2. mdmerge <INPUT_FILE>.md <INPUT_FILE>.md : Done like this, you will overwrite your source file with the result.

The second case 2. can be simply with the following command : mdmerge <FILE>.md -w

This application allows implicits options. Implicits options are the values which not begins with a hyphen char (-). They are determined with their position behind the command (mdmerge).

On the following example mdmerge -c README.md README.final.md, the first implicit option is README.md and the second is README.final.md.

Implicits options priority is lesser than Explicits ones.

The first implicit option stands for the file to merge. It's is equal to the option -i, --in.

The second implicit option stands for the output file. It's is equal to the option -o, --out.

Please find below the detail of each options for the command mdmerge.

Be warned : Explicit options have the priority on the implicit ones.

Be warned : The long options have the priority on the short ones. For instance, if you use at the same time options -i=file_1 and --in=file_2, this is the file file_2 which will be processed.

The option -i (--in) allows you to specified the input file to merged.

• It requires a value.
• The input must be a file which exists.
• It equal to the implicit options 1.

The option -o (--out) allows you to specified the target file in which the result will be placed.

• It requires a value.
• The output must be a file. If the file not exists, it will be created.
• It equal to the implicit options 2.

This option will have no effect if option -w (--write) is used.

The option -w (--write) allows you to directly overwrite the input file with the result.

• It does not requires a value.

The option -c (--clear) allows you to remove merged content between tags.

• It does not requires a value.

The detailed instruction hereafter must be placed at the begin of the line in a comment block in your Markdown file : [](<instruction>)

Once parsed by mdmerge, a closing instruction has been inserted. That will allows the application to update the included parts.

Please find below, the generic form of the instruction <instruction> :

The element separator is the colon char (:)

• <instruction> = @import><pathToFile>[..:<inclusionInstruction>][:[<codeBlockLanguage>]]
  • <pathToFile> : This is the relative path to the file used for this inclusion.
  • :<inclusionInstruction> : You can insert none to many of the inclusion instruction separated by :.
• <inclusionInstruction = <line>[,<startOffset>][,<endOffset>]
  • <line> : You can specified the line to toggle the inclusion.
  • <startOffset> : You can specified from which char you want to begin the inclusion on the line.
  • <endOffset> : You can specified when you stop the inclusion on the line
• :<codeBlockLanguage> : You can ask to mdmerge to insert your content in a Markdown code block in a specified language. You can omit <codeBlockLanguage> to let your favorite render to identify automatically the language (Example with Highligh.js)

The <inclusionInstruction> toggle the inclusion.

The generic rule is the odds elements will start the inclusion whereas the evens will stop the inclusion. When the total number of <inclusionInstruction> is odd, the last inclusion process will inclusion until the EOF is met.

Please find an example of instruction :

 [](@import>bin/mdmerge.js:53:79:js)

The instruction can be read as "Please, include here the JavaScript code from file mdmerge.js, from line 53 to line 79 in a code block js".

The result is the following

/**
 * Afficher un message dans le stream.
 *
 * @param message Message à afficher
 * @param level   Niveau de message. 0=OK,1=KO,2=WARN
 */
function log(message, level = 0, args = []){
	// 0 = Success
	// 1 = Error
	// 2 = Warn
	let levels = [
		{color: "Green", name: "SUCCESS", return: 0},
		{color: "Red", name: "ERROR", return: 1},
		{color: "Yellow", name: "WARNING", return: 0},
	];
	
	console.log(
		"[ " +
		colors.fg[levels[level].color] +
		levels[level].name +
		colors.Reset +
		" ] : " +
		message
	);

	return levels[level].return;
}

Please find below an exhaustiv list of usage cases and their development status

Their is some cases not listed here which are functional and some other ideas which are not implemented yet