Allow activation of URI includes for AsciiDoc integration
Proposal
Allow (and document) how to allow URI includes for AsciiDoc integration.
The current GitLab documentation https://docs.gitlab.com/ee/user/asciidoc.html#includes states:
// define -a allow-uri-read to allow content to be read from URI
include::https://example.org/installation.adoc[]
But, there is no documentation how to actually activate it. Is it possible to activate?
- If so, how?
- If not, please note this in the documentation.
Background
We have a self-hosted GitLab that we would like to activate URI includes for. It is vital to us since we want to include AsciiDoc files from various repositories (projects) in the same GitLab instance. Otherwise, we won't be able to be DRY.
Implementation guide
We're using a custom include processor from https://github.com/jirutka/asciidoctor-include-ext, and are also extending it in lib/gitlab/asciidoc/include_processor.rb
.
Unfortunately it looks like it doesn't support remote URLs:
# With the changes above:
pry> Gitlab::Asciidoc.render('include::https://example.com/index.html[]', {})
=> "<div>\n<p><a href=\"https://example.com/index.html\" rel=\"nofollow noreferrer noopener\" target=\"_blank\">https://example.com/index.html</a></p>\n</div>"
# This works though:
pry> Asciidoctor.convert('include::https://example.com/index.html[]', safe: :unsafe, attributes: { 'allow-uri-read' => true })
=> "<div class=\"paragraph\">\n<p><!doctype html>\n<html>\n<head>\n <title>Example Domain</title></p>\n</div>\n<div class=\"literalblock\">\n<div class=\"content\">\n<pre> <meta charset=\"utf-8\" />\n <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n <style type=\"text/css\">\n body {\n background-color: #f0f0f2;\n margin: 0;\n padding: 0;\n font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n \n }\n div {\n width: 600px;\n margin: 5em auto;\n padding: 2em;\n background-color: #fdfdff;\n border-radius: 0.5em;\n box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n }\n a:link, a:visited {\n color: #38488f;\n text-decoration: none;\n }\n @media (max-width: 700px) {\n div {\n margin: 0 auto;\n width: auto;\n }\n }\n </style> \n</head></pre>\n</div>\n</div>\n<div class=\"paragraph\">\n<p><body>\n<div>\n <h1>Example Domain</h1>\n <p>This domain is for use in illustrative examples in documents. You may use this\n domain in literature without prior coordination or asking for permission.</p>\n <p><a href=\"https://www.iana.org/domains/example\">More information…​</a></p>\n</div>\n</body>\n</html></p>\n</div>"
The gem adds some other features, and our own extension adds protection against recursive includes, so we probably want to keep it and would have to implement support for allow-read-uri
in lib/gitlab/asciidoc/include_processor.rb
.
It looks like we only need to tweak the arguments and path validation, the actual reading via OpenURI
is already handled by Asciidoc::Reader
, which the gem reuses:
- https://github.com/asciidoctor/asciidoctor/blob/633d5fee1f7cc40b87a3b74d2c379621099e3ef0/lib/asciidoctor/reader.rb#L1036-L1038
- https://github.com/jirutka/asciidoctor-include-ext/blob/master/lib/asciidoctor/include_ext/reader_ext.rb
Add Wiki setting at Admin level
There was a comment in !82689 (merged) by @alexkalderimis regarding making this setting configurable so that it's not global for the entire GitLab instance. It then has to be configurable for both group (wiki) and project (wiki + repository) level.
- Introduce a new setting at Admin level,
wiki_asciidoc_allow_uri_includes
- Type will be a boolean
- Default value:
false
- This is similar to an existing wiki setting at the instance level for page content size.
- Instance level would give us a quick way to enable this across projects and groups.
Documentation update
Files to modify: doc/user/asciidoc.md
, administration/wikis
Out of scope
Do NOT implement any features. This is outside the scope of this issue: "If it is not possible to enable URI includes for AsciiDoc integration, add this feature as an option. Ideally under the Admin section in the GUI."
This issue related to: #348685