Add latest changes from gitlab-org/gitlab@master

5 files changed, 50 insertions, 19 deletions

diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md
index c1d58c1bd4b..a71e2b3c792 100644
--- a/doc/development/code_comments.md
+++ b/doc/development/code_comments.md
@@ -7,7 +7,7 @@ check if a comment is still relevant and what needs to be done to address it.
 
 Examples:
 
-```rb
+```ruby
 # Deprecated scope until code_owner column has been migrated to rule_type.
 # To be removed with https://gitlab.com/gitlab-org/gitlab/issues/11834.
 scope :code_owner, -> { where(code_owner: true).or(where(rule_type: :code_owner)) }
diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md
index 64385a2ea79..79ed465b121 100644
--- a/doc/development/creating_enums.md
+++ b/doc/development/creating_enums.md
@@ -8,7 +8,7 @@ To use this type, add `limit: 2` to the migration that creates the column.
 
 Example:
 
-```rb
+```ruby
 def change
   add_column :ci_job_artifacts, :file_format, :integer, limit: 2
 end
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index e2f84e1200e..de7a437a1d6 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -783,33 +783,64 @@ nicely on different mobile devices.
 - When providing a shell command and its output, prefix the shell command with `$` and
   leave a blank line between the command and the output.
 - When providing a command without output, don't prefix the shell command with `$`.
+- If you need to include triple backticks inside a code block, use four backticks
+  for the codeblock fences instead of three.
 - For regular code blocks, always use a highlighting class corresponding to the
   language for better readability. Examples:
 
-  ~~~md
+  ````markdown
   ```ruby
   Ruby code
   ```
 
-  ```js
+  ```javascript
   JavaScript code
   ```
 
-  ```md
+  ```markdown
   [Markdown code example](example.md)
   ```
 
-  ```text
+  ```plaintext
   Code or text for which no specific highlighting class is available.
   ```
-  ~~~
-
-- To display raw Markdown instead of rendered Markdown, you can use triple backticks
-  with `md`, like the `Markdown code` example above, unless you want to include triple
-  backticks in the code block as well. In that case, use triple tildes (`~~~`) instead.
-- [Syntax highlighting for code blocks](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
-  is available for many languages. Use `shell` instead of `bash` or `sh` for shell output.
-- For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
+  ````
+
+Syntax highlighting is required for code blocks added to the GitLab documentation.
+Refer to the table below for the most common language classes, or check the
+[complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
+of language classes available.
+
+| Preferred language tags | Language aliases and notes                                                   |
+|-------------------------|------------------------------------------------------------------------------|
+| `asciidoc`              |                                                                              |
+| `dockerfile`            | Alias: `docker`.                                                             |
+| `elixir`                |                                                                              |
+| `erb`                   |                                                                              |
+| `golang`                | Alias: `go`.                                                                 |
+| `graphql`               |                                                                              |
+| `haml`                  |                                                                              |
+| `html`                  |                                                                              |
+| `ini`                   | For some simple config files that are not in TOML format.                    |
+| `javascript`            | Alias `js`.                                                                  |
+| `json`                  |                                                                              |
+| `markdown`              | Alias: `md`.                                                                 |
+| `mermaid`               |                                                                              |
+| `nginx`                 |                                                                              |
+| `perl`                  |                                                                              |
+| `php`                   |                                                                              |
+| `plaintext`             | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. |
+| `prometheus`            | Prometheus configuration examples.                                           |
+| `python`                |                                                                              |
+| `ruby`                  | Alias: `rb`.                                                                 |
+| `shell`                 | Aliases: `bash` or `sh`.                                                     |
+| `sql`                   |                                                                              |
+| `toml`                  | Runner configuration examples, and other toml formatted configuration files. |
+| `typescript`            | Alias: `ts`.                                                                 |
+| `xml`                   |                                                                              |
+| `yaml`                  | Alias: `yml`.                                                                |
+
+For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
 
 ## GitLab SVG icons
 
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 32017a284d5..b275a265cc6 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -240,13 +240,13 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 
 1. Create a package scoped flag name:
 
-   ```go
+   ```golang
    var findAllTagsFeatureFlag = "go-find-all-tags"
    ```
 
 1. Create a switch in the code using the `featureflag` package:
 
-   ```go
+   ```golang
    if featureflag.IsEnabled(ctx, findAllTagsFeatureFlag) {
      // go implementation
    } else {
@@ -256,7 +256,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 
 1. Create Prometheus metrics:
 
-   ```go
+   ```golang
    var findAllTagsRequests = prometheus.NewCounterVec(
      prometheus.CounterOpts{
        Name: "gitaly_find_all_tags_requests_total",
@@ -280,7 +280,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag.
 
 1. Set headers in tests:
 
-   ```go
+   ```golang
    import (
      "google.golang.org/grpc/metadata"
 
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index 73a1dd8ad8a..ae215026f56 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -195,7 +195,7 @@ When comparing expected and actual values in tests, use
 and others to improve readability when comparing structs, errors,
 large portions of text, or JSON documents:
 
-```go
+```golang
 type TestData struct {
     // ...
 }