Add a class to images

It’s very difficult to do this. There are no blackfriday hooks, that I know of. Just use an html img tag in your markdown files.

I see, thank you for your explanation. I think that this would be enabled with a hook API, like this one with filters and actions.

Thank you then, I will look how I can manage this.

1 Like

Sounds to me like a typical shortcode case. Did you try that? See new Hugo Docs: Shortcode Templates

More specifically, you can use the figure shortcode:

1 Like

Thank you for your answers!

Actually, I did know about shortcodes. My approach is, everything that is specific to this website can embed every html / shortcode, and this is not an issue for me.

But my main content should be portable. This is why I chose to write in Markdown.

The very best workflow with my posts, essays and math writings is to write in Markdown or a common md dialect, and then export to other formats. This is what I currently do with pandoc and Hugo.

This is the reason why I need to write portable, sustainable content. But if I include pictures in them, I would like to take advantage of bootstrap classes to have fluid images in the content without having to modify my Markdown. This is one example amongst others.

Another one could be to add font awesome classesto blockquotes, and so on.

I more or less managed to do what you need by modifying the Pen markdown WYSIYG editor.

You can add Pen to your site and modify it further according to your needs.

The idea is to wrap an img or whatever other element you write in hugo shortcodes on markdown export.

In Pen’s case you have to manually copy the generated markdown and save it as a file.

It’s not the most advanced solution but it will get you what you need.

See this thread for more:

Thank you very muth @alexandros!

Actually, there seems to be a lot of solutions out there.

I assume that the ideal mechanism to do what we want would be to have a filter mechanism to modify the HTML produced by Blackfriday (part of Hugo or Blackfriday??). But as it is not possible for the moment, your solution seems to be nice enough.

Is there a way to automate it in a script?

Your solution made me think of another one: actually the Pandoc’s Markdown processor enables to add classes to images, and Pandoc also has filters. So we could do a script. All markdown content could be processed with pandoc into html (or into Markdown-with-html-elements), and then it would call Hugo.

This indeed would be a workaround, as we would lose server livereload and as this would be a great performance loss.

1 Like

The Pandoc solution seems very elegant. If you make a script please do share.

Right now I’m checking out another amazing markdown editor with live preview
Much more robust than Pen it has YAML frontmatter support.

Anyway. I guess that it would be ideal if Hugo had an inbuilt shortcode that detects images in the markdown syntax. If we could also have the ability to add classes to these markdown images that would be even better.

The syntax could have a pattern of something like this
![image alternative text](/path/to/image.png){: .shadow }

(BTW this is how Gitlab has extended the img markdown syntax for classes):

This would be a very cool feature for Hugo and it would greatly reduce the need for shortcodes.

But I don’t know if it can be done. It probably involves extending Blackfriday.

Maybe we should make a separate topic asking for this feature and if @bep or someone else thinks that this is doable then file an issue on Github.

I just saw that you already filed a Github issue about img classes at Blackfriday’s repo.

1 Like

Script shared here. This indeed solved my problem!

1 Like

@lebarde and whoever else is interested

It is possible to insert classes to markdown images in Hugo.

Here is the hack

Markdown Syntax

![{{% class %}}](1.jpg)

As you can see within the brackets that Markdown reserves for the alt attribute of an image I have included a shortcode called class.

Here are the contents of class.html

{{ with $.Page.Params.title}}{{.}}{{end}}" class="thumb b-lazy

What’s going on here? It’s very simple.
As we know the brackets output begins with alt=" by inserting the shortcode right after the left bracket this is output as:

alt="Some Title" class="thumb b-lazy"

Also note that within the shortcode I have not typed closing quotes (after b-lazy).

And that’s it! Markdown syntax images with preview in WYSIWYG editors and finally classes to control them.


It’s already possible using the inbuilt figure shortcode (use the class argument).

This is not about using Hugo shortcodes. This is about adding a class to an image in (almost) pure markdown syntax, that can be previewed in any WYSIWYG editor.

eg. ![alt](img.jpg)

I mentioned the figure shortcode (inbuilt) because your hack uses a custom shortcode class. So may be your editor simply reads ![{{% class %}}](1.jpg) as ![](1.jpg) and thus it doesn’t matter.

Precisely. A slight hack to control markdown images.

But nevertheless there is an open Github issue about the ability of controlling markdown syntax images with CSS classes at Blackfriday’s repo, for quite some time now. People ask for this because with Markdown the content is portable i.e. SSG agnostic and viewable across a variety of editors.

And the custom {{% class %}} shortcode is pretty easy to remove in the future if such a need arises with a simple RegEx.

Thanks for sharing.

I did not want to use Hugo-specific language in my writings, as they may be shared in other processors (like Pandoc).

This is why I wrote this script (discussion and source on Github) :


# This script converts a .md Markdown file into a HTML file.
# It takes advantage of Pandoc for that, but keeps the front
# matter verbatim in order to process it into Hugo.

# tmp file:

BASE=`basename $1 .md`
DIR=`dirname $1`

# 1) Get the frontmatter into the final html file
sed -n '1 { /^---/ { :a N; /\n---/! ba; p} }' $1 > ${HTML}

# 2) Get the rest of the Markdown content in a temp file
sed '1 { /^---/ { :a N; /\n---/! ba; d} }' $1 >> ${TMP}

# 3) Convert Markdown into HTML using pandoc and append it to html file
pandoc -f markdown-yaml_metadata_block -t html --parse-raw ${TMP} >> ${HTML}

# 4) Remove the draft line
grep -v "draft:\s*true" ${HTML} > ${TMP}
mv ${TMP} ${HTML}

# LAST: The temporary file has been moved into $HTML,
# there is no need to delete it.
#rm ${TMP}

exit 0

Feel free to use it for you. You only have to reserve the draft:true for post that you want to convert to HTML using that rich and wide Markdown processor.

I put that in my deploy script:


# This script ensures the site is ok to build against Hugo.

# Uses md2htmlyaml (
# to convert complex Markdown files to HTML.

# Grep searches for all the drafts
# ...But there was many temporary files ending with ~.
DRAFTS=`grep -lr "draft:\s*true" content | grep -v "~"`

# Convert all the drafts
for i in $DRAFTS; do
  md2htmlyaml $i

# Publish
rm -rf public
hugo && rsync -avz --delete public/

exit 0

Enjoy :slight_smile:

My 2 cents solution to get images centered and responsive:


In the css:

img[src$='#center'] {
  display: block;
  margin: 1.0rem auto;
  max-width: 100%;
  height: auto;

Welcome @DocMarty84 to the forum, and thank you for this elegant solution.

I recently came across this post. wasn’t sure if i should start a new one since this is related. I wanted to make a template for AMP pages and the <img tag is unsupported. I did not want to change all my posts to shortcode. I found out that the package used by hugo builds the tags using archaic methods of assembling the strings instead of using a template. Here is the lines of code in black friday that is to “blame”

With this said i think im givnig up home on markdown img tags and switching to shortcode for images. Unless anyone can help out generating amp-img from markdown img code

For posterity I want to point out that since Hugo v.0.62.0 users can have full control over the rendering of Markdown syntax images without shortcodes.