ref: 9ebbf1b054d0e56d708a20bc64f3539440bd5f8a
parent: 2874fc75ce45b17fd4457440e55660d7118fbc46
author: Bjørn Erik Pedersen <[email protected]>
date: Sat Apr 8 12:33:20 EDT 2017
docs: Add docs about output format linking Fixes #3301 Fixes #3302
--- a/docs/content/extras/output-formats.md
+++ b/docs/content/extras/output-formats.md
@@ -49,7 +49,7 @@
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 @@
**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 @@
---
```
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
--- a/docs/content/extras/shortcodes.md
+++ b/docs/content/extras/shortcodes.md
@@ -157,6 +157,11 @@
[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
--- 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": [