Blog Posts BPMN DMN

OptaPlanner documentation turns over a new leaf

Blog: Drools & jBPM Blog


For years, OptaPlanner has been offering the documentation in two formats:
single-page HTML and PDF.
This now changes with the launch a new documentation website, built using Antora.

What’s so exciting about the new documentation?

First and foremost, it loads instantly as opposed to the old single-page HTML documentation.
For example, if I want to read about repeated planning,
I open the single-page HTML docs and wait nearly half a minute for the page to load, despite having a very good cable connection.
With the new documentation, it took me only 2 seconds as each chapter has its own HTML page and thus
the content that has to be loaded is limited.

This also means it’s now easier to effectively share links to a particular section.

Second, now you can search through the entire docs:

Search in the docs

The search box at the top of the page shows suggestions as soon as you start typing. Each suggestion consists of
the chapter and a link to where the search term occurs.

Third, if you spot a discrepancy in the documentation and would like to improve it, contributing was never easier:

Edit the docs

Finally, this new documentation website is much friendlier to search engines, which should make it show up in Google search results more often than before.

Building the documentation website

The documentation sources remain in
the optaplanner-docs module in the optaplanner repository,
but the website assembly, named optaplanner-website-docs, became a part of the optaplanner-website:

optaplanner-website directory structure

Similarly to the entire optaplanner-website, the optaplanner-website-docs is built using Maven. The Maven module
acts as a wrapper over Antora, which generates the static site from AsciiDoc sources.

There are two Antora playbooks referring to documentation sources. The first one, used by default, is antora-playbook.yml
that refers to the latest OptaPlanner release.

  edit_url: '{web_url}/edit/main/{path}'
    - url:
      # Updates with every release to point to the latest release branch.
      branches: [8.12.x]
      start_path: optaplanner-docs/src

To render the latest documentation:

  1. cd optaplanner-website/optaplanner-website-docs
  2. mvn clean package
  3. Open the index.html located in target/website/docs in your browser.

The second Antora playbook, antora-playbook-author.yml, is activated by the author maven profile and
refers to the current optaplanner local Git repository HEAD.

  edit_url: '{web_url}/edit/main/{path}'
    # Assuming the optaplanner local repository resides next to the optaplanner-website.
    - url: ../../optaplanner
      branches: [HEAD]
      start_path: optaplanner-docs/src

To preview local changes in the documentation:

  1. Make sure the optaplanner and optaplanner-website Git repositories are located in the same directory or change the local URL accordingly.
  2. cd optaplanner-website/optaplanner-website-docs
  3. mvn clean package -Pauthor
  4. Open the index.html located in target/website/docs in your browser.

Supported documentation formats

Introducing new formats does not have to result in abandoning the old ones, and in our case it does not.
While I encourage everyone to visit the new documentation website, the existing formats continue to be published with
every release as before.

Also, should you need to have a look at a particular version of the documentation,
it’s still at your hand in the archive.


Since the 8.12.0.Final release, there is a new documentation website available under
The documentation is now structured into pages by chapters and searchable. The single-page HTML and PDF documentation
remains available for every release.


The post OptaPlanner documentation turns over a new leaf appeared first on KIE Community.

Leave a Comment

Get the BPI Web Feed

Using the HTML code below, you can display this Business Process Incubator page content with the current filter and sorting inside your web site for FREE.

Copy/Paste this code in your website html code:

<iframe src="" frameborder="0" scrolling="auto" width="100%" height="700">

Customizing your BPI Web Feed

You can click on the Get the BPI Web Feed link on any of our page to create the best possible feed for your site. Here are a few tips to customize your BPI Web Feed.

Customizing the Content Filter
On any page, you can add filter criteria using the MORE FILTERS interface:

Customizing the Content Filter

Customizing the Content Sorting
Clicking on the sorting options will also change the way your BPI Web Feed will be ordered on your site:

Get the BPI Web Feed

Some integration examples