Merge branch 'master' into 'reply-to-comment-documentation'reply-to-comment-documentation

# Conflicts:
#   doc/user/discussions/index.md

3 files changed, 23 insertions, 5 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 652fe3ea711..a4da34a50ce 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -511,10 +511,10 @@ Currently, the following tests are in place:
 
 1. `docs lint`: Check that all internal (relative) links work correctly and
    that all cURL examples in API docs use the full switches. It's recommended
-   to [check locally](#previewing-locally) before pushing to GitLab by executing the command
+   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-com/gitlab-docs) directory.
-1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only):
+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.
diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md
index 0aa3c41a225..f2f4f5f0e1c 100644
--- a/doc/development/documentation/site_architecture/global_nav.md
+++ b/doc/development/documentation/site_architecture/global_nav.md
@@ -62,7 +62,7 @@ the consent of one of the technical writers.
 The global nav is built from two files:
 
 - [Data](#data-file)
-- [Layout](#layout-file)
+- [Layout](#layout-file-logic)
 
 The data file feeds the layout with the links to the docs. The layout organizes
 the data among the nav in containers properly [styled](#css-classes).
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 7a3a8f25c2d..0c51d3832aa 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -36,7 +36,7 @@ gem will support all [GFM markup](../../user/markdown.md) in the future. For now
 use regular markdown markup, following the rules on this style guide. For a complete
 Kramdown reference, check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
 Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in
-[`/help`](#gitlab-help).
+[`/help`](index.md#gitlab-help).
 
 ## Content
 
@@ -236,6 +236,24 @@ For other punctuation rules, please refer to the
   E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
   write `Read more about [GitLab Issue Boards](LINK)`.
 
+### Links to confidential issues
+
+Don't link directly to [confidential issues](../../user/project/issues/confidential_issues.md). These will fail for:
+
+- Those without sufficient permissions.
+- Automated link checkers.
+
+Instead:
+
+- Mention in the text that the information is contained in a confidential issue. This will reduce confusion.
+- Provide a link in back ticks (`` ` ``) so that those with access to the issue can easily navigate to it.
+
+Example:
+
+```md
+For more information, see the [confidential issue](https://docs.gitlab.com/ee/user/project/issues/confidential_issues.html) `https://gitlab.com/gitlab-org/gitlab-ce/issues/<issue_number>`.
+```
+
 ### Unlinking emails
 
 By default, all email addresses will render in an email tag on docs.gitlab.com.
@@ -612,7 +630,7 @@ In this case:
 - The code blocks are indented one or more spaces under the list item to render
   correctly.
 - Different highlighting languages are used for each config in the code block.
-- The [references](#references) guide is used for reconfigure/restart.
+- The [GitLab Restart](#gitlab-restart) section is used to explain a required restart/reconfigure of GitLab.
 
 ## API