-
Notifications
You must be signed in to change notification settings - Fork 3.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
AsciiDoc inter-document references link to .html #519
Comments
@mahkoh Can you provide a sample document? @mojavelinux Not sure if this is one for you or not. |
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:
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: 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 |
Btw, you can write your xref without the file extension:
|
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. |
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. |
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! |
@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:
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 |
Contrary to what I said above, there are no longer any side effects to setting this attribute on GitHub (as they have been addressed). |
@mojavelinux I'd be happy to accept such a PR! (Assuming that's still relevant; I'm a little thrown by the following comment.) |
@kivikakk Great! I will sent a PR. |
…ment xrefs - set outfilesuffix attribute to .adoc so links are created between AsciiDoc files
…ment xrefs - set outfilesuffix=.adoc so inter-document xref links are created between AsciiDoc files
resolves #519 enable source-to-source navigation for inter-document xrefs
AsciiDoc supports intelligent inter-document references via the following syntax:
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.,
But since the markup is rendered on demand, no such
.html
file exists. Instead, the generated link should look like this:The text was updated successfully, but these errors were encountered: