Customization

DataLeaf is designed to be customized without forking the theme.

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

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

Then configure:

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

Multiple files are supported and loaded in the order listed.

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.

All of it is defined by public --dl- tokens: typefaces and their roles, the type scale, line heights and tracking, paragraph rhythm, layout widths, the spacing scale, radius, and the light and dark palettes. The design tokens reference lists every token with its default, dark value, and role, and explains the font strategy.

Override tokens rather than component selectors. For example, to set reading text in the sans and widen the column:

:root {
  --dl-font-body: var(--dl-font-sans);
  --dl-reading: 45rem;
}

Set widths in rem rather than ch. A ch width follows whichever font is loaded, so it changes when the bundled fonts arrive and the page shifts.

The same token names are used by the light and dark schemes. The regression tests check that the default palette meets WCAG 2.2 AA contrast in both; check your own colors the same way.

Hugo gives project files precedence over theme files. To replace a theme template, copy the same path into your site and edit the local copy.

For example:

layouts/
└── single.html

overrides DataLeaf’s article template.

Use layouts/_partials/, layouts/_shortcodes/, and layouts/_markup/ for partials, shortcodes, and render hooks. These paths follow Hugo’s template system introduced in 0.146.

Do not edit the theme header to add links. Configure menus.main in your site instead.

The masthead shows the site title, then a bar with the main menu and the site tools: search, languages, and the theme selector. Main-menu links and tools wrap to remain visible on small screens; there is no collapsed menu. Nested entries remain visible below their parent with an indented rule. The header stays in document flow, including on desktop, so long or translated menus cannot cover heading destinations. Navigation requires no JavaScript. Style it through the .dataleaf-header, .dataleaf-nav, and .dataleaf-tools classes.

Set:

[params]
  themeToggle = false

to remove the manual selector while preserving system-aware dark mode. A choice stored while the selector was enabled is then ignored.

DataLeaf does not currently expose a global custom-JavaScript parameter. Prefer Hugo template overrides for scripts that need to run site-wide, keeping the default theme usable without JavaScript.

See Configuration for the full parameter reference.