Open inter-document cross references from the preview

[jmini]

It would be great if the Preview tab was able to open inter-document cross references links (using the xhref: notation or the double angled bracket notation <<..>>) in the same way than the “Asciidoctor.js Live Preview” is doing it in Chrome.

I have tried to set outfilesuffix to .adoc as described in 27.6.1. Navigating Between Source Files, but this is not enough, because this does not seems to be supported by VSCode.

A solution would be to create links using the vscode scheme:

This is an xref <a href="vscode://file/<absolute-file-path>">link</a> 

But I am not sure if the HTML backend supports this kind of customization.

[Scosh]

hi. no idea if this issue is still of interest to anyone … i feel like an entitled minority of a minority even complaining about this right now, but i encountered the same issue today and also tried to pass ifdef::env-name[:relfilesuffix: .adoc] to no avail.

my workaround right now (which is imperfect in many way) is to go against what the asciidoc documentation keeps insisting on in the Link Macro chapter and to use this macro syntax for .adoc files.

example screenshots

asciidoc markup left; vscode preview right:

the links in the vscode preview to the right-hand side can be clicked and the preview will switch to the contents of the clicked file. this does not open the source markup for the file:

problems

• not the method officially recommended and supported by asciidoc
• i don’t believe this method supports cross referencing specific sections of an .adoc file — but i haven’t done rigorous testing
• having to use the link:pass[][] syntax for files with spaces in their filename is significantly more clunky and verbose than the officially recommended xref (my text filenames usually do contain spaces)
• i don’t know how portable this is
• it would be really cool if this plugin also added the option to open the source markup of a clicked filelink from the preview (e.g. by mapping this function to the middle mouse button and adding it as a right-click option, if the vscode api allows this)

[ggrossetie]

also tried to pass ifdef::env-name[:relfilesuffix: .adoc] to no avail.

You should replace env-name by env-vscode (otherwise it won't have any effect). Having said that, it will still not work because we need to add data-href on xref links, similar to what we are doing for links:

https://github.com/asciidoctor/asciidoctor-vscode/blob/e15256254407d508aca84c3d6553d81d002f0ddc/src/asciidoctorWebViewConverter.ts#L43

Otherwise, the "click links" logic is not working as expected:

https://github.com/asciidoctor/asciidoctor-vscode/blob/52b1dabfd76c11e127ce0c7d7fa103309fc73050/preview-src/index.ts#L124-L155

my workaround right now (which is imperfect in many way) is to go against what the asciidoc documentation keeps insisting on in the Link Macro chapter and to use this macro syntax for .adoc files.

You shouldn't change the syntax of your AsciiDoc documents to accommodate an editor. I would recommend to keep using xref (as mentioned in the documentation):

ifdef::env-vscode[:relfilesuffix: .adoc]

Refer to xref:document-b.adoc#section-b[Section B] for more information.

it would be really cool if this plugin also added the option to open the source markup of a clicked filelink from the preview (e.g. by mapping this function to the middle mouse button and adding it as a right-click option, if the vscode api allows this)

It requires an extra click but you can already do that using "Show source":

Please create a new issue for this enhancement request.

[vintprox]

Ugh, such a useful mini thing that would save me hundreds of exports. Workaround with ifdef::env-vscode[:relfilesuffix: .adoc] doesn't seem to work in VSCodium - it just opens supposed adoc file in the browser, which I didn't want. I get address like:

https://file+.vscode-resource.vscode-cdn.net/home/vintprox/.../article.adoc#anchor

[aisbergde]

I am looking for any way to navigate from one file into another file, using standard AsciiDoc syntax.

There are settings:

Asciidoc › Preview: Open Links To Asciidoc Files
Controls how links to other AsciiDoc files in the preview should be opened.

But I have no idea, how this should work. It looks like the feature of links to other AsciiDoc files is implemented. But where and how I could it use? Maybe the description could be improved? Or it could be added to the documentation?

I tested this:

= test-aaa-bbb
ifdef::env-vscode[:relfilesuffix: .adoc]
ifdef::env-idea[:relfilesuffix: .adoc]

xref:test-eee-fff.adoc[]

This works fine in the IntelliJ Idea plugin preview: in the preview I can click the link and the preview will show the other document.

But in VSC the generated link in the preview is https://file+.vscode-resource.vscode-cdn.net/d:/Repos/gitlab/aisbergde/notes/test-eee-fff.adoc which is tried to open in the default browser, without success. It would be fine to enable to easy use Document to Document Cross References.

Not using the :relfilesuffix: .adoc will generate html links.

btw: is there a way to "inject" a kind of ifdef::env-vscode[:relfilesuffix: .adoc] via settings of the extensions without the need to include this into each document?

[ggrossetie]

Having said that, it will still not work because we need to add data-href on xref links, similar to what we are doing for links:

Currently, it does not work on xref only on link.

btw: is there a way to "inject" a kind of ifdef::env-vscode[:relfilesuffix: .adoc] via settings of the extensions without the need to include this into each document?

You can define an attribute in the settings:

[vintprox]

btw: is there a way to "inject" a kind of ifdef::env-vscode[:relfilesuffix: .adoc] via settings of the extensions without the need to include this into each document?

You can define an attribute in the settings:

I guess it works, but seeing it work out-of-the-box in extension would be real nice :) Cross-references links don't even open in my preview unless they are from same file.

[ggrossetie]

@mojavelinux is there any potential side effects if we use :relfilesuffix: .adoc on the VS Code preview by default?

[mojavelinux]

I don't think so. In fact, that's precisely what the attribute is for ;)