AsciiDoc inter-document references link to .html

[mahkoh]

AsciiDoc supports intelligent inter-document references via the following syntax:

<<document-b.adoc#section-b,Section B>>

When compiled, they will translate to an appropriate link depending on the output format. See this section in the Asciidoctor manual: http://asciidoctor.org/docs/user-manual/#inter-document-cross-references

On github, they translate to an html link, e.g.,

<a href=".../document-b.html#section-b">Section B</a>

But since the markup is rendered on demand, no such .html file exists. Instead, the generated link should look like this:

<a href=".../document-b.adoc#section-b">Section B</a>

[gjtorikian]

@mahkoh Can you provide a sample document?

@mojavelinux Not sure if this is one for you or not.

[mahkoh]

https://github.com/mahkoh/adocexample

[mojavelinux]

This is possible to enable manually, but not yet the default on GitHub. Here's how you do it. In your document header (under the document title), add:

ifdef::env-github[:outfilesuffix: .adoc]

That will enable GitHub's relative link logic to kick in and generate the correct link. I added an example in the following document so you can see it in action:

https://github.com/opendevise/asciidoc-samples/blob/master/runtime.adoc#examples

I'm still hesitating to make this the default on GitHub because I think it would be better (and safer) if we had a dedicated attribute named relfilesuffix as outfilesuffix has other implications. See asciidoctor/asciidoctor#1273.

[mojavelinux]

Btw, you can write your xref without the file extension:

<<document-b#section-b,Section B>>

[gdamore]

So this does this interact badly with github pages? I would have guessed that the entire site would be converted by Jekyll to HTML for GH pages, but I'm not sure.

Certainly when viewing adoc files in source repositories directly, it would seem to me that it would be best if relative suffixes were untouched.

[mojavelinux]

The behavior for navigating between files on GitHub is described here: http://asciidoctor.org/docs/user-manual/#navigating-between-source-files. GitHub Pages doesn't currently process AsciiDoc files. However, if it did, then the normal behavior would be sufficient.

[kivikakk]

Cleaning up issues — I'm going to close this as there's a workaround and a possible upstream fix.

@mojavelinux — if there's anything else from us you'd like on this one, please let me know!

[mojavelinux]

@kivikakk I would like to see this become the default value on GitHub so authors don't have to specify it. It would require adding the following to this line:

outfilesuffix=.adoc@

That sets the default to .adoc instead of .html, but still allows the author to override. I'm happy to send a PR if you can confirm that you will accept that change.

Again, the following section in the user manual explains what we are doing here. http://asciidoctor.org/docs/user-manual/#navigating-between-source-files

[mojavelinux]

Contrary to what I said above, there are no longer any side effects to setting this attribute on GitHub (as they have been addressed).

[kivikakk]

@mojavelinux I'd be happy to accept such a PR! (Assuming that's still relevant; I'm a little thrown by the following comment.)

[mojavelinux]

@kivikakk Great! I will sent a PR.