What's New

• 0.166.0 Minimum required Hugo version

• Breaking Change requiring action after upgrade

• Change Change of behavior, may require action

• New New behavior, often introducing new options

Version 9

9.4.0 (XXXX-XX-XX)

Change

• Change The text of your content is now better readable.

New

• New Your readers can now sort a table by its columns, also by several of them at once. Rows joined by merged cells stay together.

  Tables are not sortable by default. Give a single table the class sortable, or make all tables sortable with the new table.sortable option in your project configuration or a page’s front matter. A single table can then be excluded by the class nosortable.

9.3.0 (2026-10-21)

Change

• Change Level one headings, the section titles of the sidebar menu and the title of the openapi shortcode are no longer forced to uppercase but show as written. The uppercase look, inherited from the Learn theme, became iconic for this theme, but it is strongly opinionated and looks strange with many fonts, especially script and serif fonts.

  If you want to keep the iconic look for headings and the sidebar menu, add the following to your assets/css/custom.css:

  ​

  assets/css/custom.css

  h1,
  #R-sidebar .nav-title {
    text-transform: uppercase;
  }

• Change The greys of the theme now carry the tint of your theme variant.

  The borders and stripes of tables, the borders of a zoomable Mermaid diagram and of tabs with style=transparent, the shadows of cards and images, the hover of buttons, the titles of badges and the tracks of scrollbars now take their color from the variables BOX-NEUTRAL-color and BOX-GREY-color. BOX-NEUTRAL-color inherits from BOX-GREY-color. Formerly they were a fixed grey that could not be changed by a variant and was too faint in the high contrast variants.

  The border of code blocks, CODE-BLOCK-BORDER-color, now inherits from BOX-NEUTRAL-color instead of CODE-BLOCK-BG-color. The shipped variants were adjusted to this.

  If your own variant does not set CODE-BLOCK-BORDER-color, its code blocks now get a visible border in the neutral color. As code boxes take their color from it, the title and frame of callouts and tabs with style=code change as well. To restore the previous look, set CODE-BLOCK-BORDER-color in your variant to the value of CODE-BLOCK-BG-color, or set BOX-CODE-color to only change code boxes.

  If your variant sets BOX-NEUTRAL-color or BOX-GREY-color to a strong color, all these greys now show it as well.

• Change The logo of a variant is now set in the new params of the variant, which holds the values that override the site’s params while the variant is active. Setting logo directly on the variant is deprecated and you’ll get a warning; it still works for now.

  Change { identifier = 'neon', logo = { src = '/images/logo-neon.svg' } } to { identifier = 'neon', params = { logo = { src = '/images/logo-neon.svg' } } }.

• Change Printing a page and its print version now use a print variant, by default relearn-light, with the theme’s print variables made for paper on top of it. Formerly the print used a fixed look that no variant could change.

  Printed pages now also show the logo and title of your site.

  You can choose the print variant of your site with the new themeVariantPrint option, or one for each variant with its new print parameter. A variant that names itself as its print variant keeps its own fonts on paper.

  The variables PRINT-MERMAID-theme, PRINT-OPENAPI-theme and PRINT-OPENAPI-CODE-theme were removed. If you’ve set them, set MERMAID-theme, OPENAPI-theme and OPENAPI-CODE-theme in your copy of the print variables instead, or mark them !important in your print variant.

• Change The color variant relearn-bright is deprecated and will be removed with the next major release. You’ll get a warning if you use it.

  To keep it, copy assets/css/theme-relearn-bright.css from the theme into your site’s assets/css directory under a different name, like theme-my-bright.css, and use that name in the themeVariant option.

• Change The color variant relearn has only been kept for compatibility since 3.0.0, where relearn-light replaced it. It will be removed with the next major release and you’ll now get a warning if you use it.

  It is identical to relearn-light, use that name in the themeVariant option instead.

New

• New The new color variants tome-light and tome-dark give your site the look of a book, with calligraphic titles. They are the first shipped variants with tinted instead of grey content backgrounds, and show how colors the theme derives, like shadows, follow such a tint. Use them as a starting point for your own tinted variant.

  Many of the changes in this release were made to support this variant.

• New The new color yellow can be used as style in every shortcode taking one and set with BOX-YELLOW-color in your theme variant. Each shipped variant picks a yellow that is readable with its title and text colors.

  To keep it apart from yellow, orange - and with it the note severity - is now a true orange instead of an amber, and darker so its titles are readable as well.

• New The entries of the variant switcher can now be grouped by putting dividers into the themeVariant option. A divider with a name labels its group.

9.2.0 (2026-10-11)

Hugo 0.166.0

• 0.166.0 This release requires a newer Hugo version.

Change

• Change Accessibility is now a supported feature of the theme.

  With the new option link.underline set to true, links in your content are underlined, so they are told apart from the text around them by more than their color.

  To make accessibility happen, there were numerous changes, affecting all parts of the theme including the DOM.

  As a side effect, the keyboard shortcuts of the theme are now documented as well.

• Change The elements of your content, like tables, callouts, tabs, code blocks, blockquotes, Mermaid diagrams and images, now have rounded corners.

  For images, this is the new image effect rounded, which is enabled by default. If you want to restore the previous look of your images, set imageEffects.rounded to false in your project configuration.

• Change Markdown tables can now merge cells, using the syntax of Markdown Preview Enhanced. A cell containing only > merges into the cell to its right, a cell containing only ^ into the cell above.

  If one of your tables already has such a cell and should show the character itself, escape it with two backslashes, like \\>.

• Change The new pages shortcode lists pages of your site. Besides the layouts known from the now deprecated children shortcode, it can list descendants, siblings or ancestors, filter them and group and order them by any field or front matter parameter of a page.

  The children shortcode still works but issues a deprecation warning for each use, naming the pages call that replaces it. See the migration instructions.

  With type=group, the children shortcode no longer shows a multi-column layout. If you want to restore the previous behavior, replace it with the pages shortcode and columns=3.

• Change The new callout shortcode replaces the now deprecated notice shortcode, matching the name of the Markdown callouts it shares its boxes with. The parameters are unchanged.

  The notice shortcode still works but issues a deprecation warning for each use. Rename your calls to callout. See the migration instructions.

• Change Hugo’s built-in details shortcode replaces the now deprecated expand shortcode, so your content stays portable to other themes.

  The expand shortcode still works but issues a deprecation warning for each use. The parameters of the details shortcode are named differently, so a call can not just be renamed. See the migration instructions.

  If you already use the details shortcode, it now behaves like the one built into Hugo. Its content is rendered as Markdown if called with {{< details >}}, and the title parameter is honored. If your content is HTML or contains other shortcodes, set the new raw=true parameter to have it written as it is.

• Change The math shortcode now renders your formulae using Hugo’s built-in KaTeX while your site is built, instead of the MathJax library in the browser.

  The theme finds your formulae by the delimiters of Hugo’s Passthrough configuration. If your site doesn’t have it yet, add it, otherwise formulae marked by these delimiters are not rendered. With the codefence, shortcode and partial syntax, content without delimiters is rendered as one formula regardless.

  By default, formulae are written as MathML and displayed by the browser. If you prefer the look of KaTeX, which is the same in every browser, set math.output to htmlAndMathml.

  The options mathJaxInitialize and customMathJaxURL are gone. Instead, you can set any KaTeX option in math. If you defined your own macros, move them to math.macros.

  KaTeX doesn’t know every command of MathJax. A formula it can not render is written as its source and reported as a warning in your build.

• Change The front matter params.pages replaces params.children and is now honored on every page, not only on taxonomy and term pages. Together with Hugo’s cascade, you can give all listings of a subtree the same look.

  The former params.children is still honored as long as the children shortcode exists, but using it now prints a warning.

• Change How the logo and title are arranged is now set with the new logo.layout option.

  The logo.direction option is deprecated. It still works, but the theme warns you if you use it. Replace direction set to row by layout set to sidebar-row and direction set to column by layout set to sidebar-column.

• Change The elements of the topbar, like its buttons, are now configured with the topbarstart, topbarmiddle, topbarend and topbarmore options, the same way as the sidebar menus. The breadcrumb is now an element of the new middle area. You can set them in your project configuration or in the front matter of your pages.

  Redefining an area by a template in layouts/partials/topbar/area and calling the theme’s templates in layouts/partials/topbar/button is deprecated. Such an area template still defines its area, taking precedence over the options, and the button templates can still be called, but the theme warns you if you use them. The elements now live in layouts/partials/topbar/element. See the migration instructions.

• Change Versioning now builds on Hugo’s versions. All versions of your site are generated in one build of one project, and the version switcher links directly to the same page in the other versions.

  Links can point to a page in another version of your site with the new version query parameter, like /my-page?version=v1.0.0.

  The options versions, version and versionIndexURL are deprecated. They still work as long as you have not configured Hugo’s versions, but the theme warns you if you use them. See the migration instructions.

• Change Links into another language written with a language prefix like /pir/my-page are deprecated, and with them the option enableLegacyLanguageLinks. They still work if the option is set, but the theme warns you for each such link. Use the lang query parameter instead, like /my-page?lang=pir.

• Change The front matter pre and post, renamed in 5.0.0, now issue a deprecation warning. Use menuPre and menuPost instead.

• Change The options customMermaidURL and customOpenapiURL are deprecated. They still work, but the theme warns you if you use them.

  To use a different version of a library, store it in the assets directory of your site, where it replaces the shipped version. See the documentation of the mermaid and openapi shortcodes.

• Change The search with the Lunr engine now only looks for similarly written words if a word of your search term isn’t found as written. Previously, such words were always included and could bury the hits you were asking for.

New

• New The new color variants contrast-light and contrast-dark have colors chosen for high contrast.

• New A color variant can now be selected by a link with the new variant query parameter, like /my-page?variant=relearn-dark.

• New Markdown blockquotes can name the author and the source of the quotation with the new author, source and href Markdown attributes.

• New The callout shortcode has a new hint parameter to show a tooltip for the title of the box.

• New The tab shortcode has a new hint parameter to show a tooltip for a tab, which also names a tab that shows nothing but an icon.

• New The button shortcode and topbar buttons have a new istoggle parameter for buttons that show and hide something, telling assistive technology whether it is shown.

• New The cards shortcode has a new columns parameter to set the number of columns in full width mode.

• New The resources shortcode has a new pageref parameter to list the resources of another page bundle.

• New The openapi shortcode has a new lang parameter to set the language used for the reading direction of the Swagger UI and for the texts the theme adds to it. These texts are now translated.

• New The mermaid shortcode’s graph can now be focused, panned and zoomed with the keyboard.

  They now contain a new button to show it in a lightbox, where it is panned and zoomed the same way as on the page itself. Like an enlarged image, the enlarged graph has its own URL.

• New The results of the dedicated search page can now be printed, if your home page has print support activated. The new search.page.outputs option lets you decide this independently of your home page.

• New An entry of a Hugo menu can now be continued by the tree of the page it links to by setting params.type to page. For a taxonomy page, this shows all of its terms without listing them in your menu definition.

• New The theme writes no inline JavaScript anymore, so your site can be served with a strict Content Security Policy. On request, it also adds subresource integrity hashes to its scripts and stylesheets. The button and card shortcodes and topbar buttons have a new action parameter to run your own code without inline JavaScript.

• New The theme now ships a machine-readable SBOM at sbom.cdx.json, listing every third-party resource it can publish with your site, each with a license, a digest of the files the theme ships and - where upstream publishes them - a version and a package URL.

9.1.0 (2026-09-13)

Hugo 0.165.0

• 0.165.0 This release requires a newer Hugo version.

Change

• Change Assets are now busted by their content instead of by the time of your build, so a visitor only refetches what actually changed.

  Formerly every build appended a new id to each asset’s URL, emptying a visitor’s cache on each deployment even when no asset was different. If you referenced assets from your own partials, assetbusting.gotmpl is replaced by asset.gotmpl, which takes a resource and returns it ready to be linked. It is still honored but now issues a deprecation warning and will be removed with a future update of the theme.

  ​

  layouts/partials/custom-header.html

  {{ with resources.Get "/css/mine.css" }}
    {{ with partial "asset.gotmpl" . }}
  <link href="{{ .RelPermalink }}" rel="stylesheet">
    {{ end }}
  {{ end }}

  Below static this only concerns css/custom.css, js/custom.js and the favicon and logo images; everything else there is published as before. Those are published twice, once untouched and once processed - move them to assets to avoid the superfluous copy.

  As a busted name changes with its content, a build no longer overwrites the file its predecessor wrote and both remain. Purge your output directory, e.g. by building with Hugo’s --cleanDestinationDir, or it accumulates every version you ever built - which weighs most if you commit what you build, as publishing to a GitHub Pages branch does.

• Change The Perfect Scrollbar library is no longer shipped with the theme. All scrollbars are the ones of your browser now, styled by the theme.

  The scrollbars colors come from new theme variant variables, four for each of the three areas, the main content, the menu and the topbar flyouts. MAIN-SCROLLBAR-THUMB-color, MENU-SCROLLBAR-THUMB-color and TOPBAR-SCROLLBAR-THUMB-color color the moving thumb, MAIN-SCROLLBAR-TRACK-color, MENU-SCROLLBAR-TRACK-color and TOPBAR-SCROLLBAR-TRACK-color the track it moves in. Each of them has a -HOVER counterpart - like MAIN-SCROLLBAR-THUMB-HOVER-color or MENU-SCROLLBAR-TRACK-HOVER-color - for the respective hovered area.

  How many of those twelve colors you see an effect from depends on the scrollbar model your browser implements, so don’t expect all of them to show everywhere. Where the theme draws the menus scrollbar itself, all four of its colors apply and the thumb reacts to being hovered on its own. A browser that offers only the standard styling has no state for the thumb, so there the -HOVER colors are taken while the surrounding area is hovered instead. And where a browser draws an overlay scrollbar for the content or the topbar flyouts, it keeps its own and the four colors of that area go unused.

• Change The theme variant configuration has a new hidden parameter.

  If set to true, the variant will not be shown in the variant switcher but is still usable, e.g. as a sub-variant of an auto mode variant.

• Change The title above a page sidebar menu is now taken from the root page’s linkTitle front matter.

  Formerly this was documented to use the menuTitle front matter, although that was already removed in 6.0.0 in favor of Hugo’s own linkTitle. It is still honored if no linkTitle is set but now issues a deprecation warning and will be removed with a future update of the theme.

• Change Images now carry the dimensions of their resource, so a browser can reserve the space they will take before they have arrived.

  This avoids page reflows as each image loads and affects images that resolve to a resource Hugo can measure: a page resource or a file in your assets directory, in one of the common raster formats. An SVG, a remote address or a path in your static directory has no dimensions to give and is unchanged.

• Change The Lunr Languages where updated to 1.21.0.

  Searching with the Lunr adapter now finds terms that consist of digits only, like part or standard numbers.

New

• New The editURL option has a new macro ${BaseDir}, containing the directory ${FilePath} is resolved against.

  Joined, the two are the location of the displayed page on your disk during build, which lets the edit button open your local editor instead of a web service.

  ​

  yaml toml json

  params:
    editURL: vscode://file/${BaseDir}/${FilePath}

  [params]
    editURL = 'vscode://file/${BaseDir}/${FilePath}'

  {
     "params": {
        "editURL": "vscode://file/${BaseDir}/${FilePath}"
     }
  }

  The macro is written the way a URL writes a path - with forward slashes and without a leading slash - so the same setting works on Windows and on Unix-like systems.

• New The card shortcode has a new imagealt parameter, giving the card’s image a text alternative.

• New The theme has updated its Mermaid dependency to 11.17.2. This adds support for swimlanes, Venn, Ishikawa, Wardley, Cynefin and TreeView.

• New The translation for Portuguese was divided into European Portuguese and Brazilian Portuguese.

• New The search now supports the Polish language.

9.0.0 (2026-01-01)

Hugo

• Hugo When the theme introduced compatibility with Hugo 0.146.7 it had to remove a performance optimization due to a limitation in Hugo. This was later fixed in Hugo 0.149.0.

  This release reintroduces the performance optimization and will cause your page build to fail with the above mentioned Hugo versions. You either need to upgrade or downgrade Hugo to an unaffected version.

Breaking

• Breaking The children shortcode has a new layout resembling the taxonomy and term pages by setting type=group.

  Sadly, introducing usage of the shortcode in the taxonomy and term pages (see below) caused necessary breaking changes

  • the shortcode now requires enabling block attributes in your project configuration by setting markup.goldmark.parser.attribute.block to true
  • the call syntax for type=card now is {{< children >}} instead of {{% children %}} if markup.goldmark.renderer.unsafe is set to false in your project configuration (which is the default)

  In addition the shortcode learned some new parameter for displaying breadcrumbs and setting a heading depth.

Change

• Change This release comes with a new way to configure your logo image and title in the menu sidebar.

  With the new system you can

  • rely on auto detection for an image
  • remove the image completely
  • override the image for each variant
  • set color, sizes and fonts for title and image
  • let the image and title lay out vertically or horizontally
  • override the complete layout with your own partial (that’s the old way and still works)

  Nevertheless, this required massive changes to the CSS and most likely your logo will require tweaking of the CSS styles after an update.

  The easiest way to fix this is to remove a overridden layouts/partials/logo.html template in your installation and rely on the new configuration.

• Change Font Awesome was updated to version 7.1.0 which results in slightly different icons.

• Change The search results of the search box are now colored in the same way as the search results on the dedicated search page using color styles of the content area.

• Change The expand shortcode has changed its default text of Expand me... to Details to be in sync with Hugo’s built-in details shortcode and the details HTML element.

New

• New The taxonomy and term pages are now internally using the children shortcode. This makes it possible for you to set parameter of the children shortcode in your taxonomy/term pages front matter to change the layout.

  By that you can - for example - display the sub pages in a card layout. See the categories taxonomy for an example.

• New The themes dark-mode support for the openapi shortcode was changed to the built-in implementation of the used Swagger library.

Older Versions

• Version 8
• Version 7
• Version 6
• Version 5
• Version 4
• Version 3
• Version 2
• Version 1