Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/neooblaster/mdmerge
Node.js tool to make a complete Markdown document from other files with a dedicated include instruction
https://github.com/neooblaster/mdmerge
Last synced: 6 days ago
JSON representation
Node.js tool to make a complete Markdown document from other files with a dedicated include instruction
- Host: GitHub
- URL: https://github.com/neooblaster/mdmerge
- Owner: neooblaster
- Created: 2019-06-28T12:32:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-11-01T00:54:13.000Z (about 4 years ago)
- Last Synced: 2024-12-09T19:59:33.125Z (about 1 month ago)
- Language: JavaScript
- Size: 153 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# mdmerge
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.
## Getting Start
### The Command Line Interface
The simpliest command line to merge your **Markdown** is ``mdmerge .md``.
By default, the command line creates a new file nammed ``.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 .md .md`` : The merged document from
``.md`` will be place in the output file `.md`
2. ``mdmerge .md .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 .md -w``
### Implicit Options
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.
#### Implicit Option ``1``
The first **implicit** option stands for the file to merge. It's is equal
to the option ``-i``, `--in`.
#### Implicit Option ``2``
The second **implicit** option stands for the output file. It's is equal
to the option ``-o``, `--out`.
### Command Line Options
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.
#### Option ``-i``, `--in` : Input file
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`.
#### Option ``-o``, `--out` : Output file
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.
#### Option ``-w``, `--write` : Overwrite
The option ``-w`` (`--write`) allows you to directly
**overwrite** the input file with the result.
* It does not requires a value.
#### Option ``-c``, `--clear` : Clear
The option ``-c`` (`--clear`) allows you to remove
merged content between tags.
* It does not requires a value.
### The Instruction
The detailed instruction hereafter must be placed at the begin of the line
in a comment block in your Markdown file : ``[]()``
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 `` :
The element separator is the colon char (`:`)
* `` = `@import>[..:][:[]]`
* `` : This is the relative path to the file used for this inclusion.
* `:` : You can insert none to many of the inclusion instruction separated by `:`.
* `[,][,]`
* `` : You can specified the line to toggle the inclusion.
* `` : You can specified from which char you want to begin the inclusion on the line.
* `` : You can specified when you stop the inclusion on the line
* `:` : You can ask to `mdmerge` to insert your content in a Markdown code block
in a specified language. You can omit `` to let your favorite render to identify
automatically the language (Example with **Highligh.js**)
The `` 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 `` is **odd**, the last
inclusion process will inclusion until the **EOF** is met.
Please find an example of instruction :
````markdown
[](@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
[](#import>bin/mdmerge.js:53:79:js)
````js
/**
* 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;
}
````
[](#importtest/incl.md | Include the whole content of file `incl.md` in folder `test` | DONE |
| @import>test/incl.md: | Include the whole content of file `incl.md` in folder `test` in a code block | DONE |
| @import>test/incl.md:js | Include the whole content of file `incl.md` in folder `test` in a code block JavaScript `js` | DONE |
| @import>test/incl.md:53 | Include the content of file `incl.md` from line `53` to the end of file `EOF` | DONE |
| @import>test/incl.md:53: | Include the content of file `incl.md` from line `53` to the end of file `EOF` in a code block | DONE |
| @import>test/incl.md:53:js | Include the content of file `incl.md` from line `53` to the end of file `EOF` in a code block JavaScript `js` | DONE |
| @import>test/incl.md::79 | Include the content of file `incl.md` from the beginning to the line `79` | DONE |
| @import>test/incl.md::79: | Include the content of file `incl.md` from the beginning to the line `79` in a code block | DONE |
| @import>test/incl.md::79:js | Include the content of file `incl.md` from the beginning to the line `79` in a code block JavaScript `js` | DONE |
| @import>test/incl.md:53:79 | Include the content of file `incl.md` from line `53` to the line `79` | DONE |
| @import>test/incl.md:53:79: | Include the content of file `incl.md` from line `53` to the line `79` in a code block | DONE |
| @import>test/incl.md:53:79:js | Include the content of file `incl.md` from line `53` to the line `79` in a code block JavaScript `js` | DONE |
| @import>test/incl.md:53,1 | Include the content of file `incl.md` from line `53`, starting at position `1` to the end of file `EOF` | DONE |
| @import>test/incl.md:53,1: | Include the content of file `incl.md` from line `53`, starting at position `1` to the end of file `EOF` in a code block | DONE |
| @import>test/incl.md:53,1:js | Include the content of file `incl.md` from line `53`, starting at position `1` to the end of file `EOF` in a code block Javascript `js` | DONE |
| @import>test/incl.md:53,,1 | Include the line number `53` from the file `incl.md`, starting at position `0` to position `1` | DONE |
| @import>test/incl.md:53,,1: | Include the line number `53` from the file `incl.md`, starting at position `0` to position `1` in a code block | DONE |
| @import>test/incl.md:53,,1:js | Include the line number `53` from the file `incl.md`, starting at position `0` to position `1` in a code block Javascript `js` | DONE |
| @import>test/incl.md:53,2,4 | Include the line number `53` from the file `incl.md`, starting at position `02` to position `4` | DONE |
| @import>test/incl.md:53,2,4: | Include the line number `53` from the file `incl.md`, starting at position `02` to position `4` in a code block | DONE |
| @import>test/incl.md:53,2,4:js | Include the line number `53` from the file `incl.md`, starting at position `02` to position `4` in a code block Javascript `js` | DONE |
| @import>test/incl.md:53:79:526 | Include the content of file `incl.md` from line `53` to the line `79`, and from line `526` to the end of line `EOF` | DONE |
| @import>test/incl.md:53:79:526: | Include the content of file `incl.md` from line `53` to the line `79`, and from line `526` to the end of line `EOF` in a code block | DONE |
| @import>test/incl.md:53:79:526:js | Include the content of file `incl.md` from line `53` to the line `79`, and from line `526` to the end of line `EOF` in a code block JavaScript `js` | DONE |
**Their is some cases not listed here which are functional and some other ideas which are not implemented yet**