Skip to main content

Unomi 3 · Documentation

Unomi 3 manual: diagrams, theme, and depth

PlantUML in AsciiDoc, a brand-aligned HTML/PDF look, and chapters that finally match the Unomi 3 platform.

Shipping Unomi 3 without a manual that looks and reads like Unomi 3 would leave operators guessing. Over several UNOMI-882 and UNOMI-960 efforts, the project rebuilt how the official manual is authored, rendered, and navigated — from diagram toolchain to CSS theme to whole new chapters.

AsciiDoc PlantUML source builds into a branded Unomi 3 manual with diagrams

PlantUML (and GraphViz) in the build

#753 wired AsciiDoctor Diagram into manual/pom.xml: asciidoctorj-diagram + PlantUML, with GraphViz available via GRAPHVIZ_DOT / graphvizdot. CI installs GraphViz so HTML and PDF builds stay reproducible.

Diagrams live in the AsciiDoc as [plantuml] blocks — reviewable in pull requests, regenerated on every docs build, no orphaned PNGs in git. Tip today has on the order of 62 PlantUML diagrams across ~24 chapters (architecture C4, sequences, upgrade flows, condition evaluation, scheduler, past-event strategies, and more).

[plantuml]
----
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
Container(unomi, "Apache Unomi")
Component(restApi, "REST API", "JAX-RS")
@enduml
----

Local tip: install GraphViz (brew install graphviz / apt-get install graphviz), then cd manual && mvn -ntp clean install. build.sh also checks for dot.

Branded HTML & PDF theme

A later slice of #821 (UNOMI-960) replaced the default AsciiDoctor chrome with an Unomi-branded stylesheet that tracks unomi.apache.org:

  • Design tokens — --unomi-primary (#6d5ce7), accent purple, Inter typography
  • Site nav & footer via docinfo, version badge, hero cover for the HTML book
  • Responsive UX — burger nav + bottom TOC sheet under 1024px; desktop sidebar TOC from 1024px
  • PDF — dedicated unomi-theme.yml under manual/src/theme/ with matching brand assets

Reading the published manual should feel continuous with the project website, not like a separate default book skin.

Content that matches Unomi 3

#783 synced the book to Apache Unomi 3.x and expanded (or heavily refreshed) material that operators actually need:

  • Platform story — architecture, security, configuration, clustering, data structures
  • 3.1 product — multi-tenancy, task scheduler, OpenSearch notes, condition validation / evaluation, property types
  • Migrations — 2.x→3.0, 3.0→3.1, ES7→ES9, Elasticsearch→OpenSearch, V2 compatibility mode, script authoring
  • Platform upgrades — dedicated upgrades/ runbooks (Java, Karaf, Elasticsearch, Log4j, CXF/Jackson/Jetty, dependency hygiene, ITs)
  • Day-to-day APIs — request examples (including explain/tracing), GraphQL, shell commands, JavaScript tracker guide, recipes
  • Reference depth — conditions guide and builtin type catalogs (UNOMI-960), past-event conditions, profile tracking

“What’s new” for 3.1 now points readers straight into these chapters instead of leaving gaps between release notes and the old 2.x-shaped manual.

How to add a diagram

  1. Edit the relevant .adoc under manual/src/main/asciidoc/
  2. Add a [plantuml] (or GraphViz) block next to the prose it illustrates
  3. Build the manual module (GraphViz required for some diagrams)
  4. Review the generated PNG in the PR like any other source change

Website promotional diagrams stay animated SVG / Mermaid on unomi.apache.org; the manual sticks to PlantUML→PNG so AsciiDoctor HTML/PDF stay self-contained.

Open the latest manual What’s new in 3.1 Browse AsciiDoc on GitHub

← All posts