Customizing HUGO Webs
Following with the HUGO topic, there are many customizations that can be applied.
This can differ from theme to theme, but I want to consolidate here a few that found interesting and that I believe can be apply in any theme that you will choose (or maybe create?).
Tweaking HTML
How to include HTML content
Create /layouts/shortcodes folder on your HUGO folder.
Then create the file rawhtml.html with the following content:
<!-- raw html -->
{{.Inner}}
Then, you can use it in your posts by using the following logic:
Including Leaflet Map as HTML
For example, this output from leaflet map:
Customize your links
Custom URLs for Posts
Simply include the following parameter in the post configuration:
url: 'your-desired-path'
This will ignore the post-name.md from the file.
How to use nofollow links with HUGO
Add a render-link.html file which is processed (note to self: make sure you have a recent version of Hugo installed). This file is in /themes/your-theme-name/layouts/_default/_markup/ (or potentially somewhere directly too).
- This file is processed whenever a link is rendered, so you might already have something in there.
- Credit for: https://johnmu.com/nofollow-hugo/
Editing the 404 Page
You will find it in your theme folder, under layouts/404.html.
{{- define "main" }}
<div class="not-found">404</div>
{{- end }}{{/* end main */ -}}
With some basic HTML knowledge you can edit that, for example to:
{{ define "main"}}
<main id="main">
<div>
<h1 id="title"><a href="{{ "" | relURL }}">Take me back Home.</a></h1>
</div>
</main>
{{ end }}
Cover Image for your Posts
You can try with
Socialify
If your post content has ana ssociated Github repository, you can create an automatic cover for your post thanks to the fantastic work from https://socialify.git.ci/
Decide the parameters that you want to be visualized and generate the link that will be as the cover - image parameter in the post. Like this:
cover:
image:
https://socialify.git.ci/JAlcocerT/R_Stocks?description=1&descriptionEditable=Shiny%20Dashboard%20that%20displays%20free%20available%20financial%20information.%20%0A%0A&font=Inter&name=1&owner=1&pattern=Solid&theme=Auto
Pretty handy for enhance the content related to our Github Repositories.
Add your Posts Tags
To the POST page
For that you will need to customize the file ’layouts/partials/post_meta.html’ of your theme:
{{- $scratch := newScratch }}
{{- if not .Date.IsZero -}}
{{- $scratch.Add "meta" (slice (printf "<span title='%s'>%s</span>" (.Date) (.Date | time.Format (default "January 2, 2006" site.Params.DateFormat)))) }}
{{- end }}
{{- if (.Param "ShowReadingTime") -}}
{{- $scratch.Add "meta" (slice (i18n "read_time" .ReadingTime | default (printf "%d min" .ReadingTime))) }}
{{- end }}
{{- if (.Param "ShowWordCount") -}}
{{- $scratch.Add "meta" (slice (i18n "words" .WordCount | default (printf "%d words" .WordCount))) }}
{{- end }}
{{- $author := (partial "author.html" .) }}
{{- $tags := (partial "tags.html" .) }}
{{- if $tags }}
{{- $scratch.Add "meta" (slice $author $tags) -}}
{{- else}}
{{- $scratch.Add "meta" (slice $author) -}}
{{- end}}
{{- with ($scratch.Get "meta") }}
{{- delimit . " · " -}}
{{- end -}}
Also, you have to create ’layouts/partials/tags.html’:
{{- $tags := .Params.tags -}}
{{- if $tags -}}
{{- $lastIndex := sub (len $tags) 1 -}}
{{- range $index, $tag := $tags -}}
<a href="/tags/{{ $tag | urlize }}"> {{ $tag }}</a>
{{- if ne $index $lastIndex }} · {{ end -}}
{{- end -}}
{{- end -}}
This has been found thanks to an on going discussion of the PaperMod theme that I am using for the blog, but should be able to operate with other themes as well.
Add your HUGO POST Summary to Archive
Create the file (post_meta.html exists and it will affect what you see in /posts or /tags) themes/PaperMod/layouts/partials/post_meta_archives.html with the following (in the last part we make use of .Params.summary):
{{- $scratch := newScratch }}
{{- if not .Date.IsZero -}}
{{- $scratch.Add "meta" (slice (printf "<span title='%s'>%s</span>" (.Date) (.Date | time.Format (default "January 2, 2006" site.Params.DateFormat)))) }}
{{- end }}
{{- if (.Param "ShowReadingTime") -}}
{{- $scratch.Add "meta" (slice (i18n "read_time" .ReadingTime | default (printf "%d min" .ReadingTime))) }}
{{- end }}
{{- if (.Param "ShowWordCount") -}}
{{- $scratch.Add "meta" (slice (i18n "words" .WordCount | default (printf "%d words" .WordCount))) }}
{{- end }}
{{- $author := (partial "author.html" .) }}
{{- $tags := (partial "tags.html" .) }}
{{- if $tags }}
{{- $scratch.Add "meta" (slice $author $tags) -}}
{{- else}}
{{- $scratch.Add "meta" (slice $author) -}}
{{- end}}
{{- with ($scratch.Get "meta") }}
{{- delimit . " · " -}}
{{- end -}}
{{- if .Params.summary }}
{{ with .Summary }}
<div class="post-summary">{{ . }}</div>
{{ end }}
{{- end }}
Modify the Looks
HUGO Main Page: adding pinned posts
In general, you’ll need to
- Add the isPinned tag to the posts that you want to be kept in the main page
---
title: "My Pinned Post"
date: 2023-05-04T00:00:00+00:00
isPinned: true
#other_post_parameters
---
- Modify the layouts/index.html. In my case, I am using PaperMod theme right now and I have the profile mode enabled.
- When going to that index.html file, you will see that under that condition, it ‘redirects’ us to the file layouts/partials/index_profile.html. This is the file in charge of creating the main page of our blog.
Follow these steps:
- Query the pinned posts in your config.yaml file. Add this code at the beginning of the HTML file (before the opening tag):
{{ $pinnedPosts := where site.RegularPages "Params.isPinned" true }}
- Now we have the list of post that mets that condition ready, lets include them in our HUGO main page. To display the pinned posts in the profile widget. Add the following code right after the buttons div (before the closing tag of the profile_inner div):
{{- if $pinnedPosts }}
<div class="pinned-posts">
<h2>Pinned Posts</h2>
<ul>
{{- range $pinnedPosts }}
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
{{- end }}
</ul>
</div>
{{- end }}
This block checks if there are any pinned posts, and if so, creates a div with the class pinned-posts, displays a header “Pinned Posts”, and generates an unordered list with links to the pinned posts.
Better summaries and post descriptions in HUGO
When writing a new post, be sure that you use the following variables:
description: "A great description for your post."
summary: 'A great summary that will appear in the posts view, instead of the automatic initial 70 words of your post.'
If you want to change the default 70 words of summary, use the following variable in the config.yml:
summaryLength: 100 #70
favicons
https://favicon.io/favicon-converter/
- go to the theme folder
- add a /static folder
- add the files generated with the website
Use fonts
https://wowchemy.com/docs/getting-started/customization/
How to modify the main page footer
You can hide it by adding to the config.yml
params: hideFooter: false
If you want to customize it:
Modify the resulting .html in public
This is the file that will be in charge of creating the footer that will go to the /public folder when the web will be generated or that you will visualize locally:
- better option: go to themes/your_theme/layouts/_default/partials/footer.html
- and edit it accordingly
FAQ
How to customize the css for HUGO?
Modifying Archive’s css
Under you theme folder, you should be able to find a similar structure and find the proper css file that affects the archive page: /theme/PaperMod/assets/css/common/archive.css
And in that file, include:
.post-summary {
font-size: 10 px; /* 1.2rem; Adjust the font size*/
color: var(--secondary); /*#c20c0c; Adjust the font color */
margin-top: 0.5rem;
}
How to inject JS in ALL HUGO Posts?
Locate the single.html file in the theme’s layout directory (for example /theme/PaperMod/layouts/_default/single.html). Include the js before the end of the article:
</article>
{{- end }}
{{/* end main */}}
Example: Adding Mailerlite to HUGO
</footer>
<!-- MailerLite Subscription Form Container -->
<div class="ml-embedded" data-form="a-data-dorm"></div>
<!-- MailerLite Universal -->
<script>
(function(w,d,e,u,f,l,n){w[f]=w[f]||function(){(w[f].q=w[f].q||[])
.push(arguments);},l=d.createElement(e),l.async=1,l.src=u,
n=d.getElementsByTagName(e)[0],n.parentNode.insertBefore(l,n);})
(window,document,'script','https://assets.mailerlite.com/js/universal.js','ml');
ml('account', 'an-account-id');
</script>
<!-- End MailerLite Universal -->
{{- if (.Param "comments") }}
{{- partial "comments.html" . }}
{{- end }}
</article>
{{- end }}
{{/* end main */}}