mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-15 19:24:38 -04:00
Remove duplicate custom output pages
This commit is contained in:
Ryan Watters
parent
59c1bdc5a3
commit
c940f08f84
@ -66,7 +66,7 @@ Three variables per content file are often not enough for effective content mana
|
||||
|
||||
## Lookup Order for Archetypes
|
||||
|
||||
Similar to the lookup order for [templates in the `layouts` directory][lookup], Hugo looks for a default file before falling back on the base/internal archetype. For the `my-first-post.md` example, Hugo looks for the new content's archetype file in the following order:
|
||||
Similar to the [lookup order for templates][lookup] in your `layouts` directory, Hugo looks for a section- or type-specific archetype, then a default archetype, and finally an internal archetype that ships with Hugo. For example, Hugo will look for an archetype for `content/posts/my-first-post.md` in the following order:
|
||||
|
||||
1. `archetypes/posts.md`
|
||||
2. `archetypes/default.md`
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Supported Content Formats
|
||||
linktitle: Formats
|
||||
linktitle: Supported Content Formats
|
||||
description: Markdown is natively supported in Hugo and is parsed by the feature-rich and incredibly speed Blackfriday parse. Hugo also provides support for additional syntaxes (eg, Asciidoc) via external helpers.
|
||||
date: 2017-01-10
|
||||
publishdate: 2017-01-10
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Content Sections
|
||||
linktitle: Sections
|
||||
description: Hugo provides full support for content sections, which according to Hugo's default behavior, should reflect the architecture of the output website sections as well.
|
||||
description: Hugo provides full support for content sections, which according to Hugo's default behavior, will reflect the architecture of the rendered website.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
|
||||
@ -9,8 +9,8 @@ lastmod: 2017-03-31
|
||||
menu:
|
||||
docs:
|
||||
parent: "content-management"
|
||||
weight: 25
|
||||
weight: 25 #rem
|
||||
weight: 35
|
||||
weight: 35 #rem
|
||||
categories: [content management]
|
||||
tags: [markdown,content,shortcodes]
|
||||
draft: false
|
||||
@ -428,4 +428,4 @@ To learn more about creating custom shortcodes, see the [shortcode template docu
|
||||
[Speaker Deck]: https://speakerdeck.com/
|
||||
[templatessection]: /templates/
|
||||
[Vimeo]: https://vimeo.com/
|
||||
[YouTube Videos]: https://www.youtube.com/
|
||||
[YouTube Videos]: https://www.youtube.com/
|
||||
|
||||
@ -53,4 +53,4 @@ https://github.com/spf13/hugo/issues
|
||||
|
||||
The Official Hugo Twitter Account: [@GoHugoIO](https://twitter.com/GoHugoIO)
|
||||
Steve Francia: [@spf13](https://twitter.com/spf13).
|
||||
Bjørn Erik Pedersen: [@bepsays](https://twitter.com/bepsays)
|
||||
Bjørn Erik Pedersen: [@bepsays](https://twitter.com/bepsays)
|
||||
|
||||
@ -137,4 +137,4 @@ The following shows how you can override both the `"main"` and `"title"` block a
|
||||
[hugolists]: /templates/lists
|
||||
[lookup]: /templates/lookup-order/
|
||||
[rendering the section]: /templates/section-templates/
|
||||
[singletemplate]: /templates/single-page-templates/
|
||||
[singletemplate]: /templates/single-page-templates/
|
||||
|
||||
@ -1,143 +0,0 @@
|
||||
---
|
||||
title: Custom Outputs
|
||||
linktitle: Custom Output Templates
|
||||
description: Hugo can output content in multiple formats to make quick work of
|
||||
date: 2017-03-22
|
||||
publishdate: 2017-03-22
|
||||
lastmod: 2017-03-22
|
||||
categories: [content management]
|
||||
tags: ["amp","outputs"]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templatesd"
|
||||
weight: 100
|
||||
quicklinks:
|
||||
weight: 100 #rem
|
||||
draft: false
|
||||
aliases: [/extras/custom-output-types/,/content-management/custom-outputs/]
|
||||
toc: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Media Type
|
||||
|
||||
We add a media type (also known as MIME type and content type). This is a two-part identifier for file formats and format contents transmitted on the Internet.
|
||||
|
||||
For Hugo's use cases, we use the top-level type name/subtype name + suffix. An example would be `application/json+json`.
|
||||
|
||||
Users can define their own media types by using them in an `Output Format` definition (see below).
|
||||
|
||||
The full set of media types will be registered in Go's `mime` package, so they will be recognised by Hugo's development server.
|
||||
|
||||
## Output Format
|
||||
|
||||
A `Page` in Hugo can be rendered to multiple representations on the file system: All will get an HTML page and some of them will get an RSS page (home page, sections etc.).
|
||||
|
||||
When we now create a more formal definition for these output representations, the built-ins mentioned above will be the standard set that can be extended.
|
||||
|
||||
So an `OutputFormat`:
|
||||
|
||||
```
|
||||
OutputFormat:
|
||||
Name
|
||||
MediaType
|
||||
Path
|
||||
IsPlainText (default false)
|
||||
Protocol
|
||||
|
||||
# And then some optional options
|
||||
NoUglyURLs
|
||||
URI # Turn index.x into somevalue.x (similar to `RSSUri` in Hugo `0.19`)
|
||||
```
|
||||
|
||||
So:
|
||||
|
||||
* `Name`: The key.
|
||||
* `Path` - defaults to "", which is the root. Multiple outputs to the same suffix must be separated with a path, ie. "amp" for AMP output.
|
||||
* `IsPlainText`: Whether to parse the templates with `text/template` or `html/template`.
|
||||
* `Protocol`: I.e. `webcal://` for calendar files. Defaults to the `baseURL` protocol.
|
||||
|
||||
## Standard Output Formats
|
||||
|
||||
So, according to the above, the current Hugo will look like this:
|
||||
|
||||
| Name | MediaType | Path | IsPlainText
|
||||
| -------------:|-------------| -----|-----|
|
||||
| HTML | text/html+html | "" | false |
|
||||
| RSS | application/rss+xml | "" | false |
|
||||
|
||||
## Layouts
|
||||
|
||||
The current situation (slightly simplified):
|
||||
|
||||
| Kind | Layouts
|
||||
| ----------------:|:-------------|
|
||||
| home | index.html, _default/list.html |
|
||||
| section | section/SECTION.html, SECTION/list.html, _default/section.html, _default/list.html |
|
||||
| taxonomy | taxonomy/SINGULAR.html,_default/taxonomy.html, _default/list.html |
|
||||
| taxonomyTerm |taxonomy/SINGULAR.terms.html, _default/terms.html|
|
||||
| page | TYPE/LAYOUT.html, _default/LAYOUT.html, _default/single.html|
|
||||
|
||||
The above is what the Output Format `HTML` must resolve to.
|
||||
|
||||
So, let us make up some other Output Formats and see how that will have to look:
|
||||
|
||||
| Name | MediaType | Path | IsPlainText
|
||||
| -------------:|-------------| -----|-----|
|
||||
| JSON | application/json+json | "" | true |
|
||||
| AMP | text/html+html | amp | false |
|
||||
|
||||
Both of the above can be handled if we add both `Name` and the `Suffix` to the mix. Let us use the home page as an example:
|
||||
|
||||
| Type | Layouts
|
||||
| -----------:|:-------------|
|
||||
| JSON | index.json.json, index.json, _default/list.json.json, _default/list.json
|
||||
| AMP | index.amp.html, index.html, _default/list.amp.html, _default/list.html
|
||||
|
||||
* The above adds the lower-case `Name` as a prefix to the lookup path.
|
||||
* The above also assumes that it makes sense to edit the templates with the same suffix as the end result (.html, .json etc.).
|
||||
|
||||
TODO: RSS, 404 etc.
|
||||
|
||||
## Examples
|
||||
|
||||
`config.toml`:
|
||||
|
||||
```
|
||||
# Add some custom output type definitions:
|
||||
[[outputFormats]]
|
||||
name = "Calendar"
|
||||
mediaType = "text/calendar+ics"
|
||||
protocol = "webcal://"
|
||||
isPlainText = true
|
||||
|
||||
[[outputFormats]]
|
||||
name = "JSON"
|
||||
mediaType = "application/json" # Will get its file suffix from the sub-type, i.e. "json"
|
||||
isPlainText = true
|
||||
|
||||
[[outputFormats]]
|
||||
name = "AMP"
|
||||
mediaType = "text/html"
|
||||
path = "amp"
|
||||
|
||||
```
|
||||
|
||||
Note that Hugo well hard code a predefined list of the most common output types (not sure what that would be, suggestions welcome) with the obvious identifiers and sensible defaults: So whenever you want them, you can just say "json, yaml, amp ..." etc.
|
||||
|
||||
Page front matter:
|
||||
|
||||
```
|
||||
title = "My Home Page"
|
||||
outputs = ["html", "rss", "json", "calendar", "amp" ]
|
||||
```
|
||||
|
||||
About the `outputs` in the page front matter:
|
||||
|
||||
* If none is provided, it defaults to the current behaviour (i.e. HTML for all pages and RSS for the list pages)
|
||||
* If some are provided, no defaults will be added. So, if you want the plain HTML representation, you must be explicit. This way you can have the home page as JSON only if you want.
|
||||
* The names used are case-insensitive and must match either a definition in `config.toml` or the standard set.
|
||||
|
||||
{{% note %}}
|
||||
It should also be possible to set a list of default output formats in `config.toml`, avoiding the need to repeat the `outputs` list in thousands of pages, with a way to restrict each type to a set of pages (using `Kind`, probably).
|
||||
{{% /note %}}
|
||||
@ -494,4 +494,4 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
|
||||
[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
|
||||
[where]: /functions/where/
|
||||
[with]: /functions/with/
|
||||
[godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function"
|
||||
[godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function"
|
||||
|
||||
@ -104,4 +104,4 @@ The above is all that's needed. But if you want custom menu items, e.g. changing
|
||||
|
||||
{{% note %}}
|
||||
The `identifier` *must* match the section name.
|
||||
{{% /note %}}
|
||||
{{% /note %}}
|
||||
|
||||
@ -422,4 +422,4 @@ Using `first` and `where` together can be very powerful:
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
[views]: /templates/views/
|
||||
[views]: /templates/views/
|
||||
|
||||
@ -5,19 +5,20 @@ description: Hugo can output content in multiple formats, including calendar eve
|
||||
date: 2017-03-22
|
||||
publishdate: 2017-03-22
|
||||
lastmod: 2017-03-22
|
||||
categories: [content management]
|
||||
tags: ["amp","outputs"]
|
||||
categories: [templates]
|
||||
tags: ["amp","outputs","rss"]
|
||||
menu:
|
||||
main:
|
||||
parent: "Content Management"
|
||||
docs:
|
||||
parent: "templates"
|
||||
weight: 18
|
||||
weight: 18
|
||||
sections_weight: 18
|
||||
draft: false
|
||||
aliases: [/templates/outputs/,/extras/output-formats/,/doc/output-formats/,/doc/custom-output/]
|
||||
aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
Hugo `0.20` introduced the powerful feature **custom output formats**; Hugo isn't just "static HTML with an added RSS feed" anymore. *Say hello* to calendars, e-book formats, Google AMP, and JSON search indexes, to name a few.
|
||||
In addition to the default behavior of generating RSS feeds and HTML pages, Hugo can generate any text-based output, including e-book formats, Google AMP, and JSON search indexes, to name a few.
|
||||
|
||||
This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs.
|
||||
|
||||
@ -213,4 +214,4 @@ Plain text partials can currently only be included in plain text templates, and
|
||||
[config]: /getting-started/configuration/
|
||||
[lookup order]: /templates/lookup/
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
[partials]: /templates/partials/
|
||||
[partials]: /templates/partials/
|
||||
|
||||
1632
data/docs.json
Normal file
1632
data/docs.json
Normal file
File diff suppressed because it is too large
Load Diff
22
layouts/shortcodes/datatable.html
Normal file
22
layouts/shortcodes/datatable.html
Normal file
@ -0,0 +1,22 @@
|
||||
{{ $package := (index .Params 0) }}
|
||||
{{ $listname := (index .Params 1) }}
|
||||
{{ $list := (index (index .Site.Data.docs $package) $listname) }}
|
||||
{{ $fields := after 2 .Params }}
|
||||
|
||||
<table class="table table-bordered">
|
||||
<tr>
|
||||
{{ range $fields }}
|
||||
<th>{{ . }}</th>
|
||||
{{ end }}
|
||||
</tr>
|
||||
{{ range $list }}
|
||||
<tr>
|
||||
{{ range $k, $v := . }}
|
||||
{{ $.Scratch.Set $k $v }}
|
||||
{{ end }}
|
||||
{{ range $fields }}
|
||||
<td>{{ $.Scratch.Get . }}</td>
|
||||
{{ end }}
|
||||
</tr>
|
||||
{{ end }}
|
||||
</table>
|
||||
Loading…
x
Reference in New Issue
Block a user