<p>Extending a Hugo theme is nothing new and a <a href="https://gohugo.io/content-management/sections/">few</a> <a href="http://hugocodex.org/add-ons/">places</a> 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.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_customizing_your_head">Customizing your <code>&lt;head&gt;</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Let’s start with the most basic and perhaps most useful customization: modifying the <code>&lt;head</code>&gt;.
This is useful for adding your own CSS and JavaScript files, changing certain metadata, or adding icons.</p>
</div>
<div class="paragraph">
<p>First, copy the <code>head</code> partial from the theme (<code>theme/contentful/layouts/partials/head.html</code>) to your own (<code>layouts/partials/head.html</code>).
We’re simply taking advantage of <a href="https://gohugo.io/templates/lookup-order/">Hugo’s lookup order</a> where we’ve override the <code>head</code> partial with our own copy.</p>
<p>Then, feel free to add your own (or others&#39;) scripts and stylesheets, <a href="https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML">icons and other metadata</a>, or whatever suitable things.</p>
<p>In my case, I often use certain JavaScript libraries like <a href="https://www.mathjax.org/">MathJax</a> for mathematical typesetting, <a href="https://prismjs.com/">Prism</a> for syntax highlighting, and <a href="https://github.com/francoischalifour/medium-zoom/">medium-zoom</a> for interactive image zooms.</p>
</div>
<div class="paragraph">
<p>Here’s the modified code.
(The example code is snipped for brevity.)</p>
<p>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 <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script"><code>defer</code> attribute</a>.
If you have an inline script, you can simply wrap it in an event listener for page loading (<code>window.addEventListener(&#34;load&#34;, your_function_goes_here)</code>).</p>
</div>
<div class="paragraph">
<p>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 <a href="https://gohugo.io/news/0.60.0-relnotes/">Hugo v0.60.0</a>, blocks raw HTML by default and you can disable it by setting <code>markup.goldmark.renderer.unsafe</code> to <code>true</code>.</p>
</div>
<div class="paragraph">
<p>For Blackfriday, it parses even the raw HTML just fine.
Though, you have to set it as the default Markdown parser.</p>
</div>
<div class="paragraph">
<p>For <a href="https://asciidoctor.org/">Asciidoctor</a>, you can use <a href="https://asciidoctor.org/docs/user-manual/#passthroughs">passthroughs</a> to get raw HTML through.</p>
<p>This will add <a href="https://developer.twitter.com/en/docs/tweets/optimize-with-cards/guides/getting-started">Twitter cards</a> for your webpages.
(Be sure to copy the <code>head</code> partial first in your own layout folder.)</p>
<p>Thankfully, Hugo already has <a href="https://gohugo.io/templates/internal/#twitter-cards">an internal template for Twitter cards</a>.
Simply add <code>{{- template &#34;_internal/twitter_cards.html&#34; . -}}</code> somewhere in your own copy.
(For reference, <a href="https://github.com/gohugoio/hugo/blob/25a6b33693992e8c6d9c35bc1e781ce3e2bca4be/tpl/tplimpl/embedded/templates/twitter_cards.html">here’s the source code for the internal template</a>.)</p>
<p>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 <code>layouts/partials/twitter_cards.html</code>, modify it, and insert the template with <code>{{- partial &#34;twitter_cards.html&#34; -}}</code>.)</p>
<p>Similar to Twitter cards, Hugo has <a href="https://gohugo.io/templates/internal/#open-graph">an internal template for this</a>.
Simply add <code>{{- template &#34;_internal/opengraph.html&#34; . -}}</code> somewhere in your own copy.
(For reference, <a href="https://github.com/gohugoio/hugo/blob/25a6b33693992e8c6d9c35bc1e781ce3e2bca4be/tpl/tplimpl/embedded/templates/opengraph.html">here’s the source code for the internal template</a>.)</p>
<p>If you want more control and customized version of the output, I recommend to copy the internal template and create a partial (e.g., <code>layouts/partials/opengraph.html</code>) and modify it.</p>
<p>This will add an archive page similar to archive pages <a href="https://davidtranscend.com/archives/">like</a> <a href="https://lukesmith.xyz/blogindex.html">these</a>.</p>
<p>We will simply add this as a layout in our customized theme.
Let’s call it <code>archives</code> so we have to add a file in <code>layouts/_default/archives.html</code> then set a page of our project with the <code>layout</code> key in the frontmatter.</p>
<p>We want the archives page to be accessed at <code>$.Site.BaseURL/archives</code> so we’ll simply create <code>archives.adoc</code> (<a href="https://gohugo.io/content-management/formats/#list-of-content-formats">any valid content files with certain file extensions can do</a>, I’m using <a href="https://asciidoctor.org/">Asciidoctor</a>) with the following example content.</p>
<p>I want my Keybase profile to appear first than anything else for whatever reason so the <code>weight</code> key is set to -1.</p>
<p>With this data, we can then create a template out of it.
I’ve put the following template in a partial named <code>contacts</code> (i.e., <code>layouts/partials/contacts</code>).</p>
<p>For enabling output feeds, utilize the <a href="https://gohugo.io/templates/output-formats">output formats</a> in your site configuration.</p>
