Syntax highlighting

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.

Override syntax highlighting for a file type

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:

   # 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.

   gitlab:
     extra:
       ## Maximum file size for syntax highlighting
       ## https://docs.gitlab.com/ee/user/project/highlighting.html
       maximum_text_highlight_size_kilobytes: 512

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