Merge branch 'docs-code-block-rules' into 'master'

Update guidance for code blocks in docs

See merge request gitlab-org/gitlab!24956

doc/administration/packages/container_registry.md

@@ -619,7 +619,7 @@ provided by `gitlab-ctl`.
 
 Consider the following example, where you first build the image:
 
-```bash
+```shell
 # This builds a image with content of sha256:111111
 docker build -t my.registry.com/my.group/my.project:latest .
 docker push my.registry.com/my.group/my.project:latest
@@ -627,7 +627,7 @@ docker push my.registry.com/my.group/my.project:latest
 
 Now, you do overwrite `:latest` with a new version:
 
-```bash
+```shell
 # This builds a image with content of sha256:222222
 docker build -t my.registry.com/my.group/my.project:latest .
 docker push my.registry.com/my.group/my.project:latest
@@ -774,7 +774,7 @@ once a week.
 
 Create a file under `/etc/cron.d/registry-garbage-collect`:
 
-```bash
+```shell
 SHELL=/bin/sh
 PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
 

doc/administration/troubleshooting/kubernetes_cheat_sheet.md

@@ -74,7 +74,7 @@ and they will assist you with any issues you are having.
 
 - How to get cronjobs configured on a cluster
 
-  ```bash
+  ```shell
   kubectl get cronjobs
   ```
   

doc/api/protected_environments.md

@@ -17,7 +17,7 @@ Currently, these levels are recognized:
 
 Gets a list of protected environments from a project:
 
-```bash
+```shell
 GET /projects/:id/protected_environments
 ```
 
@@ -25,7 +25,7 @@ GET /projects/:id/protected_environments
 | --------- | ---- | -------- | ----------- |
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
 
-```bash
+```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/'
 ```
 
@@ -51,7 +51,7 @@ Example response:
 
 Gets a single protected environment:
 
-```bash
+```shell
 GET /projects/:id/protected_environments/:name
 ```
 
@@ -60,7 +60,7 @@ GET /projects/:id/protected_environments/:name
 | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `name` | string | yes | The name of the protected environment |
 
-```bash
+```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/production'
 ```
 
@@ -84,11 +84,11 @@ Example response:
 
 Protects a single environment:
 
-```bash
+```shell
 POST /projects/:id/protected_environments
 ```
 
-```bash
+```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments?name=staging&deploy_access_levels%5B%5D%5Buser_id%5D=1'
 ```
 
@@ -122,11 +122,11 @@ Example response:
 
 Unprotects the given protected environment:
 
-```bash
+```shell
 DELETE /projects/:id/protected_environments/:name
 ```
 
-```bash
+```shell
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/staging'
 ```
 

doc/ci/docker/using_docker_images.md

@@ -397,7 +397,7 @@ Before the new extended Docker configuration options, you would need to create
 your own image based on the `super/sql:latest` image, add the default command,
 and then use it in job's configuration, like:
 
-```Dockerfile
+```dockerfile
 # my-super-sql:latest image's Dockerfile
 
 FROM super/sql:latest

doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md

@@ -63,7 +63,7 @@ Next, we'll create a small subset of tests that exemplify most of the states I e
 this `Weapon` class to go through. To get started, create a folder called `lib/tests`
 and add the following code to a new file `weaponTests.ts`:
 
-```ts
+```typescript
 import { expect } from 'chai';
 import { Weapon, BulletFactory } from '../lib/weapon';
 
@@ -114,7 +114,7 @@ describe('Weapon', () => {
 To build and run these tests using gulp, let's also add the following gulp functions
 to the existing `gulpfile.js` file:
 
-```ts
+```typescript
 gulp.task('build-test', function () {
     return gulp.src('src/tests/**/*.ts', { read: false })
     .pipe(tap(function (file) {
@@ -140,7 +140,7 @@ to trigger the weapon. In the `src/lib` folder create a `weapon.ts` file. We'll
 to it: `Weapon` and `BulletFactory` which will encapsulate Phaser's **sprite** and
 **group** objects, and the logic specific to our game.
 
-```ts
+```typescript
 export class Weapon {
     private isTriggered: boolean = false;
     private currentTimer: number = 0;
@@ -210,7 +210,7 @@ export class BulletFactory {
 Lastly, we'll redo our entry point, `game.ts`, to tie together both `Player` and `Weapon` objects
 as well as add them to the update loop. Here is what the updated `game.ts` file looks like:
 
-```ts
+```typescript
 import { Player } from "./player";
 import { Weapon, BulletFactory } from "./weapon";
 

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)) }

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

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
 

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"
 

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 {
     // ...
 }

doc/topics/autodevops/index.md

@@ -918,7 +918,7 @@ instead of the default `ruby:latest`:
 1. Set `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` to `--build-arg=RUBY_VERSION=alpine`.
 1. Add the following to a custom `Dockerfile`:
 
-    ```docker
+   ```dockerfile
    ARG RUBY_VERSION=latest
    FROM ruby:$RUBY_VERSION
 
@@ -955,14 +955,14 @@ In projects:
   1. Activate the experimental `Dockerfile` syntax by adding the following
      to the top of the file:
 
-     ```docker
+     ```dockerfile
      # syntax = docker/dockerfile:experimental
      ```
 
   1. To make secrets available in any `RUN $COMMAND` in the `Dockerfile`, mount
      the secret file and source it prior to running `$COMMAND`:
 
-     ```docker
+     ```dockerfile
      RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND
      ```
 

doc/topics/web_application_firewall/quick_start_guide.md

@@ -182,7 +182,7 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the
 
    This is done by running the following commands:
 
-    ```bash
+   ```shell
    $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller'
    ingress-nginx-ingress-controller-55f9cf6584-dxljn        2/2     Running
 
@@ -192,7 +192,7 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the
 
 1. Verify the Rails application has been installed properly.
 
-    ```bash
+   ```shell
    $ kubectl get ns
    auto-devv-2-16730183-production     Active
 
@@ -204,7 +204,7 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the
 
 1. To make sure the Rails application is responding, send a request to it by running:
 
-    ```bash
+   ```shell
    $ kubectl get ing -n auto-devv-2-16730183-production
    NAME  HOSTS  PORTS
    production-auto-deploy  fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io  80, 443
@@ -223,7 +223,7 @@ the WAF with OWASP CRS!
 Now let's send a potentially malicious request, as if we were a scanner,
 checking for vulnerabilities within our application and examine the modsecurity logs:
 
-```bash
+```shell
 $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2
 <body>
     <p>You're on Rails!</p>