Update docs style for code blocks

Clarify rules for code blocks, including spaces
above and below, and to use tilde when code blocks
contain triple backticks

3 files changed, 16 insertions, 14 deletions

diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md
index c2ac063ce37..16a193550a1 100644
--- a/doc/administration/integration/plantuml.md
+++ b/doc/administration/integration/plantuml.md
@@ -72,12 +72,12 @@ our AsciiDoc snippets, wikis and repos using delimited blocks:
 
 - **Markdown**
 
-  ````markdown
+  ~~~markdown
   ```plantuml
   Bob -> Alice : hello
   Alice -> Bob : Go Away
   ```
-  ````
+  ~~~
 
 - **AsciiDoc**
 
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 680f2cd13c2..c1e3eb9680b 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -655,15 +655,16 @@ nicely on different mobile devices.
 
 ## Code blocks
 
-- Always wrap code added to a sentence in inline code blocks (``` ` ```).
+- Always wrap code added to a sentence in inline code blocks (`` ` ``).
   E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: master`.
   File names, commands, entries, and anything that refers to code should be added to code blocks.
   To make things easier for the user, always add a full code block for things that can be
   useful to copy and paste, as they can easily do it with the button on code blocks.
+- Add a blank line above and below code blocks.
 - For regular code blocks, always use a highlighting class corresponding to the
   language for better readability. Examples:
 
-  ````md
+  ~~~md
   ```ruby
   Ruby code
   ```
@@ -673,16 +674,17 @@ nicely on different mobile devices.
   ```
 
   ```md
-  Markdown code
+  [Markdown code example](example.md)
   ```
 
   ```text
-  Code for which no specific highlighting class is available.
+  Code or text 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).
+- 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.
 - 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
@@ -1024,7 +1026,7 @@ on this document. Further explanation is given below.
 
 The following can be used as a template to get started:
 
-````md
+~~~md
 ## Descriptive title
 
 One or two sentence description of what endpoint does.
@@ -1052,7 +1054,7 @@ Example response:
   }
 ]
 ```
-````
+~~~
 
 ### Fake tokens
 
@@ -1080,7 +1082,7 @@ You can use the following fake tokens as examples.
 ### Method description
 
 Use the following table headers to describe the methods. Attributes should
-always be in code blocks using backticks (``` ` ```).
+always be in code blocks using backticks (`` ` ``).
 
 ```md
 | Attribute | Type | Required | Description |
diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md
index df86b2a1cbe..862316b57da 100644
--- a/doc/user/asciidoc.md
+++ b/doc/user/asciidoc.md
@@ -277,11 +277,11 @@ source - a listing that is embellished with (colorized) syntax highlighting
 ----
 ```
 
-````asciidoc
+~~~asciidoc
 \```language
 fenced code - a shorthand syntax for the source block
 \```
-````
+~~~
 
 ```asciidoc
 [,attribution,citetitle]