Support editor tooling and preview
One of the barriers to adoption for Antora is tooling to use the
xref in editors and tools and a robust preview/live reload.
Issues are being filed for this in the editors now and without guidance it's a challenge to provide an implementation at this stage:
This issue could serve as a common place to discuss approaches and what is needed to support in Antora in editors and what features would be useful.
Needed, in rough order of importance:
- Supporting the include macro.
- Ability to use a file picker for a local file and have it "translated" to page ID coordinates
- Ability to lint/check hyperlinks, references and partial references.
- Ability to generate a preview of a particular page by running the antora command
- Ability to generate navigation through pick lists or a simple command (e.g. which generates a list of pages in the right format).
- Ability to generate "standardised scaffolding" (see #348 and #498).
Perhaps the first question, is "How does an extension know this is an Antora project?". And it's not straightforward. It seems that extensions need to know where the playbook is so the Antora command can be run. Unlike the component descriptor, the playbook is not well defined and commonly might be:
antora-playbook.yml. Because this is arbitrary within Antora this makes things more difficult.
So perhaps this has to be a configured path. It would be helpful if for the "simple case" of a single repo which contained the playbook and a component we had a defined structure so that could be supported "out of the box" (just open it in an editor and you're done).
I guess once the extension has found or identified the playbook it needs to run the Antora command and process the output in some fashion. I think here there are a few gaps currently in Antora to make the extension work simpler:
- Export of the content catalog (e.g. as JSON). This should allow resolution of includes. Or perhaps a custom "site generator"?
- Incremental Antora builds and perhaps a dependency graph (so a preview can be generated promptly). Should a preview be just the "local file" with all Asciidoc syntax functioning or should it be a full site view?
- Alternatively having the ability to run Antora to just generate a "single output file" relating to the "single input file" the user is currently editing.
Some of the approach in Antora for the filesystem is still in flux (#28, #27 (closed), #316, #358) and some kind of LiveReload or preview might be better than trying to generate an "in-editor" preview for Antora (see #329), partly to ease integration with the UI.
Some additional guidance, perhaps in the form of an ADR may help close this gap.
(Not sure whether this issue belongs here or perhaps in antora.org).