Merge branch '16568-document-wiki-linking-behavior' into 'master'

Add help document describing intended wiki linking behavior

Related to #16568
Closes #18019

- This documents the _intended_ behaviour of linking to wiki pages/files.

## TODO

- [x] Respond to @rymai's comments
    - [x] Use `succeed`
    - [x] Shouldn't this be <wiki_root>/miscellaneous.md here?
    - [x] what happens for file links that starts with a `/`?

See merge request !4372

5 files changed, 97 insertions, 10 deletions

diff --git a/app/views/projects/wikis/_form.html.haml b/app/views/projects/wikis/_form.html.haml
index 797a1a59e9f..643f7c589e6 100644
--- a/app/views/projects/wikis/_form.html.haml
+++ b/app/views/projects/wikis/_form.html.haml
@@ -18,9 +18,14 @@
       .error-alert
 
       .help-block
-        To link to a (new) page, simply type
-        %code [Link Title](page-slug)
-        \.
+        = succeed '.' do
+          To link to a (new) page, simply type
+          %code [Link Title](page-slug)
+
+        = succeed '.' do
+          More examples are in the
+          = link_to 'documentation', help_page_path("user/project/markdown", anchor: "wiki-specific-markdown")
+
   .form-group
     = f.label :commit_message, class: 'control-label'
     .col-sm-10= f.text_field :message, class: 'form-control', rows: 18
diff --git a/doc/README.md b/doc/README.md
index b5b377822e6..751e685b19b 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -9,7 +9,7 @@
 - [GitLab Basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab.
 - [Importing to GitLab](workflow/importing/README.md).
 - [Importing and exporting projects between instances](user/project/settings/import_export.md).
-- [Markdown](markdown/markdown.md) GitLab's advanced formatting system.
+- [Markdown](user/project/markdown.md) GitLab's advanced formatting system.
 - [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab.
 - [Permissions](user/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
 - [Profile Settings](profile/README.md)
diff --git a/doc/markdown/img/logo.png b/doc/user/project/img/markdown_logo.png
index 05c8b0d0ccf..05c8b0d0ccf 100644
--- a/doc/markdown/img/logo.png
+++ b/doc/user/project/img/markdown_logo.png
diff --git a/doc/markdown/img/video.mp4 b/doc/user/project/img/markdown_video.mp4
index 1fc478842f5..1fc478842f5 100644
--- a/doc/markdown/img/video.mp4
+++ b/doc/user/project/img/markdown_video.mp4
diff --git a/doc/markdown/markdown.md b/doc/user/project/markdown.md
index c6c7ac81c0d..7fe96e67dbb 100644
--- a/doc/markdown/markdown.md
+++ b/doc/user/project/markdown.md
@@ -28,6 +28,13 @@
 * [Line Breaks](#line-breaks)
 * [Tables](#tables)
 
+**[Wiki-Specific Markdown](#wiki-specific-markdown)**
+
+* [Wiki - Direct page link](#wiki-direct-page-link)
+* [Wiki - Direct file link](#wiki-direct-file-link)
+* [Wiki - Hierarchical link](#wiki-hierarchical-link)
+* [Wiki - Root link](#wiki-root-link)
+
 **[References](#references)**
 
 ## GitLab Flavored Markdown (GFM)
@@ -331,11 +338,11 @@ The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`.
 
     Here's a sample video:
 
-    ![Sample Video](img/video.mp4)
+    ![Sample Video](img/markdown_video.mp4)
 
 Here's a sample video:
 
-![Sample Video](img/video.mp4)
+![Sample Video](img/markdown_video.mp4)
 
 # Standard Markdown
 
@@ -533,24 +540,24 @@ will point the link to `wikis/style` when the link is inside of a wiki markdown
     Here's our logo (hover to see the title text):
 
     Inline-style:
-    ![alt text](img/logo.png)
+    ![alt text](img/markdown_logo.png)
 
     Reference-style:
     ![alt text1][logo]
 
-    [logo]: img/logo.png
+    [logo]: img/markdown_logo.png
 
 Here's our logo:
 
 Inline-style:
 
-![alt text](img/logo.png)
+![alt text](img/markdown_logo.png)
 
 Reference-style:
 
 ![alt text][logo]
 
-[logo]: img/logo.png
+[logo]: img/markdown_logo.png
 
 ## Blockquotes
 
@@ -692,6 +699,81 @@ By including colons in the header row, you can align the text within that column
 | Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
 | Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
 
+
+## Wiki-specific Markdown
+
+The following examples show how links inside wikis behave.
+
+### Wiki - Direct page link
+
+A link which just includes the slug for a page will point to that page,
+_at the base level of the wiki_.
+
+This snippet would link to a `documentation` page at the root of your wiki:
+
+```markdown
+[Link to Documentation](documentation)
+```
+
+### Wiki - Direct file link
+
+Links with a file extension point to that file, _relative to the current page_.
+
+If this snippet was placed on a page at `<your_wiki>/documentation/related`,
+it would link to `<your_wiki>/documentation/file.md`:
+
+```markdown
+[Link to File](file.md)
+```
+
+### Wiki - Hierarchical link
+
+A link can be constructed relative to the current wiki page using `./<page>`,
+`../<page>`, etc.
+
+- If this snippet was placed on a page at `<your_wiki>/documentation/main`,
+  it would link to `<your_wiki>/documentation/related`:
+
+	```markdown
+	[Link to Related Page](./related)
+	```
+
+- If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
+  it would link to `<your_wiki>/documentation/main`:
+
+	```markdown
+	[Link to Related Page](../main)
+	```
+
+- If this snippet was placed on a page at `<your_wiki>/documentation/main`,
+  it would link to `<your_wiki>/documentation/related.md`:
+
+	```markdown
+	[Link to Related Page](./related.md)
+	```
+
+- If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
+  it would link to `<your_wiki>/documentation/main.md`:
+
+	```markdown
+	[Link to Related Page](../main.md)
+	```
+
+### Wiki - Root link
+
+A link starting with a `/` is relative to the wiki root.
+
+- This snippet links to `<wiki_root>/documentation`:
+
+	```markdown
+	[Link to Related Page](/documentation)
+	```
+
+- This snippet links to `<wiki_root>/miscellaneous.md`:
+
+	```markdown
+	[Link to Related Page](/miscellaneous.md)
+	```
 ## References
 
 - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).