include:: in asciidoctor vs. gollum

[asprionj]

I have (multiple) large asciidoctor docs using recursive include:: statements to separate the docs into multiple files structured in a folder structure. Just using gollum on the local checkout of such a repo basically works, but it does not resolve the include::s correctly. In asciidoctor, an include:: can have spaces, and replacing them with either %20 or the character ID   does not work.

gollum seems to convert include:: statements on the fly to link:<target>[role=include] statements. However, a link: cannot have spaces in it, so the links are broken. One solution could be to use a pass: to wrap the (possibly) space-containing target from the include::: link:pass:[<target>][role=include]. This works in some manual tests and would allow to have recursively modularised docs being processed/shown correctly both in asciidoctor and gollum at the same time.

[dometto]

We'd definitely like gollum to be as compatible as possible with asciidoctor. Can you elaborate on how adding pass fixes the issue with spaces not being allowed in the link target? Is it preventing asciidoctor from replacing spaces with something else?

[asprionj]

I'm by no means an asciidoctor expert, just a user ;).

In this paragraph of the asciidoctor docs it's written that reserved characters need to be encoded in links.

In this paragraph the escaping in context of the link: macro is explained. The pass: methodology works well here because no link text needs to be set and still the link is shown "nicely" (not encoded, which is not nice for the eye).

Passthroughs are "for passing chunks of content directly through to the output". So, in the case of gollum outputting to HTML, the target is preserved including spaces in the resulting <a href="<target>"> ... </a> tag.

[bartkamphorst]

Could you provide us with a minimal example that we can inspect?

[dometto]

gollum seems to convert include:: statements on the fly to link:[role=include] statements.

This does not seem to be something that gollum is doing. Could it be that asciidoctor is doing this anyway? Or is there a difference between the way you are calling asciidoctor locally, and the way github-markup is calling it?

[dometto]

Ping @asprionj could you provide us with some more information (see comments above)?

[asprionj]

Sorry for the long silence. Trying to come up with an MWE, and looking at the github-markup way of calling asciidoctor, had me start playing with some things. I actually found the problem. But first, a clarification:

In gollum, it would be nice to replace adoc's include statements by links. includes are preprocessor directives and are used to make one single big file out of multiple files. This is nice if one wants to keep content separated in smaller files, re-using them in different places (or different "main files" / documents), etc. So, when converting such a "main file" using asciidoctor, one actually wants this behaviour. However, when working in gollum, it is the desired behaviour for included files to be linked instead, to be able to jump to that file (to view or edit it).

Now, I assumed that this feature has been implemented in gollumn but is still buggy. However, the only reason include statements are converted to (non-working) link statements is the :safe => :secure instruction on this line. If I add the -s secure argument (see this section in the docs) to a CLI call to asdiidoctor, I get exactly the same behaviour / output.

So, for this to work as I explained above, the substitution would have to take place before even passing the source content to the markup converter (asciidoctor, in this case). So it would have to be done by gollum itself, I assume. What are your thoughts on this?

[I do know that I'm trying to "misuse" gollum as web-based editor for something that is usually done in a local editor/IDE (actually, I do use VSCode). It would just be a nice way to make editing and/or file-wise viewing (i.e. behaviour as a Wiki) of a topics-based documentation (or "file-generation") system accessible to non-nerds within the same company.]

[dometto]

I understand the issue now. I am almost inclined to call this a bug in asciidoctor, as there seems to be no way to write includes that a) works as an include without -S secure and b) works as a link with -S unsecure.

It looks like asciidoctor has consciously decided to allow spaces in links (against the AsciiDoc spec): asciidoctor/asciidoctor#798 (comment)

Perhaps it's worth asking if they feel the should support the case of an include with spaces in the filename rendered in safe mode? If not, the best bet for gollum may be to write some kind of custom extension for asciidoc.

[dometto]

Opened an issue with asciidoc here: asciidoctor/asciidoctor#4461

[dometto]

This has been fixed in asciidoctor asciidoctor/asciidoctor#4461, gem update asciidoctor should fix the problem once the patch has been released.