Markdown attributes

December 6, 2022

Overview

Hugo supports Markdown attributes on images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.

For example:

This is a paragraph.
{class="foo bar" id="baz"}

With class and id you can use shorthand notation:

This is a paragraph.
{.foo .bar #baz}

Hugo renders both of these to:

<p class="foo bar" id="baz">This is a paragraph.</p>

Configuration

Update your site configuration to enable Markdown attributes.

Block-level elements

[markup.goldmark.parser.attribute]
title = true # default is true; applies to h1-h6 elements
block = true # default is false; applies to other block-level elements 

Stand-alone images

By default, when the Markdown renderer (Goldmark) encounters a stand-alone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the CommonMark specification.

If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.

To apply attributes to a stand-alone image element, you must disable the default wrapping behavior:

[markup.goldmark.parser]
wrapStandAloneImageWithinParagraph = false # default is true

Usage

You may add global HTML attributes, or HTML attributes specific to the current element type.

Consistent with its content security model, Hugo removes HTML event attributes such as onclick and onmouseover.

Syntax

The attribute list consists of one or more key/value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.

For example:

> This is a blockquote.
{class="foo bar" hidden=hidden}

Hugo renders this to:

<blockquote class="foo bar" hidden="hidden">
  <p>This is a blockquote.</p>
</blockquote>

Position

In most cases, place the attribute list beneath the Markdown element. For headings and fenced code blocks, place the attribute list on the right.

Element	Position of attribute list
blockquote	bottom
fenced code block	right
heading	right
horizontal rule	bottom
image	bottom
list	bottom
paragraph	bottom
table	bottom

For example:

## Section 1 {class=foo}

```bash {class=foo linenos=inline}
declare a=1
echo "${a}"
```

This is a paragraph.
{class=foo}

As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of these options.

Examples

Markdown attributes are powerful, and in some cases can replace shortcodes.

Admonitions

Markdown

> This is a note.
{.info}

> This is a warning.
{.warning}

> This is dangerous.
{.danger}

Rendered

This is a note.

This is a warning.

This is dangerous.

Sass

.danger,
.info,
.warning {
  background: #eeeeee;
  border-left-style: solid;
  border-left-width: 5px;
  border-radius: 4px;
  margin-left: 0;
  margin-right: 0;
  > p {
    padding: 9px 18px;
  }
}

.danger {
  border-left-color: #ee0000;
}

.info {
  border-left-color: #385e9d;
}

.warning {
  border-left-color: #ffbb00;
}

Drop caps

Markdown

Marius made himself these replies, and declared to himself that they were good. He had not dared to press Jean Valjean on all the points which we have just indicated, but he did not confess to himself that he did not dare to do it. He adored Cosette, he possessed Cosette, Cosette was splendidly pure.
{.dropcap}

Rendered

Marius made himself these replies, and declared to himself that they were good. He had not dared to press Jean Valjean on all the points which we have just indicated, but he did not confess to himself that he did not dare to do it. He adored Cosette, he possessed Cosette, Cosette was splendidly pure.

Sass

.dropcap:first-letter {
  color: hsl(220, 65%, 33%)
  float: left;
  font-family: serif;
  font-size: 48px;
  line-height: 48px;
  padding-right: 4px;
}

Columns

These examples split the content of a block container into columns.

Markdown

A list of items:

- Item 1
- Item 2
- Item 3
- Item 4
- Item 5
- Item 6
- Item 7
- Item 8
- Item 9
{.c .c3}

There was nothing notable in the event which thus set the bells and the bourgeois of Paris in a ferment from early morning. It was neither an assault by the Picards nor the Burgundians, nor a hunt led along in procession, nor a revolt of scholars in the town of Laas, nor an entry of “our much dread lord, monsieur the king,” nor even a pretty hanging of male and female thieves by the courts of Paris.
{.c .c2}

Rendered

A list of items:

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8
Item 9

There was nothing notable in the event which thus set the bells and the bourgeois of Paris in a ferment from early morning. It was neither an assault by the Picards nor the Burgundians, nor a hunt led along in procession, nor a revolt of scholars in the town of Laas, nor an entry of “our much dread lord, monsieur the king,” nor even a pretty hanging of male and female thieves by the courts of Paris.

Sass

.c {
  column-gap: 2em;
}

ul.c,
ol.c {
  column-gap: 3em;
  width: fit-content;
}

.c2 {
  column-count: 2;
}

.c3 {
  column-count: 3;
}

.c4 {
  column-count: 4;
}

Image sizes

These examples set the CSS image width and height properties, changing the image display size. This does not affect the image file.

Markdown

![Bryce Canyon](/images/examples/a.jpg)
{.w300}

![Bryce Canyon](/images/examples/a.jpg)
{.h100}

![Bryce Canyon](/images/examples/a.jpg)
{.r50}

Rendered

Fixed width (300px) and auto height:

Fixed height (100px) and auto width:

Responsive (50% of available width with large screens; 100% of available width with smaller screens):

Sass

img {
  &.w300 {
    width: 300px;
    height: auto;
  }
  &.h100{
    width: auto;
    height: 100px;
  }
  &.r50 {
    width: 50%;
    height: auto;
  }
}

@media only screen and (max-width: 576px) {
  img.r50 {
    width: 100%;
  }
}

Outlines

Markdown

1. Section 1
   1. Section 1.1
      1. Section 1.1.1
         1. Section 1.1.1.1
         1. Section 1.1.1.2
      1. Section 1.1.2
   1. Section 1.2
1. Section 2
{.outline}

Rendered

Section 1
1. Section 1.1
  1. Section 1.1.1
    1. Section 1.1.1.1
    2. Section 1.1.1.2
  2. Section 1.1.2
2. Section 1.2
Section 2

Sass

ol.outline {
  li {
    list-style-type: upper-roman;
    > ol {
      padding-left: 27px;
    }
    ol {
      li {
        list-style-type: upper-alpha;
        ol {
          li {
            list-style-type: decimal;
            ol {
              li {
                list-style-type: lower-alpha;
              }
            }
          }
        }
      }
    }
  }
}

Task lists

Markdown

- [x] Step 1
  - [x] Step 1.1
  - [ ] Step 1.2
- [ ] Step 2
{.todo}

Rendered

Step 1
- Step 1.1
- Step 1.2
Step 2

Sass

ul.todo {
  padding-left: 18px;
  li {
    list-style-type: none;
    > ul {
      padding-left: 27px;
    }
    input {
      margin-right: 4px;
    }
  }
}

Last modified: February 11, 2024