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 . "&nbsp;·&nbsp;" -}}
{{- 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 }}&nbsp;·&nbsp;{{ 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 . "&nbsp;·&nbsp;" -}}
{{- 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 */}}

Customizing HUGO Webs#

Tweaking HTML#

How to include HTML content#

Including Leaflet Map as HTML#

Customize your links#

Custom URLs for Posts#

How to use nofollow links with HUGO#

Editing the 404 Page#

Cover Image for your Posts#

Socialify#

Add your Posts Tags#

To the POST page#

Add your HUGO POST Summary to Archive#

Modify the Looks#

HUGO Main Page: adding pinned posts#

Better summaries and post descriptions in HUGO#

favicons#

Use fonts#

How to modify the main page footer#

Modify the resulting .html in public#

FAQ#

How to customize the css for HUGO?#

Modifying Archive’s css#

How to inject JS in ALL HUGO Posts?#

Example: Adding Mailerlite to HUGO#