= Building Docs and Website

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

The Apache Causeway website and documentation are written in link:https://asciidoctor.org/[Asciidoc], using link:https://antora.org/[Antora] as a static website generator.

== Prerequisites:

The prerequisites to install are:

* Node LTS (link:https://nodejs.org/[])
+
[source,bash]
----
sudo apt install nodejs
sudo apt install npm
----

* Antora (link:https://www.npmjs.com/package/@antora/cli[@antora/cli] & link:https://www.npmjs.com/package/@antora/site-generator-default[@antora/site-generator-default]), and Kroki (link:https://www.npmjs.com/package/asciidoctor-kroki[asciidoctor-kroki]) for diagramming support:
+
[source,bash]
----
npm i -g @antora/cli@^3.1.1 @antora/site-generator-default@^3.1.1 asciidoctor-kroki
----
+
See the link:https://docs.antora.org/antora/2.3/install/install-antora/[Antora docs] for details.

* Serve (link:https://www.npmjs.com/package/serve[serve]) for previewing:
+
[source,bash]
----
npm i -g serve@^13.0.2
----

We also generate some Asciidoc files dynamically from other source code.
This requires:

* link:https://groovy.apache.org/download.html[Groovy 2.x]
+
eg, using link:https://sdkman.io/install[sdkman]:
+
[source,bash]
----
sdk install groovy 2.5.15
----

* link:https://pandoc.org/installing.html[pandoc]
+
[source,bash]
----
sudo apt install pandoc
----

* dos2unix
+
[source,bash]
----
sudo apt install dos2unix
----


== Authoring

To create/update documentation, we strongly recommend:

* IntelliJ link:https://plugins.jetbrains.com/plugin/7391-asciidoc[Asciidoc plugin]
* IntelliJ link:https://plugins.jetbrains.com/plugin/15635-diagrams-net-integration[Diagrams.net plugin]

Even if you don't use IntelliJ as your primary IDE, it's worth using it for writing documentation - there's currently nothing as good as the Asciidoc plugin on any other editor platform, especially when it comes to writing Antora.


== Build

The `preview.sh` script can be used to build the website, also calling the documentation tooling that automates documentation from code (the xref:core:_overview:about.adoc[System Overview], large parts of the xref:refguide::about.adoc[Reference Guide] and the xref:refguide:config:about.adoc[Configuration Guide]).

Use `preview.sh -h` to view options.
The lower case flags skip steps, while the upper case flags exclude all steps except those indicated:

* `preview.sh`
+
builds everything and serves up the site

* `preview.sh -AS`
+
runs only Antora generation and serves up the site

* `preview.sh -ekcdl`
+
does the same thing, by skipping the other 5 steps.

The script can be found at the root of this git repo.




