Cleaned Use of ref and relref section, added refs of index.md and _in… (#1744)

* Cleaned Use of ref and relref section, added refs of index.md and _index.md

See https://discourse.gohugo.io/t/ref-relref-error/18904/3

Co-authored-by: Joe Mooring <joe@mooring.com>

1 files changed, 40 insertions, 13 deletions

diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md
index 5ec7dc545..151b91514 100644
--- a/content/en/content-management/cross-references.md
+++ b/content/en/content-management/cross-references.md
@@ -17,15 +17,35 @@ toc: true
 
 The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
 
-## Use `ref` and `relref`
+## Use of `ref` and `relref`
 
-```go-html-template
-{{</* ref "document" */>}}
-{{</* ref "document#anchor" */>}}
-{{</* ref "document.md" */>}}
-{{</* ref "document.md#anchor" */>}}
-{{</* ref "#anchor" */>}}
-{{</* ref "/blog/my-post" */>}}
+The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
+
+```
+.
+└── content
+    ├── about
+    |   ├── _index.md
+    |   └── credits.md
+    ├── pages
+    |   ├── document1.md
+    |   └── document2.md    // has anchor #anchor
+    ├── products
+    |   └── index.md
+    └── blog
+        └── my-post.md
+```
+
+The pages can be referenced as follows:
+
+
+```text
+{{</* ref "document2" */>}}             // <- From pages/document1.md, relative path
+{{</* ref "document2#anchor" */>}}      
+{{</* ref "document2.md" */>}}          
+{{</* ref "document2.md#anchor" */>}}   
+{{</* ref "#anchor" */>}}               // <- From pages/document2.md
+{{</* ref "/blog/my-post" */>}}         // <- From anywhere, absolute path
 {{</* ref "/blog/my-post.md" */>}}
 {{</* relref "document" */>}}
 {{</* relref "document.md" */>}}
@@ -33,15 +53,22 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
 {{</* relref "/blog/my-post.md" */>}}
 ```
 
-To generate a hyperlink using `ref` or `relref` in markdown:
+index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder:
 
-```md
-[About]({{</* ref "/page/about" */>}} "About Us")
+```text
+{{</* ref "/about" */>}}             // <- References /about/_index.md
+{{</* ref "/about/_index" */>}}      //    Raises REF_NOT_FOUND error
+{{</* ref "/about/credits.md" */>}}  // <- References /about/credits.md
+
+{{</* ref "/products" */>}}          // <- References /products/index.md
+{{</* ref "/products/index" */>}}    // <- References /products/index.md
 ```
 
-The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.
+To generate a hyperlink using `ref` or `relref` in markdown:
 
-**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
+```text
+[About]({{</* ref "/about" */>}} "About Us")
+```
 
 Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.