Hugo is great but there is a lot of smaller knowledge you need to possess to use it effectively.

Markdown

How to add id or class attributes to headings

You can add id, classes, and custom attributes to headings :

## heading {#id .className attrName=attrValue class="class1 class2"}

Otherwise your anchors may break if you change the heading text.

How to add a line break

To add a line break you need to put a trailing \ at the end of the line:

> First line \
> Second line

First line
Second line

It will prevent the strings from joining:

> First line
> Second line

First line Second line

… or two separate paragraphs with too much padding:

> First line
>
> Second line

First line

Second line

When you know a constant URL to an internal page, there is a temptation to write it directly, like <a href="/about">link</a>. The problem is that there is nothing permanent except change, which means that sooner or later this “constant” URL will change and the user will get a 404 error unless you correct it manually.

Thus, it is better to use the ref function that will throw an error when building the website, if the URL cannot be resolved:

<a href="{{<ref "/about">}}">link</a>

In the same manner, it will protect you from typos.

Plus optionally add an icon that the link is external: todox.online .

This can be done with Hugo’s markdown render hooks . Create a file render-link.html in the directory [HUGO_ROOT]/layouts/_default/_markup/.

It functions as a default shortcode for all links in markdown, converting [todox.online](https://todox.online) to the necessary HTML representation. For example, I use the following shortcode:

<a href="{{ replace .Destination "#no_external_mark" "" | safeURL }}" {{ with .Title }} title="{{ . }}" {{ end }}
{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener noreferrer" {{ end }}>
    {{- .Text | safeHTML -}}
    {{ if (and (strings.HasPrefix .Destination "http") (not (in .Destination "#no_external_mark"))) }}
        <svg width="14px" height="14px" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" style="margin-bottom: 6px; margin-top: -6px; margin-left:3px; fill: #c4c4c5;">
            <g data-name="Layer 2">
                <g data-name="external-link">
                    <rect width="24" height="24" opacity="0"/>
                    <path d="M20 11a1 1 0 0 0-1 1v6a1 1 0 0 1-1 1H6a1 1 0 0 1-1-1V6a1 1 0 0 1 1-1h6a1 1 0 0 0 0-2H6a3 3 0 0 0-3 3v12a3 3 0 0 0 3 3h12a3 3 0 0 0 3-3v-6a1 1 0 0 0-1-1z"/>
                    <path d="M16 5h1.58l-6.29 6.28a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0L19 6.42V8a1 1 0 0 0 1 1 1 1 0 0 0 1-1V4a1 1 0 0 0-1-1h-4a1 1 0 0 0 0 2z"/>
                </g>
            </g>
        </svg>
    {{ end -}}
</a>

This hook also allows to optionally remove the external icon by adding to the url #no_external_mark, for example, if the link wraps an image or another element. It will be removed from the final url: todox.online.

Icon from: thenounproject.com