Relative links in github vs firefox extension

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Relative links in github vs firefox extension

xverges
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

Reply | Threaded
Open this post in threaded view
|

Re: Relative links in github vs firefox extension

Jeremie Bresson
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
Reply | Threaded
Open this post in threaded view
|

Re: Relative links in github vs firefox extension

Ted
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
Reply | Threaded
Open this post in threaded view
|

Re: Relative links in github vs firefox extension

mojavelinux
Administrator
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



--