Documentation on DataLeaf

Installation

Tue, 29 Sep 2026 00:00:00 +0000

DataLeaf requires Hugo 0.158.0 or later (standard or Extended edition) and Git. Hugo 0.158 introduced the language locale, label, and direction APIs used by the theme. No Sass pipeline or Extended-only functionality is required. Hugo Modules also requires Go 1.22 or later.

Check your Hugo installation:

bash

hugo version

Git submodule

From the root of an existing Hugo site:

Configuration

Tue, 29 Sep 2026 00:00:00 +0000

DataLeaf keeps configuration deliberately small. Unset optional parameters fall back to simple defaults.

Content sections

DataLeaf uses Hugo’s mainSections for the home page, archives, and adjacent-article navigation:

toml

mainSections = ["blog", "notes"]

This is a root configuration setting, not a theme parameter. If omitted, Hugo chooses the top-level section with the most pages. The example site explicitly selects posts; your site can use any section names. Home and taxonomy introductions come from their _index.md content. Empty collections remain usable, and undated pages omit date metadata in the interface.

Technical content

Tue, 29 Sep 2026 00:00:00 +0000

DataLeaf includes render hooks and shortcodes for technical and scientific writing.

Posts

Lists, term pages, documentation contents, and search results share one entry: the title, a plain-text summary, and beside them the date, reading time, and up to four tags. From 72rem the date and metadata sit in a rail beside the title, as on articles. To change the summary, override layouts/_partials/summary.html.

Metadata and social previews

Tue, 29 Sep 2026 00:00:00 +0000

DataLeaf emits canonical URLs, standard descriptions, Open Graph metadata, X/Twitter Card metadata, and JSON-LD structured data.

Description fallbacks

For pages, DataLeaf uses this order:

page front matter description;
the generated page summary;
site-level params.description.

For list and home pages, the site description is the normal fallback.

Example:

yaml

---
title: "Calibration under dataset shift"
description: "A practical note on probability calibration when deployment data drift."
---

Canonical URLs

Every rendered page receives:

Customization

Tue, 29 Sep 2026 00:00:00 +0000

DataLeaf is designed to be customized without forking the theme.

Add site-specific CSS

Create static/css/custom.css in your Hugo site:

css

:root {
 --dl-reading: 40rem;
 --dl-primary: #3730a3;
}

Then configure:

toml

[params]
 customCSS = ["css/custom.css"]

Multiple files are supported and loaded in the order listed.

Design system

DataLeaf is typography-led: reading text and titles are set in a serif, the interface and metadata in a sans, and structure comes from thin rules, alignment, and whitespace rather than cards, shadows, or rounded containers. Color is restrained: one accent for links and focus, a muted second color for annotations, and semantic tints for callouts.

Design tokens

Sat, 03 Oct 2026 00:00:00 +0000

DataLeaf’s visual language is defined by CSS custom properties in the theme’s assets/css/tokens.css. Components use only these tokens, so a site can adjust the design by overriding them in custom CSS without touching component selectors. The regression tests keep this page in sync with the stylesheet and check that the default colors meet WCAG 2.2 AA in both color schemes.

The design is editorial rather than app-like: reading text and titles are set in a serif, the interface and metadata in a sans, and structure comes from thin rules, alignment, and whitespace instead of cards and shadows. Color is restrained: one accent for links and focus, a muted second color for annotations, and semantic tints for callouts.

Upgrading

Tue, 29 Sep 2026 00:00:00 +0000

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

Git submodule

Fetch the latest theme commit:

bash

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

Then rebuild locally:

bash

hugo --gc --minify

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

Hugo module

Update module dependencies:

Releasing DataLeaf

Tue, 29 Sep 2026 00:00:00 +0000

DataLeaf uses a controlled GitLab CI job to create version tags and GitLab releases from reviewed main commits.

Prepare a release

Before publishing:

update CHANGELOG.md;
add or update RELEASE_NOTES_<version>.md;
verify the merge request pipeline;
merge the release preparation to main;
verify the main pipeline and GitLab Pages deployment.

Publish

Open Build > Pipelines > New pipeline in GitLab and select the main branch.

Internationalization

Wed, 30 Sep 2026 00:00:00 +0000

DataLeaf uses Hugo’s native i18n system for theme-owned interface strings.

Translation tables

The theme ships with:

text

i18n/
├── en.toml
└── pt-PT.toml

A site can override any key by providing its own files under i18n/, including region-specific files such as pt-PT.toml. The theme also mounts the Portuguese table as pt.toml, so bare pt works without duplicating the translation source or losing partial pt-PT overrides.

Quality checks

Wed, 30 Sep 2026 00:00:00 +0000

DataLeaf validates the generated production site and independent consuming sites.

Pipeline

The architecture fixtures exercise empty sites, inferred and explicit main sections, custom taxonomies and permalinks, nested menus, reordered and disabled outputs, missing optional parameters, language subdirectories and separate domains, regional translation overrides, included and global resources, and math rendered inside shortcodes. They validate generated HTML and links and retain an architecture.json report beside the build manifest.

Hugo Themes distribution

Wed, 30 Sep 2026 00:00:00 +0000

DataLeaf includes a distribution package for the official Hugo Themes directory.

What the directory reads

The Hugo Themes Site Builder imports each listed theme as a Hugo Module directly from its Git host. It then reads:

theme.toml, for the name, description, license, authors, demo link, and tags;
hugo.toml, which upstream requires to declare the supported Hugo versions in [module.hugoVersion] (the directory does not currently display them);
images/screenshot.png (at least 1500×1000) and images/tn.png (at least 900×600), both 3:2. JPEG files are also accepted.

The repository also needs an open-source license and an English README.md that uses absolute image URLs.