include:: on Github

[Chad Maughan]

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]

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]

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

... [show rest of quote]

--

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

[ch007m]

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::) ?