In a recent release, Platen added much stronger integration with Shoelace. This brings a host of benefits, especially around composing configurable theme components and icons.
With this release, Platen raises a warning when you use legacy components and markup, but still defaults to those legacy implementations. In the future, the new components and markup will become the default. Later, opting to use the legacy options will raise an error instead of a warning. Finally, the legacy implementations will be removed.
We strongly recommend you migrate your site and any theme customizations to use the new components and markup.
Display Updates #
The display
section of the configuration has expanded to cover several new features, replacing old non-configurable
components of the theme with much more configurable and functional components.
Table of Contents #
The table of contents (TOC) implementation has been reworked from a minimalist set of nested list items that linked to the headings on the current page to a collapsible list of links using Shoelace’s Tree and Tree Item components.
If you enable the updated TOC, you can customize the indentation for the TOC as well as the collapse and expand icons. Further, the implementation supports adding icons before and after the link text in the TOC by specifying attributes on headings in your Markdown.
Multilingual Languages Icon #
For multilingual sites, the languages icon in the site menu that displays for the translated pages dropdown is now
implemented as a Shoelace Icon and is configurable. You can use the platen.display.menu.languages_icon
settings to configure it.
Mobile Controls Buttons #
The controls at the top of content pages for showing the site menu and the table of contents have been updated to use
Shoelace’s Icon Buttons. They use Shoelace’s Tooltip to display extra information when you
hover on them. You can configure both buttons with the menu_control
and toc_control
settings in
platen.display.mobile
. You can override the icons, the tooltips, and the accessibility labels.
Footer Link Buttons #
The links at the bottom of the page for seeing the last edit to a page and editing it online have been reworked. Instead of links, they’re now Shoelace Buttons.
The new button for the last edited on link now displays how long its been since the page was last updated. If you hover on the button, it displays the localized time and date for that last update. Clicking the link takes you to the commit that last updated the file.
The new button for the edit this page link is simpler and doesn’t have a tooltip.
You can configure both buttons, including replacing their icons, updating their text, or removing them entirely, with
the last_edited_on
and edit_this_page
settings in platen.display.footer
.
Updating Your Configuration #
To update your configuration to use the new display settings, you can either update the _params/platen/display.yaml
file in your site’s data
folder or your hugo.yaml
site configuration file.
For your convenience, Platen supports configuring your site with data files in the _params
folder. If you followed
the Happy Path when setting up your site, or if you used the Platen Template, you already have the data
files and folders created for configuring Platen from your site data.
The tabs below explain how you can use either option to update your configuration and take advantage of the new functionality.
data/_params
Update the _params/platen/display.yaml
file in your site’s data
folder.
Make sure the settings below are defined correctly in the file.
table_of_contents:
languages_icon:
use_legacy: false
mobile:
menu_control:
use_legacy: false
toc_control:
use_legacy: false
footer:
last_edited_on:
use_legacy: false
edit_this_page:
use_legacy: false
hugo.yaml
If you’d rather manage your configuration options in a single configuration
file, you can edit your hugo.yaml
file.
Ensure the following key-value pairs are set in your hugo.yaml
configuration
file.
platen:
display:
table_of_contents:
languages_icon:
use_legacy: false
mobile:
menu_control:
use_legacy: false
toc_control:
use_legacy: false
footer:
last_edited_on:
use_legacy: false
edit_this_page:
use_legacy: false
We strongly recommend using the data files to manage your configuration if you’re setting more than one or two options. It’s much more maintainable in the long run. Each configuration section is easier to read.
Markup #
Alongside general components, Platen has updated older markup to use Shoelace components, making them more customizable.
Buttons #
The buttons markup used to display a normal link that Platen styled to look like a button. Now the markup renders Shoelace Buttons, which are much more configurable. To see the full list of new options, see the markup’s documentation.
A few highlights include being able to add icons to your buttons, change their shape and color, and indicate that the button downloads a file.
To enable the new buttons markup, set platen.markup.buttons.use_legacy
to false
in your site configuration or in
the _params/platen/markup.yaml
file in your site’s data folder.
Details #
The details markup used to display an HTML <details>
element that required classes to customize.
Now this markup renders Shoelace Details, which are more configurable.
With the new markup, you can configure the icons displayed on the details block to indicate that a reader can collapse or expand the block.
To enable the new details markup, set platen.markup.details.use_legacy
to false
in your site configuration or in
the _params/platen/markup.yaml
file in your site’s data folder.
Tabs #
The tabs markup used to display tabbed content in <div>
elements controlled by custom inputs and
required classes to customize. Now, this markup renders a Shoelace Tab Group instead. To see the full list
of new options, see the markup’s documentation.
A few highlights include customizing where tabs are placed relative to their content, defining closable tabs, and making tabs scrollable when they don’t fit on the page.
To enable the new tabs markup, set platen.markup.tabs.use_legacy
to false
in your site configuration or in the
_params/platen/markup.yaml
file in your site’s data folder.