Version 5.0 Beta 0 (October 2020)
What’s new?
There are a number of exciting updates in this version that we hope you will like, including:
- š Data visualization
- Save your data and plot settings using the Plotly JSON format and then visualize your data using the new chart shortcode š
- Check out the data visualization demo and documentation
- 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" >}}
- For example, place
- 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 in Beta 1 release note)
- 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 š
Update to this version
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 yournetlify.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/_default/config.toml
:
- Remove
theme = "academic"
- Add to the bottom of the file:
[module] [[module.imports]] path = "github.com/wowchemy/wowchemy-hugo-themes/netlify-cms-academic" [[module.imports]] path = "github.com/wowchemy/wowchemy-hugo-themes/wowchemy"
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 0 version (rather than the cutting edge work-in-progress version), you can ensure this by running:
hugo mod clean
hugo mod get github.com/wowchemy/wowchemy-hugo-themes/[email protected]
hugo mod get github.com/wowchemy/wowchemy-hugo-themes/[email protected]
hugo mod tidy
Apply Breaking Changes
- Optionally, add the following lines to your
config/_default/params.toml
- view example:# PLACE THIS NEW [CMS] CONFIG SECTION AT THE END OF THE FILE # Content Management System [cms] # Enable the admin panel. See https://wowchemy.com/docs/install/ netlify_cms = true # Icon Pack Extensions [icon.pack] ai = true # Enable the Academicons icon pack https://jpswalsh.github.io/academicons/
- 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 tofalse
- Set
netlify_cms = true
to enable the Netlify Identity authentication for you to login to the Netlify CMS admin panel
- Set
- The media library folder is now configurable, with the default changing from
static/img/
tostatic/media/
as it can now contain any kind of media. Either:
- Rename your site’s
static/img/
folder tostatic/media/
(and update any references to theimg/
folder in your Markdown files); - OR, add
media_dir = "img"
toparams.toml
to continue using the legacy location (note Netlify CMS usesmedia
folder)
- To align better with the Hugo framework, rename the
name
field totitle
in author profiles within theauthor/
folder and ensure each author profile is within its own folder - view example
- E.g.
name: Nelson Bighetti
is renamed totitle: Nelson Bighetti
incontent/authors/admin/_index.md
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. [permalinks] authors = "/author/:slug/" tags = "/tag/:slug/" categories = "/category/:slug/" publication_types = "/publication-type/:slug/"
- Rename any instances of the
alert
shortcode tocallout
asalert
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 https://github.com/wowchemy/wowchemy-hugo-themes/blob/main/wowchemy/data/address_formats.toml to
data/address_formats.toml
or contribute an improvement - 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.
Troubleshooting
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/_index.md
(view example).
Add author notes for affiliations and contributions
Author notes can be added to a page’s front matter in the form:
authors:
- "Someone"
- "Someone else"
author_notes:
- "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:

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’sicon
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 theicon
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 >}}
Choose a copyright license
Enables adding Creative Commons copyright licenses on both site wide and per page basis with the new params.toml
and front matter option:
# PLACE THESE PARAMS IN THE MAIN CONFIG SECTION (NOT UNDER ANY [SUBSECTION])
# Show a copyright license from creativecommons.org 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}"}
More intuitive appearance selector

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.
Related content
You can now customize which types of page show recommended content in the footer by adding the following option to your params.toml
:
# PLACE THESE PARAMS IN THE MAIN CONFIG SECTION (NOT UNDER ANY [SUBSECTION])
# Show related content at the bottom of pages?
show_related = {page = false, post = true, project = true, publication = true, talk = true}
Screen reading featured images
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.
Fixes
- 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
- The social sharing logic was attempting to use the legacy system of defining the avatar image name in
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)