Wrong xref link with page containing permalink

[gdolle]

Hi, it seems that xref link does not resolve path to html when the .adoc file contains a permalink.

For example

= dir/FILE1.adoc
:page-permalink: /hello/

= FILE2.adoc

<<dir/FILE1.adoc#, Link to the FILE1>>

The html will translate the link to localhost:4000/dir/FILE1.html instead of localhost:4000/hello/index.html.

asciidoctor (1.5.5)
jekyll-asciidoc (2.1.0.dev)

(cc @prudhomm)

[prudhomm]

@mojavelinux any idea ? may be we are missing something regarding jekyll-asciidoctor ?

[mojavelinux]

This is really going outside of the design of inter-document cross references. They simply don't have the awareness of the path mapping that would be required to use them in this context. They are intended for simple document-to-document mapping in a standalone context.

I recommend instead to just use the regular link macro, which allows you to construct paths using abitrary variables.

I'm currently working on a new design of inter-document referencing for use in a site that will have this level of awareness. But it's something that has to be done using extensions (or post-processors). Asciidoctor (the core processor) is not a site generator, so it needs the help of other software for handling page URL mapping. This may be something we can later roll into the Jekyll AsciiDoc plugin, but there's still a lot of design to be done before that.

[mojavelinux]

To be clear, here's what Asciidoctor does with this:

<<dir/FILE1.adoc#, Link to the FILE1>>

It changes '.adoc' to '.html'. That's it. (Though if the file was included in the current file, it will create a local reference instead).

[jaredmorgs]

I think I got bitten by this issue as well when trying to link two blog posts together.

When I tried to use the more document-centric xref syntax to link directly to the filename, this resulted in the link getting appended as a path in the URL.

In my case I had a _config.yml permalink structure set up as permalink: '/:title/'

example.com/this-is-the-source-with-the-xref/ is the post where I set the xref to the other blog post.

example.com/this-is-the-target-post/ is the other blog post that I'm linking to from the source blog post.

So for a post that had the URL example.com/this-is-the-source-with-the-xref/ when you click the link, the URL was transformed into `example.com/this-is-the-source-with-the-xref/this-is-the-target-post/

Its almost like jekyll-asciidoc can not overwrite any permalink information. If the permalink was ignored in this case, I feel the xref would have worked because it would have resolved the URL to example.com/this-is-the-target-post/ when you clicked the xref from the source post.

I thought that I could pass through the Jekyll liquid syntax through a passthrough block which does get you close.

https://jekyllrb.com/docs/liquid/tags/#link

With this syntax I tried using a pass:[{% link _posts/2016-07-26-name-of-post.adoc %}] format which Jekyll does transform and generates the link based on your permalink pattern, but from there you can't seem to use any linking strategy to convert the text as a link.

[mojavelinux]

Here's the correct way to link from one post to another when the post is written in AsciiDoc:

link:{% post_url 2021-04-27-Use-a-token-to-access-gitlab-using-sourcetree %}[Use a personal access token to access GitLab using SourceTree]

NOTE: I don't know why the file extension has to be excluded, but it fails otherwise.

Though you also have to enable liquid processing on the AsciiDoc file by adding the following entry to the front matter:

liquid: true

The reason the xref doesn't work is because Asciidoctor doesn't know anything about Jekyll's permalink translation. So it's necessary to use the Liquid helper to handle the translation, then give the result back to AsciiDoc to make a link in the normal way. The link: prefix is required because what you get back is a pathname, not an absolute URL.

[mojavelinux]

NOTE: I don't know why the file extension has to be excluded, but it fails otherwise.

It looks like in Jekyll 4, it assumes you have left off the file extension. See https://github.com/jekyll/jekyll/blob/master/lib/jekyll/tags/post_url.rb#L19-L20 and https://github.com/jekyll/jekyll/blob/master/features/post_url_tag.feature#L11