Develop Notes

GitLab Wiki MarkDown Support iframe

Abstarct: This article introduce how to configure the GitLab and let the GitLab Wiki MarkDown support the iframe html element.

GitLab is a great software to deploy git repository and manage issues. Meanwhile, the wiki system is also awesome.

The wiki of GitLab support Markdown, AsciiDoc and RDoc, which nearly include all the syntax and presentation for a document even for formal thesis and paper.

Currently, most of the developers use the Markdown as the main document language, the GitLab not only support the standard MarkDown but also support other features. This markdown is called GitLab Flavour Markdown (GFM).

According to the official document, we can find that it supports the Inline HTML which means that we can add any HTML source code to render the Wiki. This feature can enhance the ability of representation of our document.

However, there are some limitations when using the HTML. Thinking about the security, there is a whitelist HTML syntax that can be rendered. If you use the HTML tag which is not in the whitelist, the DOM will be ignored.

This whitelist is based on the Sanitize which is Whitelist-based Ruby HTML and CSS sanitizer. The detailed document is HTML::Pipeline’s SanitizationFilter class.

Now the problem is that, is it possible to add some other HTML into the GitLab wiki (on-premise not cloud)? The answer is yes! We can customise the SanitizationFilter by ourselves.

Sanitize official example

youtube_transformer = lambda do|env| node = env[:node] node_name = env[:node_name]# Don't continue if this node is already whitelisted or is not an element.returnif env[:is_whitelisted] || !node.element?# Don't continue unless the node is an iframe.returnunless node_name == 'iframe'# Verify that the video URL is actually a valid YouTube video URL.returnunless node['src'] =~ %r|\A(?:https?:)?//(?:www\.)?youtube(?:-nocookie)?\.com/|# We're now certain that this is a YouTube embed, but we still need to run# it through a special Sanitize step to ensure that no unwanted elements or# attributes that don't belong in a YouTube embed can sneak in. Sanitize.node!(node, {:elements => %w[iframe],:attributes => {'iframe' => %w[allowfullscreen frameborder height src width] } })# Now that we're sure that this is a valid YouTube embed and that there are# no unwanted elements or attributes hidden inside it, we can tell Sanitize# to whitelist the current node. {:node_whitelist => [node]}end

GitLab relative sanitization_filter file

The first and important thing to let GitLab wiki support the iframe is finding the corresponding configuration: sanitization_filter.rb

By using the Linux shell to search sudo find / -name "sanitization_filter.rb" we can find there are two files with this name.

# YouTube Special lambda { |env| node = env[:node] node_name = env[:node_name]# Don't continue if this node is already whitelisted or is not an element.returnif env[:is_whitelisted] || !node.element?# Don't continue unless the node is an iframe.returnunless node_name == 'iframe'# Verify that the video URL is actually a valid YouTube video URL.returnunless node['src'] =~ %r|\A(?:https?:)?//(?:www\.)?youtube(?:-nocookie)?\.com/|# We're now certain that this is a YouTube embed, but we still need to run# it through a special Sanitize step to ensure that no unwanted elements or# attributes that don't belong in a YouTube embed can sneak in. Sanitize.node!(node, {:elements => %w[iframe],:attributes => {'iframe' => %w[allowfullscreen frameborder height src width] } })# Now that we're sure that this is a valid YouTube embed and that there are# no unwanted elements or attributes hidden inside it, we can tell Sanitize# to whitelist the current node. {:node_whitelist => [node]} },