Where to Discuss?

Local Group


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 ?

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.

# An example of Hugo site for tutorial purpose.


    suffix = "yml"

    baseName    = "index"
    mediaType   = "text/yaml"
    isPlainText = true
    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.




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, no need to recreate.

$ cat content/pages/

Layout: Baseof: JSON

Our base is as simply as this below.

{{ block "main" .}}{{ end }}

Layout: Single: JSON

The detail is in

{{ 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 $ }},
      "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.

Hugo: JSON Content Type

3: Text and YAML


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

Layout: Baseof: Text and YAML

Our base for both yml and txt, have the same content.

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

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/

Hugo: Text Content Type

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

Hugo: YAML Content Type

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/
├── baseof.json.json
├── baseof.txt.txt
├── baseof.yml.yml
├── list.html
├── single.html
├── single.json.json
├── single.txt.txt
└── single.yml.yml

Hugo: Archive Summary

What is Next ?

There are, some interesting topic about Hugo miscellanous range loop. Consider continue reading [ Hugo - Sidebar ].

Thank you for reading.