Banzai

GitLab's HTML pipeline for rendering Markdown, references, mentions, code highlighting, math, and Mermaid.

Purpose

Whenever user-supplied text is shown — issue descriptions, comments, wiki pages, MR descriptions, commit messages, file READMEs — Banzai converts it from Markdown to safe HTML and rewrites GitLab references like #123, !456, @username, and [ref:file:line] into rich links.

Source

lib/banzai/
├── pipeline/                # Composable HTML pipelines
│   ├── full_pipeline.rb
│   ├── plain_markdown_pipeline.rb
│   ├── single_line_pipeline.rb
│   └── ...
├── filter/                  # Individual HTML transforms (one class per concern)
│   ├── reference/
│   │   ├── issue_reference_filter.rb
│   │   ├── merge_request_reference_filter.rb
│   │   ├── user_reference_filter.rb
│   │   └── ...
│   ├── markdown_filter.rb
│   ├── code_block_filter.rb
│   ├── emoji_filter.rb
│   ├── math_filter.rb
│   ├── mermaid_filter.rb
│   ├── kroki_filter.rb
│   ├── front_matter_filter.rb
│   ├── sanitization_filter.rb
│   └── ...
├── renderer.rb              # Cached + uncached entry points
├── reference_parser/        # Reverse: parse rendered HTML back to references
└── ...

A "pipeline" is an ordered list of filters. Each filter takes an HTML/Nokogiri tree, transforms it, and returns the modified tree.

Common pipelines

Pipeline	Used for
Banzai::Pipeline::FullPipeline	Issue/MR descriptions, comments, wikis
Banzai::Pipeline::PlainMarkdownPipeline	Markdown that shouldn't get reference resolution
Banzai::Pipeline::SingleLinePipeline	Branch descriptions, short labels
Banzai::Pipeline::EmailPipeline	Notifications
Banzai::Pipeline::CommitDescriptionPipeline	Commit messages
Banzai::Pipeline::WikiPipeline	Wiki content (extra link rewriting)

Reference filters

The filters under lib/banzai/filter/reference/ recognize patterns like #123, !456, @user, [issue:gitlab-org/gitlab#123], etc., and turn them into rich anchor tags. Each filter:

1. Walks text nodes looking for its pattern.
2. Validates and looks up the referenced object via a ReferenceParser.
3. Substitutes a styled link.

User permissions are checked before exposing the referenced object's title — invisible references render as plain text.

Reference parsers

lib/banzai/reference_parser/ is the reverse of reference filters. Given rendered HTML, it extracts the references back out (used for notifications, mentions, etc.).

Caching

Markdown rendering is expensive. Banzai caches output per (content, project, current_user) key:

• Per-record cache via MarkdownCache (lib/gitlab/markdown_cache/) — stored on the model.
• Per-request cache via RequestStore.
• HTML invalidation on referenced object changes.

Sanitization

Banzai::Filter::SanitizationFilter strips dangerous HTML using a strict allowlist. Custom variants exist for emails (SanitizationFilter::Email) and for trusted server-rendered fragments.

Diagrams

• Mermaid diagrams render client-side; Banzai marks the code block with lang="mermaid".
• Kroki for AsciiDoc diagrams; Banzai sends the source to a Kroki server (lib/gitlab/kroki.rb).
• Math via KaTeX; Banzai marks math blocks with js-render-math.

Asciidoc and other markups

Other markups go through lib/gitlab/asciidoc/ (Asciidoctor) and lib/gitlab/other_markup.rb (rdoc, textile, etc.). They eventually feed into Banzai for reference resolution.

Where to make changes

• New reference type: subclass Banzai::Filter::Reference::AbstractReferenceFilter, add a ReferenceParser, register in the relevant pipeline.
• New diagram type: add a filter and corresponding frontend renderer.
• New sanitization rule: extend the allowlist in SanitizationFilter.

Related

• Frontend — diagram and math rendering happens client-side.