Merge branch 'master' into 'template-improvements-for-documentation'

# Conflicts:
#   .gitlab/issue_templates/Feature proposal.md

1 files changed, 30 insertions, 20 deletions

diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 721e26f2de9..c188819560e 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -272,20 +272,26 @@ Inside the document:
 - For regular code blocks, always use a highlighting class corresponding to the
   language for better readability. Examples:
 
-      ```md
-       ```ruby
-       Ruby code
-       ```
-
-       ```js
-       JavaScript code
-       ```
-
-       ```md
-       Markdown code
-       ```
-      ```
-
+  ````md
+  ```ruby
+  Ruby code
+  ```
+
+  ```js
+  JavaScript code
+  ```
+
+  ```md
+  Markdown code
+  ```
+
+  ```text
+  Code for which no specific highlighting class is available.
+  ```
+  ````
+
+- To display raw markdown instead of rendered markdown, use four backticks on their own lines around the
+  markdown to display. See [example](https://gitlab.com/gitlab-org/gitlab-ce/blob/8c1991b9bb7e3b8d606481fdea316d633cfa5eb7/doc/development/documentation/styleguide.md#L275-287).
 - For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
 
 ## Alert boxes
@@ -383,7 +389,7 @@ Which renders to:
 > ### This is an `h3`
 >{:.no_toc}
 
-## Specific sections and terms
+## Terms
 
 To maintain consistency through GitLab documentation, the following guides documentation authors
 on agreed styles and usage of terms.
@@ -412,7 +418,7 @@ The following are recommended verbs for specific uses.
 |:------------|:--------------------------------|:-------------------|
 | "go"        | making a browser go to location | "navigate", "open" |
 
-### GitLab versions and tiers
+## GitLab versions and tiers
 
 - Every piece of documentation that comes with a new feature should declare the
   GitLab version that feature got introduced. Right below the heading add a
@@ -437,7 +443,7 @@ The following are recommended verbs for specific uses.
     > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
     ```
 
-#### Early versions of EE
+### Early versions of EE
 
 If the feature was created before GitLab 9.2 (before [different EE tiers were introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1851)):
 
@@ -450,7 +456,7 @@ For example:
 > [Introduced](<link-to-issue>) in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/).
 ```
 
-### Product badges
+## Product badges
 
 When a feature is available in EE-only tiers, add the corresponding tier according to the
 feature availability:
@@ -471,12 +477,16 @@ keyword "only":
 The tier should be ideally added to headers, so that the full badge will be displayed.
 However, it can be also mentioned from paragraphs, list items, and table cells. For these cases,
 the tier mention will be represented by an orange question mark that will show the tiers on hover.
-E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**.
+
+For example:
+
+- `**[STARTER]**` renders as **[STARTER]**
+- `**[STARTER ONLY]**` renders as **[STARTER ONLY]**
 
 The absence of tiers' mentions mean that the feature is available in GitLab Core,
 GitLab.com Free, and all higher tiers.
 
-#### How it works
+### How it works
 
 Introduced by [!244](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/244),
 the special markup `**[STARTER]**` will generate a `span` element to trigger the