Repository navigation
Asciidoctor: support include directives for other asciidoc files #1095
Description
A lot of time has passed since latest comments from devs in #172 and #335.
I think after years things have changed in your infrastructure, why not to bring up this issue again with some more input and news?
For example, AFAIK GitHub started to use containers which could help to isolate things from unintentional access and improve security.
Also take a look at asciidoctor/asciidoctor#1088. The author of Asciidoctor is ready for a conversation about this, there is even proposed a way to implement this with custom include preprocessor. If there are still some concerns about resolving the issue, please provide a constructive feedback so both sides can collaborate.
Activity
chevdor commentedon Oct 18, 2017
I totally 👍 this request. Includes are an amazing feature of Asciidoc over Markdown and would help a lot providing users with good and up-to-date documentation.
I would add image to the same bucket. I think it is not supported today, probably for the same reason includes are not.
mojavelinux commentedon Oct 25, 2017
The image macros are supported on GitHub. You can see them in action here: https://github.com/asciidoctor/atom-asciidoc-preview
mojavelinux commentedon Oct 25, 2017
If GitHub is committed to enabling includes for AsciiDoc files, I'm willing to do whatever needs to be done in Asciidoctor to make it happen. I've already added an extension point so the include directive can be handled by a custom function. That allows the GitHub code to resolve the file from the git repository instead of from the file system.
ericis commentedon Nov 30, 2017
Fully support this. Seems like a basic capability and we're struggling without it 👎
http://asciidoctor.org/docs/user-manual/#include-directive
Github does NOT support asciidoc include (github/markup#1095).
github doesn't support includes, what a pain
nailgilaziev commentedon Feb 11, 2018
it will be great to use a full power of asciidoc from github frontend.
For example I use restdocs & spring to generate snippets for documentation of my API.
Most of documentations is handwritten and only generated snippets was included.
I want to store this documentation in github and collaboratively edit it with others via github instruments(pull requests).
kavaliro commentedon Feb 20, 2018
This issue was an unpleasant surprise. I agree with @ericis; this is fundamental functionality which is expected by Asciidoc users.
Since @mojavelinux has enabled custom handling , this seems simple:
This seems fairly solvable. Maybe I'm not seeing the full extent of it?
denuno commentedon Feb 24, 2018
I think it's been a solvable problem for a while now, technically-- at this point it's just someone flipping a couple switches by the looks of it.
This is hands down one of the best features of AsciiDoc and it's a crying shame that there is so little support for it in git-related tooling (GH, Gollum, GitBookIO, etc.).
FWIW, it's not like images are that much safer than other types of content, but for years now I could generate images of my source code and include it that way (ridiculous, as no copy/paste), or generate the content itself and include it that way (which defeats the purpose of nice rendering via GH out of the box).
Someday, it would be nice to move into the brave new future and get some
include::sourceFile[tags=tagName]type stuff going... I know not many people like writing docs but this stuff is gold for folks who-- well, may not love writing them, but at least who want to write them as smartly as possible-- and right now those folks have to do the work twice to get it to look nice, basically, and while it can be automated... it shouldn't need to be, in this day and age! 😃obilodeau commentedon Feb 25, 2018
So it's pretty clear the reason it hasn't been implemented yet is security. I believe it is also a reason why GitHub's staff doesn't really engage with the community in order to solve that problem because it would require them to expose their threat model and pieces of their architecture which could help attackers.
You are missing the broader point. Include processing is more complex, not because the destination is dangerous, but because of the way it interacts. Just as an example: An include can include includes which could include the first top-level include. This would DoS a naive parser. Analogous to the Billion Laugh Attack and it could be done in so many ways that it's hard to prevent them all with parser restrictions. Another different, yet complex to fix, example: AsciiDoc includes can be URIs, URI includes could be used to perform SSRF attacks in order to explore GitHub's infrastructure in means that shouldn't be allowed.
So I think the reason why GitHub is not doing it is because <1% of their users care and there are numerous ways to abuse the feature so doing it safely is hard. Implementing a hard feature for <1% is not worth the resources (or the risk).
Don't shoot the messenger here: I want AsciiDoc includes to work on GitHub! It's just that I can see why it's a tricky one to implement.
denuno commentedon Feb 25, 2018
Nothing wrong with sharing how you think-- no shots here, but I disagree that it's security holding this up per se. 😃
Mainly because in the comments above, both injection attacks, and recursion have solutions (and have been solved elsewhere in github infrastructure already)... it's weird that infinite recursion is even on the list, IMHO-- same with the "naive" parser idea... anyone can write a bad parser, we can't protect against that (and I'd be scared if we could!).
Same goes for the security concerns you bring up. They've been brought up, and even addressed, already. If not in this thread/ticket, than in multiple other ones, which leads me to my last refutation, that being the idea this problem affects a negligible number of people.
It seems to be effecting many people (including authors of popular tools who are representing thousands of people), as you can tell by the various tickets around this issue. The same-ish issue (for MD) has the highest number of comments at the moment, and it's just a bump of several other tickets (all of which seem to have "solved" the problems raised but appear to be in a holding pattern). Plus figure a good 85% of people probably don't file a ticket when they hit a problem...
I'll close by saying that security through obscurity isn't really much protection. There's a reason crypto libs have to be published to be valid, and that's because obscurity is "soft" protection at best, and a huge security concern at worst. It's cool GH is sharing the markup plugin-- tho note numbers 2-5 from the docs ("internal code") seem to be a source of bottlenecks.
Pretty sure The Future will be mostly folks who put source code out so it can be verified/checked (been saying this for years, but at least it doesn't sound crazy anymore... how much does OSS power these days?), and if you don't think someone can just call up their friend who works at Large Company X to get a peek at sources... ¯_(ツ)_/¯ anyhow, at this point it's not a tech barrier as far as I can see, and it's fine if something else is holding this up, but there's been little to no feedback from project maintainers, and it's depressing to see so much input and so many orphaned/ghosted PRs going back years and whatnot (in general around this issue). But not that much. 😃 Mainly I'm just tossing in another +1, in a now age-old tradition. 😜
mojavelinux commentedon Feb 27, 2018
@obilodeau Thank you for sharing your insight on this issue. You provided a lot of context for what the security concern actually entails.
I want to emphasize two things. First, Asciidoctor has from the very beginning offered up the include processor as an extension point (for GitHub, I might add). That means that GitHub could write code that takes over processing of the include, so there's 0 risk of insecure code that they themselves did not introduce. That doesn't make it easy, to be sure, but that should mitigate the third-party risk argument.
Second, I'm willing to make any reasonable change in Asciidoctor that would further accommodate this feature. So far, I have heard absolutely nothing from GitHub on this issue, which doesn't bode well if we expect to make any progress. My offer stands to work with GitHub if they need me to get this feature implemented. (code, documentation, whatever)
I don't expect GitHub to use the built-in include processor, but there is protection against this scenario. An include can only go to a fixed number of levels before it's terminated. Most users would be happy with 3-5 levels, if even that.
I would not except these to work on GitHub. They don't even work on Asciidoctor without a command-line / API flag. I think includes that work within the set of repository files is already a huge boon for us AsciiDoc writers.
If they went with that argument, then I'd say they don't know the AsciiDoc community very well. AsciiDoc users are bonkers for includes, rightfully so. As Denny points out:
If you want my prediction on this issue, it will be resolved as soon as GitLab implements it. That's not trolling, that's just sound competition in the marketplace. After all, GitLab just implemented stem support (i.e, math expressions) in AsciiDoc files.
mojavelinux commentedon Feb 27, 2018
Btw, here's a link to corresponding issue in the GitLab issue tracker.
https://gitlab.com/gitlab-org/gitlab-ce/issues/18045
Interesting to note that @jirutka has already submitted a full patch for a custom include processor that works with a repository manager like GitHub and GitLab. So the code is there. We just need the will.
jyutzler commentedon Feb 27, 2018
I am fine with a very restrictive policy here, even restricting includes to the same repository. My issue is that I have documents that I want modularized but I also want to be able to present them on the web as complete documents and right now I can't do that. I have to kick off a separate process to generate the file then post that. Whether I do this manually or through some sort of agent is irrelevant, it is a nuisance and completely unnecessary.
kavaliro commentedon Feb 28, 2018
3-5 levels would be perfect imho. Five gives a few levels for document structure and a couple of levels for templates. Three would suffice for most use cases, but five would handle almost all of them.
While I can handle all of the includes before pushing the content to github, effectively that means I'm no longer able to use github as source control (for the same reason our .gitignore files exclude /bin.)
One use case I have uses include to add an svg, and the text fields of the svg are then changed via substitutions. Which really isn't that complex--an svg is just xml after all--but it's not something you can do with the standard image handler.
Count me among those who are bonkers for includes. Includes really are a must have feature for asciidoc.
178 remaining items
Update reduce-readme.yml with reference link
github-actions commentedon Jun 3, 2026
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
jerstlouis commentedon Jun 3, 2026
Still caring about this issue as an active standard editor.
jeras commentedon Jun 3, 2026
With the increase in supply-chain attacks, allowing GitHub actions to rewrite asciidoc files does not seem like a good workaround anymore.
janderssonse commentedon Jun 5, 2026
Next year is the year of AGI, Linux desktop and proper maintenance of this repo, including great asciidoc-support. :) Cheers to almost a decade since the above was written, and still no action from GitHub.
jseguillon commentedon Jun 5, 2026
Yeah this issue is definitely my fav. Probably I'll be retired before GitHub acts on it 🙃
github-actions commentedon Aug 5, 2026
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
jimisola commentedon Aug 5, 2026
Nice try. It might be stale but it is still desirable.
chevdor commentedon Sep 29, 2026
Sailing towards the 10y anniversary for this issue, no stress folks... Even wayyy past if you consider #172 and #335.
In the meantime, having that on my list for my local gitea install, it was wrapped up in less than an hour. No AGI required here...
toastal commentedon Oct 3, 2026
Nice; this is as it should be. We should be able to fork/fix our code forges & encourage self-hosting instead of begging a megacorporation trying to create shareholder value to care.