Syntax Highlighting

GitLab provides syntax highlighting on all files through Highlight.js and the Rouge Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient.

The paths here are Git’s built-in .gitattributes interface.

The Web IDE and Snippets use Monaco Editor for text editing, which internally uses the Monarch library for syntax highlighting.

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 would normally receive Perl syntax highlighting
    # but if we also use Prolog, we may want to override highlighting for
    # files with this 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

By default, GitLab renders any file larger than 512 KB in plain text. To change this value:

  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.

        ## Maximum file size for syntax highlighting
        maximum_text_highlight_size_kilobytes: 512
  3. Commit, push, and merge your changes into your default branch.