File includes are not working on bitbucket

[dbalakirev]

Hey,

We are evaluating writing our doc files with asciidoc instead of markdown.

One feature I am excited about is the include possibility.
In asciidoc I could write:

[source,perl]
----
include::lib/dirlist.pl[lines=9..17]
----

Which gets processed and resolved in the IDEA Asciidoc support, but when viewed on our bitbucket server, it gets translated to:

link:lib/dirlist.pl[]

I learned that for example github also does this, probably due to the so called safe mode:

http://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely

But at least the link should work I guess (meaning I'd like to have the actual link not the text "link").

We are running version 2.3.1 of the plugin.

Could you please suggest a workaround?

[christiangalsterer]

Hi @dbalakirev,

I will look into it the next days.

[christiangalsterer]

I finally found some time to look into your request.
Unfortunately it is not just changing the security level but additional changes are needed to parse the links and map them to bitbucket resources. This is somehow doable, but is not as as simply as it seemed in the first place.

When you say "I learned that for example github also does this" does this mean that github also doesn't render the include or that it support this (I could also try this but as you obviously tried it, would be great if you can clarify this question.

[dbalakirev]

Thanks for checking out this issue!

I meant that to my knowledge includes won't work on github either.

What works there though, is it successfully replaces the include with a link.
From this page, I ended up at this example:
include::include.adoc[]

This include gets translated to a clickable link.

If this would work for the bitbucket plugin, the content would be accessible already for developers.

[myannou]

Hi,
I am facing the same issue.
The include feature of ascciiDoc with tags is one of the silver bullet that make me choice asciiDoc over MarkDown.
Unfortunately my knowledge on this part is too low to help fixing this issue.
But as you guess, I will be more than interested if you fix this issue ;-)

Thanks
Yann

[mkobit]

Adding to this issue as well as we are affected, but using include:file[tags=myTags] for source code documentation also does not work.

README.adoc

= Include Bug
:toc:

.Full source include
[source, groovy]
----
include::source-code.groovy[]
----

.Tagged source Include
[source, groovy]
----
include::source-code.groovy[tags=code]
----

source-code.groovy

def myVar = 'variable'
// tag::code[]
println(myVar)
println('We are in the tag')
// end::code[]

[achimgrimm]

Would it be possible to change the rendering from client side rendering to server side rendering?

[christiangalsterer]

I think where the rendering is done if not relevant for getting the support for includes.
I hope fully have some time in the next days and will look into it again what is possible here.

[christiangalsterer]

I now had some time to look into. Here a first overview how different includes are rendered.

File Includes

include::include/ad.adoc[]
include::{includedir}/ad.adoc[]

are both rendered into a HTML link in the same way as on GitHub.

Source Includes

[source,java]
----
include::include/Java.java[]
----

is rendered as

link:include/Java.java[]

in the same way as on GitHub.

Unfortunately it works only on master branch correctly as the link doesn't include the branch information, but I have a local fix already available.

Will proceed with some use cases and tests before cutting a new release with better support
support for includes.

[dbalakirev]

That sounds promising. I am happy to give us a try, should you have a release. Of course I guess it will take a couple of days until I get them update the plugin version in our company bitbucket installation.

[christiangalsterer]

I tested it with the latest release version actually.

[dbalakirev]

Ah ok. I misunderstood. I thought you actually had to fix something. Then I will test on our side to see if the problem is still around. Thanks for looking into it.

[christiangalsterer]

Add-on 2.4.0 and 3.1.0 are now released supporting file includes.