Indenting markdown usually isn’t difficult, however there could be a few gotchas. Skip down to the end for a quick little Hugo shortcode for inserting indents in markdown.

The Problem

Earlier today, I wanted to indent a markdown page element that included a link, but for some reason, the HTML that wrapped the markdown link was breaking the things.

Search the web for how to “indent without adding a bullet or number in markdown” and you’ll likely come across multiple suggestions that rely on a mix of HTML tags and CSS styles.

Most suggestions either involve wrapping the target line with a div styled with a margin to create the indent or a ul and li pair styled to hide the bullet. These suggestions usually work when indenting plain text, but for some reason, they were breaking the link.

For example:

1

<div style="margin-left: 2em;">A: [Link](http://example.com)</div>

and

1

<ul><li style="list-style-type: none;">B: [Link](http://example.com)</li></ul>

Both of the above examples produced a malformed link when the site was built. As shown here, the markdown link was interpreted as plain text.

• B: [Link](http://example.com)

The issue can be avoided by inserting a blank line between the opening tags and the link markdown, but it’s not pretty.

1
2
3

<div style="margin-left: 2em;">

    A: [Link](http://example.com)</div>

and

1
2
3

<ul><li style="list-style-type: none;">

    B: [Link](http://example.com)</li></ul>

That worked:

• B: Link

Some people may not care too much about their site’s generated HTML, but if you do, you may find this solution is even less ideal once you view the source in a browser. That blank line not only introduces a new paragraph, but the p is opened after the div/li and isn’t closed until after the div/ul are closed.

1
2
3
4
5

<div style="margin-left: 2em;">
<p>A: <a href="http://example.com">Link</a></div></p>

<ul><li style="list-style-type: none;">
<p>B: <a href="http://example.com">Link</a></li></ul></p>

While browsers are pretty forgiving and try to understand what’s intended, opening and closing HTML tags should be handled like a Last In, First Out (LIFO) stack. Whichever tag you open last should be closed first.

Stack Good: <b><i>Last In, First Out (LIFO)</i></b>
Queue Bad: <b><i>First In, First Out (FIFO)</b></i>

The Solution

In this case, a better indent solution is to use a simple span styled as an inline-block with an appropriate left margin.

Wrapping the markdown link with the span works fine:

1

<span style="display:inline-block; margin-left: 2em;">C: [Link](http://example.com)</span>

Closing the span before the markdown is even cleaner:

1

<span style="display:inline-block; margin-left: 2em;"></span>D: [Link](http://example.com)

C: Link

D: Link

The Shortcode

To avoid having to insert custom individually styled spans everytime I want to indent something, I created a shortcode to simply things.

1
2
3
4
5

{{- if isset .Params 0 -}}
<span style="display:inline-block; width:{{ .Get 0 }};"></span>
{{- else -}}
<span style="display:inline-block; width:2em;"></span>
{{- end -}}

The argument after indent is optional. It will default to 2em. When using a %, wrap the value in quotes.

1
2
3
4
5

{{​< indent >}}E: [Default Indent](#e)</li></ul>
{{​< indent 2em >}}E: [2em Indent](#e)</li></ul>
{{​< indent 32px >}}E: [32px Indent](#e)</li></ul>
{{​< indent 3rem >}}E: [3rem Indent](#e)</li></ul>
{{​< indent "10%" >}}E: [10% Indent](#e)</li></ul>

E: Default Indent
E: 2em Indent
E: 32px Indent
E: 3rem Indent
E: 10% Indent

Enjoy