First Class / Special Support for Orgmode Markup via org-ruby
Release notes
- Problem: org-mode issues that require modification of rendering behavior cannot progress
- Proposal: Add first-class support for org mode markup by rendering with org-ruby instead of github-markup .
Problem to solve
Many of the org-mode issues require direct modification of current rendering behavior. See #14290, #25056, #32207, and #23170 (closed), for some examples.
This poses a problem, because while gitlab does depend on org-ruby, org-ruby machinery is never invoked directly. Instead, org-mode files go through github-markup via other_markup.rb, according to #15405 (comment 214809778).
We could add fixes to github-markup and bump the version here to fix bugs, but this support strategy doesn't work for proposals such as #23849, which suggest we extend org mode with existing GFM features like PlantUML / Mermaid graphs.
Proposal
For any of these issues to progress, org mode markup must have first-class support, in the same way that asciidoc was given. We must add special support for org mode via its own module, with its own self.render
method.
Since the org-ruby gem is already a dependency for gitlab, adding support is as easy as creating an Orgmode::Parser
object that is roughly equivalent to how github-markup already handles things.
Further details
This proposal would be the first stepping stone to real support for org mode markup in gitlab. Once implemented, proposals such as #23849 that hope to bring gfm / asciidoc features over to org-mode could actually see some more action.
Implementation Details
I'd like to add some characterizing info here about implementation, so this feature might be easier to deliver as a community contribution. As I mentioned earlier, the scope of this issue is only to get a setup that works similarly to the existing functionality. Currently, we use github-markup to render org mode markup, which renders the incoming content
with the following:
Orgmode::Parser.new(content, {
:allow_include_files => false,
:skip_syntax_highlight => true
}).to_html
So, maybe we should have a /lib/gitlab/org_mode.rb
file with something like the following:
module Gitlab
# Parser/renderer for org mode markup.
module Orgmode
# Public: Converts the provided markup into HTML.
#
# input - the source text in a markup format
#
def self.render(file_name, input, context)
html = Orgmode::Parser.new(content, {
:allow_include_files => false,
:skip_syntax_highlight => true
}).to_html
.force_encoding(input.encoding)
context[:pipeline] ||= :markup
html = Banzai.render(html, context)
html.html_safe
end
end
end
(I'm not a ruby programmer, so forgive me if I've made any dumb mistakes here)
Aside from this, which is the meat of the main logic, there would likely need to be other changes made that support this, including but not necessarily limited to:
- Add
.org
extension to wiki contexts in markup helper spec - Add
.org
extension to markup contexts in markup helper spec - Implement
orgmode?
andorgmode_unsafe
functions in markup helper spec - Add
orgmode_unsafe
call tomarkup_unsafe
function in markup helper
While these last few steps aren't necessary for a minimum viable MR, these would be what you'd need to do to support future org mode issues:
- Add an org mode banzai pipeline which would allow us to actually go in and sanitize the html produced by the
self.render
. This would also be where we'd include filters that support GFM extensions, such as syntax highlighting1, plantuml graphs2, etc. - Add filters if needed to support the pipeline mentioned above