<commit_before>:navigation: asciidocgenerator/User Docs/Readme
:toc:

= asciidocgenerator

asciidocgenerator is a webapplication which can convert and publish asciidoc files in html and pdf. This application also provides integratoin for GitLab webhooks.

== Building

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.

== Running

The *.war file should be deployable on every Java EE 7 Web-Profile compliant app server (look into the link:https://github.com/konradrenner/asciidocgenerator/blob/master/asciidocgenerator-web/src/main/resources/project-defaults.yml[project-defaults.yml] file for required configurations of the server). Be aware that the link:https://github.com/asciidoctor/asciidoctorj[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.

=== Initial Keycloak setup

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. Users which should be able to open the settings of the asciidocgenerator app must have the role "admin".

=== Properties

The following table displays properties which can be set at application start (if you want to overrule the defaults) via the -D argument:

[cols="3*", options="header"] 
|===
|Property
|Default
|Description

|asciidocgenerator.token
|none
|Token for authentication at a GitLab server

|asciidocgenerator.baseDirectory
|~/.asciidocgenerator/files
|Location of generated files
|===

== Using

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 also define diagrams in your asciidoc files (e.g. plantuml) and the app will render it. Be aware that if you want asciidocgenerator to render also diagrams, graphviz must be installed on the system.

=== The user interface
<commit_msg>added config options section for wildfly swarm<commit_after>:navigation: asciidocgenerator/User Docs/Readme
:toc:

= asciidocgenerator

asciidocgenerator is a webapplication which can convert and publish asciidoc files in html and pdf. This application also provides integratoin for GitLab webhooks.

== Building

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.

== Running

The *.war file should be deployable on every Java EE 7 Web-Profile compliant app server (look into the link:https://github.com/konradrenner/asciidocgenerator/blob/master/asciidocgenerator-web/src/main/resources/project-defaults.yml[project-defaults.yml] file for required configurations of the server). Be aware that the link:https://github.com/asciidoctor/asciidoctorj[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.

=== Initial Keycloak setup

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. Users which should be able to open the settings of the asciidocgenerator app must have the role "admin".

=== Properties

The following table displays properties which can be set at application start (if you want to overrule the defaults) via the -D argument:

[cols="3*", options="header"] 
|===
|Property
|Default
|Description

|asciidocgenerator.token
|none
|Token for authentication at a GitLab server

|asciidocgenerator.baseDirectory
|~/.asciidocgenerator/files
|Location of generated files
|===

=== WildFly Swarm configuration

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:

- link:https://reference.wildfly-swarm.io/configuration.html[Configuration of a WildFly Swarm Application]
- link:http://wildfly-swarm.io/tutorial/step-4/[Environment specific configuration]
- link:https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/v/2016.9/configuration/project_stages.html[Project Stages]
- link:https://github.com/wildfly-swarm/wildfly-swarm-examples[WildFly Swarm Examples]

== Using

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 also define diagrams in your asciidoc files (e.g. plantuml) and the app will render it. Be aware that if you want asciidocgenerator to render also diagrams, graphviz must be installed on the system.

=== The user interface

{'fraction_non_alphanumeric': 0.07381267460667548, 'fraction_numerical': 0.002646669607410675, 'mean_word_length': 4.99295154185022, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 9, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4569901', 'n_tokens_mistral': 1909, 'n_tokens_neox': 1857, 'n_words': 852}