Merge branch 'issue-31818-asciidoc-mermaid-diagram' into 'master'

Add support for Mermaid diagram in AsciiDoc

See merge request gitlab-org/gitlab!36127

doc/user/asciidoc.md

@@ -364,6 +364,89 @@ comment - content which is not included in the output document
 |===
 ```
 
+### Colors
+
+It’s possible to have color written in `HEX`, `RGB`, or `HSL` format rendered with a color indicator.
+Supported formats (named colors are not supported):
+
+- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
+- RGB: `` `RGB[A](R, G, B[, A])` ``
+- HSL: `` `HSL[A](H, S, L[, A])` ``
+
+Color written inside backticks will be followed by a color "chip":
+
+```plaintext
+- `#F00`
+- `#F00A`
+- `#FF0000`
+- `#FF0000AA`
+- `RGB(0,255,0)`
+- `RGB(0%,100%,0%)`
+- `RGBA(0,255,0,0.3)`
+- `HSL(540,70%,50%)`
+- `HSLA(540,70%,50%,0.3)`
+```
+
+### STEM
+
+To activate equation and formula support,
+set the `stem` attribute in the document's header to `latexmath`.
+Equations and formulas will be rendered using [KaTeX](https://katex.org/):
+
+```plaintext
+:stem: latexmath
+
+latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]
+
+[stem]
+++++
+sqrt(4) = 2
+++++
+
+A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))].
+```
+
+### Diagrams and flowcharts
+
+It's possible to generate diagrams and flowcharts from text in GitLab using
+[Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com).
+
+#### Mermaid
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31818) as a [community contribution](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36127) in GitLab 13.3.
+
+Visit the [official page](https://mermaidjs.github.io/) for more details.
+If you're new to using Mermaid or need help identifying issues in your Mermaid code,
+the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool
+for creating and resolving issues within Mermaid diagrams.
+
+In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block:
+
+```plaintext
+[mermaid]
+----
+graph LR
+    A[Square Rect] -- Link text --> B((Circle))
+    A --> C(Round Rect)
+    B --> D{Rhombus}
+    C --> D
+----
+```
+
+#### PlantUML
+
+To make PlantUML available in GitLab, a GitLab administrator needs to enable it first.
+Read more in [PlantUML & GitLab](../administration/integration/plantuml.md).
+
+Once enabled, you should write your text inside the `plantuml` block:
+
+```plaintext
+[plantuml]
+----
+Bob -> Alice : hello
+----
+```
+
 ### Multimedia
 
 ```plaintext

lib/banzai/filter/ascii_doc_post_processing_filter.rb

@@ -8,6 +8,9 @@ module Banzai
           node.set_attribute('class', 'code math js-render-math')
         end
 
+        doc.search('[data-mermaid-style]').each do |node|
+          node.set_attribute('class', 'js-render-mermaid')
+        end
         doc
       end
     end

lib/banzai/filter/base_sanitization_filter.rb

@@ -25,7 +25,7 @@ module Banzai
 
           # Allow data-math-style attribute in order to support LaTeX formatting
           whitelist[:attributes]['code'] = %w(data-math-style)
-          whitelist[:attributes]['pre'] = %w(data-math-style)
+          whitelist[:attributes]['pre'] = %w(data-math-style data-mermaid-style)
 
           # Allow html5 details/summary elements
           whitelist[:elements].push('details')

lib/banzai/filter/syntax_highlight_filter.rb

@@ -14,7 +14,7 @@ module Banzai
       LANG_PARAMS_ATTR = 'data-lang-params'
 
       def call
-        doc.search('pre:not([data-math-style]) > code').each do |node|
+        doc.search('pre:not([data-math-style]):not([data-mermaid-style]) > code').each do |node|
           highlight_node(node)
         end
 

lib/gitlab/asciidoc.rb

@@ -4,6 +4,7 @@ require 'asciidoctor'
 require 'asciidoctor-plantuml'
 require 'asciidoctor/extensions'
 require 'gitlab/asciidoc/html5_converter'
+require 'gitlab/asciidoc/mermaid_block_processor'
 require 'gitlab/asciidoc/syntax_highlighter/html_pipeline_adapter'
 
 module Gitlab
@@ -46,6 +47,7 @@ module Gitlab
     def self.render(input, context)
       extensions = proc do
         include_processor ::Gitlab::Asciidoc::IncludeProcessor.new(context)
+        block ::Gitlab::Asciidoc::MermaidBlockProcessor
       end
 
       extra_attrs = path_attrs(context[:requested_path])

lib/gitlab/asciidoc/mermaid_block_processor.rb

+# frozen_string_literal: true
+
+require 'asciidoctor'
+
+module Gitlab
+  module Asciidoc
+    # Mermaid BlockProcessor
+    class MermaidBlockProcessor < ::Asciidoctor::Extensions::BlockProcessor
+      use_dsl
+
+      named :mermaid
+      on_context :literal, :listing
+      parse_content_as :simple
+
+      def process(parent, reader, attrs)
+        create_mermaid_source_block(parent, reader.read, attrs)
+      end
+
+      private
+
+      def create_mermaid_source_block(parent, content, attrs)
+        # If "subs" attribute is specified, substitute accordingly.
+        # Be careful not to specify "specialcharacters" or your diagram code won't be valid anymore!
+        subs = attrs['subs']
+        content = parent.apply_subs(content, parent.resolve_subs(subs)) if subs
+        html = %(<div><pre data-mermaid-style="display">#{CGI.escape_html(content)}</pre></div>)
+        ::Asciidoctor::Block.new(parent, :pass, {
+          content_model: :raw,
+          source: html,
+          subs: :default
+        }.merge(attrs))
+      end
+    end
+  end
+end

spec/lib/banzai/filter/ascii_doc_post_processing_filter_spec.rb

@@ -10,6 +10,12 @@ RSpec.describe Banzai::Filter::AsciiDocPostProcessingFilter do
     expect(result).to eq('<pre data-math-style="inline" class="code math js-render-math">some code</pre><div data-math>and</div>')
   end
 
+  it "adds class for elements with data-mermaid-style" do
+    result = filter('<pre data-mermaid-style="display">some code</pre>').to_html
+
+    expect(result).to eq('<pre data-mermaid-style="display" class="js-render-mermaid">some code</pre>')
+  end
+
   it "keeps content when no data-math-style found" do
     result = filter('<pre>some code</pre><div data-math>and</div>').to_html
     expect(result).to eq('<pre>some code</pre><div data-math>and</div>')

spec/lib/banzai/filter/syntax_highlight_filter_spec.rb

@@ -26,6 +26,14 @@ RSpec.describe Banzai::Filter::SyntaxHighlightFilter do
     include_examples "XSS prevention", ""
   end
 
+  context "when contains mermaid diagrams" do
+    it "ignores mermaid blocks" do
+      result = filter('<pre data-mermaid-style="display"><code>mermaid code</code></pre>')
+
+      expect(result.to_html).to eq('<pre data-mermaid-style="display"><code>mermaid code</code></pre>')
+    end
+  end
+
   context "when a valid language is specified" do
     it "highlights as that language" do
       result = filter('<pre><code lang="ruby">def fun end</code></pre>')

spec/lib/gitlab/asciidoc_spec.rb

@@ -418,6 +418,50 @@ module Gitlab
           expect(output).to include("a href=\"README.adoc\"")
         end
       end
+
+      context 'with mermaid diagrams' do
+        it 'adds class js-render-mermaid to the output' do
+          input = <<~MD
+            [mermaid]
+            ....
+            graph LR
+                A[Square Rect] -- Link text --> B((Circle))
+                A --> C(Round Rect)
+                B --> D{Rhombus}
+                C --> D
+            ....
+          MD
+
+          output = <<~HTML
+            <pre data-mermaid-style="display" class="js-render-mermaid">graph LR
+                A[Square Rect] -- Link text --&gt; B((Circle))
+                A --&gt; C(Round Rect)
+                B --&gt; D{Rhombus}
+                C --&gt; D</pre>
+          HTML
+
+          expect(render(input, context)).to include(output.strip)
+        end
+
+        it 'applies subs in diagram block' do
+          input = <<~MD
+            :class-name: AveryLongClass
+
+            [mermaid,subs=+attributes]
+            ....
+            classDiagram
+            Class01 <|-- {class-name} : Cool
+            ....
+          MD
+
+          output = <<~HTML
+            <pre data-mermaid-style="display" class="js-render-mermaid">classDiagram
+            Class01 &lt;|-- AveryLongClass : Cool</pre>
+          HTML
+
+          expect(render(input, context)).to include(output.strip)
+        end
+      end
     end
 
     context 'with project' do