Support Antora

[Skeeve]

Yesterday, 2021-08-22 I learned about Antora at FrOSCon 2021. It was presented by the developer of the IntelliJ Asciidoctor Plugin.

While I'm not yet using Asciidoctor, I only learned about it a day ago ;), It sounds quite promising and useful, what he presented. Unfortunately there is no recording available yet.

Features

workspace

• support non-git workspace when Antora support is enabled #695

antora.yml

• detect antora.yml files in the workspace and ask user if they want to enable Antora support

site-manifest.json

• allow to configure a path to a site-manifest.json file
• read and parse the site-manifest.json file to provide autocompletion on pages (xref, include, link...)

Preview

• include AsciiDoc attributes defined in the antora.yml in the preview #691
• resolve image resource IDs in the preview
• resolve include resource IDs in the preview
• resolve xref resource IDs in the preview

Navigate

• support "Go to" (cmd+click) on image resource IDs (for instance, image:2.0@cli:commands:seaswell.png[]) #692
• support "Go to" (cmd+click) on xref resource IDs (for instance, xref:module:filename.adoc[])
• support "Go to" (cmd+click) on include resource IDs (for instance, include::include::ROOT:partial$treeline-warning.adoc[])

Auto-completion

• add images auto-completion when Antora is enabled #693
  • images within the same module
  • images from other modules
  • images from other components
• add includes auto-completion in this order
  • attachments within the same module
  • attachments from other modules
  • attachments from other components
• add xref auto-completion in this order
  • pages within the same module
  • pages from other modules
  • pages from other components

Suggestions/actions

• transform a resource ID to a fully qualified ID (for instance, from image:seaswell.png[] to image:2.0@cli:commands:seaswell.png[])
• suggest to simplify a resource ID (for instance, from image:2.0@cli:commands:seaswell.png to image:seaswell.png[] if the image is referenced in the same component/module/version)

[aisbergde]

Antora support in the IntelliJ Asciidoctor Plugin is excellent and was the only reason for me to install and use IntelliJ.

But my main editor is VSC and of course I would like to do also much more in VSC when working with asciidoc files.

Another point is: It is very easy to install VSC also without admin rights and the asciidoctor-vscode plugin even works in Azure Data Studio. And it is always allowed to install Azure Data Studio in my projects, because it is installed together with SSMS (SQL Server Management Studio). So normally I find ways to install and use this VSC Plugin, but it is much harder to be allowed to install and use IntelliJ.

[Skeeve]

The recording: https://media.ccc.de/v/froscon2021-2656-online-dokumentation_fur_nutzer_mit_asciidoc_und_antora

German only :(

[danyill]

It would be good to have a list of capabilities that mean "supporting Antora" so that we can progress them. I'm beginning to use Antora on a project and would like some of these capabilities also.

We have quite a lot of issues requesting support now (#230, #358, #380 and #409). Perhaps we can use this issue to scope out some requirements.

What are the most important things? From the current issues it seems to be:

• Processing a resource id in images, pages (xrefs and links)
• Being able to link to a production site?
• Do we need to be able to reference a playbook file and have vs-code open other folders/workspaces for different components?

How do achieve this concretely?

• Do we re-implement Antora functions (resource id processing might be something we can just "pull in"?) or do we effectively bundle Antora into this extension?
• Do we use our own UI or wait until Antora 3 and use extensions to gain the content and perhaps reduce the level of processing used (we probably don't need to build a full UI -- or do we ).

I don't speak German... I also haven't used the IntelliJ tool -- however there is a good feature list on the extension docs which is probably where we should start:

https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/antora.html

[anb0s]

I'm investigating the AsciiDoc with Antora as alternative solution to Markdown with MkDocs for middle and big architecture documentation projects (many products, components, branches etc.). I'm also investigating the issues with relative image rendering (PlantUML, Vega etc.), completion support for xrefs and others in VSCode.

@Skeeve the video above now encouraged me to continue investigating the issues and help with reporting, testing and may be resolving them...

@danyill in the Q&A session from the video the maintainer (Alexander Schwartz) of IntelliJ AsciiDoc plugin is talking about sharing knowledge and support (chat, online meeting etc.) if similar features are needed in VSCode and somebody wants to implement them :)

Lets start with the feature list and known issues...

[ggrossetie]

It would be good to have a list of capabilities that mean "supporting Antora" so that we can progress them. I'm beginning to use Antora on a project and would like some of these capabilities also.

💯
That would be extremely useful!
Maybe @ahus1 can help us since the IntelliJ plugin has an excellent support for Antora.

I've created a similar issue on the browser extension: asciidoctor/asciidoctor-browser-extension#299.

I guess the first would be to detect that we are in an Antora module (probably locating the antora.yml file). If that's the case, then we should use a specific logic to resolve external resources (images, partials, examples...).

[ahus1]

Hi @Mogztter - thanks for summoning me.

I am happy to support in answering questions like "How did you..." and "Why did you...", also "What did you do before/after...". Pick my brain :-)

Regarding the video: I pre-recorded the same talk in English for DevConf.US and also FOSDEM, see https://www.youtube.com/watch?v=MG-sajf2PP4 for details. As it was pre-recorded, there is no Q&A at the end. DevConf.US published a recording that included the Q&A as well, see https://www.youtube.com/watch?v=LT0a--DNJhI (but the quality of the pre-recorded part is not as good there).

Regarding features: I learned when implementing it for the IntelliJ plugin that the functionality can be grown incrementally. Users will provide feedback on early functionality. Ideally there is fast feedback (think earth-sky as described by the ZertoMQ community). For the IntelliJ plugin, @danhaywood picked "sky", shared his needs, did a lot of tests and provided valuable input that steered development.

Adding to @Mogztter's thoughts: recognizing that an AsciiDoc file is part of a component by locating an antora.yml file is definitely the first step. What could be next is to set some attributes for the preview like :icons: font (for nicer admonitions) as Antora does this by default, and setting the imagesdir to the module's folder so that images show up in the preview.

Functionality could then be added bit by bit: Picking up attributes from the component descriptor, settings more Antora attributes, picking up page names for xrefs, etc.

For the IntelliJ plugin I decided to imitate Antora's behavior by re-implementing some of the behavior, for example resolving includes and xrefs. I can show where I hooked into Asciidoctor to inject the necessary functionality.

When growing functionality, some features targeted the editor for auto-completion and inspections, others targeted the preview.
For a start, it was supporting only references within the same component. Only later I added functionality to resolve cross-component references.

This week and next I'll have only time to comment on issues. From Sep 27 onwards I'm happy to join a synchronous communication (video call, etc.)

[LukeCz]

Hi, it would be great to include 2 features from Antora to this plugin: extended syntax for include and image macros, basically ability to specify module.

[MLNW]

Native support for Antora would be a great addition to this plugin!

[apupier]

some Antora support has been provided with this PR #580
it is not part of a released version (yet).
I do not know the features that are covered.
@marieflorescontact Could you provide some information on it?

[marieflorescontact]

For now the extension detects the antora.yml file and offers the user to activate the Antora support (#580).

I am currently working on the following features:

• Resoving Antora Ids for the following macros: image, video, xref (include seems a little bit more complicated 🤔)
• Drop into editor using this api to create a macro depending on the file type. (Use the drop into editor API (VS Code 1.70) #624)

[aisbergde]

When is a preview version planned? I would like to test this Antora feature.