Preface
This article is intended for beginner.
Goal: Custom content output example: json, text, yaml
1: Prepare
We can make a custom content for archiving.
Content: Archives
Remember our last archive page ?
-
- content/pages/archives.md
- gitlab.com/…/pages/archives.md
+++
type = "archives"
title = "Archives by Date"
+++
Instead of just html page, we will enhanced this archive, to output different custom content type.
+++
type = "archives"
title = "Archives by Date"
outputs = ["html", "txt", "yml", "json"]
+++
Why do we even need these custom outputs ?
-
The HTML, we already seen in previous chapter
-
The JSON artefact as a search data source for lunr json.
-
The YAML artefact to build data source for related pages, something that you usually seen in wordpress posts.
-
The plain text artefact, is just another demo. Because not every browser can handle yaml type, I use the plain fo easiness reason
Main Configuration
In order to do this, we need to make a little adjustment in our beloved config file. Making some new definition in config.toml.
-
- config.toml
- gitlab.com/…/config.toml
# An example of Hugo site for tutorial purpose.
...
[mediaTypes]
[mediaTypes."text/yaml"]
suffix = "yml"
[outputFormats]
[outputFormats.yml]
baseName = "index"
mediaType = "text/yaml"
isPlainText = true
[outputFormats.txt]
baseName = "index"
mediaType = "text/plain"
isPlainText = true
-
JSON is already a standard output type. So we don’t need to change anything.
-
On the other hand, we need to define YAML mediaTypes.
-
However, we still need to define txt output formats.
Note that, newer Hugo require suffixes, instead of suffix.
2: JSON
Reading
Preparation
We need these two artefacts.
$ touch themes/tutor-04/layouts/archives/baseof.json.json
$ touch themes/tutor-04/layouts/archives/single.json.json
We have already this archives.md, no need to recreate.
-
- content/pages/archives.md
- gitlab.com/…/pages/archives.md
$ cat content/pages/archives.md
Layout: Baseof: JSON
Our base is as simply as this below.
-
- themes/tutor-04/layouts/archives/baseof.json.json
- gitlab.com/…/layouts/archives/baseof.json.json
{{ block "main" .}}{{ end }}
Layout: Single: JSON
The detail is in
-
- themes/tutor-04/layouts/archives/single.json.json
- gitlab.com/…/layouts/archives/single.json.json
{{ define "main" }}
{{- $posts := where .Site.Pages "Type" "post" -}}
{{- $postCount := len $posts -}}
{
{{ range $i, $e := $posts }}
"{{ .URL | urlize }}": {
"title": {{ jsonify $e.Title }},
"content": {{ jsonify ($e.Params.excerpt | default $e.Summary) }},
"url": {{ jsonify .Permalink }},
"author": {{ jsonify $e.Params.author }},
"category": {{ jsonify $e.Section }}
}
{{- if not (eq (add $i 1) $postCount) }},{{ end -}}
{{ end }}
}
{{ end }}
Server Output: Browser
Now you can see JSON output in your favorite browser.
- http://localhost:1313/pages/archives/index.json
This will produce something similar as shown below:
{
"/quotes/2018/09/13/mothers-no-crying-in-baseball/": {
"title": "Mothers - No Crying in Baseball",
"content": "There\u0026rsquo;s no crying in baseball. Try to understand.",
"url": "http://localhost:1313/quotes/2018/09/13/mothers-no-crying-in-baseball/",
"author": "epsi",
"category": "quotes"
},
"/quotes/2018/09/07/julian-baker-something/": {
...
},
...
}
Modern browser automatically format, the JSON output in nice view collapsable view.
3: Text and YAML
Preparation
We need these two artefacts.
$ touch themes/tutor-04/layouts/archives/baseof.yml.yml
$ touch themes/tutor-04/layouts/archives/single.yml.yml
$ touch themes/tutor-04/layouts/archives/baseof.txt.txt
$ touch themes/tutor-04/layouts/archives/single.txt.txt
We have already the archives.md.
Layout: Baseof: Text and YAML
Our base for both yml and txt, have the same content.
-
- themes/tutor-04/layouts/archives/baseof.yml.yml
- gitlab.com/…/layouts/archives/baseof.yml.yml
-
- themes/tutor-04/layouts/archives/baseof.txt.txt
- gitlab.com/…/layouts/archives/baseof.txt.txt
Our base for both yml and txt, are as simply as this below.
{{ block "main" .}}{{ end }}
Layout: Single: Text and YAML
The detail are also the same for both
-
- themes/tutor-04/layouts/archives/single.yml.yml
- gitlab.com/…/layouts/archives/single.yml.yml
-
- themes/tutor-04/layouts/archives/single.txt.txt
- gitlab.com/…/layouts/archives/single.txt.txt
You can create anything that suit your own needs.
{{- define "main" -}}
# Helper for related links
# {{ .Title }}
{{ range (where .Site.Pages "Type" "post") }}
{{- if .Date }}
- id: {{ .Date.Format "06010204" }}
title: "{{ .Title }}"
url: {{ .URL }}
{{ end -}}
{{ end }}
{{- end -}}
Server Output: Browser: Text
Now you can see plain text output in your favorite browser.
- http://localhost:1313/pages/archives/index.txt
This will produce something like:
# Helper for related links
# Archives by Date
- id: 18091335
title: "Mothers - No Crying in Baseball"
url: /quotes/2018/09/13/mothers-no-crying-in-baseball/
- id: 18090735
title: "Julian Baker - Something"
url: /quotes/2018/09/07/julian-baker-something/
So we can easily copy paste the output to any text editor.
Server Output: Browser: YAML
Now you can download YAML output in your favorite browser.
- http://localhost:1313/pages/archives/index.yml
Since no handle for text/yaml in browser, the browser will ask if it should be downloaded
So we can easily copy downloaded files using any file manager.
4: Summary
Since we have four type, we have four single layouts, as shown in tree below.
$ tree themes/tutor-04/layouts/archives/
themes/tutor-04/layouts/archives/
├── baseof.json.json
├── baseof.txt.txt
├── baseof.yml.yml
├── list.html
├── single.html
├── single.json.json
├── single.txt.txt
└── single.yml.yml
What is Next ?
There are, some interesting topic about Hugo miscellanous range loop. Consider continue reading [ Hugo - Sidebar ].
Thank you for reading.