debian-mirror-gitlab/doc/user/project/highlighting.md

83 lines
3 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2021-02-22 17:27:13 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference
---
2021-03-11 19:13:27 +05:30
# Syntax Highlighting **(FREE)**
2016-08-24 12:49:21 +05:30
2022-08-13 15:12:31 +05:30
GitLab provides syntax highlighting on all files through [Highlight.js](https://github.com/highlightjs/highlight.js/) and the
2022-05-07 20:08:51 +05:30
[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).
2020-07-28 23:09:34 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2020-07-28 23:09:34 +05:30
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.
2016-08-24 12:49:21 +05:30
2022-05-07 20:08:51 +05:30
## Override syntax highlighting for a file type
2016-08-24 12:49:21 +05:30
2022-05-07 20:08:51 +05:30
NOTE:
The Web IDE [does not support `.gitattribute` files](https://gitlab.com/gitlab-org/gitlab/-/issues/22014).
2016-08-24 12:49:21 +05:30
2022-05-07 20:08:51 +05:30
To override syntax highlighting for a file type:
2021-10-27 15:23:28 +05:30
2022-05-07 20:08:51 +05:30
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:
2021-10-27 15:23:28 +05:30
2022-05-07 20:08:51 +05:30
```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
```
2016-08-24 12:49:21 +05:30
2022-05-07 20:08:51 +05:30
1. Commit, push, and merge your changes into your default branch.
2016-08-24 12:49:21 +05:30
2022-05-07 20:08:51 +05:30
After the changes merge into your [default branch](repository/branches/default.md),
all `*.pl` files in your project are highlighted in your preferred language.
2016-08-24 12:49:21 +05:30
2022-07-23 23:45:48 +05:30
You can also extend the highlighting with Common Gateway Interface (CGI) options, such as:
2016-08-24 12:49:21 +05:30
``` conf
2022-05-07 20:08:51 +05:30
# JSON file with .erb in it
2016-08-24 12:49:21 +05:30
/my-cool-file gitlab-language=erb?parent=json
2022-05-07 20:08:51 +05:30
# An entire file of highlighting errors!
2016-08-24 12:49:21 +05:30
/other-file gitlab-language=text?token=Error
```
2022-05-07 20:08:51 +05:30
## Disable syntax highlighting for a file type
2020-07-28 23:09:34 +05:30
2022-05-07 20:08:51 +05:30
To disable highlighting entirely for a file type, follow the instructions for overriding
the highlighting for a file type, and use `gitlab-language=text`:
2021-06-08 01:23:25 +05:30
2022-05-07 20:08:51 +05:30
```conf
# Disable syntax highlighting for this file type
*.module gitlab-language=text
```
2021-06-08 01:23:25 +05:30
2022-05-07 20:08:51 +05:30
## Configure maximum file size for highlighting
2021-06-08 01:23:25 +05:30
2022-05-07 20:08:51 +05:30
By default, GitLab renders any file larger than 512 KB in plain text. To change this value:
2021-06-08 01:23:25 +05:30
2022-05-07 20:08:51 +05:30
1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example)
configuration file for your project.
2021-06-08 01:23:25 +05:30
1. Add this section, replacing `maximum_text_highlight_size_kilobytes` with the value you want.
```yaml
gitlab:
extra:
## Maximum file size for syntax highlighting
## https://docs.gitlab.com/ee/user/project/highlighting.html
maximum_text_highlight_size_kilobytes: 512
```
2022-05-07 20:08:51 +05:30
1. Commit, push, and merge your changes into your default branch.