Merge branch 'master' into 'id-test-codeowners'id-test-codeowners

# Conflicts:
#   .gitlab/CODEOWNERS

4 files changed, 145 insertions, 146 deletions

diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md
index ca29353ecbe..ac93ada5a4b 100644
--- a/doc/development/documentation/feature-change-workflow.md
+++ b/doc/development/documentation/feature-change-workflow.md
@@ -121,27 +121,27 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to
 
 - **Prior to merging**, documentation changes committed by the developer must be reviewed by:
 
-   1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
-   1. Optionally: Others involved in the work, such as other devs or the PM.
-   1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge.
-      This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed.
-      - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change,
-        and your degree of confidence in having users of an RC use your docs as written.
-      - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes.
-      - You can request a review and if there is not sufficient time to complete it prior to the freeze,
-        the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue.
-      - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR.
-      - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
-      - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
-   1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
+  1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
+  1. Optionally: Others involved in the work, such as other devs or the PM.
+  1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge.
+     This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed.
+     - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change,
+       and your degree of confidence in having users of an RC use your docs as written.
+     - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes.
+     - You can request a review and if there is not sufficient time to complete it prior to the freeze,
+       the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue.
+     - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR.
+     - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
+     - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
+  1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
 
 - Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review), link it from the MR, and
   mention the original MR author in the new issue. Alternatively, the maintainer can ask the MR author to create and link this issue before the MR is merged.
 
 - After merging, documentation changes are reviewed by:
 
-   1. The technical writer--**if** their review was not performed prior to the merge.
-   2. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
+  1. The technical writer -- **if** their review was not performed prior to the merge.
+  1. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
       Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset.
 
 ### Technical Writer role
diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md
index a12c3d5ea7b..80fbd4b6427 100644
--- a/doc/development/documentation/improvement-workflow.md
+++ b/doc/development/documentation/improvement-workflow.md
@@ -52,9 +52,9 @@ To request a post-merge review, [create an issue for one using the Doc Review te
 **3. Maintainer**
 
 1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review.
-2. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone.
-3. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
-4. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR.
+1. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone.
+1. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
+1. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR.
 
 ## Other ways to help
 
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 36a2f47a55b..19b26618882 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -57,35 +57,22 @@ See the [Structure](styleguide.md#structure) section of the [Documentation Style
 We currently maintain two sets of docs: one in the
 [gitlab-ce](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) repo and
 one in [gitlab-ee](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc).
-They are similar, and most pages are identical, but they are different repositories.
-With the single codebase effort, we want to make those two sets identical, so when the
-time comes to have only one codebase, we'll be ready.
-
-Here are some links to get you up to speed with the current effort:
-
-- [CE/EE codebases blueprint](https://about.gitlab.com/handbook/engineering/infrastructure/blueprint/ce-ee-codebases/)
-- [CE/EE codebases merge design](https://about.gitlab.com/handbook/engineering/infrastructure/design/merge-ce-ee-codebases/)
-- [Single docs codebase epic](https://gitlab.com/groups/gitlab-org/-/epics/199)
-- [Issue board of related issues](https://gitlab.com/groups/gitlab-org/-/boards/981090?&label_name[]=Documentation&label_name[]=single%20codebase)
-- [Related merge requests](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=all&label_name[]=Documentation&label_name[]=single%20codebase)
-- [Visualize the existing diffs](https://leipert-projects.gitlab.io/is-gitlab-pretty-yet/diff/?search=%5Edoc)
+They are identical, but they are different repositories. When the
+time comes to have only one codebase for the GitLab project, we'll be ready.
 
 ### CE first
 
-After a given documentation path is aligned across CE and EE, all merge requests
-affecting that path must be submitted to CE, regardless of the content it has.
-This means that:
+All merge requests for documentation must be submitted to CE, regardless of the content
+it has. This means that:
 
-- For **EE-only docs changes**, you only have to submit a CE MR.
+- For **EE-only docs changes**, you only have to submit an MR in the CE project.
 - For **EE-only features** that touch both the code and the docs, you have to submit
-  an EE MR containing all changes, and a CE MR containing only the docs changes
+  an EE MR containing all code changes, and a CE MR containing only the docs changes
   and without a changelog entry.
 
 This might seem like a duplicate effort, but it's only for the short term.
-A list of the already aligned docs can be found in
-[the epic description](https://gitlab.com/groups/gitlab-org/-/epics/199#ee-specific-lines-check).
 
-Since the docs will be combined, it's crucial to add the relevant
+Since the CE and EE docs are combined, it's crucial to add the relevant
 [product badges](styleguide.md#product-badges) for all EE documentation, so that
 we can discern which features belong to which tier.
 
@@ -94,19 +81,9 @@ we can discern which features belong to which tier.
 There's a special test in place
 ([`ee_specific_check.rb`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/ee_specific_check/ee_specific_check.rb)),
 which, among others, checks and prevents creating/editing new files and directories
-in EE under `doc/`.
-
-We have a long list of documentation paths that are either whitelisted or not.
-Paths in the whitelist (not commented out) will not be subject to the test,
-which means you are allowed to create/change docs content in EE for the time
-being. The goal is to not have any doc whitelisted.
-
-At the time of this writing, the only items left to be aligned are the API docs:
-
-- `doc/api/*` ([issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60045) / [merge request](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27491))
-
-Eventually, once all docs are aligned, we'll remove any doc reference from that
-script, so it catches everything.
+in EE under `doc/`. This should fail when changes to anything in `/doc` are submitted
+in an EE MR. To pass the test, simply remove the docs changes from the EE MR, and
+[submit them in CE](#ce-first).
 
 ## Changing document location
 
@@ -134,18 +111,18 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
 1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md`
 1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with:
 
-    ```md
-    This document was moved to [another location](../../administration/lfs.md).
-    ```
+   ```md
+   This document was moved to [another location](../../administration/lfs.md).
+   ```
 
 1. Find and replace any occurrences of the old location with the new one.
    A quick way to find them is to use `git grep`. First go to the root directory
    where you cloned the `gitlab-ce` repository and then do:
 
-    ```sh
-    git grep -n "workflow/lfs/lfs_administration"
-    git grep -n "lfs/lfs_administration"
-    ```
+   ```sh
+   git grep -n "workflow/lfs/lfs_administration"
+   git grep -n "lfs/lfs_administration"
+   ```
 
 NOTE: **Note:**
 If the document being moved has any Disqus comments on it, there are extra steps
@@ -319,45 +296,45 @@ You can combine one or more of the following:
 1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path`
    method:
 
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
-    ```
+   ```haml
+   = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
+   ```
 
 1. **Opening links in a new tab.** This should be the default behavior:
 
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
-    ```
+   ```haml
+   = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
+   ```
 
 1. **Linking to a circle icon.** Usually used in settings where a long
    description cannot be used, like near checkboxes. You can basically use
    any font awesome icon, but prefer the `question-circle`:
 
-    ```haml
-    = link_to icon('question-circle'), help_page_path('user/permissions')
-    ```
+   ```haml
+   = link_to icon('question-circle'), help_page_path('user/permissions')
+   ```
 
 1. **Using a button link.** Useful in places where text would be out of context
    with the rest of the page layout:
 
-    ```haml
-    = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
-    ```
+   ```haml
+   = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'
+   ```
 
 1. **Using links inline of some text.**
 
-    ```haml
-    Description to #{link_to 'Help page', help_page_path('user/permissions')}.
-    ```
+   ```haml
+   Description to #{link_to 'Help page', help_page_path('user/permissions')}.
+   ```
 
 1. **Adding a period at the end of the sentence.** Useful when you don't want
    the period to be part of the link:
 
-    ```haml
-    = succeed '.' do
-      Learn more in the
-      = link_to 'Help page', help_page_path('user/permissions')
-    ```
+   ```haml
+   = succeed '.' do
+     Learn more in the
+     = link_to 'Help page', help_page_path('user/permissions')
+   ```
 
 ### GitLab `/help` tests
 
@@ -488,15 +465,17 @@ Currently, the following tests are in place:
    that all cURL examples in API docs use the full switches. It's recommended
    to [check locally](#previewing-the-changes-live) before pushing to GitLab by executing the command
    `bundle exec nanoc check internal_links` on your local
-   [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory.
+   [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. In addition,
+   `docs-lint` also runs [markdownlint](styleguide.md#markdown-rules) to ensure the
+   markdown is consistent across all documentation.
 1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-ee-merge-conflicts-beforehand) (runs on CE only):
-    When you submit a merge request to GitLab Community Edition (CE),
-    there is this additional job that runs against Enterprise Edition (EE)
-    and checks if your changes can apply cleanly to the EE codebase.
-    If that job fails, read the instructions in the job log for what to do next.
-    As CE is merged into EE once a day, it's important to avoid merge conflicts.
-    Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
-    essential to avoid them.
+   When you submit a merge request to GitLab Community Edition (CE),
+   there is this additional job that runs against Enterprise Edition (EE)
+   and checks if your changes can apply cleanly to the EE codebase.
+   If that job fails, read the instructions in the job log for what to do next.
+   As CE is merged into EE once a day, it's important to avoid merge conflicts.
+   Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
+   essential to avoid them.
 1. [`ee-files-location-check`/`ee-specific-lines-check`](#ee-specific-lines-check) (runs on EE only):
    This test ensures that no new files/directories are created/changed in EE.
    All docs should be submitted in CE instead, regardless the tier they are on.
@@ -559,15 +538,16 @@ A file with `proselint` configuration must be placed in a
 #### `markdownlint`
 
 `markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases))
- are followed for Markdown syntax.
- Our [Documentation Style Guide](styleguide.md) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
- elaborate on which choices must be made when selecting Markdown syntax for
- GitLab documentation. This tool helps catch deviations from those guidelines.
+are followed for Markdown syntax. Our [Documentation Style Guide](styleguide.md) and
+[Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
+elaborate on which choices must be made when selecting Markdown syntax for GitLab
+documentation. This tool helps catch deviations from those guidelines, and matches the
+tests run on the documentation by [`docs-lint`](#testing).
 
 `markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
- either on a single Markdown file or on all Markdown files in a project. For example, to run
- `markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
- run the following commands from within the `gitlab-ce` project:
+either on a single Markdown file or on all Markdown files in a project. For example, to run
+`markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
+run the following commands from within the `gitlab-ce` project:
 
 ```sh
 cd doc
@@ -597,7 +577,7 @@ The following sample `markdownlint` configuration modifies the available default
   "line-length": false,
   "no-trailing-punctuation": false,
   "ol-prefix": { "style": "one" },
-  "blanks-around-fences": false,
+  "blanks-around-fences": true,
   "no-inline-html": {
     "allowed_elements": [
       "table",
@@ -612,11 +592,15 @@ The following sample `markdownlint` configuration modifies the available default
       "a",
       "strong",
       "i",
-      "div"
+      "div",
+      "b"
     ]
   },
   "hr-style": { "style": "---" },
-  "fenced-code-language": false
+  "code-block-style": { "style": "fenced" },
+  "fenced-code-language": false,
+  "no-duplicate-header": { "allow_different_nesting": true },
+  "commands-show-output": false
 }
 ```
 
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 1ca965f8ae9..e84d65f424e 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -36,17 +36,17 @@ For the Troubleshooting sections, people in GitLab Support can merge additions t
 
 Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it.
 
-   - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
-   - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.
+- If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
+- Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.
 
 ### No special types
 
 In the software industry, it is a best practice to organize documentatioin in different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/):
 
 1. Tutorials
-2. How-to guides
-3. Explanation
-4. Reference (for example, a glossary)
+1. How-to guides
+1. Explanation
+1. Reference (for example, a glossary)
 
 At GitLab, we have so many product changes in our monthly releases that we can't afford to continually update multiple types of information.
 If we have multiple types, the information will become outdated. Therefore, we have a [single template](structure.md) for documentation.
@@ -107,6 +107,22 @@ Hard-coded HTML is valid, although it's discouraged to be used while we have `/h
 - Special styling is required.
 - Reviewed and approved by a technical writer.
 
+### Markdown Rules
+
+GitLab ensures that the Markdown used across all documentation is consistent, as
+well as easy to review and maintain, by testing documentation changes with
+[Markdownlint (mdl)](https://github.com/markdownlint/markdownlint). This lint test
+checks many common problems with Markdown, and fails when any document has an issue
+with Markdown formatting that may cause the page to render incorrectly within GitLab.
+It will also fail when a document is using non-standard Markdown (which may render
+correctly, but is not the current standard in GitLab documentation).
+
+Each formatting issue that mdl checks has an associated [rule](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md),
+and the rules that are currently enabled for GitLab documentation are listed in the
+[`.mdlrc.style`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.mdlrc.style) file.
+Configuration options are set in the [`.mdlrc`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.mdlrc.style)
+file.
+
 ## Structure
 
 ### Organize by topic, not by type
@@ -142,9 +158,9 @@ The table below shows what kind of documentation goes where.
 ### Working with directories and files
 
 1. When you create a new directory, always start with an `index.md` file.
-  Do not use another file name and **do not** create `README.md` files.
+   Do not use another file name and **do not** create `README.md` files.
 1. **Do not** use special characters and spaces, or capital letters in file names,
-  directory names, branch names, and anything that generates a path.
+   directory names, branch names, and anything that generates a path.
 1. When creating a new document and it has more than one word in its name,
    make sure to use underscores instead of spaces or dashes (`-`). For example,
    a proper naming would be `import_projects_from_github.md`. The same rule
@@ -221,14 +237,14 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
 - Use sentence case for titles, headings, labels, menu items, and buttons.
 - Insert an empty line between different markups (e.g., after every paragraph, header, list, etc). Example:
 
-    ```md
-    ## Header
+  ```md
+  ## Header
 
-    Paragraph.
+  Paragraph.
 
-    - List item 1
-    - List item 2
-    ```
+  - List item 1
+  - List item 2
+  ```
 
 ### Tables overlapping the TOC
 
@@ -287,12 +303,12 @@ Check specific punctuation rules for [list items](#list-items) below.
 - Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period.
 - Separate list items from explanatory text with a colon (`:`). For example:
 
-    ```md
-    The list is as follows:
+  ```md
+  The list is as follows:
 
-    - First item: this explains the first item.
-    - Second item: this explains the second item.
-    ```
+  - First item: this explains the first item.
+  - Second item: this explains the second item.
+  ```
 
 **Examples:**
 
@@ -504,16 +520,16 @@ To embed a video, follow the instructions below and make sure
 you have your MR reviewed and approved by a technical writer.
 
 1. Copy the code below and paste it into your markdown file.
-  Leave a blank line above and below it. Do NOT edit the code
-  (don't remove or add any spaces, etc).
+   Leave a blank line above and below it. Do NOT edit the code
+   (don't remove or add any spaces, etc).
 1. On YouTube, visit the video URL you want to display. Copy
-  the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`)
-  and replace the video title and link in the line under `<div class="video-fallback">`.
+   the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`)
+   and replace the video title and link in the line under `<div class="video-fallback">`.
 1. On YouTube, click **Share**, then **Embed**.
 1. Copy the `<iframe>` source (`src`) **URL only**
-  (`https://www.youtube.com/embed/VIDEO-ID`),
-  and paste it, replacing the content of the `src` field in the
-  `iframe` tag.
+   (`https://www.youtube.com/embed/VIDEO-ID`),
+   and paste it, replacing the content of the `src` field in the
+   `iframe` tag.
 
 ```html
 leave a blank line here
@@ -595,7 +611,7 @@ In most cases, content considered for a note should be included:
 #### When to use
 
 Use a note when there is a reason that most or all readers who browse the
-section should see the content. That is, if missed, it’s likely to cause 
+section should see the content. That is, if missed, it’s likely to cause
 major trouble for a minority of users or significant trouble for a majority
 of users.
 
@@ -731,24 +747,24 @@ a helpful link back to how the feature was developed.
 - For features that need to declare the GitLab version that the feature was introduced. Text similar
   to the following should be added immediately below the heading as a blockquote:
 
-    ```md
-    > Introduced in GitLab 11.3.
-    ```
+  ```md
+  > Introduced in GitLab 11.3.
+  ```
 
 - Whenever possible, version text should have a link to the issue, merge request, or epic that introduced the feature.
   An issue is preferred over a merge request, and a merge request is preferred over an epic. For example:
 
-    ```md
-    > [Introduced](<link-to-issue>) in GitLab 11.3.
-    ```
+  ```md
+  > [Introduced](<link-to-issue>) in GitLab 11.3.
+  ```
 
 - If the feature is only available in GitLab Enterprise Edition, mention
   the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers)
   the feature is available in:
 
-    ```md
-    > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
-    ```
+  ```md
+  > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
+  ```
 
 ### Removing version text
 
@@ -855,14 +871,14 @@ When there is a list of steps to perform, usually that entails editing the
 configuration file and reconfiguring/restarting GitLab. In such case, follow
 the style below as a guide:
 
-```md
+````md
 **For Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    external_url "https://gitlab.example.com"
-    ```
+   ```ruby
+   external_url "https://gitlab.example.com"
+   ```
 
 1. Save the file and [reconfigure] GitLab for the changes to take effect.
 
@@ -872,17 +888,16 @@ the style below as a guide:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    gitlab:
-      host: "gitlab.example.com"
-    ```
+   ```yaml
+   gitlab:
+     host: "gitlab.example.com"
+   ```
 
 1. Save the file and [restart] GitLab for the changes to take effect.
 
-
 [reconfigure]: path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: path/to/administration/restart_gitlab.md#installations-from-source
-```
+````
 
 In this case:
 
@@ -901,9 +916,9 @@ on this document. Further explanation is given below.
 
 - Every method must have the REST API request. For example:
 
-    ```
-    GET /projects/:id/repository/branches
-    ```
+  ```
+  GET /projects/:id/repository/branches
+  ```
 
 - Every method must have a detailed
   [description of the parameters](#method-description).
@@ -955,7 +970,7 @@ You can use the following fake tokens as examples.
 
 | Token type            | Token value                                                        |
 |:----------------------|:-------------------------------------------------------------------|
-| Private user token    | `<your_access_token>`                                             |
+| Private user token    | `<your_access_token>`                                              |
 | Personal access token | `n671WNGecHugsdEDPsyo`                                             |
 | Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
 | Application secret    | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
@@ -1076,6 +1091,6 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_
 
 [cURL]: http://curl.haxx.se/ "cURL website"
 [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
-[gfm]: https://docs.gitlab.com/ce/user/markdown.html#newlines "GitLab flavored markdown documentation"
+[gfm]: ../../user/markdown.md#newlines "GitLab flavored markdown documentation"
 [ce-1242]: https://gitlab.com/gitlab-org/gitlab-ce/issues/1242
 [doc-restart]: ../../administration/restart_gitlab.md "GitLab restart documentation"