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 and educators.

👉 Learn about the exciting journey in our blog post

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

🙌 A big shout out to Christian and Rodri for kindly volunteering to support the community and moderate discussions.

Based on your feedback, there is now a choice of templates so you can more easily create other kinds of site in addition to the popular academic resume template, whilst still utilizing the same core features and documentation. Learn more in our blog post.

Based on your feedback, there is now a choice of templates.

Version 5 Releases

Welcome to the ⭐ EPIC ⭐ v5 release of Wowchemy.

Since version 5 is a major new release, we have taken an agile approach to provide some iterative pre-release beta versions prior to the full release. So what’s new in each iteration and how can you update? Continue reading below.

This version is currently in beta testing! Please help by providing your feedback and contributing.

You can help beta test by updating to the latest v5.0.0-beta.1 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 in Beta 0?

❤️ If you upgrade, please kindly give back and help support further improvements like this by sponsoring on Github

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

  • 📈 Data visualization
  • Cite pages and publications with the new Cite shortcode
    • {{< cite page="/publication/preprint" view="4" >}}
  • 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)
  • 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" >}}
  • 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
  • Add spoilers such as to reveal answers to questions (details below)

Other improvements include:

  • Significant performance increase such as by preloading pages
  • Customize the see all link in the Pages widget (details below)
  • 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)
  • Flicker-free light/dark theming
    • There’s no longer page flicker when a user’s light/dark preference differs to the theme’s default light/dark mode
  • 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

Learn how to use these exciting new features on your site by following the links and checking out the New Features section on this page 🚀

What’s new in Beta 1?

❤️ If you upgrade, please kindly give back and help support further improvements like this by sponsoring on Github

  • Changes to Contact form
    • for Formspree forms, a Form ID is now required - check your form still works as expected
    • if email is entered in params.toml, it’s now displayed in the Contact widget (since Formspree no longer uses this option)
  • Support for both 1 and 2 column widget variations for the following widgets: pages, featured, experience, accomplishments, contact, blank, tag_cloud, portfolio
  • Support for multiple books (e.g. multiple courses, notebooks, docs, or knowledge bases) each with its own dedicated sidebar menu
    • previously, pages from all books were listed together in the sidebar
  • Support for listing multiple books (e.g. multiple courses, notebooks, docs, or knowledge bases) - by creating an of type: page in the parent folder which contains multiple book folders
  • You can now choose from an incredible 34+ languages for your site
  • We have added more safe defaults for parameters in case they are not provided. This means that you can now remove any parameters you don’t need from params.toml. For example, comments config can be removed for a site that doesn’t use comments.
  • Create call-to-action buttons with new shortcode (details below)
  • Customize the see all link in the Featured widget (details below)
  • Add support for Microsoft Clarity analytics - see Guides > Analytics
  • Push footer to window bottom for short pages (except book pages)
  • Reduce wordwrap hyphenation (similar to other blogging platforms)
  • Fix Hugo not mounting the speaker notes plugin for Markdown slides
  • There’s now a minimal test site for testing and inspiration purposes (similar to the Hello World template)
  • Add experimental require_isotope = false option. If a site doesn’t require the Isotope Layout Engine (i.e. not using filter on publication archive page or the Portfolio widget), it can be disabled in params.toml for performance increase. Useful for very minimal templates such as the Hello Starter template.
  • Removed back to top button which received limited use given the fixed navbar, ToC sidebar for Books, and smarter scrolling in browsers.

💪 Some other exciting achievements between the v5.0.0 Beta 0 and Beta 1 releases include:

What’s new in Beta 2?

❤️ If you upgrade, please kindly give back and help support further improvements like this by sponsoring on Github

  • Now you can edit the homepage, publications, and slide decks in the Wowchemy CMS in addition to other content types (#1631)
  • Migration to the very latest web best practices
    • The demo of the light Academic template now achieves 100% Accessibility, 100% Best Practices, and 100% SEO scores
    • Hero widget’s image can now be moved from the media library to the widget page folder, e.g. home/, to become responsively sized.
  • Significantly improved site performance
    • Refer to the new Performance guide that has been added to the Guides sections of the docs
    • Unused styles can also now be removed from a site for advanced optimization
  • Improved performance for redirects (aliases)
    • Dedicated Netlify redirects file can now be generated from front matter aliases by adding redirects to config.toml > outputs > home, and disableAliases = true to config.toml.
  • Significantly improved default security of sites
    • Default security headers added with configurable CSP
    • CSP is configurable via (string) and (boolean).
    • To enable, add headers to config.toml > outputs > home
  • Improved Book navigation for courses/docs/notebooks - see below
  • The Portfolio widget can now be filtered on the backend by a set of tags (e.g. active/inactive projects or courses)
  • Option to un-publish author pages (see below)
  • Show button links in listings irrespective of their page type
    • For example, if a blog post has an attachment, it will now be linked in the listing as well as in its page header.
  • Add option to show social links in the site header (#2010) - see below
  • Add support for all event types beyond just talks
  • Add Cyberpunk and Earth theme packs
  • Show popular queries in the search dialog
    • Click the search icon above for a real, live example
  • The Spoiler and Table of Contents shortcodes now use the newly standardised collapsable HTML toggle component - functions similarly to GitHub toggle lists
  • Significant refactoring and optimization of the code base
  • Enable homepage section backgrounds to be set to gradient colors in color theme packs
  • Fix avatar image when sharing author profiles due to breaking change in Hugo (#1987)
  • Fix code highlight theme not applying in dark mode
  • Migrate Google Maps integration to be compatible with the latest API
  • Upgrade Reveal.js from v3.8.0 to v4.1.0 (#2018)
    • Slides now get a menu, support for Mermaid diagrams, and customization via the full range of RevealJS options
  • Translation updates to English, Hebrew, EU, ES
  • More comprehensive continuous integration pipeline to mitigate risk of bugs from contributions and increase code quality
Now you can edit widgets and their backgrounds in the online editor (CMS).

Did you know that archive pages can’t yet be edited in the Wowchemy CMS? You can hide archive pages from the CMS by adding cms_exclude to their front matter and editing them separately in the GitHub Editor if needed. Homepage editing in the CMS is also currently constrained to the options which all widgets have in common, such as title, position, and background. A future release may add more specific options.

Don’t want to publish author pages?

Given your feedback on having the option to provide author data, such as author names and avatars, but not to publish dedicated author pages for personal sites, Hugo team have responded by adding such capability to Hugo. Therefore, we have migrated away from the temporary link_authors workaround to support Hugo’s new capability.

To un-publish author pages from your site, create a content/authors/ file with the following:

  render: never
    render: never
    list: always

Curious to learn how these new options work? Check out Hugo’s docs.

To use, add label and display options to the superuser’s (e.g. content/authors/admin/ social links:

- icon: twitter
  icon_pack: fab
  label: Follow me on Twitter
    header: true

Improved book navigation

Easier book navigation for users on both desktop and mobile:

  1. Breadcrumbs can be shown at the top of pages on large screens
    • Add the following to the bottom of params.toml to use breadcrumb navigation on Book pages on large screens:
        page_types = {book = true}
  2. In the case of multiple courses/docs/notebooks (aka book of books), a link back to the list of courses/docs/notebooks is added to the book menu
    • Example: courses/learn-python/ will have a new item added to the book menu to link back to courses/ whereas a site with just a first-level book e.g. docs/ won’t see any change to the menu.
  3. The book menu now shows the chapter in the book’s mobile menu
  4. Dynamically show in-page table of contents when the right sidebar becomes hidden on smaller screens
    • Add {{< toc hide_on="xl" >}} where you would like the in-page ToC to appear

What’s new in Beta 3 (Upcoming)?

  • Custom list views
  • List view generator
  • Layout consistency improvements
  • Add option to disable publication filtering for large sites (#1327)[]

What’s new in Beta 4 (Upcoming)?

  • Support for customization of both light and dark modes of a color theme
  • Theme pack generator

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.78.2. (Future Hugo versions may work but are untested.)

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

Convert your site to use Hugo Modules

Wowchemy and its templates, such as Academic, use the open source Hugo tool to generate sites, converting Markdown to HTML.

Hugo team have taken the strategic decision to significantly transform Hugo with a plugin-like Module system, similar to competing static site generators. Hugo Modules are now the core building blocks in Hugo.

As such, we have taken the initiative to create a dedicated repository for Hugo Modules and convert the Wowchemy templates to use the new modular system.

If your site does not contain a go.mod file (i.e. was based on the old Academic Kickstarter template), it can be converted to use Hugo Modules.

You can attempt to upgrade in the cloud by using the GitHub editor. Otherwise, we can edit locally - the full version of Hugo now requires Git and Go, so let’s run a couple of commands to install those dependencies on your computer. It’s worth mentioning that the Hugo team hope to remove these dependencies in a future version of Hugo.

Open your Terminal (Mac/Linux) or Powershell (Windows) app and use the cd command to navigate to your website folder.

Remove the Git submodule for Academic:

git submodule deinit themes/academic    
git rm themes

(Alternatively, deleting the .gitmodules file and the themes folder may remove most of the old system.)

If you use the Netlify CMS admin panel, remove the static/admin/ folder as we’ll install it via the Module plugin system so that your site can automatically get updates for it.

Then update config/_defaults/config.toml:

  • Remove theme = "academic"
  • Add to the bottom of the file:
        path = ""
        path = ""

Add then hugo mod init my-site to create a go.mod file for Hugo to record your Hugo Modules (or copy the new go.mod file to your site folder). The go.mod file tells Hugo which version of Wowchemy (or any other modules) to load.

You may find it useful to compare your site with the latest Academic template.

If you wish to use the tagged v5.0.0 Beta 2 version (rather than the latest master), you can ensure this by running:

hugo mod clean
hugo mod get[email protected]
hugo mod get[email protected]
hugo mod tidy

Site Changes

Apply any relevant site changes consecutively. For example, if you are upgrading from v4 to the latest v5 Beta, apply Beta 0 changes, then Beta 1 changes, and so on. Whereas, if you wish to upgrade from v5 Beta 1 to Beta 2, just apply any relevent changes from the Beta 2 section below.

Site Changes for Beta 0

  1. Optionally, add the following lines to your config/_default/params.toml - view example:
    # Content Management System
     # Enable the admin panel. See
     netlify_cms = true
    # Icon Pack Extensions
     ai = true  # Enable the 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
  2. 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 (note Netlify CMS uses media folder)
  3. 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/

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 in a future release
    • 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.

Site Changes for Beta 1

Update with:

hugo mod clean
hugo mod get[email protected]
hugo mod get[email protected]
hugo mod tidy

Required Changes

  • Require Hugo Extended v0.78.2. (Future Hugo versions may work but are untested.)
    • Update your Hugo version in netlify.toml to 0.78.2

Optional Changes

  • Changes to Contact form
    • for Formspree forms, a Form ID is now required - check your form still works as expected
    • if email is entered in params.toml, it’s now displayed in the Contact widget (since Formspree no longer uses this option)

Site Changes for Beta 2

Update with:

hugo mod clean
hugo mod get[email protected]
hugo mod get[email protected]
hugo mod tidy

See any errors such as “failed to resolve output format” when upgrading? Check out the Troubleshooting guide.

Optional Changes

  • To increase performance of redirects (aliases)
    • A dedicated Netlify redirects file can now be generated from front matter aliases by adding redirects to config.toml > outputs > home, and disableAliases = true to config.toml
  • To increase site security and privacy (for Netlify hosted sites):
    • Add headers to config.toml > outputs > home
    • Optionally, set your Content Security Policy (CSP) via (string) and (boolean)
  • If using events/talks:
    • Rename content/talk folder to content/event (if applicable)
    • Remove type or layout set to talk in the front matter of any event/talk page (if applicable)
    • In any homepage (widget page) section which filters on events/talks (e.g. the default content/home/, find the page_type option in the front matter and change its value from talk to event
    • To keep any existing /talk/ URLs, set the following in config.toml:
        event = "/talk/:slug/"


Check out the troubleshooting guide.

If you deploy with Netlify, you might see Error: failed to download modules...unknown subcommand "mod" in which case login to Netlify and set GO_VERSION to 1.12 in your Environment settings. Then click Deploys tab, and from the Trigger Deploy dropdown, choose Deploy Site.

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

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:


# 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}"}

Create buttons and call-to-actions

Create buttons and call-to-actions (CTA) with new shortcodes.

Example CTA button:

{{< cta cta_text="Do something" cta_link="/" cta_new_tab="false" >}}

Example CTA with a link to an alternate action:

{{< cta cta_text="Do something" cta_link="/" cta_new_tab="false" cta_alt_text="Alternative action" cta_alt_link="/" cta_alt_new_tab="false" >}}

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.

Want to customize the See All link in the Pages and Featured widgets? Now you can!

There’s now the choice to hide the link, change the text, or change the link itself by adding the following TOML or YAML snippet to the bottom of the front matter for your Pages or Featured widget instances:


    enable = true
    text = "See all blog posts"
    link = "post/"


    enable: true
    text: See all blog posts
    link: post/

For details, see #1800.

You can now customize which types of page show recommended content in the footer by adding the following option to your params.toml:


# Show related content at the bottom of pages?
show_related = {page = false, post = true, project = true, publication = true, talk = true}

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)
  • Add Norwegian (nb) translation (#1914)
  • 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.