Hugo on Schallbert's Blog

Continuous Deployment for a Hugo site

Schallbert — Tue, 15 Sep 2026

I have just migrated my website from Hugo to Jekyll. Now, I want to automate the build and deployment process so that changes are rolled out as soon as I finish an article and push it via git push followed by a merge into main to my Gitea instance.

The Command Chain

I rent a VPS where I run all my applications in Docker. The task now is to create a workflow in Gitea (“Actions”) that checks out the repository update, passes it to Hugo to generate the HTML pages, and then saves the output to the disk in a location where my web server can read and serve the files.

Lessons Learned

I had already managed to set this up for my Jekyll website build and deployment, so I can draw on some previous experience.

Typically, standardized actions are used for this purpose. I’ll simplify things significantly here and list only the key components, without deep-diving in messy details like permission settings (is Hugo allowed to write to this folder? Does the hugo user have sufficient privileges?):

checkout makes a specific version of the source repository available
actions-hugo installs Hugo within the Action’s virtual machine so the website can be built
upload-artifact uploads the site generated by Hugo to the web server

However, since I am operating within Docker on the same machine, I can skip the hassle of logging into the web server “from the outside”. So, I’m taking a different approach.

Docker shared volumes

I can make the built files directly available to my Caddy application by passing the volume (that Caddy reads from) through to the Action.

Heads up: Action volume != Hugo volume

But this doesn’t work with actions-hugo: It is not a Docker container itself, so it cannot mount volumes. While it does successfully build the website, it sends the artifacts into oblivion as soon as the Action finishes running.

So, I need a Hugo runtime that executes inside a Docker container itself, following the DinD approach. I can then pass the volume with write access.

The workflow

But which Docker container should I choose?

Imagine here several hours of research and numerous failed attempts while setting up the workflow on my server.

My investigation revealed the following:

checkout@v4 requires Node.js—specifically, at least version node:18. The Docker container must have it installed.
The action requires git. Ideally, the Docker container should already include this as well.
Hugo needs go. That makes sense.

Adjusting the runner operating system

My runner from 2023 did not age well. It is based on node:16-bullseye, a Debian-based VM. I experiment a bit with Alpine, but that installation is too minimal for my needs and would require too many manual adjustments. After all, the runner has to execute other workflows besides this one. Ultimately, I decide to stick with Debian and just upgrade the Node version. The implementation in the runner configuration looks like this:

# /gitea/runner/config.yml

# The labels of a runner are used to determine which jobs the runner can run, and how to run them. 
# Like: ["macos-arm64:host", "ubuntu-latest:docker://node:16-bullseye", "ubuntu-22.04:docker://node:16-bullseye"]
# If it's empty when registering, it will ask for inputting labels. 
# If it's empty when execute `deamon`, will use labels in `.runner` file. 
labels: [ubuntu-latest:docker://node:20-bullseye]

Afterwards, the runner container must be restarted. Ideally, you should reboot Gitea as well; this ensures that runner registration works reliably.

Writing the workflow script

To handle the dependencies described above, I’m opting for a “batteries-included” approach. This allows me to assemble the components without manual adjustments and rely on the long-term maintenance of the containers, given their widespread use (with pull counts in the millions). This website was very helpful in making my selection.

Finally, I create my workflow based on the container from Hugomods.

# /.gitea/workflows/build-deploy-with-hugo.yml

name: Deploy Hugo site
run-name: ${{ gitea.actor }} builds Hugo site
on:
 push:
 branches:
 - main

jobs:
 # Build job
 build:
 runs-on: ubuntu-latest # this is the "label" the runner will use and map to docker target OS
 container: 
 image: hugomods/hugo:latest
 volumes: 
 - /tmp/blog-artifacts:/tmp/blog-artifacts

 steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v4
 with:
 submodules: recursive  # Fetches Hugo themes
 fetch-depth: 0

 - name: --- BUILD WITH HUGO --- # chown -R hugo /tmp/blog-artifacts
 run: |
 hugo \
 --minify \
 --cleanDestinationDir \
 --destination /tmp/blog-artifacts

Cleaning the destination folder

In the example above, I opted for a “direct deployment”. This is a basic approach without a safety net, and without copying artifacts around or restarting the server. The reason: the Hugo build process takes less than 2,000ms for my site. It is only within this window that Caddy could theoretically encounter and serve “corrupt” data. Specifically, the window is even smaller as occurrence is limited to the Hugo build writing artifacts to the disk.

To minimize inconsistencies regardless, I use the --cleanDestinationDir option with Hugo. This ensures the destination directory is always clean; consequently, in the event of an issue, Caddy won’t display a broken site but will instead generate a 404 error.

Submodules

As noted in my project documentation, you can use “submodules” in Hugo to load themes. These are integrated into the project and—provided they are linked correctly—can be utilized within the workflow:

with:
submodules: recursive  # Fetches Hugo themes
fetch-depth: 0

If everything is configured correctly, you should not encounter the following error message:

# workflow action's error message due to incoherent submodules' commit references
# actions/checkout@v4:
Fetching submodules
/usr/bin/git submodule sync
/usr/bin/git -c protocol.version=2 submodule update --init --force
Submodule 'themes/terminal' (https://github.com/panr/hugo-theme-terminal.git) registered for path 'themes/terminal'
Cloning into '/workspace/schallbert/blog-hugo/themes/terminal'...
fatal: remote error: upload-pack: not our ref 719505fc89332baa69bffb90cee708ff124dd143
Fetched in submodule path 'themes/terminal', but it did not contain 719505fc89332baa69bffb90cee708ff124dd143. Direct fetching of that commit failed.
Error: The process '/usr/bin/git' failed with exit code 1
Error: Process completed with exit code 1.

A prerequisite is that the submodules have been correctly loaded locally:

schallbert@machine:~ git submodule add -f https://github.com/<my/hugo-theme>.git themes/my-hugo-theme
schallbert@machine:~ git submodule update --init --recursive

The status check must not return an empty string; instead, it must include a commit hash. Example:

schallbert@machine:~ git submodule status
44d9a1890d228745ffc300b37a7d73e940ef9fa9 themes/terminal (v4.2.5)

Further confirmation is provided by the .gitmodules file, which must contain a reference to the theme:

schallbert@machine:➜/blog git:(main) ✗ nano .gitmodules
[submodule "themes/terminal"]
path = themes/terminal
url = https://github.com/panr/hugo-theme-terminal.git

If this does not work, the submodules must be completely removed and then re-initialized as described above:

git submodule deinit -f themes/<my-theme>
git rm -r --cached themes/<my-theme>
rm -rf .git/modules/themes/<my-theme>

Common Issues: Hugo Versions and Deprecations

The checkout action completed successfully, but the Hugo build fails:

error calling partial: "/workspace/schallbert/blog-hugo/layouts/_partials/head.html:37:40": execute of template failed: template: _partials/head.html:37:40: executing "_partials/head.html" at <$.Page.Language.Locale>: can't evaluate field Locale in type *langs.Language
Error: Process completed with exit code 1.

Locally on my machine, Hugo builds successfully but issues a few warnings:

Changes to Language Identifiers and Evaluation as of v0.158

schallbert@machine:➜/blog git:(main) ✗ hugo build --logLevel info
WARN deprecated: site.Language.Locale was deprecated in Hugo v0.158.0 and will be removed in a future release. Use .Page.Language.Locale instead.
WARN deprecated: .Language.Lang was deprecated in Hugo v0.158.0 and will be removed in a future release.

You might think these errors would be easy to fix. Unfortunately, they can be very good at hiding:

in submodules loaded as third-party content (e.g., in themes). A project-wide search in the IDE usually excludes submodules and yields no results.
as variables in your own code that access the old parameters only indirectly: Up until now, I’ve been using .Page.Site.Home.AllTranslations to determine if I am currently on the “main language” version of a given page. The scoping alone is illogical, and in my opinion, it is rightly being removed. What I want to achieve can now be done much more easily using .Page.Language.IsDefault.

Updating Submodules

I see two possible approaches for handling submodules:

Contact the maintainers (or open an issue) to let them know their code is becoming outdated and ask them to update their themes.
Copy the affected files out of the submodule and integrate them into my own folder structure. In my case, for example, the affected language-menu.html would find a new home at /layouts/partials/language-menu.html. I can then fix the issues there myself.

Implementing Custom Solutions

If the error message doesn’t make the solution obvious, the Hugo community is a great resource. For instance, there is detailed documentation available regarding the deprecations in v0.158.

Comparing Versions

Hmm. As the image shows, my container uses the hugo extended package from hugomods, which provides version v0.154.5; I had selected a stable release for the Action. Let’s compare this with my local version, which now builds perfectly without a single warning:

➜ blog git:(main) ✗ hugo version
hugo v0.162.1+extended linux/amd64

The classic scenario: A change introduced in v0.158 altered the internal API. Older versions don’t recognize the new fields and throw errors. Newer versions, however, flag the use of the old fields as an issue.

I believe these problems can only be reliably avoided if the pipeline is identical for both local and remote environments. In other words: boot up a virtual machine on your local computer running the CI operating system and encapsulate everything within Docker. That certainly makes sense if you work in a larger organization where multiple users face this same issue.

To fix the problem, I switch to the image: hugomods/hugo:latest version within the remote container instead. However, I still end up with version mismatches between my local setup and the CD pipeline. The latest version frankly isn’t available for my operating system yet, and the Docker release also lags slightly behind the original releases.

The build and release times are fantastic, aren’t they? Getting a website change online in just 12 seconds, including spinning up the container and so on, is something I’ve certainly never experienced before. The process takes around 20 seconds when it has to fetch and download container references from scratch, such as when the latest tag in the registry is updated.

The linked article offers a detailed benchmark comparing Hugo and Jekyll.

Migrating from Jekyll to Hugo

Schallbert — Sun, 06 Sep 2026

Project Profile

Difficulty: Medium (3/5)
Cost: €0
Time: ~20h

In this project, I describe my migration from Jekyll using the Minimal Mistakes theme to Hugo, utilizing a heavily modified Terminal theme.

Why switch at all?

For quite some time, I hadn’t been fully satisfied with building my website using Jekyll. The trigger for the switch was a day when I suddenly couldn’t build the site locally due to a compatibility issue in Ruby. Standard commands like bundle update --conservative or bundle install didn’t help. Even manually installing the problematic packages using commands like gem install commonmarker-0.23.12 or gem install posix-spawn -v 0.3.15 -- --with-cflags="-Wno-incompatible-function-pointer-types" failed to resolve the problem.

Updating Ruby and Jekyll themselves didn’t work either. Besides, build times with Jekyll had become quite long. Since moving the site from GitHub Pages to my own server, I am no longer tied to Jekyll, making a switch more attractive.

This no-build-locally problem was just the final nudge that made me begin this laborious task. I hate it when technology doesn’t do what I want - even though I admit that often times, I am the root cause for that myself.

Further difficulties with Jekyll

CI/CD: My deployment pipeline had failed months ago due to similar errors, forcing me to revert to an older version of Jekyll. This increases technical debt and the attack surface of my GitHub Actions. I would have to look for a well-maintained container solution from another provider. Searching for and setting one up would require additional time.
RSS feed: I wanted to provide an RSS feed for my website. However, my experiments with Jekyll showed that only “posts” were included, not “announcements.” I wanted to fix this.
Image formats: Jekyll normally generates cover images (thumbnails) for posts within the RSS feed. Unfortunately, this stopped working after I switched from .jpg to the more space-efficient .avif format. Despite several attempts, I couldn’t get a solution approved through the pull request review process.
Icons: The theme I was using relies on Font Awesome to display icons and is quite large overall for a static website. Since I didn’t want to load assets from external sources, I stored the library locally. My plan was to select only the icons I actually needed and delete the rest. With the switch to Hugo, this is no longer necessary.

Opportunities

I expect Hugo to deliver faster build times, a simplified CI/CD process (without the need to install Bundler, Ruby, etc.), and a resolution to the difficulties described above. Hugo’s approach to dependency and package management differs fundamentally from Jekyll’s: additional content is integrated via Git Submodules, and dependency management relies on Go modules rather than a Gemfile.

The migration tool

The folder structures for content differ significantly between Jekyll and Hugo. I am therefore using an import tool included with Hugo, which correctly imports at least the articles located under /posts. However, specific content such as overview pages (/tags, /pages/error, /pages/legal), and pages hosting projects and announcements (/_announcements, /_projects), will not be migrated automatically and must be copied and modified manually.

Adjusting Front Matter

Many of the customizations I implemented in Jekyll either do not work correctly in Hugo or cause the build process to fail. Consequently, the front matter of every Markdown file must be adjusted and, in some cases, cleaned up.

---
# Alt: So kann die Front matter einer Übersichtsseite in Jekyll aussehen
lang: de
title: Beitragsarchiv
subtitle: Diese Sammlung enthält alle meine Beiträge
layout: collection
collection: posts
permalink: /posts-archive/
entries_layout: grid
classes: wide
author_profile: false
---

In my case, there are several theme-specific parameters in the front matter, such as layout, classes, and author_profile. The lang parameter from my Jekyll internationalization extension isn’t even valid Hugo syntax; Hugo expects the language setting either as a field under params: lang or defined at the folder level. Other custom parameters tailored to personal preference can also be defined and passed via params.

Permalinks are no longer included in the front matter; instead, configuration is handled centrally.

Hugo-compatible front matter might look like this:

---
title: Post Archive
description: This collection contains all my posts
layout: collection
---

Theme Configuration

I can install a basic configuration for my theme using the following command:

➜ blog git:(main) ✗ git submodule add https://github.com/panr/hugo-theme-terminal ./themes/terminal

To activate it, I need to specify it in the main configuration file:

# /hugo.toml

# Add it only if you keep the theme in the `themes` directory.
# Remove it if you use the theme as a remote Hugo Module.
theme = "terminal"

And just like that, Hugo builds the site using the Terminal theme and its default colors.

However, the layout isn’t vertically centered and is too narrow for my taste; the text is quite small, and I want “my” blog colors to be different as well. Therefore, I am creating a .css file that overrides some properties of the base theme. It must be located in the /static folder and named after the theme.

/* /static/terminal.css */

:root{
 --background: #252a34;
 --background-highlight: #475064;
 --foreground: #d2eaef;
 --foreground-dimmed: #8b9ea2;
 --accent: #25a679;
 --accent-highlight: #79ae9c;
 --radius: 8px;
 --font-size: 1.35rem;
 --line-height: 1.8em;
}

/* Use system fonts, reduce transferred kB */
body{
 font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif !important; 
}

/* make content wider */
body .container{
 max-width: 70rem;
 width: 90%;
}

And just like that, it looks almost like it used to.

Organizing the folder structure

Unlike the version of Jekyll I was using, Hugo features built-in internationalization (i18n). This requires me to restructure my folders and explicitly sort content into /de and /en directories. Instead of sitting at a higher folder level, content is now stored directly within the content folder—under /_pages, /_announcements, and /_posts—which makes things much tidier.

Before

.
├── _announcements
├── assets
│ ├── css
│ │ ├── fontawesome
│ │ ├── katex
│ │ ├── main.scss # <-- theme import, customization
│ │ └── webfonts
│ ├── js
│ │ ├── lunr
│ │ ├── _main.js
│ │ ├── main.min.js
│ │ ├── plugins
│ │ └── vendor
│ └── video
├── banner.js
├── CNAME
├── _config.yml
├── _data
│ ├── de
│ │ ├── l10n.yml
│ └── en
│ ├── l10n.yml
├── en
│ └── index.html
├── Gemfile
├── Gemfile.lock
├── _includes # <-- Layouts (HTML), partials, 3rd-party
├── index.html # <-- Landing page
├── _layouts # <-- Page layouts
├── _pages
│ ├── 404.md # <-- German version
│ ├── [...]
│ ├── en
│ │ ├── 404.md # <-- English version
│ │ ├── [...]
├── _posts/
│ └── en 
├── _projects/
├── _sass
│ ├── minimal-mistakes # <-- Styles (SCSS) for layouts and partials
│ ├── minimal-mistakes.scss
│ └── _video.scss
├── _site/ # <-- Build artifacts
├── staticman.yml

After

Hugo’s documentation provides a good overview of the folder structure. The root folders content, layouts, and static are the most important for day-to-day work with articles and the website’s appearance.

.
├── archetypes
├── assets
├── content
│ ├── de
│ │ ├── about.md
│ │ ├── announcements/
│ │ ├── posts/
│ │ └── projects/
│ └── en
│ ├── about.md
│ ├── [...]
├── data
├── hugo.yml
├── layouts
│ ├── _default
│ │ ├── baseof.html # <-- defines header, add-ons, content, footer structure
│ │ ├── index.html # <-- landing page
│ │ ├── list.html # <-- grid view
│ │ └── single.html # <-- post view
│ ├── _markup
│ │ └── render-link.html # <-- link highlighting and function (referrer, tabs)
│ ├── _partials
│ │ ├── cover.html # <-- cover (thumbnail) image rendering
│ │ └── math.html # <-- math rendering (katex)
│ └── _shortcodes
│ ├── audio.html
│ ├── image.html
│ └── [...]
├── resources
│ └── _gen
│ └── assets/
├── static
│ ├── assets
│ │ ├── audio/
│ │ ├── css/ # <-- contains overrides for custom layouts 
│ │ ├── docs/
│ │ ├── images/
│ │ ├── js/ # <-- math (katex) JS lives here
│ │ └── video/
│ └── terminal.css # <-- Central theme override (colors, formatting, styling)
└── themes
 └── terminal # <-- GIT submodule: Vanilla "Terminal" theme

With both solutions, layouts are defined in HTML and styles/formatting in CSS. However, since I had to use more plugins with Jekyll, the setup is more extensive.

Manual Adjustments: Shortcodes

Hugo’s shortcodes allow you to define non-text content (media, links, formatting, styles) that is then rendered according to specific rules. To do this, you create an HTML file that defines the wrapper and includes the relevant CSS classes. You also add the desired formatting to the theme’s overriding CSS file.

Since I am by no means an expert, I simply experiment until I am happy with the layout and no longer see any artifacts or overlapping elements.

.
├── layouts
│ └── _shortcodes
│ └── my-shortcode.html # <-- Custom shortcode file
├── static
│ └── terminal.css # <-- Central theme override (colors, formatting, styling)

Syntax: Hugo and Jekyll

In Hugo, shortcodes are represented in the Markdown file using the following syntax:

{{< shortcode-html-filename options >}}
{{< image src="/path/to/image.avif" alt="Image: alt text" position="right" >}}

By comparison, shortcode-like decorators in Jekyll using Liquid, the templating language employed by Jekyll look like this:

### Liquid in interpreter code
{% Liquid bracket syntax %}
### Liquid "shortcode" pendant
{% include gallery id="gallery" caption="Eindrücke von **MobFobAmp**. Zum Vergrößern anklicken." %}
### Liquid decorator for layouting
{:.list-inline}

image

Example of image display. A centered image follows on the next line.

The standard Markdown image syntax [Alt Text](/path/to/image) renders as a centered image without text wrapping by default in Hugo. However, for a pleasing layout, I need a few variations that require some additional CSS and HTML code.

Centered image, no text wrapping
Left-aligned image, text wrapping on the right
Right-aligned image, text wrapping on the left

First, Hugo retrieves the file path and alt text. Then, it reads the desired formatting defined via the position variable from the Markdown file. Finally, it applies the image-wrapper class from the CSS file. To ensure better readability, the image alignment applies only to the desktop version of the site (>684px).

The theme customizations required to display images correctly are quite extensive. I also developed a gallery feature for posts containing a large number of images. Consequently, I wrote a separate article covering image formatting and alignment.

audio

I use standard browser-native features to display the audio player.

Your browser does not support the audio element.

Beispielplayer: A lead melody on electric bass

{{- /* /layouts/_shortcodes/audio.html */ -}}

{{ $src := .Get "src" }}
{{ $caption := .Get "caption" | default "" }}

<div class="media-wrapper">
 <div class="media-container">
 <audio controls>
 <source src="{{ $src }}" type="audio/mp3">
 Your browser does not support the audio element.
 </audio>
 {{ with $caption }}
 <div class="media-title">{{ . }}</div>
 {{ end }}
 </div>
</div>

In css, I use a wrapper and a media container to display titles within the player frame and to simplify formatting. Here, too, I have implemented custom behavior for a responsive layout on mobile devices or when the browser window is resized.

video

The CSS is identical to that of the audio element; there are only minor differences in the HTML. The container I use supports both “embed links” from sites like PeerTube and local source files via the src= attribute.

Your browser does not support the video tag.

Video example (local): linear glides with ball bearing.

{{- /* /layouts/_shortcodes/video.html */ -}}

{{- $src := .Get "src" -}}
{{- $title := .Get "title" | default "" -}}
{{- $caption := .Get "caption" | default "" -}}

<div class="media-wrapper">
 <div class="media-container">
 {{- if hasPrefix $src "http" -}}
 <iframe src="{{ $src }}" frameborder="0" allowfullscreen></iframe>
 {{- else -}}
 <video controls>
 <source src="{{ $src }}" type="video/mp4">
 Your browser does not support the video tag.
 </video>
 {{- end -}}

 {{- if or $title $caption -}}
 <div class="media-title">
 {{- if $title -}}{{ $title }}{{- else -}}{{ $caption }}{{- end -}}
 </div>
 {{- end -}}
 </div>
</div>

Updates

My content ages, too. Sometimes I switch technologies or providers, and sometimes third parties move away from solutions I’ve described implementing here on the blog. That’s why I introduced update-shortcodes.

Links

I want the following behavior for links on my blog:

internal links should open in the same tab and redirect the user.
internal links should point to pages in the same language, rather than leading to the default language or back to the homepage.
external links should be marked with an icon: ↗
external links should open in a new tab: target="_blank"
external links should neither access the original content nor be able to see the referrer: rel="noopener noreferrer"

To achieve this, I create the file render-link.html in /layouts/_markup. I present the code and the background details in a separate post: Hugo Multi-language: Internal Permalinks

The CSS override looks like this:

/* /static/terminal.css */

.external-link .external-link-icon{
display: inline-block; 
font-size: var(--font-size); 
vertical-align: middle; 
transform: translateY(-0.1em);
}

Manual Customizations: Partials

You can think of partials as the layout building blocks for a Hugo website. They are stored in /layouts/_partials and override the defaults of the theme being used. Since the original file is no longer loaded at all, the recommended approach is to copy the original file into the folder and then customize it manually.

index

The blog’s homepage is entirely custom-written; it is not in Markdown format but in HTML. It displays its content differently than all other blog pages, so it wasn’t worth the effort for me to program specific templates. In the corresponding /layouts/_partials/index.html file, I load the necessary CSS files and define the page structure. The following table provides an overview of my changes.

File	Purpose	Customization
cover	thumbnail / cover image for overview pages, lists, and grids	Add custom cover image decorator, alt text
head	Defines Favicon, search console, page parameters, feeds etc.	Custom favicon path
header	Page header containing menu, logo, navigation etc.	Add logo and subtitle to menu, lang selector
logo	Custom page logo, title, subtitle	Full
math	Displays math content with Latex/Katex	None, implement math support

Math

My blog is designed to support mathematical notation. I use KaTeX for this.

{{- /* /layouts/_partials/math.html */ -}}

<link rel="stylesheet" href="/assets/css/katex.min.css">
<script defer src="/assets/js/katex.min.js"></script>
<script defer src="/assets/js/contrib/auto-render.min.js" onload="renderMathInElement(document.body);"></script>

<script>
 document.addEventListener("DOMContentLoaded", function() {
 renderMathInElement(document.body, {
 delimiters: [
 {left: '\\[', right: '\\]', display: true}, // block
 {left: '$$', right: '$$', display: true}, // block
 {left: '\\(', right: '\\)', display: false}, // inline
 ],
 throwOnError : false
 });
 });
</script>

cover image

I use the term cover to refer to a blog post’s title image. It is displayed on overview pages, in article and tag lists, etc., and is intended to complement the blog post’s content. My RSS feed should also use these images to provide an overview of various articles on my readers’ devices.

It is highly compressed and requires minimal bandwidth, resulting in a low resolution (440x220 or 640x352). To ensure a consistent look, the images are also always monochrome.

I use the following Markdown syntax to embed the cover image:

---
cover_alt: 'Image: Hugo console build output. It shows a full build time below 2sec. (~90% reduction over build time with Jekyll)'
cover: /assets/images/migrating-hugo-to-jekyll/hugo-jekyll-build-compare-cover.avif
---

Next, I create the file cover.html in the layouts/_partials directory and add the following code:

{{- /* /layouts/_partials/cover.html */ -}}

{{- /* Handles cover-image generation */ -}}

{{- $cover := false -}}
{{- $autoCover := default $.Site.Params.autoCover false }}

{{- if index .Params "cover" -}}
 {{- if .Resources.GetMatch .Params.Cover }}
 {{- $cover = (.Resources.GetMatch .Params.Cover).RelPermalink -}}
 {{- else -}}
 {{- $cover = absURL .Params.Cover -}}
 {{- end -}}
{{- else if $.Site.Params.AutoCover -}}
 {{- if (not .Params.Cover) -}}
 {{- if .Resources.GetMatch "cover.*" -}}
 {{- $cover = (.Resources.GetMatch "cover.*").RelPermalink -}}
 {{- end -}}
 {{- end -}}
{{- end -}}

{{if $cover -}}
 <!-- Cover image found -->
 <img src="{{ $cover }}"
 class="post-cover"
 alt="{{ .Params.cover_alt | plainify | default (.Description| plainify) }}"
 title="{{ .Params.CoverCredit |plainify|default (.Title | plainify) }}" />
{{- end }}

The code searches for and extracts the path to the cover image. If a valid path is found, the image is displayed as post-cover with the corresponding CSS.

I insert the cover image into the XML template as the first element within the <description> tag; the actual article follows only after that. Most feed readers then use this image as the cover for their overview lists.

Manual Adjustments: Layouts

To ensure my Hugo site continues to feel very similar to my previous Jekyll site, I need to make a few changes to the layouts. I have described them below.

baseof.html

This is where the base content is defined. Definitions for the header and footer are imported, and stylesheets are linked. The vast majority of the changes described above are imported here.

{{- /* /layouts/baseof.html */ -}}

<!DOCTYPE html>
<html lang="{{ $.Site.Language }}">
<head>
 {{ if .Param "math" }}
 {{ partialCached "math.html" . }}
 {{ end }}
 {{ block "title" . }}
 <title>{{ if .IsHome }}{{ $.Site.Title }}{{ else }}{{ .Title }} :: {{ $.Site.Title }}{{ end }}</title>
 {{ end }}
 {{ partial "head.html" . }}
 <link rel="stylesheet" href="{{ "/assets/css/gallery.css" | relURL }}"> 
 <link rel="stylesheet" href="{{ "/assets/css/media.css" | relURL }}">
</head>
<body>
{{ $container := cond ($.Site.Params.FullWidthTheme | default false) "container full" (cond ($.Site.Params.CenterTheme | default false) "container center" "container") }}

<div class="{{- $container -}}{{- cond ($.Site.Params.oneHeadingSize | default false) " headings--one-size" "" }}">

 {{ partial "header.html" . }}

 <div class="content">
 {{ block "main" . }}
 {{ end }}
 </div>

 {{ block "footer" . }}
 {{ partial "footer.html" . }}
 {{ end }}
</div>

</body>
</html>

list.html

I need a list view for overview pages such as Articles, Tags, and Projects. I want to display four items per row. Each item gets its own “card” featuring a cover image, title, short description, and, if available, additional details like reading time. Hugo’s paginator crawls the relevant folder and compiles the content, while my list.css stylesheet handles the formatting and display.

{{- /* /layouts/_default/list.html */ -}}

{{ define "main" }}
 <link rel="stylesheet" href="{{ "/assets/css/list.css" | relURL }}">
 {{ with .Content }}
 <div class="index-content">
 {{ . }}
 </div>
 {{ end }}

 <div class="posts posts-grid">
 {{ range .Paginator.Pages }}
 <article class="post on-list">
 <a href="{{ .Permalink }}" class="post-card" aria-label="{{ .Title }}">
 {{ partial "cover.html" . }}

 <div class="post-card-body">
 <h4 class="post-title">
 {{ .Title | markdownify }}
 </h4>

 <div class="post-excerpt">
 {{ if .Description }}
 <p>{{ .Description }}</p>
 {{ end }}
 </div>

 {{- if and (.Param "readingTime") (eq (.Param "readingTime") true) -}}
 <div class="post-reading-time">
 {{ .ReadingTime }} {{ $.Site.Params.minuteReadingTime | default "min read" }}
 </div>
 {{- end -}}
 </div>
 </a>
 </article>
 {{ end }}

 {{ partial "pagination.html" . }}
 </div>
{{ end }}

single.html

My single.html is almost identical to the default implementation found in terminal. I only added the option to include a “banner-image” associated with the title and imported the _partial/cover.html snippet to load a cover image.

<article class="post">
{{ with .Params.banner }}
<img
src="{{ . }}"
class="post-banner"
alt="{{ $.Params.banner_alt | plainify | default ' ' }}"
/>
{{ end }}

Given all these changes, one might consider forking the theme to create a custom version… 🤔

Quality Control

Another new addition to my website is a check for broken links. The site has grown up and now contains so many internal and external links that manual checking is no longer practical. The article on htmltest configuration for Hugo documents the tool I use and how I account for Hugo-specific quirks during the process.

Publishing

I also need an automated pipeline for Hugo. Whenever I push a change to the main branch, the website should be automatically rebuilt and deployed. I describe exactly how this works in the article Building and Deploying a Hugo Website with GitHub Actions and Docker.

Performance

What has all this effort achieved? For users, the appearance and navigation remain very similar to the Jekyll-based site. However, the improvements are evident in faster load times, reduced data transfer, and better overall clarity. I provide a detailed comparison in the article Jekyll vs. Hugo Benchmarking.

Schallberts Blog with Hugo

Schallbert — Sun, 06 Sep 2026

What’s happened?

To mark its fifth anniversary 🥳, I’m moving schallbert’s Blog onto a new technical foundation!

I have migrated this blog from Jekyll to the site generator Hugo. It was a major undertaking: I dedicated a large portion of my free time to it over the course of about four months. The lion’s share of that effort went into creating and refining the styling, adapting my content to the new environment, fixing broken links, and documenting the migration process.

Why did I do it?

I was increasingly at odds with Jekyll: the main reasons were the numerous dependencies prone to frequent breakage, the ever-increasing build times, and the complex environment required for deployment to my server.

My site now builds about five times faster than before.

It loads less styling (CSS, JS), and the images are even more space-efficient.

Plus, I no longer have to keep Ruby and countless gems up to date.

When choosing a Hugo theme, I prioritized functionality over mere visual appeal. As a result, the site is now much simpler and more performant.

What’s in it for readers?

RSS logo ^[1]

The blog now offers an RSS feed. Plus, my projects are now included in the tags view. Finally, the migration process spawned numerous articles; these are intended to make such a move easier for others than it was for me and to clarify Hugo’s structural concepts.

What’s left to do?

I haven’t quite finished the overhaul yet:

Optimize the website for mobile viewing ✓
Enable centered display of images at native resolution ✓
Ensure the feed correctly displays article cover images ✓
Achieve a more consistent look via CSS (colors, image borders, etc.)
Make overview pages span the full screen width and display larger images
Add missing English translations ✓
Implement tags more specifically and with clearer distinctions
Add a sticky table of contents on the left-hand side

These pages will see further detailed improvements over the coming weeks. I’m looking forward to it!

schallbert

Image alignment and formatting in Hugo

Schallbert — Sat, 29 Aug 2026

Why do this?

My theme cannot derive image formatting or positioning from standard Markdown syntax like ![Image Alt Text](/path/to/image/). However, I need this capability to place images aligned left, center, or right, with or without text wrap. So, I have to take matters into my own hands and code a solution myself.

Getting started with shortcodes, layouts, and CSS

I get an overview at cshire and quickly realize that my initial attempt using /layouts/render-image.html isn’t working.

Debugging

This method lets me determine whether render-image.html is actually being read and applied—independent of any CSS:

<div style="border: 3px dashed red; padding: 10px; margin: 10px; font-weight: bold;">
RENDER-IMAGE.HTML IS BEING READ!
</div>

That works. So, Hugo must be missing something during the Markdown processing stage.

Troubleshooting

I can see now that Hugo is rendering the layout but isn’t processing my images correctly. Why? Because a trigger, called shortcode, is missing. In Hugo, shortcodes are created in Markdown using {{ <shortcode-name> parameter1="String" parametern="string" }}, processed via the corresponding template file /layouts/shortcodes/<shortcode-name>.html, and finally displayed based on CSS styling.

Shortcode: image.html

So, I create a shortcode template that allows me to pass a few extra parameters to the image beyond just the source file (src) and alt text (alt): position, caption, attrid, and attrlink. The image position and caption are self-explanatory. I wanted a way to include attribution for images I didn’t create myself. For these, I either access open content governed by terms such as Creative Commons or obtain prior written consent from the copyright holder.

{{- /* layouts/_shortcodes/image.html */ -}}

{{- $src := .Get "src" -}}
{{- $alt := .Get "alt" | default "" -}}
{{- $position := .Get "position" | default "center" -}}
{{- $caption := .Get "caption" -}}
{{- $attrid := .Get "attrid" -}}
{{- $attrlink := .Get "attrlink" -}}

<figure class="media-frame media-frame--{{ $position }}">
 <img src="{{ $src }}" alt="{{ $alt }}">

 {{- if $caption -}}
 <figcaption class="media-caption">
 <span class="caption-text">{{ $caption }}</span>
 {{- if and $attrid $attrlink -}}
 <a
 href="{{ $attrlink }}"
 class="attr-link"
 aria-label="Attribution {{ $attrid }}"
 >
 <sup class="attr-id">[{{ $attrid }}]</sup>
 </a>
 {{- end -}}
 </figcaption>
 {{- end -}}
</figure>

This template reads the parameters provided via the shortcode and wraps the <img> tag in a <figure class="media-frame"> container, which holds the positioning information. If an image caption and/or attribution is provided, it is displayed within a <figcaption class="media-caption"> element.

Using the shortcode

In Markdown, a fully configured image would look like this:

{{< image src="/path/to/image.jpg"
alt="Example placeholder image for shortcode demonstration purposes"
caption="Shortcode demo image"
attrid="1" attrlink="https://example.com/"
position="right" >}}

Migration

But how do I convert the ![alt](/path/to/image) {: .align-center} syntax I previously used in Jekyll into the format shown above?

With a script! To do this, I’m creating a Python program that scans through all my articles, looking for images using the aforementioned formatting. When it finds a match, it extracts the src, alt, and position attributes and replaces the entire expression with the equivalent Hugo shortcode.

import os
import re
from pathlib import Path

# spaces/tabs only, no newlines
SPACES = r'[ \t]*'

IMG_WITH_OPTIONAL_ALIGN = re.compile(
 r'!\[([^\]]*?)\]\(([^)]*?)\)' # alt, src
 + SPACES + # optional spaces/tabs before decorator
 r'(?:\{:' + SPACES + # literal "{:"
 r'[^}\n]*?\.align-(center|left|right)\b[^}\n]*?' # decorator body (no newlines)
 r'\})?' # optional "}"
)

def convert_image_alignments(directory):
 def repl(m):
 alt = m.group(1).replace('"', "'")
 src = m.group(2)
 position = m.group(3) or ''
 # return built Hugo shortcode. Escape Python f-string curly brace { with {{.
 return f'{{{{< image src="{src}" alt="{alt}" position="{position}" >}}}}'

 for root, _, files in os.walk(directory):
 for file in files:
 if not file.endswith('.md'):
 continue

 filepath = Path(root) / file
 content = filepath.read_text(encoding='utf-8')

 new_content = IMG_WITH_OPTIONAL_ALIGN.sub(repl, content)
 if new_content != content:
 filepath.write_text(new_content, encoding='utf-8')
 print(f"Updated: {filepath}")

if __name__ == "__main__":
 project_root = input("Enter the path to your project root: ").strip()
 if os.path.isdir(project_root):
 convert_image_alignments(project_root)
 print("Conversion complete!")
 else:
 print("Invalid directory path.")

I enlisted the help of the large-language model Mistral for the regexes, but otherwise, the script is kept simple.

In Jekyll, images with titles and/or attribution were declared as figure elements. I am writing a very similar script for these as well and running it during the migration process.

CSS

Let’s move on to image display. I am creating a dedicated CSS file, /assets/css/media.css, designed to standardize the size and formatting of images as well as other embedded media such as audio and video files for both mobile and desktop views. To achieve this, it utilizes the class attributes defined in the template.

Here is an excerpt from the file to illustrate: this section defines the behavior of the media-frame object. Each asset (image, video, or audio) is embedded within a frame that provides the necessary breathing room for the display. The position attribute determines the placement and presentation style.

By default, the content is centered and displayed at its native resolution, provided it does not exceed the maximum text width.

.media-frame img,
.media-frame audio,
.media-frame video {
 display: block;
 width: auto;
 max-width: 100%;
 height: auto;

 margin: 0;
 padding: 0;
 border: 0;
 border-radius: 0;
}

.media-frame--center {
 margin-left: auto;
 margin-right: auto;
}

/* Left/Right align only for Non-mobile use */
@media (min-width: 768px) {
 .media-frame--left {
 float: left;
 max-width: 60%;
 margin-top: 0.35em;
 margin-right: 1rem;
 margin-bottom: 0.75rem;
 }

 .media-frame--right {
 float: right;
 max-width: 60%;
 margin-top: 0.35em;
 margin-left: 1rem;
 margin-bottom: 0.75rem;
 }
}

Images aligned to one side have their width restricted to allow text to flow around them. Additionally, minimum margins relative to other objects are defined to prevent frames from touching when media elements appear in succession. In the mobile view, space is so limited that images are always displayed centered.

Gallery

To display multiple images in a single location, I create a gallery shortcode along with the corresponding CSS. The gallery displays images in a grid. Hovering the mouse over an image makes it appear brighter than the others. Clicking an image displays a large version of it at the bottom of the gallery, reusing the media shortcode described earlier.

The images to be displayed are defined as a list—specifying src and alt attributes—within the Markdown document’s front matter. Here is an excerpt from the template used to process the shortcode.

<section class="hugo-gallery">
 <div class="hugo-gallery__frame">
 <div class="hugo-gallery__grid" role="list">
 {{- range $i, $img := $items -}}
 {{- $src := $img.src -}}
 {{- $alt := $img.alt | default (printf "Gallery image %d" (add $i 1)) -}}

 {{- $thumbURL := $src -}}
 {{- $p := strings.TrimPrefix $src "/assets/" -}}

 {{- with resources.Get $p -}}
 {{- $thumb := .Fit "400x220" -}}
 {{- $thumbURL = $thumb.RelPermalink -}}
 {{- end -}}

 <a
 class="hugo-gallery__thumb"
 href="#gallery-full-{{ $i }}"
 aria-label="{{ $alt }}">
 <img
 src="{{ $thumbURL }}"
 alt="{{ $alt }}"
 class="hugo-gallery__thumb-img"
 loading="lazy">
 </a>
 {{- end -}}
 </div>

I iterate through all the images defined in the front matter, limit their size to a manageable 400x220px, and arrange them in a grid using the class hugo-gallery__grid.

Tests

Creating the templates was relatively quick. However, I’m constantly at odds with CSS. Some override from another file keeps getting in the way, or I end up conflicting with the styles in the base CSS. That’s why I need a place to test formatting and layout.

So, I created an image test page for myself. Curious? Check how media is displayed in Hugo

htmltest configuration ideas for Hugo

Schallbert — Mon, 10 Aug 2026

I am now nearly finished migrating my website to Hugo. I had to make several adjustments to the front matter of each article so that they would function in Hugo much as they did in Jekyll. Changes to the folder structure, partly from the migration itself and partly from my experience as an author, meant I had to revise links in practically every article along the way. I now have nearly 340 of them, counting translations.

I cannot manage the sheer volume of links without some assistance. So, I need a tool.

htmltest

Htmltest is a utility that scans HTML files for issues. Among other things, it tracks down broken links. I install it using

# Red Hat-based Linux package manager install command
sudo dnf install htmltest

and run it against the HTML files built by Hugo in the /public directory:

htmltest public/
# [...]
✘✘✘ failed in 2.890119823s
2612 errors in 337 documents

That is quite a lot of errors! Furthermore, the way the information is presented seems rather cluttered to me: see the image.

Redirecting output to a file

Consequently, I am finding it quite difficult to work with this tool at first. I had assumed a few links might have broken, but I certainly didn’t expect thousands of errors. So I fell victim to the typical “not-invented-here” syndrome and programmed my own tool in Python, which, in hindsight, turned out not to be good enough. In short:

Htmltest is a good and incredibly fast tool. If you make its output readable and interpret it correctly, you can be quite happy with it. After a bit of experimentation, I arrived at the following command:

htmltest public/ 2>&1 | ansi2html > htmltest-output.html

Meaning: “Run htmltest in the /public/ folder. Redirect errors from stderr to stdout. Pipe the output to ansi2html¹. Write its output to a file named htmltest-output.html.”

That already looks much better!

Error categories

For my purposes, the errors found by htmltest can be sorted into a few categories:

Hugo-specific errors, such as “target does not exist” messages caused by livereload.js.
Incomplete links that work in practice but trigger “href lacks trailing slash” errors. These types of errors account for the lion’s share of the reported issues.
Lookup errors (GET <src> [...] failure in name resolution) caused by a lack of connection, insufficient permissions, active bot protection, or the target server being offline.
Hard “target does not exist” errors caused by broken links. These are the specific ones I actually wanted to fix.

Cleaning up the log

How do I ensure only category 4 errors are displayed? By making a few changes to the tools and resolving the trailing-slash errors.

Category 1 errors, triggered by Hugo’s useful livereload function, look like this:

target does not exist --- en/tags/tools/index.html --> /livereload.js?mindelay=10&v=2&port=1313&path=livereload

LiveReload is the feature that saves me from constantly hitting F5 in the browser window whenever Hugo builds the site after I save a Markdown file. However, I can temporarily disable it for the test. The following solution reduces the number of generated errors by one per HTML page:

hugo server --disableLiveReload

I avoid category 3 lookup errors by focusing on internal links, over which I have complete control. The -s, --skip-external parameter in htmltest helps with this:

htmltest -s public/ 2>&1 | ansi2html > htmltest-output.html
# [...]
✘✘✘ failed in 494.7678ms
446 errors in 337 documents

I can fix broken external links later. For now, I want to resolve the issues caused by the migration.

“Missing trailing slash”: Fixing errors via markup

I struggled for a long time with the many “href lacks trailing slash” errors, as I would have had to append a / to almost every Markdown link in every article. Fortunately, I found a solution in my render-link.html markup:

{{- /* /layouts/_markup/render-link.html */ -}}

{{- $url := .Destination | safeURL -}}
{{- $is_external := or (strings.HasPrefix $url "http://") (strings.HasPrefix $url "https://") -}}
{{- $is_anchor := strings.HasPrefix $url "#" -}}
{{- $is_asset := strings.HasPrefix $url "/assets/" -}}

[...]

{{- /* Add / to internal paths that have no file extension */ -}}
{{- if and (not $is_external) (not $is_anchor) (not $is_asset) -}}
 {{- $parsed := urls.Parse $url -}}
 {{- if and $parsed (not (strings.HasSuffix $parsed.Path "/")) (eq (path.Ext $parsed.Path) "") -}}
 {{- $url = printf "%s/" $url -}}
 {{- end -}}
{{- end -}}

[...]

Meaning: Internal links that point to neither headings (is_anchor) nor media files (is_asset) have a / appended if, and only if, they have valid syntax (parsed) and do not already end with a slash.

This resolves 95% of the error messages, resulting in cleaner HTML. I handle the remaining 5% by adding a few slashes in the Hugo configuration. Examples:

# hugo.yml
url: "/en/" # /en -> /en/
logoHomeLink: "/en/" # /en -> /en/

Done! All that remain are hard internal errors.

htmltest -s public/ 2>&1 | ansi2html > htmltest-output.html
# [...]
✘✘✘ failed in 359.28ms
102 errors in 84 documents

Manual Search and Fix

What follows is purely a matter of tedious legwork. I open the target document (the one being linked to) and check for inconsistencies, such as heading links that differ between languages. If I find any, I add specific anchor links to the heading.

### Heading {#heading3}

If everything is fine in the target file, I then open all the source files that use the broken link and correct it manually. In most cases, the target file has moved to a different folder, or the language prefix is incorrect.

The Result

After a few hours of exhausting, lab manual work, I am rewarded:

htmltest public/ -s 2>&1
Skipping the checking of external links.
htmltest started at 10:51:23 on public
========================================================================
✔✔✔ passed in 238.970354ms
tested 338 documents

Soon I’ll be able to go online with my new-old site!

ansi2html (or colorized-logs) is a utility that converts console output to HTML, including formatting and text colors. ↩︎

Hugo Multi-Lang: Internal Permalinks

Schallbert — Mon, 27 Jul 2026

Anyone building a multilingual blog with Hugo might be familiar with the following problem:

Internal links in articles across different languages point only to pages in the default language.

Configuration

The issue stems from the following setting:

# hugo.yml

defaultContentLanguage: "de"
defaultContentLanguageInSubdir: false
disableDefaultLanguageRedirect: true

My default language is German, and the corresponding articles are built into the blog’s root directory. No redirect to the /de language directory takes place.

The directory structure is as follows:

├── content
│ ├── de
│ │ ├── about.md
│ │ ├── announcements
│ │ ├── legal.md
│ │ ├── posts
│ │ ├── privacy.md
│ │ └── projects
│ └── en
│ ├── about.md
│ ├── legal.md
│ ├── posts
│ ├── privacy.md
│ └── projects

The Problem with the Default Language

I make articles in my default language accessible via URLs like example.com/my-post and example.com/my-2nd-post/ by using the slug parameter. In the secondary language, however, they appear as example.com/en/my-post and example.com/en/my-2nd-post/.

If I want to link two articles internally, the link always points to the article in my default language.

# English version of my post
# example.com/en/my-post
---
slug: my-post

---
Post's English content
[2nd](/my-2nd-post)

As a result, instead of the desired /en/my-2nd-post, I end up at the German version: /my-2nd-post. I find this annoying, as it would require me to manually adjust every link in every article. Unfortunately, Hugo does not seem to provide a built-in solution for this. So, I am creating a rule for how links should be rendered:

{{- /* /layouts/_markup/render-link.html */ -}}

Solution: Language-Dependent Link Prefixes

Here is what needs to happen: When a relative link within the site is encountered during the build process, a language prefix (such as /en) should be prepended to the link only if the language of the page being rendered is not the default language (since I do not need a language prefix for the default language, given that defaultContentLanguageInSubdir is set to false).

Retrieving the Default Language

But how do I access the default language? The defaultContentLanguage parameter is not accessible within templates. After some research, I found a suitable solution to the problem in the Hugo community: The default language is usually the first language in the weight-based index (which determines the order in which languages appear): index .Page.Site.Home.AllTranslations 0. When I access this, the “first” one is my default language.

Code for render-link.html

{{- /* /layouts/_markup/render-link.html */ -}}

{{- $url := .Destination | safeURL -}}
{{- $currentLang := .Page.Language.Locale -}}

{{- $is_external := or (strings.HasPrefix $url "http://") (strings.HasPrefix $url "https://") -}}
{{- $is_anchor := strings.HasPrefix $url "#" -}}
{{- $is_asset := strings.HasPrefix $url "/assets/" -}}
{{- $is_lang_prefixed := strings.HasPrefix $url (printf "/%s/" $currentLang) -}}

{{- if $is_anchor -}}
 {{- $url = printf "%s%s" .Page.RelPermalink $url -}}
{{- else -}}
 {{- if not $is_external -}}
 {{- if and (not $is_lang_prefixed) (not $is_asset) (not .Page.Language.IsDefault) -}}
 {{- $url = printf "/%s%s" $currentLang $url -}}
 {{- end -}}
 {{- end -}}
{{- end -}}

{{- /* Add / to internal paths that have no file extension */ -}}
{{- if and (not $is_external) (not $is_anchor) (not $is_asset) -}}
 {{- $parsed := urls.Parse $url -}}
 {{- if and $parsed (not (strings.HasSuffix $parsed.Path "/")) (eq (path.Ext $parsed.Path) "") -}}
 {{- $url = printf "%s/" $url -}}
 {{- end -}}
{{- end -}}

<a href="{{ $url | relURL }}"{{ if $is_external }} target="_blank" rel="noopener noreferrer" class="external-link"{{ end }}>
 {{- .Text | safeHTML -}}
 {{- if $is_external -}}
 <span class="external-link-icon" aria-hidden="true">↗</span>
 {{- end -}}
</a>

As long as the default language and the weight index match, meaning the default language appears at the very top, this works perfectly well.

Additional functions

Here is what else the code does:

Checks if links are “external” - that is, leading away from my site. These are assigned a separate window and the ↗ indicator.
Checks if the link points to a heading “anchor.” See below for details.
Checks if the link points to a (media) file or “asset.” Asset links are not modified. If it is a heading link, it is expanded to the full URL if necessary. This follows this pattern: #heading --> /<opt_lang>/<opt_category>/<title>/#heading

Correctly resolving permalinks to headings

I have also found a solution for highly specific permalinks within a page. Let’s assume I have headings in different languages:

---
# German
# content/de/posts/yyyy-mm-dd-hugo-create-language-specific-permalinks.md

description: Mit _markup interne Links richtig routen
title: "Hugo Multi-Lang: Interne Permalinks"
slug: hugo-create-language-specific-permalinks
---

## Richtig auflösende Permalinks auf Überschriften {#permalinks}
Lorem Ipsum...

---
# English
# /content/en/posts/yyyy-mm-dd-hugo-create-language-specific-permalinks.md

description: Routing internal links with _markup
title: "Hugo Multi-Lang: Internal Permalinks"
slug: hugo-create-language-specific-permalinks
---

## Correct Permalinks to headings {#permalinks}
Lorem Ipsum...

Then, clicking this link back to the #permalinks heading should take the user back to the heading, regardless of the language. The key to this solution is introducing a heading definition (Heading-ID) in Markdown: in this case, {#permalinks}.

It doesn’t work quite yet.

This is because #permalinks points to <blog's baseurl>/#permalinks, meaning the link to the current page is missing. But we can fix that, too: I’ll extend the link renderer with a few lines of code to prepend the current page URL.

Code for render-link.html with heading support

{{- $is_anchor := strings.HasPrefix $url "#" -}}

{{- if $is_anchor -}}
{{- $url = printf "%s%s" .Page.RelPermalink $url -}}
{{- end -}}

Now, (#permalinks) expands to /hugo-create-language-specific-permalinks/#permalinks, so the link finally leads to the correct destination.