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.3.0 (2026-10-21)

Change

• Change Level one head'ns, th' section titles o' th' sidebar menu an' th' title o' th' openapi shortcode be no longer forced t' uppercase but show as written. Th' uppercase look, inherited from th' Learrrn theme, became iconic fer this theme, but it be strongly opinionated an' looks strange wit' many fonts, especially script an' serif fonts.

  If ye want t' keep th' iconic look fer head'ns an' th' sidebar menu, add th' follow'n t' yer assets/css/custom.css:

  ​

  assets/css/custom.css

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

• Change Th' greys o' th' theme now carry th' tint o' yer theme variant.

  Th' borders an' stripes o' tables, th' borders o' a zoom'ble Merrrmaid diagram an' o' tabs wit' style=transparent, th' shadows o' cards an' images, th' hover o' buttons, th' titles o' badges an' th' tracks o' scrollbars now take their color from th' variables BOX-NEUTRAL-color an' 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 an' was too faint 'n th' high contrast variants.

  Th' border o' code blocks, CODE-BLOCK-BORDER-color, now inherits from BOX-NEUTRAL-color instead o' CODE-BLOCK-BG-color. Th' shipped variants were adjusted t' this.

  If yer own variant does not set CODE-BLOCK-BORDER-color, its code blocks now get a vis'ble border 'n th' neutral color. As code boxes take their color from it, th' title an' frame o' callouts an' tabs wit' style=code change as well. T' restore th' previous look, set CODE-BLOCK-BORDER-color 'n yer variant t' th' value o' CODE-BLOCK-BG-color, or set BOX-CODE-color t' only change code boxes.

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

• Change Th' logo o' a variant be now set 'n th' new params o' th' variant, which holds th' values that override th' site’s params while th' variant be active. Sett'n logo directly on th' variant be deprecated an' you’ll get a warning; it still works fer now.

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

• Change Print'n a plank an' its print version now use a print variant, by default relearn-light, wit' th' theme’s print variables made fer paper on top o' it. Formerly th' print used a fixed look that no variant could change.

  Printed planks now also show th' logo an' title o' yer ship.

  Ye can choose th' print variant o' yer ship wit' th' new themeVariantPrint option, or one fer each variant wit' its new print parameter. A variant that names itself as its print variant keeps its own fonts on paper.

  Th' variables PRINT-MERMAID-theme, PRINT-OPENAPI-theme an' PRINT-OPENAPI-CODE-theme were removed. If you’ve set them, set MERMAID-theme, OPENAPI-theme an' OPENAPI-CODE-theme 'n yer copy o' th' print variables instead, or mark them !important 'n yer print variant.

• Change Th' color variant relearn-bright be deprecated an' will be removed wit' th' next major release. You’ll get a warning if ye use it.

  T' keep it, copy assets/css/theme-relearn-bright.css from th' theme into yer site’s assets/css directory under a different name, like theme-my-bright.css, an' use that name 'n th' themeVariant option.

• Change Th' color variant relearn has only been kept fer compatibility since 3.0.0, whar' relearn-light replaced it. It will be removed wit' th' next major release an' you’ll now get a warning if ye use it.

  It be identical t' relearn-light, use that name 'n th' themeVariant option instead.

New

• New Th' new color variants tome-light an' tome-dark give yer ship th' look o' a book, wit' calligraphic titles. They be th' first shipped variants wit' tinted instead o' grey rrrambl'n backgrounds, an' show how colors th' theme derives, like shadows, follow such a tint. Use them as a start'n point fer yer own tinted variant.

  Many o' th' changes 'n this release were made t' support this variant.

• New Th' new color yellow can be used as style 'n every shortcode tak'n one an' set wit' BOX-YELLOW-color 'n yer theme variant. Each shipped variant picks a yellow that be read'ble wit' its title an' text colors.

  T' keep it apart from yellow, orange - an' wit' it th' note severity - be now a true orange instead o' an amber, an' darker so its titles be read'ble as well.

• New Th' entries o' th' variant switcher can now be grouped by putt'n dividers into th' themeVariant option. A divider wit' a name labels its group.

9.2.0 (2026-10-11)

Cap'n Hugo 0.166.0

• 0.166.0 This release requires a newer Cap'n Hugo version.

Change

• Change Accessibility be now a supported feature o' th' theme.

  Wit' th' new option link.underline set t' true, links 'n yer rrrambl'n be underlined, so they be told apart from th' text around them by more than their color.

  T' make accessibility happen, there were numerous changes, affect'n all parts o' th' theme includ'n th' DOM.

  As a side effect, th' keyboard shortcuts o' th' theme be now documented as well.

• Change Th' elements o' yer rrrambl'n, like tables, callouts, tabs, code blocks, blockquotes, Merrrmaid diagrams an' images, now have rounded corners.

  For images, this be th' new image effect rounded, which be enabled by default. If ye want t' restore th' previous look o' yer images, set imageEffects.rounded t' false 'n yer project configurat'n.

• Change Marrrkdown tables can now merge cells, us'n th' rules o' Marrrkdown Preview Enhanced. A cell contain'n only > merges into th' cell t' its right, a cell contain'n only ^ into th' cell above.

  If one o' yer tables already has such a cell an' should show th' character itself, escape it wit' two backslashes, like \\>.

• Change Th' new planks shortcode lists planks o' yer ship. Besides th' layouts known from th' now deprecated children shortcode, it can list descendants, sibl'ns or ancestors, filter them an' group an' order them by any field or front matter parameter o' a plank.

  Th' children shortcode still works but issues a deprecat'n warning fer each use, nam'n th' planks call that replaces it. See th' migrat'n instruct'ns.

  Wit' type=group, th' children shortcode no longer shows a multi-column layout. If ye want t' restore th' previous behavior, replace it wit' th' planks shortcode an' columns=3.

• Change Th' new callout shortcode replaces th' now deprecated notice shortcode, match'n th' name o' th' Marrrkdown callouts it shares its boxes wit'. Th' parameters be unchanged.

  Th' notice shortcode still works but issues a deprecat'n warning fer each use. Rename yer calls t' callout. See th' migrat'n instruct'ns.

• Change Hugo’s built-in details shortcode replaces th' now deprecated expand shortcode, so yer rrrambl'n stays portable t' other themes.

  Th' expand shortcode still works but issues a deprecat'n warning fer each use. Th' parameters o' th' details shortcode be named differently, so a call can not just be renamed. See th' migrat'n instruct'ns.

  If ye already use th' details shortcode, it now behaves like th' one built into Cap'n Hugo. Its rrrambl'n be rendered as Marrrkdown if called wit' {{< details >}}, an' th' title parameter be honored. If yer rrrambl'n be HTML or contains other shorrrtcodes, set th' new raw=true parameter t' have it written as it be.

• Change Th' math shortcode now renders yer formulae us'n Hugo’s built-in KaTeX while yer ship be built, instead o' th' MathJax library 'n th' browser.

  Th' theme finds yer formulae by th' delimiters o' Hugo’s Passthrough configurat'n. If yer ship doesn’t have it yet, add it, otherwise formulae marked by these delimiters be not rendered. Wit' th' codefence, shortcode an' partial rules, rrrambl'n without delimiters be rendered as one formula regardless.

  By default, formulae be written as MathML an' displayed by th' browser. If ye prefer th' look o' KaTeX, which be th' same 'n every browser, set math.output t' htmlAndMathml.

  Th' options mathJaxInitialize an' customMathJaxURL be gone. Instead, ye can set any KaTeX option 'n math. If ye defined yer own macros, move them t' math.macros.

  KaTeX doesn’t know every command o' MathJax. A formula it can not render be written as its source an' reported as a warning 'n yer build.

• Change Th' front matter params.pages replaces params.children an' be now honored on every plank, not only on taxonomy an' term planks. Together wit' Hugo’s cascade, ye can give all list'ns o' a subtree th' same look.

  Th' former params.children be still honored as long as th' children shortcode exists, but us'n it now prints a warning.

• Change How th' logo an' title be arranged be now set wit' th' new logo.layout option.

  Th' logo.direct'n option be deprecated. It still works, but th' theme warns ye if ye use it. Replace direct'n set t' row by layout set t' sidebar-row an' direct'n set t' column by layout set t' sidebar-column.

• Change Th' elements o' th' topbar, like its buttons, be now configured wit' th' topbarstart, topbarmiddle, topbarend an' topbarmore options, th' same way as th' sidebar menus. Th' breadcrumb be now an element o' th' new middle area. Ye can set them 'n yer project configurat'n or 'n th' front matter o' yer planks.

  Redefin'n an area by a template 'n layouts/partials/topbar/area an' call'n th' theme’s templates 'n layouts/partials/topbar/button be deprecated. Such an area template still defines its area, tak'n precedence over th' options, an' th' button templates can still be called, but th' theme warns ye if ye use them. Th' elements now live 'n layouts/partials/topbar/element. See th' migrat'n instruct'ns.

• Change Version'n now builds on Hugo’s versions. All versions o' yer ship be generated 'n one build o' one project, an' th' version switcher links directly t' th' same plank 'n th' other versions.

  Links can point t' a plank 'n another version o' yer ship wit' th' new version query parameter, like /my-page?version=v1.0.0.

  Th' options versions, version an' versionIndexURL be deprecated. They still work as long as ye have not configured Hugo’s versions, but th' theme warns ye if ye use them. See th' migrat'n instruct'ns.

• Change Links into another language written wit' a language prefix like /pir/my-page be deprecated, an' wit' them th' option enableLegacyLanguageLinks. They still work if th' option be set, but th' theme warns ye fer each such link. Use th' lang query parameter instead, like /my-page?lang=pir.

• Change Th' front matter pre an' post, renamed 'n 5.0.0, now issue a deprecat'n warning. Use menuPre an' menuPost instead.

• Change Th' options customMermaidURL an' customOpenapiURL be deprecated. They still work, but th' theme warns ye if ye use them.

  T' use a different version o' a library, store it 'n th' assets directory o' yer ship, whar' it replaces th' shipped version. See th' documentat'n o' th' mermaid an' openapi shorrrtcodes.

• Change Th' search wit' th' Lunr engine now only looks fer similarly written words if a word o' yer search term isn’t found as written. Previously, such words were always included an' could bury th' hits ye were ask'n fer.

New

• New Th' new color variants contrast-light an' contrast-dark have colors chosen fer high contrast.

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

• New Marrrkdown blockquotes can name th' author an' th' source o' th' quotat'n wit' th' new author, source an' href Marrrkdown attributes.

• New Th' callout shortcode has a new hint parameter t' show a tooltip fer th' title o' th' box.

• New Th' tab shortcode has a new hint parameter t' show a tooltip fer a tab, which also names a tab that shows noth'n but an ay'con.

• New Th' button shortcode an' topbar buttons have a new istoggle parameter fer buttons that show an' hide someth'n, tell'n assistive technology whether it be shown.

• New Th' cards shortcode has a new columns parameter t' set th' number o' columns 'n full width mode.

• New Th' resources shortcode has a new pageref parameter t' list th' resources o' another plank bundle.

• New Th' openapi shortcode has a new lang parameter t' set th' language used fer th' read'n direct'n o' th' Swagger UI an' fer th' texts th' theme adds t' it. These texts be now translated.

• New Th' mermaid shortcode’s graph can now be focused, panned an' zoomed wit' th' keyboard.

  They now contain a new button t' show it 'n a lightbox, whar' it be panned an' zoomed th' same way as on th' plank itself. Like an enlarged image, th' enlarged graph has its own URL.

• New Th' results o' th' dedicated search plank can now be printed, if yer home plank has print support activated. Th' new search.page.outputs option lets ye decide this independently o' yer home plank.

• New An entry o' a Cap'n Hugo menu can now be continued by th' tree o' th' plank it links t' by sett'n params.type t' plank. For a taxonomy plank, this shows all o' its terms without list'n them 'n yer menu definit'n.

• New Th' theme writes no inline JavaScript anymore, so yer ship can be served wit' a strict Rrrambl'n Security Policy. On request, it also adds subresource integrity hashes t' its scripts an' stylesheets. Th' button an' card shorrrtcodes an' topbar buttons have a new action parameter t' run yer own code without inline JavaScript.

• New Th' theme now ships a machine-read'ble SBOM at sbom.cdx.json, list'n every third-party resource it can publish wit' yer ship, each wit' a license, a digest o' th' files th' theme ships an' - whar' upstream publishes them - a version an' a package URL.

9.1.0 (2026-09-13)

Cap'n Hugo 0.165.0

• 0.165.0 This release requires a newer Cap'n Hugo version.

Change

• Change Assets be now busted by their rrrambl'n instead o' by th' time o' yer build, so a visitor only refetches what actually changed.

  Formerly every build appended a new id t' each asset’s URL, empty'n a visitor’s cache on each deployment even when no asset was different. If ye referenced assets from yer own partials, assetbust'n.gotmpl be replaced by asset.gotmpl, which takes a resource an' returns it ready t' be linked. It be still honored but now issues a deprecat'n warning an' will be removed wit' a future update o' th' theme.

  ​

  layouts/partials/custom-header.html

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

  Below static this only concerns css/custom.css, js/custom.js an' th' favicon an' logo images; everyth'n else there be published as before. Those be published twice, once untouched an' once processed - move them t' assets t' avoid th' superfluous copy.

  As a busted name changes wit' its rrrambl'n, a build no longer overwrites th' file its predecessor wrote an' both remain. Purge yer output directory, e.g. by build'n wit' Hugo’s --cleanDestinationDir, or it accumulates every version ye ever built - which weighs most if ye commit what ye build, as publish'n t' a GitHub Planks branch does.

• Change Th' Perfect Scrollbar library be no longer shipped wit' th' theme. All scrollbars be th' ones o' yer browser now, styled by th' theme.

  Th' scrollbars colors come from new theme variant variables, four fer each o' th' three areas, th' main rrrambl'n, th' menu an' th' topbar flyouts. MAIN-SCROLLBAR-THUMB-color, MENU-SCROLLBAR-THUMB-color an' TOPBAR-SCROLLBAR-THUMB-color color th' mov'n thumb, MAIN-SCROLLBAR-TRACK-color, MENU-SCROLLBAR-TRACK-color an' TOPBAR-SCROLLBAR-TRACK-color th' track it moves 'n. Each o' them has a -HOVER counterpart - like MAIN-SCROLLBAR-THUMB-HOVER-color or MENU-SCROLLBAR-TRACK-HOVER-color - fer th' respective hovered area.

  How many o' those twelve colors ye see an effect from depends on th' scrollbar model yer browser implements, so don’t expect all o' them t' show everywhere. Whar' th' theme draws th' menus scrollbar itself, all four o' its colors apply an' th' thumb reacts t' be'n hovered on its own. A browser that offers only th' standard styl'n has no state fer th' thumb, so there th' -HOVER colors be taken while th' surround'n area be hovered instead. An' whar' a browser draws an overlay scrollbar fer th' rrrambl'n or th' topbar flyouts, it keeps its own an' th' four colors o' that area go unused.

• Change Th' theme variant configurat'n has a new hidden parameter.

  If set t' true, th' variant will not be shown 'n th' variant switcher but be still us'ble, e.g. as a sub-variant o' an auto mode variant.

• Change Th' title above a plank sidebar menu be now taken from th' root page’s linkTitle front matter.

  Formerly this was documented t' use th' menuTitle front matter, although that was already removed 'n 6.0.0 'n favor o' Hugo’s own linkTitle. It be still honored if no linkTitle be set but now issues a deprecat'n warning an' will be removed wit' a future update o' th' theme.

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

  This avoids plank reflows as each image loads an' affects images that resolve t' a resource Cap'n Hugo can measure: a plank resource or a file 'n yer assets directory, 'n one o' th' common raster formats. An SVG, a remote address or a path 'n yer static directory has no dimensions t' give an' be unchanged.

• Change Th' Lunr Languages whar' updated t' 1.21.0.

  Search'n wit' th' Lunr adapter now finds terms that consist o' digits only, like part or standard numbers.

New

• New Th' editURL option has a new macro ${BaseDir}, contain'n th' directory ${FilePath} be resolved against.

  Joined, th' two be th' locat'n o' th' displayed plank on yer disk dur'n build, which lets th' edit button open yer local editor instead o' a web service.

  ​

  yaml toml json

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

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

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

  Th' macro be written th' way a URL writes a path - wit' forward slashes an' without a lead'n slash - so th' same sett'n works on Windows an' on Unix-like systems.

• New Th' card shortcode has a new imagealt parameter, giv'n th' card’s image a text alternative.

• New Th' theme has updated its Merrrmaid dependency t' 11.17.2. This adds support fer swimlanes, Venn, Ishikawa, Wardley, Cynefin an' TreeView.

• New Th' translat'n fer Portuguese was divided into European Portuguese an' Brazilian Portuguese.

• New Th' search now supports th' Polish language.

9.0.0 (2026-01-01)

Cap'n Hugo

• Cap'n Hugo When th' theme introduced compatibility wit' Cap'n Hugo 0.146.7 it had t' remove a performance optimizat'n due t' a limitat'n 'n Hugo. This was later fixed 'n Hugo 0.149.0.

  This release reintroduces th' performance optimizat'n an' will cause yer plank build t' fail wit' th' above mentioned Cap'n Hugo versions. Ye either need t' upgrade or downgrade Cap'n Hugo t' an unaffected version.

Break'n

• Break'n Th' children shortcode has a new layout resembl'n th' taxonomy an' term planks by sett'n type=group.

  Sadly, introduc'n usage o' th' shortcode 'n th' taxonomy an' term planks (see below) caused necessary breaking changes

  • th' shortcode now requires enabl'n block attributes 'n yer project configurat'n by sett'n marrrkup.goldmark.parser.attribute.block t' true
  • th' call rules fer type=card now be {{< children >}} instead o' {{% children %}} if marrrkup.goldmark.renderer.unsafe be set t' false 'n yer project configurat'n (which be th' default)

  In addit'n th' shortcode learned some new parameter fer display'n breadcrumbs an' sett'n a head'n depth.

Change

• Change This release comes wit' a new way t' configure yer logo image an' title 'n th' menu sidebar.

  Wit' th' new system ye can

  • rely on auto detect'n fer an image
  • remove th' image completely
  • override th' image fer each variant
  • set color, sizes an' fonts fer title an' image
  • let th' image an' title lay out vertically or horizontally
  • override th' complete layout wit' yer own partial (that’s th' old way an' still works)

  Nevertheless, this required massive changes t' th' CSS an' most likely yer logo will require tweak'n o' th' CSS styles after an update.

  Th' easiest way t' fix this be t' remove a overridden layouts/partials/logo.html template 'n yer installat'n an' rely on th' new configurat'n.

• Change Font Awesome was updated t' version 7.1.0 which results 'n slightly different ay'cons.

• Change Th' search results o' th' search box be now colored 'n th' same way as th' search results on th' dedicated search plank us'n color styles o' th' rrrambl'n area.

• Change Th' expand shortcode has changed its default text o' Expand me... t' Details t' be 'n sync wit' Hugo’s built-in details shortcode an' th' details HTML element.

New

• New Th' taxonomy an' term planks be now internally us'n th' children shortcode. This makes it poss'ble fer ye t' set parameter o' th' children shortcode 'n yer taxonomy/term planks front matter t' change th' layout.

  By that ye can - fer example - display th' sub planks 'n a card layout. See th' categories taxonomy fer an example.

• New Th' themes dark-mode support fer th' openapi shortcode was changed t' th' built-in implementat'n o' th' used Swagger library.

Older Versions

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