Merge branch '354772-aqualls-polish1' into 'master'

Apply light CTRT polish to syntax highlight page

See merge request gitlab-org/gitlab!82725

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.