Output Formats

Hugo can display your content in different formats like HTML, JSON, Google AMP, etc. To do this, templates must be provided.

The Relearn theme by default comes with templates for HTML, HTML for print, RSS and Markdown. If this is not enough, this page describes how you can create your own output formats.

If you instead just want to customize the layout of an existing output format, the theme got you covered as well.

Creating an Output Format

Suppose you want to be able to send your articles as HTML formatted emails. The pages of these format need to be self contained so an email client can display the content without loading any further assets.

Therefore we add a new output format called email that outputs HTML and assembles a completely custom HTML document structure.

  1. Add the output format to your hugo.toml

    hugo.
    [outputFormats]
  [outputFormats.email]
    baseName = 'index.email'
    isHTML = true
    mediaType = 'text/html'
    name = 'email'
    noUgly = true
    permalinkable = false

[outputs]
  home = ['html', 'rss', 'email']
  page = ['html', 'rss', 'email']
  section = ['html', 'rss', 'email']
    outputFormats:
  email:
    baseName: index.email
    isHTML: true
    mediaType: text/html
    name: email
    noUgly: true
    permalinkable: false
outputs:
  home:
  - html
  - rss
  - email
  page:
  - html
  - rss
  - email
  section:
  - html
  - rss
  - email
    {
   "outputFormats": {
      "email": {
         "baseName": "index.email",
         "isHTML": true,
         "mediaType": "text/html",
         "name": "email",
         "noUgly": true,
         "permalinkable": false
      }
   },
   "outputs": {
      "home": [
         "html",
         "rss",
         "email"
      ],
      "page": [
         "html",
         "rss",
         "email"
      ],
      "section": [
         "html",
         "rss",
         "email"
      ]
   }
}

  2. Create a file layouts/_default/baseof.email.html

    ​
    <!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
  <style type="text/css">
    /* add some styles here to make it pretty */
  </style>
  <style type="text/css">
    /* add chroma style for code highlighting */
    {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
  </style>
</head>
<body>
  <main>
    {{- block "body" . }}{{ end }}
  </main>
</body>
</html>

    The marked block construct above will cause the display of the article with a default HTML structure. In case you want to keep it really simple, you could replace this line with just {{ .Content }}.

  3. Optional: create a file layouts/_default/views/article.email.html

    In our case, we want to display a disclaimer in front of every article. To do this we have to define the output of an article ourself and rely on the above block statement to call our template.

    ​
    <article class="email">
  <blockquote>
    View this article on <a href="http://example.com{{ .RelPermalink }}">our website</a>
  </blockquote>
  {{ partial "article-content.html" . }}
</article>

  4. Optional: create a file layouts/_default/_markup_/render-image.email.html

    In our case, we want to convert each image into a base 64 encoded string to display it inline in the email without loading external assets.

    ​
    {{- $dest_url := urls.Parse .Destination }}
{{- $dest_path := path.Clean ($dest_url.Path) }}
{{- $img := .Page.Resources.GetMatch $dest_path }}
{{- if and (not $img) .Page.File }}
  {{- $path := path.Join .Page.File.Dir $dest_path }}
  {{- $img = resources.Get $path }}
{{- end }}
{{- if $img }}
  {{- if (gt (len $img.Content) 1000000000) }}
    {{/* currently resizing does not work for animated gifs :-( */}}
    {{- $img = $img.Resize "600x webp q75" }}
  {{- end }}
  <img src="data:{{ $img.MediaType }};base64,{{ $img.Content | base64Encode }}">
{{- end }}

Partials

For HTML Output Formats

If you want to keep the general HTML framework and only change specific parts, you can provide these files for your output format independently of one another:

  • layouts/_default/views/article.<FORMAT>.html: Optional: Controls how a page’s content and title are displayed
  • layouts/_default/views/body.<FORMAT>.html: Optional: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
  • layouts/_default/views/menu.<FORMAT>.html: Optional: Defines the sidebar menu layout
  • layouts/_default/views/storeOutputFormat.<FORMAT>.html: Optional: Stores the output format name for use in the framework to let the body element been marked with an output format specific class

For a real-world example, check out the print output format implementation

For Non-HTML Output Formats

  • layouts/_default/list.<FORMAT>: Mandatory: Controls how sections are displayed
  • layouts/_default/single.<FORMAT>: Mandatory: Controls how pages are displayed
  • layouts/_default/baseof.<FORMAT>: Optional: Controls how sections and pages are displayed. If not provided, you have to provide your implementation in list.<FORMAT> and single.<FORMAT>

For a real-world example, check out the markdown output format implementation

Migration to Relearn 7 or higher

Previous to Relearn 7, HTML output formats did not use the baseof.html but now do.

For HTML Output Formats

  • Move your files layouts/partials/article.<FORMAT>.html to layouts/_default/views/article.<FORMAT>.html

    The files will most likely require further modifications as they now receive the page as it context (dot .) instead of the .page and .content parameter.

    Old:

    ​
    {{- $page := .page }}
{{- $content := .content }}
{{- with $page }}
<article class="default">
  <header class="headline">
    {{- partial "content-header.html" . }}
  </header>
  {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}

  {{ $content | safeHTML }}

  <footer class="footline">
    {{- partial "content-footer.html" . }}
  </footer>
</article>
{{- end }}

    New:

    ​
    <article class="default">
  <header class="headline">
    {{- partial "content-header.html" . }}
  </header>
  {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}

  {{ partial "article-content.html" . }}

  <footer class="footline">
    {{- partial "content-footer.html" . }}
  </footer>
</article>

For Non-HTML Output Formats

  • Merge your files layouts/partials/header.<FORMAT>.html, layouts/partials/footer.<FORMAT>.html to layouts/_default/baseof.<FORMAT>.html

    Old:

    ​
    <!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
  <style type="text/css">
    /* add some styles here to make it pretty */
  </style>
  <style type="text/css">
    /* add chroma style for code highlighting */
    {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
  </style>
</head>
<body>
  <main>
    ​
      </main>
</body>
</html>

    New:

    The upper part of the file is from your header.<FORMAT>.html and the lower part is from your footer.<FORMAT>.html.

    The marked line needs to be added, so your output format uses a potential layouts/_default/views/article.<FORMAT>.html

    ​
    <!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
  <style type="text/css">
    /* add some styles here to make it pretty */
  </style>
  <style type="text/css">
    /* add chroma style for code highlighting */
    {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
  </style>
</head>
<body>
  <main>
    {{- block "body" . }}{{ end }}
  </main>
</body>
</html>