docToolchain / docToolchain

a AsciiDoc Toolchain for technical Software Documentation, focused on Software Architecture Documentation
https://doctoolchain.github.io/docToolchain/
MIT License
723 stars 226 forks source link

use the asciidoctor-tabs block switch extension in favor of spring #1357

Open childnode opened 4 months ago

childnode commented 4 months ago

refering to https://github.com/docToolchain/docToolchain/issues/191

to me it looks like, the springboot "Block switch" syntax back from 2019

.Windows
[role='Primary']
--
content
--

.Linux
[role='secondary']
--
content
--

has been superseded by my 2022+ favorite : the https://github.com/asciidoctor/asciidoctor-tabs

[tabs]
======
Windows::
+
====
content
====

Linux:: content.
======

resp.

[tabs]
--
Windows:: content 1
Linux:: content 2
--

unfortunately the first do not harmonize with the syntax in general where blocks do have a style first in the attribute list:

The first positional (unnamed) attribute in the block attribute list is used to declare the block style.

that's correct for [tabs] but inaccurate for [role] formal options

the -- from spring is the "open block" (see also list of block types) and should be used with a style

in advantage, the .\w+\n[role= syntax is correct with block titles

on the other hand, nested tabs on asciidoctor-tabs with surrounding ====== block identifier is uncommon 🤕 but I see that is an bad example only and can be used with any accurate nested block syntax, even they misuse the predefined Example/Admotion delimit ====

Conclusion

SpringBoot asciidoctor extension:

❌ Con:

🤕 HD:

✅ Pro:

asciidoctor-tabs extension:

❌ Con:

🤕 HD:

✅ Pro:

childnode commented 4 months ago

ok, I see this is implemented manually here but not by the spring-asciidoctor-extensions

ok, perhaps I will look forward to contribute a change to make make docToolchain compatible to new syntax, but as least it is not that straight forward because [tabs] is not exposed as role in CSS and can't be processed in JS

image

actual result from docToolchain: image

rdmueller commented 4 months ago

A contribution would be welcome!

Yes I implemented it just in the html theme because I could see a need for the plugin 😁