doc_preprocessing

This library helps the markdown writers by adding invisible commands in markdown.
Have the possibility to "include" and "ref" any markdown part with invisible commands.

This package can be added in the current project by adding "@4dsas/doc_preprocessing": "^1.0.5" in the package.json
It adds special command to help writing markdown
All commands will disappear during the preprocess.

Reference and Include

The commands "Reference" and "Include" enables to duplicate markdown

$3

The command is ``REF`. It is used as:

`
content
`

with:

* _nameOfReference_: is the name of the reference it should be unique
* _content_: is any content you wish it includes break lines.

Example:

`


Title


Ref1
`

The preprocess will remove all commands

Before:
`


Title


Ref1 TEST
Ref2


Ref3

`

After:
`


Title

Ref1 TEST
Ref2

Ref3
`

A reference is generally paired with an include

$3

The command is `INCLUDE` . It is used as:

`

`

with:

* _nameOfReference_: is the name of the reference created by @REF@

Before:
`


Title


Ref1 TEST
Ref2


BEFORE TEST INCLUDE
Ref3

`
After:
`

Title

Ref1 TEST
Ref2

Ref3
BEFORE Ref1 TEST INCLUDE
`


The reference and include does not have a location restriction, it will work with any markdown file.




How it works?

A first pass will find all the `REFERENCE` and store them.
A reference is stored with it's ID, the file path. But also the start and end index.

A second pass will replace all the `INCLUDE` by its reference if found.
Moreover all the markdown comments will be cleaned up if they are not recognised.

A log message is displayed for any error found.

The program will only search inside ".md" or ".mdx" files, the other files are untouched or copied to the new destination depending on their last modification date.

The watch system works the same way but if a REF is changed all files including this REF will be altered.




Settings


List of arguments available:

- path: where the folder to process is located [obligatory]
- output: the folder to output all processed files [optional]
- config: add other Ref from a file [optional]
- syntax: output folder to write a formated JSON of REF [optional]
- build_dependencies: folder to build dependencies [optional]
- watch: watch a folder and all changes will be repercuted to the output folder [optional]
- settings: settings file to load must be a valid JSON [optional]
- settings_type: load a specific section [optional]
- args_dependencies: set arguments to be used by the dependencies [optional]
- list_args: Object used to pass values between dependencies. Ex {"language": "en"} in the dependency all %language% will eb replaced by "en" [optional]
- exclude_list: Excludes a list of folder [optional]

A dependency can be loaded via git
`json
"dependencies":[
{
"name":"orda",
"branch":"main",
"url":"git:https://github.com/doc4d/orda.git"
}
`
or can be loaded in local:
`json
"dependencies":[
{
"name":"orda",
"url":"file:../../orda/"
}
`

If a file namaed .doc_preprocessing.json exists it will be loaded. The section default is taken first, can be overloaded by the other sections if selected.


`json
{
"default":
{
"path":"../docs/",
"config":"../docs/preprocessing.conf",
"output":"",
"syntax":"",
"build_dependencies":".doc_preprocessing_build/",
"dependencies":[
{
"name":"orda2",
"url":"git:https://github.com/doc4d/orda.git",
"branch": "main"
}
]
},
"build": {
"output":"../docs/"
},
"build_translate": {
"path":"translated_docs/*",
"output":"translated_docs/",
"args_dependencies":{
"settings_type": "translation"
}
},
"start_watch" : {
"watch":true,
"output":"../docsPostProcessed/"
},
"syntax4D": {
"path":"../docs/API/",
"syntax":"./syntax/4D/"
},
"syntax4D_translate": {
"path":"translated_docs/*/API/",
"args_dependencies":{
"settings_type": "translation"
},
"syntax":"./syntax/4D/"
},
"syntaxViewPro": {
"path":"../docs/ViewPro/",
"syntax":"./syntax/ViewPro/",
"config":""
},
"syntaxViewPro_translate": {
"path":"translated_docs/*/ViewPro/",
"syntax":"./syntax/ViewPro/",
"config":"",
"args_dependencies":{
"settings_type": "translation"
}
}
}
`

$3

doc_preprocess --settings-type='syntax_4d' loads default and syntax_4d. Can be overloaded by adding arguments.

doc_preprocess --settings-type='syntax_4d' --path=../../docs` will change the path of docs