docs: new nav structure

[TomCools]

A new nav structure with subheadings has been implemented.
This adjusts the nav.adoc file to make use of that.

[Copilot]

🟡 Changes recommended

The updated nav.adoc contains invalid/incorrect list and link syntax (missing *, incorrect nesting levels, and malformed external link attribute lists) that will likely break or misrender the documentation navigation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the Antora documentation navigation (nav.adoc) to use the new grouped nav structure with subheadings and reorganized sections.

Changes:

• Introduces titled nav groups (for example, “Getting started”, “Domain modeling”) and restructures list nesting.
• Adds new “Upgrading Timefold Solver” entries (including release notes) and an “Additional resources” group.
• Reorders existing sections to fit the new hierarchy.

File summaries

File	Description
docs/src/modules/ROOT/nav.adoc	Reworks the Antora nav structure to use group headings and updated link organization.

Review details

Suppressed comments (5)

docs/src/modules/ROOT/nav.adoc:48

• The '.Deploying to the Timefold Platform' section starts its items at ** level without a parent *, which breaks the nav list structure; change these items to * level.

.Deploying to the Timefold Platform
** xref:deploying-to-platform/introduction.adoc[Overview]
** xref:deploying-to-platform/guide.adoc[Guide]
** xref:deploying-to-platform/model-metadata.adoc[leveloffset=+1]
** xref:deploying-to-platform/metrics.adoc[leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:63

• The '.Responding to change' section starts its items at ** level without a parent *, which breaks the nav list structure; change these items to * level.

.Responding to change
** xref:responding-to-change/continuous-planning.adoc[leveloffset=+1]
** xref:responding-to-change/real-time-planning.adoc[leveloffset=+1]
** xref:responding-to-change/non-disruptive-replanning.adoc[leveloffset=+1]
** xref:responding-to-change/recommendation-api.adoc[leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:67

• The '.Example use cases' section starts its items at ** level without a parent *, which breaks the nav list structure; change these items to * level.

.Example use cases
** xref:quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc[Vehicle routing (guide)]
** https://github.com/TimefoldAI/timefold-quickstarts[More examples on GitHub^]

docs/src/modules/ROOT/nav.adoc:83

• The '.Commercial editions' section starts its items at ** level without a parent *, which breaks the nav list structure; change these entries to * level.

.Commercial editions
** xref:commercial-editions/commercial-editions.adoc[Overview]
** xref:commercial-editions/installation.adoc[Installation]
** xref:commercial-editions/performance-improvements.adoc[leveloffset=+1]
** xref:constraints-and-score/understanding-the-score.adoc[Score analysis]

docs/src/modules/ROOT/nav.adoc:54

• The '.Optimization algorithms' section uses **/*** nesting without a top-level * parent item, which will mis-nest or invalidate the nav list; shift the first level to * and nest subitems under it.

.Optimization algorithms
** xref:optimization-algorithms/overview.adoc[Overview]
** xref:optimization-algorithms/construction-heuristics.adoc[leveloffset=+1]
** xref:optimization-algorithms/local-search.adoc[leveloffset=+1]
** xref:optimization-algorithms/exhaustive-search.adoc[leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The updated nav file includes syntax that likely prevents the Introduction item from showing and may render stray [leveloffset=+1] text for external links.

Review details

Suppressed comments (2)

docs/src/modules/ROOT/nav.adoc:73

• The external links use a double-bracket syntax (...[Text][leveloffset=+1]) that AsciiDoc will treat as stray text and can break or pollute the rendered nav.

* https://github.com/TimefoldAI/timefold-solver/releases[New and noteworthy][leveloffset=+1]
* xref:upgrading-timefold-solver/overview.adoc[leveloffset=+1]
* xref:upgrading-timefold-solver/upgrade-from-v1.adoc[leveloffset=+1]
* https://docs.timefold.ai/timefold-solver/1.x/upgrading-timefold-solver/upgrade-from-optaplanner[Upgrading from OptaPlanner][leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:1

• The introduction entry is no longer a list item, which likely prevents it from appearing in the Antora navigation.

xref:introduction.adoc[leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The nav includes external links with two bracketed attribute lists (e.g. ...[Label][leveloffset=+1]), which is invalid AsciiDoc macro syntax and may render incorrectly in the sidebar.

Review details

Suppressed comments (2)

docs/src/modules/ROOT/nav.adoc:70

• These external-link nav entries use two bracketed attribute lists, but AsciiDoc link macros accept only a single attribute list so the trailing "[leveloffset=+1]" will likely render as literal text or be ignored.

* https://github.com/TimefoldAI/timefold-solver/releases[New and noteworthy][leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:73

• This external-link nav entry uses two bracketed attribute lists, but AsciiDoc link macros accept only a single attribute list so the trailing "[leveloffset=+1]" will likely render as literal text or be ignored.

* https://docs.timefold.ai/timefold-solver/1.x/upgrading-timefold-solver/upgrade-from-optaplanner[Upgrading from OptaPlanner][leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

There is an invalid external-link syntax in the navigation file that may render incorrectly or break nav parsing.

Review details

Suppressed comments (1)

docs/src/modules/ROOT/nav.adoc:70

• The navigation entry uses an invalid external-link syntax (...[text][leveloffset=+1]), which will likely render [leveloffset=+1] literally or break Antora nav parsing.

* https://github.com/TimefoldAI/timefold-solver/releases[New and noteworthy][leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[triceo]

Although I like the concept overall, the current results a bit less:

• The menu is too long vertically, requiring too much scrolling to figure out what even is the contents of the documentation.
• Several sections (such as "Commercial Editions") have IMO far too many chapters.
• Some sections (such as "Deploying to Platform") should have been part of other sections. (In this case, I'd make it part of "As a service".)

I wonder if the sections should be foldable and folded by default. That would solve pretty much everything I list here.