Asciidoctor :: Discussion

include:: on Github

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

Chad Maughan

include:: on Github

I have a bunch of .adoc files on Github that include a generated csv file as part of a table. The generation of the documentation works fantastic but I'd love to have the rendering of the table included on Github. From my experimentation, I'm guessing that isn't possible, is it?

[format="csv", cols=">2s,8"]
|===
include::file.csv[]
|===

On a more general level, is there documentation some where of what part of Asciidoc syntax Github supports?

Thanks!

mojavelinux

Re: include:: on Github

Administrator

Welcome Chad!

GitHub disables the include directive for security reasons, which I can appreciate. This is one of several features that are disabled in the :server safe mode.

Asciidoctor 0.1.4 introduced an include processor extension point, which I'm hoping can be used (eventually) to open up the include directive in a way that fits GitHub's security requirements (such as grabbing the file to include from the git tree).

I was just talking to Sarah about adding a section to the manual that covered which features of Asciidoctor are affected by the safe mode setting. Once that's written up, then you can see what's enabled on GitHub simply by looking at the row for :server safe mode.

Here's a quick rundown of what behavior gets modified:

* include directive disabled

* backend set to html5

* icons disabled

* docinfo files disabled

* data-uri disabled (no embedding of base64 assets data into the data-uri attribute permitted)

* docdir and docfile attributes not available

* source highlighting (this will be enabled automatically once Asciidoctor is upgraded on GitHub; it will highlight using Pygments)

One of the changes coming in the Asciidoctor upgrade (whenever that is, I have no way to predict) is that include directives will be turned into links, so at the very least they are interactive.

I hope that helps!

Cheers,

-Dan

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

mojavelinux

Re: include:: on Github

Administrator

In reply to this post by Chad Maughan

Correction. Where I said "server" safe mode, I meant "secure" safe mode. The default safe mode for the API is "server" and the default safe mode for the CLI is "unsafe".

The "server" safe mode is a step down from "secure" and allows features like "icons" and "linkcss". We'll get that all clarified in the manual.

-Dan

On Mon, Sep 30, 2013 at 8:13 PM, Dan Allen <[hidden email]> wrote:

Welcome Chad!

GitHub disables the include directive for security reasons, which I can appreciate. This is one of several features that are disabled in the :server safe mode.

Asciidoctor 0.1.4 introduced an include processor extension point, which I'm hoping can be used (eventually) to open up the include directive in a way that fits GitHub's security requirements (such as grabbing the file to include from the git tree).

I was just talking to Sarah about adding a section to the manual that covered which features of Asciidoctor are affected by the safe mode setting. Once that's written up, then you can see what's enabled on GitHub simply by looking at the row for :server safe mode.

Here's a quick rundown of what behavior gets modified:

* include directive disabled
* backend set to html5
* icons disabled
* docinfo files disabled
* data-uri disabled (no embedding of base64 assets data into the data-uri attribute permitted)
* docdir and docfile attributes not available
* source highlighting (this will be enabled automatically once Asciidoctor is upgraded on GitHub; it will highlight using Pygments)

One of the changes coming in the Asciidoctor upgrade (whenever that is, I have no way to predict) is that include directives will be turned into links, so at the very least they are interactive.

I hope that helps!

Cheers,

-Dan

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

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

ch007m

Re: include:: on Github

In reply to this post by mojavelinux

It seems that this github restriction is still there even with Asciidoctor 1.5.

Question : Do we have a trick or workaround (replacing include:: by link::) ?

Charles Moulliard
Apache Committer / Technologist Evangelist / Blogger / MiddleWare Specialist
Twitter : @cmoulliard