Extending Contentful

2020-05-12T17:25:55+08:00

Extending a Hugo theme is nothing new and a few places provide a place for the most common extensions. In this post, I’ll be listing a few personal recipes I’ve always used for extending a Hugo theme. Though this only applies specifically to Contentful and may need some tweaking when applying it other themes.

Customizing your `<head>`

Let’s start with the most basic and perhaps most useful customization: modifying the <head>. This is useful for adding your own CSS and JavaScript files, changing certain metadata, or adding icons.

First, copy the head partial from the theme (theme/contentful/layouts/partials/head.html) to your own (layouts/partials/head.html). We’re simply taking advantage of Hugo’s lookup order where we’ve override the head partial with our own copy.

Then, feel free to add your own (or others') scripts and stylesheets, icons and other metadata, or whatever suitable things.

In my case, I often use certain JavaScript libraries like MathJax for mathematical typesetting, Prism for syntax highlighting, and medium-zoom for interactive image zooms.

Here’s the modified code. (The example code is snipped for brevity.)

<!--snip-->

{{- /* MathJax */ -}}
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

{{- /* Prism.js */ -}}
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/themes/prism-tomorrow.min.css" type="text/css">
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/components/prism-core.min.js"></script>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/plugins/autoloader/prism-autoloader.min.js">
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/plugins/keep-markup/prism-keep-markup.min.js">

{{- /* medium-zoom */ -}}
<script defer src="https://cdn.jsdelivr.net/npm/medium-zoom@1.0.5/dist/medium-zoom.min.js"></script>
<script>window.addEventListener('load', () => mediumZoom('article img', { 'background': 'rgba(0, 0, 0, 0.75)' }))</script>

Since most of the JavaScript libraries used here are not really a requirement (except for MathJax for mathematical typesetting), I’ve set them to be loaded at the end of the page loading with defer attribute. If you have an inline script, you can simply wrap it in an event listener for page loading (window.addEventListener("load", your_function_goes_here)).

If you want document-specific libraries, you have to pass some raw HTML through the parser of the document. For Goldmark, the default Markdown parser starting Hugo v0.60.0, blocks raw HTML by default and you can disable it by setting markup.goldmark.renderer.unsafe to true.

For Blackfriday, it parses even the raw HTML just fine. Though, you have to set it as the default Markdown parser.

For Asciidoctor, you can use passthroughs to get raw HTML through.

Twitter cards

This will add Twitter cards for your webpages. (Be sure to copy the head partial first in your own layout folder.)

Thankfully, Hugo already has an internal template for Twitter cards. Simply add {{- template "_internal/twitter_cards.html" . -}} somewhere in your own copy. (For reference, here’s the source code for the internal template.)

You could also roll your own Twitter cards but I recommend to modify the internal template instead fitting your specific needs. (Copy the internal template from the given link, create it as a partial in layouts/partials/twitter_cards.html, modify it, and insert the template with {{- partial "twitter_cards.html" -}}.)

Open Graph protocol

Next up, we’re implementing Open Graph protocol for our webpages. Commonly used for making suitable format when sharing the content on certain sites like Facebook. (Be sure to copy the head partial first in your own layout folder.)

Similar to Twitter cards, Hugo has an internal template for this. Simply add {{- template "_internal/opengraph.html" . -}} somewhere in your own copy. (For reference, here’s the source code for the internal template.)

If you want more control and customized version of the output, I recommend to copy the internal template and create a partial (e.g., layouts/partials/opengraph.html) and modify it.

An archive page

This will add an archive page similar to archive pages like these.

{{- define "main" -}}

<h1>{{ .Title }}</h1>

{{ .Content }}

<hr>

{{- /* Creating a section that lists out regular pages by year */ -}}
{{ range $.Site.RegularPages.GroupByPublishDate "2006" }}
    {{- /* Skip regular pages with an invalid creation date string. */ -}}
    {{- /* This is convenient if we want to exclude certain posts to be listed by giving no value to `date` in the frontmatter. */ -}}
    {{- /* We will also exclude hidden pages. */ -}}
    {{ if ne .Key "0001" }}
        <section data-year="{{ .Key }}">
            <h2 id="{{ .Key }}">{{ .Key }}</h2>
            <ul>
            {{- range where .Pages "Params.hidden" "!=" true -}}
                <li>
                    <date>{{ .Date.Format "2006-01-02" }}</date> -
                    <a aria-label="{{ .Title }}" href="{{ .Permalink }}">{{ .Title }}</a>
                </li>
            {{- end -}}
            </ul>
        </section>
    {{- end }}
{{ end }}

{{- end -}}

We will simply add this as a layout in our customized theme. Let’s call it archives so we have to add a file in layouts/_default/archives.html then set a page of our project with the layout key in the frontmatter.

We want the archives page to be accessed at $.Site.BaseURL/archives so we’ll simply create archives.adoc (any valid content files with certain file extensions can do, I’m using Asciidoctor) with the following example content.

---
title: "Archives"
layout: "archive"
---

= Archives

This is the archives of the century.

Configurable social media links

Most themes offer quick social media links with site configuration. However, it is only limited to popular media sites such as Facebook, Twitter, Instagram, GitHub, etc.

To get around this, we’ll make use of data templates. Let’s create a quick game plan how does it work.

The data is a top-level dictionary/object with each key contains an object with the following fields.

url is the… contact link itself and it is required to have it.
name is the text to appear in the output. Also required to have.
weight is an integer similar to how Hugo sorts the pages with the lower weight having high precedence; if this key is absent, it will be interpreted as 0.

And here’s the data example in TOML which is placed in data/contact.toml.

[github]
    name = "GitHub"
    url = "https://github.com/foo-dogsquared"

[gitlab]
    name = "Gitlab"
    url = "https://gitlab.com/foo-dogsquared"

[keybase]
    name = "Keybase"
    url = "https://keybase.io/foo_dogsquared"
    weight = -1

[twitter]
    name = "Twitter"
    url = "https://twitter.com/foo_dogsquared"

I want my Keybase profile to appear first than anything else for whatever reason so the weight key is set to -1.

With this data, we can then create a template out of it. I’ve put the following template in a partial named contacts (i.e., layouts/partials/contacts).

<address>
{{- range (sort $.Site.Data.contact "weight" "asc") -}}
| <a rel="me" href="{{ .url }}">{{- .name -}}</a> |
{{- end -}}
</address>

A suggestion (and an exercise) for extending this is to create image links. Maybe add another key named image that accepts either URL. The name would now be the image alternative text.

RSS, Atom, and JSON Feed Support

2019-09-04T17:22:44+08:00

This theme supports RSS, Atom, and JSON feed output for more ways of publishing web content for your visitors. It is also suitable for reading content from feed readers.

Here are the following documents used as references for the creation of the output feed templates.

In this demo, it is enabled and you should be able to see them through the following links:

RSS: $HUGO_URL/index.rss
Atom: $HUGO_URL/index.atom
JSON: $HUGO_URL/index.json

For enabling output feeds, utilize the output formats in your site configuration.

If you’re settling with this option, here’s an example template for enabling all of the feed formats.

# Visit the following for more information:
# https://gohugo.io/templates/output-formats

# Defining the media type of the output formats
# For JSON format, it doesn't need to be since it's already built-in into Hugo
[mediaTypes]
    [mediaTypes."application/atom+xml"]
        suffixes = ["atom", "atom.xml"] # You can remove the "atom.xml" if you want

    # Redefining RSS media type for the additional suffix
    [mediaTypes."application/rss+xml"]
        suffixes = ["rss", "rss.xml"] # You can remove the "rss.xml" if you want



# Including all of the feed output formats in the build
[outputFormats]
    [outputFormats.Rss]
        mediaType = "application/rss+xml"
        baseName = "feed"

    [outputFormats.Atom]
        mediaType = "application/atom+xml"
        baseName = "feed"

    [outputFormats.Json]
        mediaType = "application/json"
        baseName = "feed"


# Indicating what output formats shall be included
# for the following kinds
[outputs]
    # .Site.BaseURL/index.* is available
    home = ["HTML", "JSON", "RSS", "ATOM"]

    # .Site.BaseURL/$section/index.* is available
    section = ["HTML", "JSON", "RSS", "ATOM"]

Contentful