Hugo on Aamnah - Frontend Web Developer

Add author profiles to blog posts on Hugo websites

Thu, 27 Jun 2024 22:31:33 +0300

How to show Author details with every Hugo blog post

Load content from a github repo for a hugo website as a module

Tue, 25 Jun 2024 21:03:21 +0300

NOTES:

In 2024 a bug stopped hugo mod init (and the other hugo mod commands) when a module.toml already existed. Fixed in Hugo v0.134.3 (September 2024).
Install Hugo from the apt package or the official release binary instead of the snap. The snap is strictly confined, so hugo mod can’t reach your SSH keys and you get weird permission errors with SSH auth

https://gohugo.io/commands/hugo_mod/

In order to load modules, your site needs to be a module itself.

Hugo assets directory

Sat, 08 Jun 2024 13:43:17 +0300

If you want any file to be processed by Hugo Pipes, for example compiling Sass stylesheets or converting TypeScript files to JavaScript, it needs to be in the assets directory, which by default is assets/, but can be configured in config.toml
Only the files in assetDir that are processed will be included in the final build
Unlike staticDir which can take an array of values for multiple static directories, there can only be one assetDir

1staticDir = ['assets', 'static']
2assetDir = 'assets/'

If you are creating or using a custom theme, the files in the themes asset directory themes/foo/assets will NOT be processed by Hugo pipes by default.
You can however mount multiple asset directories. Mounting a new directory means the default directory is ignored, so be sure to explicitly add it again if you want the default directory to work

Targeting a template for Hugo website content pages

Wed, 05 Jun 2024 17:34:45 +0300

To use a specific layout for your content pages and override the default template lookup order, you specify layout, kind, or both in the front matter. Here are a bunch of examples:

layouts/notes/baseof.html - serves as the templates for the notes SECTION
layouts/page/notes.html - serves as the template for the notes PAGE

Here’s an example directory structure for your layouts:

themes/amnastic/layouts/notes/     
├── baseof.html
├── landing.html                
├── section.html               
└── single.html                  
                                                               
0 directories, 4 files

If you just define layout:notes in your content page, it will render the PAGE layout at layouts/pages/notes.html

1# use the template at layouts/pages/notes.html
2layout: notes

If you just define type:notes, it will render the layout template at layouts/notes/baseof.html or layouts/notes/single.html

1# use the template at layouts/notes/baseof.html or layouts/notes/single.html
2type: notes

If you define a type and a layout both, it will look under the type directory for that specific layout, like the following:

1type: notes # look under layouts/notes/
2layout: landing # for a layout called landing, i.e. layouts/notes/landing.html

Defining layouts for subsections

I have one notes (usually called posts) with folders serving as post categories. From Hugo’s perspective, notes/ is a section and all the individual directories inside notes/, for example notes/algorithms/, notes/android etc. are all sub-sections. In my site, i have about 50+ of these subsections.

Customizing Chroma in Hugo and Light/Dark syntax highlighting themes

Wed, 30 Nov 2022 15:45:44 +0500

tl;dr

Disable inline styles for syntax highlighting
Generate stylesheets
Use an inline <style> tag in your template file, and load Hugo partials inside a media query (or load stylesheet based on a data attribute value)

Hugo uses Chroma by default. You can use Prism instead if you want.

Chroma renders the highlighted syntax at build time

PrismJS gives you a lot of flexibility in terms of plugins, themes and portability.

PrismJS renders client side whereas Chroma probably renders at build time. Chroma is probably really good for site performance.

Using PrismJS for Hugo sites

Wed, 30 Nov 2022 13:08:36 +0500

NOTE: I have stopped using Prism for syntax highlighting and use Hugo’s built-in Chroma highlighting instead. The huge advantage Chroma has over Prism is site performance. Chroma renders the highlighted syntax at build time whereas Prism renders client side. Prism is also going to download ~50kb on site load. The file size is actually bigger if you are using many plugins and supporting many languages.

Hugo uses Chroma by default. You can use Prism instead if you want. PrismJS gives you a lot of flexibility in terms of plugins, themes and portability.

Hugo Modules

Wed, 16 Nov 2022 00:00:01 +0500

Hugo modules are read-only.
You can mount any folder from any public remote or local location, including GitHub repos and local folders on your system
What sort of a module it is determined by the target path where it is mounted
What can be a module? One or more of the 7 component types defined in Hugo: static, content, layouts, data, assets, i18n, and archetypes.

Getting started

You should be using versions of Go and Hugo that support modules
Your Hugo site itself needs to be initialized as a module in order for this to work
Import a module by mentioning its path. By default all modules are assumed to be themes.
Mount a module (or a folder) in a particular location by mention source and target locations
hugo serve automatically fetches the modules if needed
hugo mod vendor shows the mounted modules in a directory called _vendor inside your project root instead of loading them in cacheDir

1hugo mod init github.com/aamnah/aamnah.com
2
3# this will create a file called: go.mod

1hugo mod vendor

What can i mount as a module?

Any form of assets. For example: Icon libraries like Heroicons or Remix Icons
Any form of shared content. For example: documentation for a project
Any theme or UI framework
Branding assets
archetypes for creating new content based on templates. For example: archetypes for creating blog posts with pre-filled front matter
Anything that fits the 7 content types of hugo.

Hugo Config Directories

Tue, 15 Nov 2022 23:21:18 +0500

The file is named after a configuration root object. Root objects are the ones that have a single square bracket. For example: [module], [menu], [Params] etc. These you can split into their own files, named after the object. For example: module.toml, menu.toml or menus.toml, params.toml etc.
Since the files are named after the root object, you’d skip mentioning the root object itself, i.e. the config will be top-level.

Code samples

Here’s a chunk of configuration from the config.toml file

Auto compiling Sass and SCSS in Hugo

Fri, 28 Oct 2022 00:00:00 +0500

1{{ $scss := resources.Get "scss/main.scss" }}
2{{ $css := $scss | resources.toCSS }}
3
4<link rel="stylesheet" href="{{ $css.RelPermalink }}">

Your Sass files need to be in the assets/ folder for you to be able to pipe commands with |. By default the assetDir is assets/ in the project root. By default, you can only have one assetDir
- You can mount your theme’s assets directory themes/BLAH/assets/ (i.e. multiple assetDirs) as a module with a custom mount configuration. Read: Hugo assets directory
:= is also known as the walrus operator. It means definition and assignment
resources.Getlocates the filename given in Hugo’s assets filesystem and creates a Resource object that can be used for further transformations.
RelPermalink would get the relative permalink. Meaning /scss/main.css instead of http://mysite.com/scss/main.css

1{{ $scss := resources.Get "scss/main.scss" }}
2{{ $css := $scss | ToCSS }}
3
4<link rel="stylesheet" href="{{ $css.RelPermalink }}">

1{{ $style := resources.Get "scss/main.scss" | resources.ToCSS }}
2
3<link rel="stylesheet" href="{{ $style.RelPermalink }}">

You can also specify options like you normally would if you ran dart-sass or sass CLI