Asciidoctor :: Discussion

Re: Link versus XRef

Posted by mojavelinux on Jun 10, 2013; 11:09pm
URL: https://discuss.asciidoctor.org/Re-Link-versus-XRef-tp327p328.html

This is use case that can be satisfied once GitHub upgrades to Asciidoctor 0.1.3. The reason we can't solve it now is because Asciidoctor 0.1.0 (currently on GitHub) didn't have enough tools to be able do the solution.

So here's the solution:

In the header, you define an attribute for the extension of relative documents, guarded by the environment in which the document is being viewed. Something like:

ifdef::host-github[:ext-relative: .asciidoc]

ifndef::host-github[:ext-relative: {outfilesuffix}]

(outfilesuffix is set automatically based on the backend in use).

Then you create your relative links like:

* index{ext-relative}
* Creating-a-Source-Module{ext-relative}

I'm really itching to be able to use this setup because we need it for the asciidoctor.org site as well. I'll add this to the wiki as a tip, but it's not available for use just yet.

Btw, there are other ways to check for the host environment...but again, you can't do those types of conditionals until Asciidoctor is upgraded on GitHub.

-Dan

On Mon, Jun 10, 2013 at 4:57 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I believe an xref is the correct way to do this. A link is for linking to sections or anchors you create, I believe. Sorry for the uncertainly, this isn't something I typically do.

On Mon, Jun 10, 2013 at 3:52 PM, ghillert [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

I am still missing something obvious - I have multiple asciidoc files. Within an asciidoc file, I may link to another asciidoc file. This works fine on Github but when converting the asciidoc files to e.g. HTML the links stop working. It looks like the links are not rewritten to end with *.html. For example, I have the following 2 files:

* index.asiidoc
* Creating-a-Source-Module.asciidoc

I have a link in index.asiidoc:

link:Creating-a-Source-Module[Source Modules]

However, the resulting html is:

...Creating-a-Source-Module

Without the html ending appended. Should I rather use xref?

Thanks!

Cheers,

Gunnar

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Link-versus-XRef-tp326.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--
Jason Porter
http://en.gravatar.com/lightguardjp

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Re-Link-versus-XRef-tp327.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen