Syntax highlighting

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

GitLab provides syntax highlighting for files through two complementary systems:

• Rouge (Ruby gem): Server-side highlighting that processes files on GitLab servers. It is used for:
  • Repository file viewing
  • Merge request diffs
  • Commit diffs
  • Compare view
  • Blame view
• Highlight.js: Client-side highlighting that runs in your browser. It is used to view repository files in the browser for supported languages.

The paths here use the .gitattributes interface in Git.

[!note] The Web IDE and snippets use the Monaco Editor for text editing, which internally uses the Monarch library for syntax highlighting.

Override syntax highlighting for a file type

[!note] The Web IDE does not support .gitattributes files. For more information, see epic 18651.

To override syntax highlighting for a file type:

1. If a .gitattributes file does not exist in the root directory of your project, create a blank file with this name.

2. For each file type you want to modify, add a line to the .gitattributes file declaring the file extension and your desired highlighting language:

   confCopy

   # This extension typically receives Perl syntax highlighting. If you
   # also use Prolog, you can override highlighting for this file extension:
   *.pl gitlab-language=prolog
   

3. Commit, push, and merge your changes into your default branch.

After the changes merge into your default branch, all *.pl files in your project are highlighted in your preferred language.

You can also extend the highlighting with Common Gateway Interface (CGI) options, such as:

# JSON file with .erb in it
/my-cool-file gitlab-language=erb?parent=json

# An entire file of highlighting errors!
/other-file gitlab-language=text?token=Error

Disable syntax highlighting for a file type

To disable highlighting entirely for a file type, follow the instructions for overriding the highlighting for a file type, and use gitlab-language=text:

# Disable syntax highlighting for this file type
*.module gitlab-language=text

Configure maximum file size for highlighting

The following file size limits apply to the syntax highlighters:

• Rouge (server-side): 512 KB by default (configurable)
  • Files larger than this limit render in plain text without syntax highlighting.
• Highlight.js (client-side): 2 MB (not configurable)
  • Falls back to Rouge highlighting if a language is not supported.
  • Files larger than this limit cannot be highlighted in the frontend and must be viewed as raw content.

To change the Rouge highlighting limit:

1. Open the gitlab.yml configuration file for your project.

2. Add this section, replacing maximum_text_highlight_size_kilobytes with the value you want.

   yamlCopy

   gitlab:
     extra:
       ## Maximum file size for syntax highlighting
       ## https://docs.gitlab.com/user/project/repository/files/highlighting/#configure-maximum-file-size-for-highlighting
       maximum_text_highlight_size_kilobytes: 512
   

3. Commit, push, and merge your changes into your default branch.