Version 5.0 (WIP)

Introducing Wowchemy

We are thrilled to unveil the new Wowchemy branding and restructuring of the various Hugo Academic related projects to unite the ecosystem in one place on our mission to empower creators.

👉 Learn about the exciting journey in our blog post

This version is currently in beta testing! We anticipate releasing the finalised v5 shortly.

You can help beta test by updating to the latest v5.0.0-beta.0 release (or current master) version on GitHub, following the guide below. Remember to check back here for the final notes once it is released.

What’s new?

Welcome to the ⭐ EPIC ⭐ v5 release of Wowchemy.

We invite you to browse the new Wowchemy ecosystem on GitHub, star your favourite repositories to show your support ⭐️, and connect with the community:

There are a number of exciting updates in this version that we hope you will like, including:

  • A choice of new templates so you can more easily create other kinds of site in addition to the popular academic resume template
  • New book layout for multi-page content - easily create online courses, notebooks, knowledge bases, project documentation, or - you guessed it - books
    • Similar to the docs layout, but more intuitive to use
    • No need to manually define all the book menu links!
    • New shortcode for listing child pages {{< list_children >}}
    • We’ve already converted this Wowchemy Docs site to the books layout to make managing content even simpler
  • Add podcasts and music to your pages with the new Audio shortcode
    • For example, place markvard.mp3 in a page’s folder and use {{< audio src="markvard.mp3" >}}
  • Cite pages and publications with the new Cite shortcode
    • {{< cite page="/publication/preprint" view="4" >}}
  • Now also edit authors, talks, publications, projects, and the homepage (to an extent) in the Netlify CMS admin panel
  • Use emojis and custom SVG images as icons in the Featurette (skills) widget
  • Option to highlight specific authors (such as colleagues) in author lists (details below)
  • Add author notes such as for clarifying affiliations or contributions (details below)
  • Add spoilers such as to reveal answers to questions (details below)
  • Create call-to-action buttons with new shortcode
  • More widgets now support both 1 and 2 column variations
  • Experimental support for customization of both light and dark modes of a color theme

Other improvements include:

  • Significant performance increase such as by preloading pages
  • Ability to add a Creative Commons copyright license on either a site wide or per page basis (details below)
  • Ability to write the names of authors, tags, and categories in Unicode (e.g. Chinese)
  • More intuitive approach for users to choose a light, dark, or automatic (system default) appearance
  • Screen reader support added for featured images
  • Initial support for Right to Left (RTL) languages
  • Enable non-rectangular widget styles and shaped background reveals with the experimental clip_path option under a widget’s [design] section
    • Refer to CSS clip-path docs and generators for inspiration - draw a heart, a circular reveal of an underlying photographic background, or even a bear :D

Carry on reading to learn how to use these exciting new features on your site 🚀

How do I upgrade my site?

Want to update to this version? Refer to the update guide in conjunction with the changes mentioned below.

Note that if you are running the master (development) version rather than an official tagged release, some of these changes may already have been applied.

Alternatively, you may wish to start fresh with one of the new templates and migrate your domain and content across.

Supported Hugo Versions

This release is compatible with Hugo Extended v0.73-0.76. (Future Hugo versions may work but are untested.)

  • If you deploy your site with Netlify, update HUGO_VERSION in your netlify.toml to "0.76.5".
  • If you run Hugo on your computer, update the Hugo Extended app to a compatible version

Site Changes

  1. As a prerequisite, if your site does not contain a go.mod file (i.e. was based on the old Academic Kickstarter template), convert your site to use Hugo Modules.
    • After, if you wish to use the tagged v5.0.0 Beta 0 version (rather than master), you can ensure this by running:
    hugo mod get[email protected]
  2. Optionally, add the following lines to your config/_default/params.toml - view example:
    # Show related content at the bottom of pages?
    show_related = {page = false, post = true, project = true, publication = true, talk = true}
    # Show a copyright license from in the site footer?
    # Page specific copyright licenses are also possible by adding this option to a page's front matter.
    copyright_license = {enable = false, allow_derivatives = false, share_alike = true, allow_commercial = false, notice = "This work is licensed under {license}"}
    ## Content Management System
     # Enable the admin panel. See
     netlify_cms = true
    ## Icon Pack Extensions
     ai = true  # Academicons icon pack
    • Customize the new options above to your liking
      • Set ai = true above if your site uses the academic (ai) icon pack, otherwise you can get a performance boost by setting it to false
      • Set netlify_cms = true to enable the Netlify Identity authentication for you to login to the Netlify CMS admin panel
  3. The media library folder is now configurable, with the default changing from static/img/ to static/media/ as it can now contain any kind of media. Either:
    • Rename your site’s static/img/ folder to static/media/ (and update any references to the img/ folder in your Markdown files);
    • OR, add media_dir = "img" to params.toml to continue using the legacy location
  4. To align better with the Hugo framework, rename the name field to title in author profiles within the author/ folder and ensure each author profile is within its own folder - view example
    • E.g. name: Nelson Bighetti is renamed to title: Nelson Bighetti in content/authors/admin/
  5. If you use the Netlify CMS admin panel, remove the static/admin/ folder and install the admin module in your config/_default/config.toml:
      # Any existing modules here...
      # Install Netlify CMS
        path = ""
    • This change adds support for editing talks, publications, and projects in Netlify CMS in addition to fixing TypeError: e.replace is not a function error when using Netlify CMS (#1593)

Optional Changes

  • Make taxonomy URLs singular, consistent with other Wowchemy pages by adding the following to your config/_default/config.toml file:
    # Workaround Hugo publishing taxonomy URLs as plurals - consistently use singular across Wowchemy.
      authors = "/author/:slug/"
      tags = "/tag/:slug/"
      categories = "/category/:slug/"
      publication_types = "/publication-type/:slug/"
  • Rename any instances of the alert shortcode to callout as alert will be deprecated in a future release - warning messages will show which pages to update
  • Convert any pages using the docs type to use the more intuitive books type
    • docs type is still available to use, but may be deprecated at some stage
    • the books type doesn’t require any menu items to be created
  • If you are using a custom address format, the address formats have moved to a dedicated file. To modify the available formats, copy to data/address_formats.toml
  • Update your data/page_sharer.toml (if exists) to open WhatsApp sharing links in the WhatsApp mobile app rather than the web app
  • For non-English sites, add language pack options for translating Light (theme_light), Dark (theme_dark), and Automatic (theme_auto). Refer to the docs on customising the interface language for more info.


Check out the troubleshooting guide.

You can also compare your site structure, config, and front matter with those in the templates. Alternatively, consider starting fresh with one of the new templates and migrating your domain and content across.

If the issue is not resolved, feel free to post on our GitHub Discussions Forum with a link to your GitHub repository and a description of the issue.

New features for authors

Highlight authors in author lists

Multiple author names can now be highlighted in bold in author lists, for example if you wish to highlight your colleagues.

If you wish to highlight an author name in bold, add highlight_name: true to their author profile. The default user profile can be found at content/authors/admin/ (view example).

Add author notes for affiliations and contributions

Author notes can be added to a page’s front matter in the form:

- "Someone"
- "Someone else"
- "Equal contribution"
- "Equal contribution"

where the index of each author note corresponds with an author in the authors list.

An author note is rendered as a tooltip next to an author’s name:

Add author notes for affiliations and contributions.

Emojis and custom SVG images as icons

Use emojis and custom SVG images as icons in the Featurette (skills) widget.

In the future, we plan to extend support for emojis and custom SVG icons to other Wowchemy components.

Icon pack “emoji” gives you the ability to use emojis as icons

  • See all icons
  • Enter the emoji shortcode, such as :heart:, in Wowchemy’s icon field

Icon pack “custom” gives you the ability to use custom SVG icons

  • Create an SVG icon in your favorite image editor or download one from a site such as Flat Icon
  • Place the custom SVG icon in assets/images/icon-pack/, creating the folders if necessary
  • Reference the SVG icon name (without .svg extension) in the icon field

Examples for use in Featurette (skills) widget:

# Uncomment to use emoji icons.
# [[feature]]
#  icon = ": heart :"  # Remember to remove the spaces around the colons.
#  icon_pack = "emoji"
#  name = "Emojiness"
#  description = "100%"  

# Uncomment to use custom SVG icons.
# Place custom SVG icon in `assets/images/icon-pack/`, creating folders if necessary.
# Reference the SVG icon name (without `.svg` extension) in the `icon` field.
# [[feature]]
#  icon = "your-custom-icon-name"
#  icon_pack = "custom"
#  name = "Surfing"
#  description = "90%"

Create spoilers

To create a spoiler:

{{< spoiler text="Click to view the spoiler" >}} You found me! {{< /spoiler >}}

View the spoiler demo

Enables adding Creative Commons copyright licenses on both site wide and per page basis with the new params.toml and front matter option:

copyright_license = {enable = false, allow_derivatives = false, share_alike = true, allow_commercial = false, notice = "This work is licensed under {license}"}

Create buttons and call-to-actions

Create buttons and call-to-actions with new shortcodes.

Examples coming soon.

More intuitive appearance selector

Version 5 makes choosing a site appearance even more intuitive with textual labels rather than icons for the light, dark, and auto (system default) modes.

Rather than a 3-way icon-based toggle through light, dark, and automatic modes, present the user with a dropdown list of modes displayed in full textual representation. See #1596.

Adds language pack options for translating Light (theme_light), Dark (theme_dark), and Automatic (theme_auto).

Integration with Netlify Identity for Netlify CMS

Netlify Identity has been integrated for logging into Netlify CMS. It can be controlled via the new cms option in params.toml, as described in the Site Changes above.

If you had manually added the Netlify Identity script, it can be removed.

An optional alt_text parameter can be added when specifying a featured image in a page’s front matter. Alt text is used to describe the image when the page is read aloud by a screen reader. See #1592.

Additionally, the profile photo alt text has been improved from “avatar” to the person’s name, in alignment with major CMS and social sites.


  • Fix social sharing image for author pages
    • The social sharing logic was attempting to use the legacy system of defining the avatar image name in site.Params.avatar, however since the author system was added to Wowchemy, site.Params.avatar is now a group of params and the avatar itself is stored in the author’s page bundle.
    • Hence, use the avatar in the author’s page bundle (if it exists) to represent an author page
    • This bug could affect the image used to represent a page in social sharing and RSS

Language Packs

  • Initial support added for Right To Left (RTL) languages
  • Add Arabic (ar) language pack (#1642, #1654)
  • Add Somali language pack (#1607)
  • Add Lithuanian language pack (#1617)
  • Fix Czech translation (#1597)
  • Update NL translation (#1622)

Thank you

Last but certainly not least, a big Thank You to all the folks that helped to make Wowchemy even better.

Has Wowchemy helped you? Please consider supporting Wowchemy.

As always, we welcome your feedback.