diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2017-04-08 16:33:20 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2017-04-08 16:33:20 +0200 |
commit | 9ebbf1b054d0e56d708a20bc64f3539440bd5f8a (patch) | |
tree | 9c13d9102d0a388b57d45af745becf2d8d330d72 /docs | |
parent | 2874fc75ce45b17fd4457440e55660d7118fbc46 (diff) |
docs: Add docs about output format linking
Fixes #3301
Fixes #3302
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/extras/output-formats.md | 29 | ||||
-rw-r--r-- | docs/content/extras/shortcodes.md | 5 | ||||
-rw-r--r-- | docs/data/docs.json | 21 |
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": [ |