docs: Add docs about output format linking

Fixes #3301
Fixes #3302

3 files changed, 47 insertions, 8 deletions

diff --git a/docs/content/extras/output-formats.md b/docs/content/extras/output-formats.md
index 10d6a3bea..784a692d5 100644
--- a/docs/content/extras/output-formats.md
+++ b/docs/content/extras/output-formats.md
@@ -49,7 +49,7 @@ Given a media type and some additional configuration, you get an `Output Format`
 
 This is the full set of built-in output formats in Hugo:
 
-{{< datatable "output" "formats" "Name" "MediaType" "Path" "BaseName" "Rel" "Protocol" "IsPlainText" "IsHTML" "NoUgly">}}
+{{< datatable "output" "formats" "Name" "MediaType" "Path" "BaseName" "Rel" "Protocol" "IsPlainText" "IsHTML" "NoUgly" "NotAlternative">}}
 
 **Note:**
 
@@ -84,6 +84,7 @@ Field | Description
 **IsPlainText** | Use Go's plain text templates parser for the templates. **Default:** _false_.
 **IsHTML** | Used in situations only relevant for `HTML` type of formats, page aliases being one example.|
 **NoUgly** | If `uglyURLs` is enabled globally, this can be used to turn it off for a given output format. **Default:** _false_.
+**NotAlternative** |  Enable if it doesn't make sense to include this format in an the `.AlternativeOutputFormats` format listing on `Page`, `CSS` being one good example. Note that we use the term "alternative" and not "alternate" here, as it does not necessarily replace the other format, it is an alternative representation.  **Default:** _false_.
 
 
 ## Output Formats for your pages
@@ -118,6 +119,32 @@ A `Page` with `YAML` front matter defining some output formats for that `Page`:
  ---
  ```
  Note that the names used for the output formats are case insensitive.
+ 
+## Link to Output Formats
+ 
+ `Page` has both  `.OutputFormats` (all formats including the current) and `.AlternativeOutputFormats`, the latter useful for creating a `link rel` list in your `head` section:
+ 
+ ```
+ {{ range .AlternativeOutputFormats -}}
+ <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+ {{ end -}}
+  ```
+  
+Note that `.Permalink` on `RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). 
+
+This is how you link to a given output format:
+
+```
+{{ with  .OutputFormats.Get "json" -}}
+<a href="{{ .Permalink }}">{{ .Name }}</a>
+{{- end }}
+```
+From content files, you can use the `ref` or `relref` shortcodes:
+
+```
+[Neat]({{</* ref "blog/neat.md" "amp" */>}})
+[Who]({{</* relref "about.md#who" "amp" */>}})
+```
 
 ## Templates for your Output Formats
 
diff --git a/docs/content/extras/shortcodes.md b/docs/content/extras/shortcodes.md
index b31b2b4ca..52a2f2a36 100644
--- a/docs/content/extras/shortcodes.md
+++ b/docs/content/extras/shortcodes.md
@@ -157,6 +157,11 @@ Read more on [cross-references]({{% ref "extras/crossreferences.md" %}}).
 
     [Neat]({{</* ref "blog/neat.md" */>}})
     [Who]({{</* relref "about.md#who" */>}})
+    
+If the page exists in multiple [output formats]({{< relref "extras/output-formats.md" >}}),  `ref` or `relref` can be used with a output format name:
+ 
+     [Neat]({{</* ref "blog/neat.md" "amp" */>}})
+ 
 
 #### Example Output
 
diff --git a/docs/data/docs.json b/docs/data/docs.json
index 6bcf6ab3d..12bda6e3c 100644
--- a/docs/data/docs.json
+++ b/docs/data/docs.json
@@ -77,7 +77,8 @@
         "Protocol": "",
         "IsPlainText": false,
         "IsHTML": true,
-        "NoUgly": false
+        "NoUgly": false,
+        "NotAlternative": false
       },
       {
         "MediaType": "text/css+css",
@@ -88,7 +89,8 @@
         "Protocol": "",
         "IsPlainText": true,
         "IsHTML": false,
-        "NoUgly": false
+        "NoUgly": false,
+        "NotAlternative": true
       },
       {
         "MediaType": "text/csv+csv",
@@ -99,7 +101,8 @@
         "Protocol": "",
         "IsPlainText": true,
         "IsHTML": false,
-        "NoUgly": false
+        "NoUgly": false,
+        "NotAlternative": false
       },
       {
         "MediaType": "text/calendar+ics",
@@ -110,7 +113,8 @@
         "Protocol": "webcal://",
         "IsPlainText": true,
         "IsHTML": false,
-        "NoUgly": false
+        "NoUgly": false,
+        "NotAlternative": false
       },
       {
         "MediaType": "text/html+html",
@@ -121,7 +125,8 @@
         "Protocol": "",
         "IsPlainText": false,
         "IsHTML": true,
-        "NoUgly": false
+        "NoUgly": false,
+        "NotAlternative": false
       },
       {
         "MediaType": "application/json+json",
@@ -132,7 +137,8 @@
         "Protocol": "",
         "IsPlainText": true,
         "IsHTML": false,
-        "NoUgly": false
+        "NoUgly": false,
+        "NotAlternative": false
       },
       {
         "MediaType": "application/rss+xml",
@@ -143,7 +149,8 @@
         "Protocol": "",
         "IsPlainText": false,
         "IsHTML": false,
-        "NoUgly": true
+        "NoUgly": true,
+        "NotAlternative": false
       }
     ],
     "layouts": [