diff options
Diffstat (limited to 'doc/user/project/highlighting.md')
| -rw-r--r-- | doc/user/project/highlighting.md | 68 |
1 files changed, 38 insertions, 30 deletions
diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 728f51a8062..ef0c787b9d3 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -7,61 +7,67 @@ type: reference # Syntax Highlighting **(FREE)** -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the +[Rouge](https://rubygems.org/gems/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](https://git-scm.com/docs/gitattributes). NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. -<!-- vale gitlab.Spelling = NO --> - -If GitLab is guessing wrong, you can override its choice of language using the -`gitlab-language` attribute in `.gitattributes`. For example, if you are working in a Prolog -project and using the `.pl` file extension (which would normally be highlighted as Perl), -you can add the following to your `.gitattributes` file: +## Override syntax highlighting for a file type -<!-- vale gitlab.Spelling = YES --> - -``` conf -*.pl gitlab-language=prolog -``` +NOTE: +The Web IDE [does not support `.gitattribute` files](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). -<!-- vale gitlab.Spelling = NO --> +To override syntax highlighting for a file type: -When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. +1. If a `.gitattributes` file does not exist in the root directory of your project, + create a blank file with this name. +1. For each file type you want to modify, add a line to the `.gitattributes` file + declaring the file extension and your desired highlighting language: -<!-- vale gitlab.Spelling = YES --> + ```conf + # 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 + ``` -The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +1. Commit, push, and merge your changes into your default branch. -``` conf -/Nicefile gitlab-language=ruby -``` +After the changes merge into your [default branch](repository/branches/default.md), +all `*.pl` files in your project are highlighted in your preferred language. -To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through common gateway interface (CGI) options, such as: +You can also extend the highlighting with common gateway interface (CGI) options, such as: ``` conf -# json with erb in it +# JSON file with .erb in it /my-cool-file gitlab-language=erb?parent=json -# an entire file of highlighting errors! +# An entire file of highlighting errors! /other-file gitlab-language=text?token=Error ``` -These configurations only take effect when the `.gitattributes` -file is in your [default branch](repository/branches/default.md). +## Disable syntax highlighting for a file type -NOTE: -The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). +To disable highlighting entirely for a file type, follow the instructions for overriding +the highlighting for a file type, and use `gitlab-language=text`: -## Configure maximum file size for highlighting +```conf +# Disable syntax highlighting for this file type +*.module gitlab-language=text +``` -You can configure the maximum size of the file to be highlighted. +## Configure maximum file size for highlighting -The file size is measured in kilobytes, and is set to a default of `512 KB`. Any file _over_ the file size is rendered in plain text. +By default, GitLab renders any file larger than 512 KB in plain text. To change this value: -1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) configuration file. +1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) + configuration file for your project. 1. Add this section, replacing `maximum_text_highlight_size_kilobytes` with the value you want. @@ -72,3 +78,5 @@ The file size is measured in kilobytes, and is set to a default of `512 KB`. Any ## https://docs.gitlab.com/ee/user/project/highlighting.html maximum_text_highlight_size_kilobytes: 512 ``` + +1. Commit, push, and merge your changes into your default branch. |