Commit 73772eca authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

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
parents a8851a3c fc492c89
......@@ -18,9 +18,14 @@
.error-alert
.help-block
= 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
......
......@@ -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)
......
......@@ -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).
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment