How to dynamically hide asciidoc element

Question

I use org.asciidoctor.convert plugin for gradle to generate API documentation for my team. I include files:

include::{snippets}/index/curl-request.adoc[] 

and want to place it's content into spoiler or anything like that. Is there any way to somehow hide dynamicaly asciidoc elements? I try to use

pass:[<details open>  
include::{snippets}/index/curl-request.adoc[]
</details>]

but it is not processed include inside it. Any ideas will be higly appreciated. Without hiding snippets my documentation have almost unlimited scrol :). If no such way with ascii doc, suggestions of other documentation formats, where i can include files content and place it into the spoiler is also appreciated.

Endophyte

Are you adding the includes into a block, like a source block? If you are you can add roles to the resultant element then style / use javascript to do the rest. – Hodge

Answer 1

As Guillaume Grossetie has mentioned here

Using passthrough to include raw HTML is not recommended because now your document is tightly coupled with the output.

and it is deprecated. The new syntax for collapsible/foldable sections is

.some description
[%collapsible]
====
this
is
going
to be
folded
====

Inductile

Answer 2

As this was so helpful for me - I added here the solution from Robin's comment.

No CSS and Javascript needed!

Here is an example:

+++ <details><summary> +++
Check `reference.conf`:
+++ </summary><div> +++
----
play {
  http {
    secret.key = asdf
    secret.key = ${?SECRET_KEY}
    ...
  }
  ...
}
----
+++ </div></details> +++

This creates a collapsed element:

..and this expanded image:

Update

As Foad's answer looks more elegant, I tried his proposed solution for a ReDoc Markup with no success.

Meaning

This is not rendered on Github – Inductile

This works almost fine on vscode except it doesn't show the syntax highlighting properly. Atom editor has a far better layout and syntax highlighting but has issues with this feature plus it takes ages to render! All in all thanks a lot :) – Inductile

@Foad Unless I'm misunderstanding your comment, it appears that Github implemented the functionality sometime between when you wrote that and now. FYI for anyone else who happens by here. – Mcdonough

Answer 3

This is a late answer but maybe it will help you/others. The following asciidoc features are the key for implementing dynamic showing/hiding of blocks:

If your output is only HTML then you can embed any HTML in the document using

++++ any HTML contents ++++

This includes

• <style> tags containing custom CSS classes
• custom HTML tags for show/hide functionality like <input type="checkbox" />
• <script> tags containing Javascript code to hide/show some blocks, e.g. by adding event listeners to checkboxes.

As @LightGuard has already mentioned, role attributes are converted to CSS class references. E.g.

[source,role="someCssClass"]
----
...
----

is converted to something like

<div class="someCssClass">
</div>

So you can reference this CSS class from Javascript code and implement show/hide by modifying the display CSS attribute.

For a simple example implementation see https://raw.githubusercontent.com/NorbertSandor/jsinterop.xyz/master/jsinterop-project/jsinterop-website/src/main/asciidoc/index.asciidoc (near the top of the file).

Soudan

This was very useful! I actually used this to wrap lengthy snippets includeed from other files - see below - note it seems three pluses +++ not four is what you need: +++ <details><summary> +++ Some long text summarised +++ </summary><div> +++ include::snippets/some-long-text.adoc[] +++ </div></details> +++ – Ultimately

@Ultimately I was trying your suggestion and the wrap works, but the include is displayed as "include...", not rendered to the snippet. – Windsor

@Windsor I'm not sure why that would be, but it sounds like a parse error. You can see examples of my suggestion here: raw.githubusercontent.com/UKHomeOffice/lev-api-docs/master/… - and the end result (after having been parsed in HTML with ASCIIdoctor) here: lev-api-dev.notprod.homeoffice.gov.uk/docs/… – Ultimately

@Ultimately I must have missed something on my first try, because I tried again the next day and now it works :) – Windsor