Asciidoctor :: Discussion

Relative links in github vs firefox extension

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

xverges

Apr 22, 2015; 7:37am

Relative links in github vs firefox extension

1 post

Hi, Asciidoctor experts.

This is my first time here.

Short version:

I have an asciidoc file in a git repo. If I create a link to a file in the project with

link:adapters/.jshintrc[]

it is rendered properly by github, but the Firefox extension creates a link without href

Longer context:

I'm looking for a way to include small code samples in my document

In my firefox extension, this works nicely

[source, json]
----
include::adapters/.jshintrc[]
----

but the problem is in github. I am aware that inclusion is supposed to be changed by a link, but what I get is something that will puzzle people landing in the github page:

<div class="highlight highlight-json">
<pre>
link:adapters/.jshintrc[]
</pre>
</div>

Given this reasonable restriction, what approach would you recommend for my use case?

Thanks for your time.
-Xavier

Jeremie Bresson

Apr 22, 2015; 9:20am

Re: Relative links in github vs firefox extension

163 posts

You should check this:
Link to an other document

Are you using the official firefox addon? Because includes are not working for me there:
Unresolved directive in <stdin> - include::../inc.adoc[] #21
This is a limitation of firefox itself.

GitHub includes are also not always working. Check this:
example-manual.adoc (from the maven example repo but it does not matters).

At the end of the doc you have:

[source,asciidoc]
----
.include::subdir/_b.adoc[]
====
include::subdir/_b.adoc[]
====

WARNING: Includes can be tricky!
----

And this is not working.

If browser preview matters to you, Dan Allen told us, that the Asciidoctor.js Live Preview Extension for Chrome is the best solution for now. (Learn more about our meeting at JavaLand and the extension setup).

Another tip that Dan told us about GitHub preview, is that there is a tool called gist.asciidoctor.org, where you can preview the same document: example-manual.adoc. Rendering should be better with this tool.

Ted

Apr 22, 2015; 5:14pm

Re: Relative links in github vs firefox extension

126 posts

In reply to this post by xverges

I'd say since includes don't work on GitHub at this time, you'll have to paste your content into the main document.

I've been experimenting with links and includes on GitHub too. These are are my test documents: https://github.com/tedbergeron/Asciidoctor-Website

I've used an include to bring in the header.adoc file. As you can see in GitHub it only creates a link, but does not include it like it does when viewing these files locally with the Asciidoctor Live Preview in browsers.

- Ted @TedAtCIS

mojavelinux

Apr 30, 2015; 11:41pm

Re: Relative links in github vs firefox extension

Administrator

2681 posts

In reply to this post by xverges

Welcome Xavier!

In my firefox extension, this works nicely

[source, json]
----
include::adapters/.jshintrc[]
----

but the problem is in github.

This is a known issue. It's also known that the link shows in source form instead a listing block since substitutions are not processed. I tried to fix this issue, but it turns out to be a bit more complex than expected since the include directive isn't aware of the context (it doesn't know it's inside a listing block).

One solution to the problem is to use a conditional directive to hide content on GitHub and perhaps do something different:

----

ifdef::env-github[]

do something on GitHub

endif::[]

ifndef::env-github[]

do something when not on GitHub

endif::[]

----

But a better solution to the problem--one I've been contemplating for some time--is to have two documents...one is the raw source and one the expanded source. You can use a build (like Rake or Gradle) to expand the raw source (essentially processing includes) automatically and push the result to GitHub whenever a change is made to the raw source.

In short, you'd be doing a publishing step, except you are publishing the expanded AsciiDoc source instead of the HTML. It's not super elegant, but it might allow you to use includes while still using GitHub. The end users would never know ;)

Cheers,

-Dan

On Wed, Apr 22, 2015 at 1:37 AM, xverges [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi, Asciidoctor experts.

This is my first time here.

Short version:

I have an asciidoc file in a git repo. If I create a link to a file in the project with

link:adapters/.jshintrc[]

it is rendered properly by github, but the Firefox extension creates a link without href

Longer context:

I'm looking for a way to include small code samples in my document

In my firefox extension, this works nicely

[source, json]
----
include::adapters/.jshintrc[]
----

but the problem is in github. I am aware that inclusion is supposed to be changed by a link, but what I get is something that will puzzle people landing in the github page:

<div class="highlight highlight-json">
<pre>
link:adapters/.jshintrc[]
</pre>
</div>

Given this reasonable restriction, what approach would you recommend for my use case?

Thanks for your time.
-Xavier

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Relative-links-in-github-vs-firefox-extension-tp3011.html

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

... [show rest of quote]

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