Add support for collapsible sections

[jrodewig]

To improve our breaking changes documentation, the Elasticsearch writers would like to use collapsible sections in our HTML output.

As of writing, it doesn't appear this is supported. I've documented my attempts to implement collapsible sections below.

Option 1: Use the Asciidoctor[%collapsible] block

I first tried to use the [%collapsible] block added in Asciidoctor 2.0:

[%collapsible]
.Details
====
Content to collapse.
====

However, our docs build uses Asciidoctor 1.5 which doesn't support this block type.

Option 2: Use an html passthrough

I then tried to use passthrough blocks to use HTML details and summary tags.

++++
<details><summary>
Details
</summary><div>
++++

Content to collapse.

++++
</div></details> 
++++

However, docbook doesn't allow us to pass these HTML elements on directly. After looking at the docbook DTD, I don't believe any collapsible elements are supported.

[jrodewig]

Adding the #team-discuss label as I want to gauge interest in this feature and see if anyone has other workarounds.

[gchaps]

@jrodewig +1 for collapsible sections. In Kibana, we can use them for breaking changes, and also for examples.

[bmorelli25]

APM doesn't have a specific use case, but it's a welcome enhancement.

[alaudazzi]

@jrodewig I have been using collapsible sections (also called "Zippies") in my previous job. It's a great solution to enhance navigation and discoverability in general. It would be nice to see it implemented in our doc. Happy to contribute!

[jrodewig]

Since @nik9000 migrated our docbooks to direct HTML (thanks again Nik!), we can now use the html passthrough method (option 2).

Here's a proof of concept I worked up using a section of the Elasticsearch 8.0 breaking changes:

• Preview: http://collapsible-sections.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/breaking-changes-8.0.html#_indices_created_before_7_0
• Source: https://github.com/elastic/elasticsearch/compare/master..jrodewig:collapsible-sections

[nik9000]

I think collapsible would be nicer though! I can probably make that work.

[benskelker]

Thanks @jrodewig - I tried playing with. The details tag is not supported in MS IE/Edge.

[jrodewig]

@benskelker Good to know. It looks like there are several polyfills for IE/Edge, but none of those are easily implemented via HTML itself. It seems like implementing this through Asciidoctor is preferable.

[nik9000]

It turns out that Asciidoctor just uses <details> and <summary> anyway. But I'll open a PR in a few minutes to add support for it via the native asciidoctor syntax. And docs. And a polyfill to (hopefully) get it working in IE.