====== Create embedded documentation based on markdown files ======

With GroIMP 2.1.4 it is possible to use a markdown file to generate the content of the embedded documentation of a GroIMP plugin. The idea is that the README.md file of a git repository is then doubly used. Yet since the pipeline depends on pandoc, it is in theory also possible to use a [[https://pandoc.org/chunkedhtml-demo/3.1-general-options.html|large number of other import formats]] including docx,odt or latex.


===== Requirements =====

To use this pipeline it is required that pandoc is installed, and that the project contains the files
template.docbook and copyfilter.lua in the directory ''src/main/resources/doc''. Both files can be found in the [[https://gitlab.com/grogra/groimp-template/newplugin-maven|maven template]].


===== Enabling/ disabling the pipeline =====

By default this pipeline is disabled, since parts of GroIMP contain docbook based documentation. To enable it for a certain plugin the maven property "maven.assembly.generate.docbook" must be defined in the pom.xml. The value can be any of the phases of the main pom.xml

<code xml>
<properties>
   [...]
   <maven.assembly.generate.docbook>generate-resources</maven.assembly.generate.docbook>
</properties>
</code>

To disable this pipeline the same property must be deleted or set to "None"



===== Selecting a source =====

The source of the pipeline is by default "README.md" (caution it is case sensitive), if the source is suppose to be any different file it can be defined in the "MarkdownDocFile" option:

<code xml>
<properties>
   [...]
   <maven.assembly.generate.docbook>generate-resources</maven.assembly.generate.docbook>
   <MarkdownDocFile>embedded.md</MarkdownDocFile>
</properties>
</code>
At this position it would also be possible to set other formats e.g.: ''MarkdownDocFile>docu.odt</MarkdownDocFile>''
Moreover it is possilbe to set several files (only markdown) as a parameter, this files then will be concatenated and process as one and create one docbook file:  ''<MarkdownDocFile>README.md docu.md extra.md</MarkdownDocFile>''  


===== Markdown Syntax (GroIMP flavored Markdown) =====

The markdown flavor used here is the one of pandoc with only a very few additions:


==== Images ====

To ensure that images included in the file are shown in the readme.md on Git as well as in the embedded documentation, all images must be saved in the ''src/main/resources/doc/res'' directory. 

To scale an image in size please use:''[Label](scr/main/resources/doc/res/image.png){ height=75px }''
The content of [Lable] is then in the documentation used as the the label of the image.


==== In GroIMP references ====

If the documentation is about a certain panel, option or example, it is possible to create a hyperlink in GroIMP that shows this resource. This works based on the 'command:' link feature of the GroIMP webview. 

To ensure that this links do no weirdly show up on the Readme in the git the following syntax can be used. 

<code>
*panels/explorers/graphobjects*
*examples:graphexplorer/GraphObjectRef*
*preferences:graphExplorer/subGraph*
</code>

This will, on git, only show the paths in italic. For GroIMP it will be preprocessed to create the links to the commands to present the requested resource. 


==== Tables ====

to add a table the the following syntax can be used:

<code>
| header 1 | header 2 | header 3 |
| ---      | ---      | ---      |
| cell 1   | cell 2   | cell 3   |
| cell 4 | cell 5 is longer | cell d |
| cell 7   |          | cell 9   |

</code>


==== Defining the title ====

By default the title of the chapter of documentation is the name of the plugin in the maven pom. 
This name can be change by adding the variable "ftitle" to the first markdown file:

<code>
---
ftitle: GroIMP user manual
...

</code>