Enable includes

[mojavelinux]

In theory, includes should be able to work in DocGist. First, set the safe option to 'server'. Then, set the base_dir option to the base URL of the file being rendered. Some content-origin stuff might need to be set to make this work...however docgist is pulling the original content, the include mechanism needs the same access.

[nawroth]

Right, we'd need to give Asciidoctor access to the gist fetchers somehow.
How about patching the include macro?

[mojavelinux]

Patching the include macro is as straightforward as implementing an IncludeProcessor extension.

While there are some caveats with this extension point at the moment, it will work for 80% of the cases rather easily.

The main caveat is that a custom IncludeProcessor must handle all aspects of the include, which includes line and tag selection. I do plan to make that a concern that is handled by the core after invoking the IncludeProcessor#process method, but that's in the future.

[mojavelinux]

As a side note, this is the extension point that will eventually allow includes to work on GitHub, assuming they entertain the idea.

[nawroth]

What's the current state of the IncludeProcessor?

[mojavelinux]

Very usable. @mogztter has been working on docs for writing extensions in JavaScript.

[nawroth]

I realized that a document with many includes could use up the allowed rate limit on the GitHub API pretty fast. "For unauthenticated requests, the rate limit allows you to make up to 60 requests per hour." Could work for other hosts though.

[jexp]

We could use gh-pages

[mojavelinux]

This is a major value proposition for DocGist since GitHub security is unwilling or unable to enable includes. DocGist provides an ideal workaround. The rate limit is just something we'll have to work through, but I don't think we should let it be a show stopper.

[mojavelinux]

Since includes work in the Chrome extension, I'm not entirely sure I understand why we can't make it work the same way in DocGist. In theory, the Chrome extension and DocGist would be subject to the same rate limit problem, and that's never been a factor. cc: @Mogztter