Upgrading

DataLeaf is still pre-1.0, so upgrades may include template or configuration changes.

Fetch the latest theme commit:

git submodule update --remote --merge themes/dataleaf

Then rebuild locally:

hugo --gc --minify

Commit the updated submodule reference only after the site builds successfully.

Update module dependencies:

hugo mod get -u gitlab.com/DiogoRibeiro7/dataleaf
hugo mod tidy

Then run:

hugo --gc --minify

Check:

1. the DataLeaf release notes;
2. the minimum Hugo version;
3. any configuration changes;
4. local template overrides;
5. local CSS that targets DataLeaf component classes.

Template overrides deserve particular attention because Hugo will continue using your local copy even if the upstream theme template changes.

The visual design moved from rounded cards to an editorial system. Sites with custom CSS should check:

• reading text is now set in Source Serif 4, and the interface in IBM Plex Sans; both are bundled, and --dl-font-serif, --dl-font-sans, and --dl-font-mono select other fonts;
• the palette changed to ink on paper, and the dark scheme is a separate palette rather than an inversion;
• --dl-radius is now 0; form controls use the new --dl-radius-control;
• --dl-shadow and --dl-secondary-soft were removed;
• --dl-reading is now 42rem and --dl-reading-narrow 37rem, so the layout no longer shifts when the fonts load; an override in ch still works but brings the shift back;
• tags, taxonomy terms, and adjacent-article links are plain text on rules instead of pills and cards;
• the stylesheet is split into assets/css/fonts.css, tokens.css, and main.css, bundled into one file; a site that overrides the theme’s main.css must also provide the other two or keep the theme’s copies;
• --dl-flow-space is now 1em, so paragraph spacing follows the text size; --dl-active-bg was removed;
• new tokens cover typeface roles, the spacing scale, line heights, tracking, layout widths, and the link, annotation, and mark colors; see Design tokens;
• params.fonts.bundled = false disables the bundled fonts.

The header became a publication masthead: the site title on its own line, then a bar with the main menu and the site tools. Check:

• the header links to the search page automatically when search is enabled, so remove any Search entry from menus.main; the site title links home, so a Home entry is optional;
• the language links and theme selector moved into .dataleaf-tools, and .dataleaf-header__actions was removed; the bar is .dataleaf-header__bar;
• main-menu links are plain text in the reading color, the tools smaller and muted; the theme selector is no longer a bordered button.

The home page hero was replaced by an editorial front page. Check:

• .dataleaf-hero, .dataleaf-hero__lede, and .dataleaf-section were removed; the front page uses .dataleaf-front with __intro, __latest, and __topics, plus .dataleaf-feature and .dataleaf-entry;
• the home page’s title is now its main heading, so give content/_index.md a title that states what the site is about;
• _partials/summary.html overrides still apply to front-page summaries;
• --dl-text-display is smaller, at most 3rem.

Articles became a manuscript layout. Check:

• the metadata and tags moved out of .dataleaf-article__header into .dataleaf-article__meta, which sits with the table of contents in .dataleaf-article__rail; the header now holds the section, title, and a .dataleaf-article__dek subtitle from the page description;
• from 72rem, .dataleaf-article is a grid with the rail (--dl-rail) beside the reading column, and the table of contents is sticky; it is no longer a box;
• tables, display equations, and code wider than --dl-reading may extend up to --dl-wide-content; figures do so when marked {.wide};
• --dl-text-3xl, the article title size, is smaller, at most 2.5rem;
• previous and next links form a ruled row instead of two blocks, and the article components use logical properties, so they mirror on right-to-left sites.

Technical content moved from component-library styling to scientific typesetting. Check:

• code blocks sit on a light tint of the page in light mode, no longer a dark panel; syntax colors are the new --dl-code-comment, --dl-code-keyword, --dl-code-string, --dl-code-function, and --dl-code-number tokens;
• statements have no tinted background: --dl-statement-bg, --dl-definition-bg, --dl-remark-bg, and --dl-example-bg were removed, and theorem bodies are italic;
• callouts lost their outer border: --dl-callout-border, --dl-tip-border, --dl-warning-border, and --dl-important-border were removed;
• tables use journal rules instead of cell borders and a tinted header; figures lost their frame, and captions sit below a hairline.

Lists, taxonomies, the archive, and search became one editorial index. Check:

• section and term lists, documentation contents, and search results use the front page’s entry row, .dataleaf-entry with __title, __summary, __aside, __date, __meta, and __terms, from the new _partials/entry.html; .dataleaf-entry__body, .dataleaf-post-list, .dataleaf-post-card, and .dataleaf-search-result__title were removed, and search results keep .dataleaf-search-result as a hook;
• discovery pages use .dataleaf-index with a shared _partials/index-header.html instead of .dataleaf-reading, which was removed; from 72rem they follow the article grid, with dates and metadata in the rail;
• taxonomy pages list terms alphabetically by title in .dataleaf-terms instead of by count in .dataleaf-term-list;
• archive years show their number of entries, and the search field is set on a rule with a text button rather than as a boxed control;
• entry and search dates use Hugo’s :date_medium format, also in the search index’s dateLabel;
• the new contents layout lists a section on one page; the example documentation uses it;
• two interface strings are new, contents and entry_count; add them to your own translation tables, or builds run with --panicOnWarning stop at the English-fallback warning.

The dark palette, browser interface color, and small-screen behavior were refined. Check:

• strong rules (tables, list openings, archive years, pagination, previous and next, and the search field) use the new --dl-rule token instead of --dl-text; it is ink in light mode and a softer grey in dark mode, so override it alongside --dl-text if you changed the text color;
• the page head has one theme-color per color scheme, matching --dl-bg, and the theme selector points the browser at the chosen scheme;
• previous and next articles sit side by side from 40rem instead of 48rem; the theme now uses four breakpoints, listed in the design tokens reference;
• pagination arrows are wrapped in .dataleaf-pagination__arrow and mirror on right-to-left pages;
• code blocks, inline code, and display mathematics are set left to right on right-to-left pages;
• in forced colors, highlighted code lines take the system highlight and unavailable pagination the system grey text.

The page no longer shifts while the bundled fonts load. Check:

• --dl-reading and --dl-reading-narrow are in rem; keep overrides in rem, because a ch width changes when the fonts arrive;
• --dl-font-serif and --dl-font-sans name "Source Serif 4 Fallback", "Source Serif 4 Times Fallback", and "IBM Plex Sans Fallback" after the bundled families. These metric-matched faces exist only with the bundled fonts; if you replace the bundled families with your own web fonts, drop them or define fallbacks that match your fonts.

For reproducible production sites, pin DataLeaf to a release tag rather than tracking the latest commit continuously.

Use Hugo 0.158.0 or later. Standard Hugo is sufficient. Move local overrides from layouts/_default/single.html to layouts/single.html, from layouts/_default/terms.html to layouts/taxonomy.html, and from layouts/partials/ to layouts/_partials/. Apply the same root-layout migration to baseof.html, list.html, search.html, and archives.html.

Copy the complete search output configuration from Configuration. TOML literal strings for math delimiters use one backslash, as shown in Installation. Site-wide images intended for a subpath deployment should omit the leading slash. The header now displays your site title.