Merge branch 'refs/heads/main' into fork/max-requests-caffeine

# Conflicts:
#	solr/CHANGES.txt

dev-docs/ref-guide/asciidoc-syntax.adoc

@@ -503,90 +503,88 @@ This means that if we want an entire section of content to be given a specific r
 
 TIP: For more on Roles in Asciidoctor, see https://docs.asciidoctor.org/asciidoc/latest/attributes/roles/[Role Attribute] in the Asciidoctor User Guide.
 
-=== Creating Tabbed Sections
-Hopefully a little bit of background on roles is helpful to understanding the rest of what we'll do to create a tabbed section in a page.
-
-See the Bootstrap docs on https://getbootstrap.com/docs/4.1/components/navs/#tabs[nav tabs] for details on how to use tabs and pills with Bootstrap.
-As a quick overview, tabs in Bootstrap are defined like this:
-
-[source,html]
-----
-<ul class="nav nav-pills"> <--1-->
-  <li class="active"><a data-toggle="pill" href="#sec1">Section 1</a></li>
-  <li><a data-toggle="pill" href="#sect2">Section 2</a></li>
-</ul>
-
-<div class="tab-content"> <--2-->
-  <div id="sect1" class="tab-pane active"> <--3-->
-    <h3>Section 1</h3>
-    <p>Some content.</p>
-  </div>
-  <div id="sect2" class="tab-pane">
-    <h3>Section 2</h3>
-    <p>Some other content.</p>
-  </div>
-</div>
-----
-<1> This section creates an unordered list with a line item for each tab.
-The `data-toggle` and `class` parameters are what tell Bootstrap how to render the content.
-<2> Note the class defined here: `<div class="tab-content">`.
-This defines that what follows is the content that will make up the panes of our tabs.
-We will need to define these in our document.
-<3> In our document, we need to delineate the separate sections of content that will make up each pane.
-
-We have created some custom JavaScript that will do part of the above for us if we assign the proper roles to the blocks of content that we want to appear in the tab panes.
-To do this, we can use Asciidoctor's block delimiters to define the tabbed content, and the content between the tab.
-
-. Define an "open block" (an unformatted content block), and give it the role `.dynamic-tabs`.
-An open block is defined by two hyphens on a line before the content that goes in the block, and two hyphens on a line after the content to end the block.
-We give a block a role by adding a period before the role name, like this:
+== Tabbed Sections
+Tabbed sections are supported via https://github.com/asciidoctor/asciidoctor-tabs[`@asciidoctor/tabs`].
+
+There are different ways to display tabbed sections via the asciidoctor tabs extension, but most of the time only the format of an example is needed.
+This format wraps each tab content into an example block.
+
+=== Referencing
+
+By providing an ID to the `[tabs]` block like below, you can control the ID used for referencing the tabbed section.
+An ID is also generated for each tab by aggregating the normalized tab label to the end of the `[tabs]` ID.
+This allows a direct referencing of a specific tab, even if it is not currently selected.
+
+=== Tab Synchronization
+
+The IDs are also used for synchronizing the tab selection across the entire page.
+This synchronization requires the tab labels to be named the same, so that the generated ID is correctly recognized.
+To enable this feature, add `:tabs-sync-option:` below the page title.
+
+[source,asciidoc]
+----
+= Page Title
+:tab-sync-option:
+...
+----
+
+It is also possible to group tabbed sections to sync only a set of tabs, or disable the syncing entirely.
+See the https://github.com/asciidoctor/asciidoctor-tabs?tab=readme-ov-file#syntax[@asciidoctor/tabs syntax] fore more information.
+
+=== Tabs Example
+
+. Define a tabs block and give it an optional ID.
 +
-[source,text]
+[source,asciidoc]
 ----
-[.dynamic-tabs]
---
-The stuff we'll put in the tabs will go here.
---
+[tabs#tab-section-id]
 ----
 
-. Next we need to define the content for the tabs between the open block delimiters.
-.. We enclose each tab pane in another type of block, and "example" block.
-This allows us to include any kind of content in the block and be sure all of the various types of elements (heading, text, examples, etc.) are included in the pane.
-.. We give the example block another role, `tab-pane`, and we must make sure that each pane has a unique ID.
-We assign IDs with a hash mark (\#) followed by the ID value (`#sect1`).
-.. We also need to define a label for each tab.
-We do this by adding another role, `tab-label` to the content we want to appear as the name of the tab.
-.. In the end one pane will look like this:
+. Next, we add an example block to wrap the tab's content with an outline. This is used for improved readability.
 +
-[source,text]
+[source,asciidoc]
 ----
-[example.tab-pane#sect1] <--1-->
-==== <--2-->
-[.tab-label]*Section 1*  <--3-->
-My content...
-====
+[tabs#tab-section-id]
+======
+
+======
 ----
-<1> When we define the example block with `[example]`, it's followed by `.tab-pane#sect1` as the class (each class separated by a period `.`) and the ID defined in the tab definition earlier.
-Those will become the classes (`class="tab-pane active"`) and ID (`id="sect1"`) in the resulting HTML.
-<2> Example blocks are delimited by 4 equal signs (`====`) before and after the enclosed content.
-<3> The words "Section 1" will appear in the HTML page as the label for this tab.
 
-.. Create `[example.tab-pane#id]` sections for each tab, until you finally end up with something that looks like this:
+. Inside the example block, we can add our tabs. Each tab label is suffixed with `::` and the tab's content is wrapped inside a listing block.
 +
-[source,text]
+[source,asciidoc]
 ----
-[.dynamic-tabs]
---
-[example.tab-pane#sect1]
+Tab 1::
++
 ====
-[.tab-label]*Section 1*
-My content...
+The first tab's content.
 ====
 
-[example.tab-pane#sect2]
+Tab 2::
++
 ====
-[.tab-label]*Section 2*
-My content...
+The second tab's content.
 ====
---
 ----
+
+The final result will look something like this:
+
+[source,asciidoc]
+----
+[tabs#tab-section-id]
+======
+Tab 1::
++
+====
+The first tab's content.
+====
+
+Tab 2::
++
+====
+The second tab's content.
+====
+======
+----
+
+The tab section can be referenced via `#tab-section-id`, and each tab can be referenced via `#tab-section-id-tab-1` and `#tab-section-id-tab-2` accordingly.

solr/CHANGES.txt

@@ -148,6 +148,8 @@ Improvements
 
 * SOLR-17346: Synchronise stopwords from snowball with those in Lucene (Alastair Porter via Houston Putman)
 
+* SOLR-16198: Introduce tabbed sections again in the Ref Guide.  (Christos Malliaridis via Eric Pugh)
+
 * SOLR-17160: Core Admin "async" request status tracking is no longer capped at 100; it's 10k.
   Statuses are now removed 5 minutes after the read of a completed/failed status.  Helps collection
   async backup/restore and other operations scale to 100+ shards.  (Pierre Salagnac, David Smiley)

solr/solr-ref-guide/build.gradle

@@ -62,6 +62,7 @@ ext {
     antoraVersion = "3.1.4"
     antoraLunrExtensionVersion = "1.0.0-alpha.8"
     asciidoctorMathjaxVersion = "0.0.9"
+    asciidoctorTabsVersion = "1.0.0-beta.6"
     linkCheckerVersion = "1.4.2"
     gulpCliVersion = "2.3.0"
     // Most recent commit as of 2022-06-24, this repo does not have tags
@@ -246,6 +247,14 @@ task downloadAsciidoctorMathjaxExtension(type: NpmTask) {
     outputs.dir("${project.ext.nodeProjectDir}/node_modules/@djencks/asciidoctor-mathjax")
 }
 
+task downloadAsciidoctorTabsExtension(type: NpmTask) {
+    group = 'Build Dependency Download'
+    args = ["install", "-D", "@asciidoctor/tabs@${project.ext.asciidoctorTabsVersion}"]
+
+    inputs.property("asciidoctor-tabs version", project.ext.asciidoctorTabsVersion)
+    outputs.dir("${project.ext.nodeProjectDir}/node_modules/@asciidoctor/tabs")
+}
+
 task downloadAntora {
     group = 'Build Dependency Download'
     description "Download all Antora build dependencies for site generation."
@@ -254,6 +263,7 @@ task downloadAntora {
     dependsOn tasks.downloadAntoraSiteGenerator
     dependsOn tasks.downloadAntoraLunrExtension
     dependsOn tasks.downloadAsciidoctorMathjaxExtension
+    dependsOn tasks.downloadAsciidoctorTabsExtension
 }
 
 task downloadLinkValidator(type: NpmTask) {

solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc

@@ -1,5 +1,6 @@
 = Collections API
 :page-show-toc: false
+:tabs-sync-option:
 // 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
@@ -46,11 +47,11 @@ However, there is a limit of 10,000 on the number of async call responses stored
 
 *Input*
 
-[.dynamic-tabs]
---
-[example.tab-pane#v1asyncexample]
+[tabs#asyncexample]
+======
+V1 API::
++
 ====
-[.tab-label]*V1 API*
 
 [source,bash]
 ----
@@ -59,10 +60,9 @@ http://localhost:8983/solr/admin/collections?action=SPLITSHARD&collection=collec
 ----
 ====
 
-[example.tab-pane#v2asyncexample]
+V2 API::
++
 ====
-[.tab-label]*V2 API*
-
 [source,bash]
 ----
 curl -X POST http://localhost:8983/api/collections/collection1/shards -H 'Content-Type: application/json' -d '
@@ -75,7 +75,7 @@ curl -X POST http://localhost:8983/api/collections/collection1/shards -H 'Conten
 '
 ----
 ====
---
+======
 
 
 [source,text]
@@ -101,29 +101,26 @@ curl -X POST http://localhost:8983/api/collections/collection1/shards -H 'Conten
 Request the status and response of an already submitted <<Asynchronous Calls,Asynchronous Collection API>> (below) call.
 This call is also used to clear up the stored statuses.
 
-[.dynamic-tabs]
---
-[example.tab-pane#v1asyncrequeststatus]
+[tabs#asyncrequeststatus]
+======
+V1 API::
++
 ====
-[.tab-label]*V1 API*
-
 [source,bash]
 ----
 http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1000
 
 ----
 ====
-
-[example.tab-pane#v2asyncrequeststatus]
+V2 API::
++
 ====
-[.tab-label]*V2 API*
-
 [source,bash]
 ----
 curl -X GET http://localhost:8983/api/cluster/command-status/1000
 ----
 ====
---
+======
 
 === REQUESTSTATUS Parameters
 
@@ -190,23 +187,21 @@ http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1004
 
 Deletes the stored response of an already failed or completed <<Asynchronous Calls,Asynchronous Collection API>> call.
 
-[.dynamic-tabs]
---
-[example.tab-pane#v1asyncdeletestatus]
+[tabs#asyncdeletestatus]
+======
+V1 API::
++
 ====
-[.tab-label]*V1 API*
-
 [source,bash]
 ----
 http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=1000
 
 ----
 ====
 
-[example.tab-pane#v2asyncdeletestatus]
+V2 API::
++
 ====
-[.tab-label]*V2 API*
-
 Delete a single request response:
 [source,bash]
 ----
@@ -219,7 +214,7 @@ Flush out all stored completed and failed async request responses:
 curl -X DELETE http://localhost:8983/api/cluster/command-status?flush=true
 ----
 ====
---
+======
 
 === DELETESTATUS Parameters