Upgrade to Asciidoctor.js 2.2.x

added [Domain] Backend [Type] Feature labels

changed the description

mentioned in merge request !423 (closed)

Getting the Antora tests to all pass with (to me) plausible changes isn't hard :-) The other items on your list... I have no idea.

added [Progress] In Review label

mentioned in issue #347 (closed)

mentioned in merge request !443 (closed)

There's the SyntaxHighlighter extension api in asciidoctor 2. This should be exposed somehow to use via Antora configuration.

mentioned in issue #448 (closed)

marked this issue as related to #402 (closed)

marked this issue as related to #448 (closed)

marked this issue as related to #600 (closed)

Hello! I stumbled across this one after finding that the collapsible feature as of Asciidoctor 2.0.0 is what I was looking for to solve a major requirement. I would have liked to see upgrading to Asciidoctor.js 2.0.x top priority, but it doesnt seem so? Please give me a clue to when I can expect it to happen?

(Looking at https://docs.antora.org/antora/2.3/project/release-schedule/ and https://gitlab.com/antora/antora/-/milestones/20, but I guess I missed something?)

Unfortunately getting the AsciiDoc spec project going and the Asciidoctor doc site upgraded is following the normal schedule of programming projects, the first 95% takes the first 95% of the time, and the remaining 5% takes the remaining 95% of the time. I hope I'm wrong but I doubt Dan will have time to work on Antora soon, and even if he does it's not clear that the Asciidoctor 2 upgrade will be in Antora 3.

However, with ingenuity, you might not need to wait. I haven't personally tried this, but https://docs.asciidoctor.org/asciidoctor/latest/extensions/compound-block-processor/ shows a Ruby extension that implements the collapsible block functionality. It would be easy to write the equivalent in Javascript. I believe this also needs css and possibly js support, which would involve extracting it from the Asciidoctor css and js and adding it to your Antora UI bundle.

If you want to experiment with the possible future of Antora, I have a recent integration of Asciidoctor 2 using pipeline extensions and replaceable pipeline stages (issue 699). This is not officially part of Antora and if you use it is almost certain to require several configuration changes before anything related becomes part of Antora. I haven't looked into the css/js aspects here at all. I think the extension approach is safer at this point but I'll come up with some instructions for this experimental approach if you want.

Apparently (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) it will work without css/js support.

@djencks Please do not comment on my availability. I can speak for myself.

@djencks Also please stop directing people to your fork. This is not helpful for the community.

@erikhag1 There are two main blockers for the upgrade to Asciidoctor 2. The first is that Antora's own docs are incompatible with Asciidoctor 2 and need to be updated. This can be seen by running the docs site with the current version of Antora and comparing them to the version with the open MR applied. There's an assumption about how source blocks are interpreted that we need to correct. The other main blocker is that we need to clearly communicate what changes users need to watch out for that could impact their site, since Asciidoctor 2 brings about some noteworthy syntax changes. This information will be included in the docs and linked from the release notes.

I'm still keeping the possibility open that the Asciidoctor 2 upgrade can happen with the Antora 3 release. If not, it will almost certainly be included in the major version that follows it. Personally, I want to get to Asciidoctor 2 as much as anyone else, so that is definitely driving me to get it done.

Thanks a lot for your prompt and ellaborate responses, Dan and David! I'm eager to see this happen, but of course I understand your issues, I respect your priorities and admire your work:)

Meanwhile, I've established a less than perfect workaround with generating two variants of most documents and xref-ing to the more detailed variant.

(On my side, this is part of a POC where I'm generating Asciidoc/Antora books from Archimate models in the Archi tool, with reference architectures for data sharing in the university sector as showcase. If you're interested, I could tell you more about it and the potential it has as a key component in cross sector co-creation of architecture documentation, counting the Norwegian public sector. Btw. I'm working as an Enterprise Architect at the Norwegian Digitalisation Agency, equipped with rusty programming skills - I just want to make IT happen...)

I'd love to find out more about what you are doing!

mentioned in merge request !619 (merged)

marked this issue as related to #663 (closed)

One thing I forgot to mention is that there was an unresolved performance issue with Asciidoctor.js 2 with Node > 10. I'm happy to report this has now been addressed. See https://blog.yuzutech.fr/blog/node-investigating-performance-regression/index.html for details.

I ran the code with the upgrade against a large Antora site and found that the performance difference is now within a reasonable limit. (On my machine, the time it took to build the site under test went from 3m with Asciidoctor 1.5.x using Node 10 to 3m21s with Asciidoctor 2.2.x using Node 14).

mentioned in merge request !621 (merged)

changed title from Upgrade to Asciidoctor.js 2.0.x to Upgrade to Asciidoctor.js 2.2.x

changed milestone to %v3.0.x

mentioned in commit 325a440f

closed with commit 82c8e14b

closed with merge request !621 (merged)

removed [Progress] In Review label

added [Version] 3.0.0 label

Upgrade to Asciidoctor.js 2.2.x

Child items ...

Activity

Upgrade to Asciidoctor.js 2.2.x

Blocks

Relates to

Activity