asciidocgenerator is a webapplication which can convert and publish asciidoc files into html and pdf. This application also provides integratoin for GitLab webhooks. Note that the asciidoc files must be UTF-8 encoded!
Just clone this repository, go into the asciidocgenerator-web folder and type "mvn package". After the build has completed, you will find a *.war file and a *.jar file in the target folder.
The *.war file should be deployable on every Java EE 7 Web-Profile compliant app server (look into the project-defaults.yml file for required configurations of the server). Be aware that the asciidoctorj libs must be available in the system classloader of the appserver!
But we strongly recommend running the "fat jar" (asciidocgenerator-swar.jar), just with "java -jar" command. This will boot a WildFly Swarm instance with everything needed. If you start the app the first time, you have to create a realm in the provided Keycloak instance.
Before the first start, just open "[URL]:[PORT]/auth" (e.g. localhost:8080/auth) in a browser. First you have to create a Keycloak admin user. After this, create a new realm like described here: https://dzone.com/articles/securing-wildfly-swarm-apps-with-keycloak
The Realm name and resource has to be "asciidocgenerator". If you use this convention, the existing keycloak.json must not be changed (if you want to use your own keycloak.json, specify the proper Wildfly Swarm system property ). Users which should be able to open the settings of the asciidocgenerator app must have the role "admin".
The following table displays properties which can be set at application start (if you want to overrule the defaults) via the -D argument:
| Property | Default | Description |
|---|---|---|
none |
Token for authentication at a GitLab server |
|
asciidocgenerator.baseDirectory |
~/.asciidocgenerator/files |
Location of generated files |
If you use the "fat jar" you can use all properties of WildFly Swarm to configure it. Please visit the following sites for full details:
The only thing you need to define in your asciidoc files, so that they will be converted and published, is the :navigation: header field. The value after the :navigation: field must be in the following form "groupname/mainnavigation/sidenavigation".
Example: :navigation: Group/Example/Simple adoc
Example if you want a folder in the sidenavigation: :navigation: Group/Example/Folder/Nav Point
If you want to attach one or more tags to an article, just include the :keywords: header field. The following example attaches two tags to the file ("work" and "very important").
Example: :keywords: work, very important
asciidocgenerator also comes with the asciidoctorj-diagram plugin, so it is possible to embed diagrams in your asciidoc files (e.g. plantuml) and the app will render it. Be aware that it is possible, that you need graphviz installed on the system, if you want asciidocgenerator to render diagrams (plantuml for examples supports generation via jdot, so that there is no graphviz necessary ⇒ have a look at this file to see how to turn on plantuml generation via jdot).
The user interface consists of the main navigation, the side navigation and the asciidoc content. The left part of the main navigation displays the "group", right from the seperator there is the navigation part and the right part of the main navigation are action buttons (article details, generate pdf, tags, settings). Every entry, except the action buttons, is configured via the :navigation: header field of the asciidoc-document.
The asciidocgenerator webapp provides integration for GitLab webhooks. You just have to provide the asciidocgenerator.token-Property and configure a webhook for the "Tag Push Hook". The webhook must be configured to send a POST Request to the following URL: http://[URL]:[PORT]/api/v1/generator/gitlabtagpushed
It is also possible to generate html and pdf files from adoc files which are stored on the local file system. Just have a look at the "localfolder_generation_template.json" and "post_localfoldercontent" files to get an idea how to convert and publish local files. On Linux/Unix systems you can use the "post_localfoldercontent"-script out of the box, just type "./post_localfoldercontent --help" to see how it works (if you don’t specify any options, the asciidoc-examples folder of this repository wil be tried to upload to a local running asciidocgenerator instance).