DevLab

DevLab v0.9.0: layouts, collections and extension slots

2026-10-02T00:00:00+00:00

DevLab v0.9.0 lets a project combine a landing page, blog, several manuals and a book in one Zola site. Layouts are selected in content front matter, reading roots are registered in configuration, and template slots let a site replace individual parts of the interface.

Layouts follow content settings

The theme provides ordinary page and section layouts, dated articles, documentation, Reader, landing pages and downloads. Zola's template selects a layout. A section's page_template applies recursively to its descendants. A closer section or a page can override it.

A URL no longer implies a layout. A page under content/manual/ can use page.html without receiving a documentation shell. A post outside the blog directory can use blog-page.html and receive article metadata and a TOC. Custom layouts declare their context in the layout_context block.

Site architecture explains the content model, layout selection and ownership of site files.

Landing pages use ordered blocks

A landing page now reads an array of blocks. Authors choose their order and can repeat feature or content sections. The built-in types are hero, features, learn, workflow, cta and content.

For example, in content/product.md:

+++
title = "Acme"
description = "Tools for inspecting build logs."
template = "landing.html"

[extra.devlab.home]
blocks = [
  { type = "hero", actions = [{ label = "Read the manual", path = "/manual/" }] },
  { type = "features", title = "Tools", items = [{ title = "Log search", description = "Find failed jobs and related output." }] },
  { type = "content" },
]
+++

## Installation

Add the package and configure the log directory.

The hero uses the page title and description. The content block renders its Markdown body. A hero must come first and can appear only once. Duplicate block IDs and unknown block types stop the build. A site can add a block type through partials/landing-block.html.

See Landing blocks for fields and inheritance.

Manuals and books have named collections

A collection identifies a reading root by its content source. For a site with content/manual/_index.md and content/api/_index.md, configuration can contain:

[extra.devlab.collections.manual]
section = "manual/_index.md"

[extra.devlab.collections.api]
section = "api/_index.md"
show_toc = false

[extra.devlab.navigation]
links = [
  { name = "Home", path = "/" },
  { collection = "manual" },
  { collection = "api" },
]

The theme gets each root's URL and title from Zola. Sidebar, mobile tree, breadcrumbs and reading links use the active collection. Source ancestry keeps a page in that collection when the page sets a custom public path. The corresponding header link stays active and its sidebar branch stays open.

Reading options inherit from site defaults, then the collection, ancestor sections and current content. page_actions merges individual fields, so a local Copy link setting preserves the inherited Edit URL. Arrays replace the previous array.

Curated navigation selects distinct branches within the collection. Foreign, duplicate and overlapping entries fail the build. Catalog pages show one level of content in both automatic and curated modes: direct pages and links to child sections.

Navigation also accepts text dividers such as { label = "Applications" }. An optional translations map supplies labels for other languages. Dividers appear in the desktop sidebar and mobile Docs menu, without links, toggles or keyboard focus. They do not create pages or affect Previous/Next links. A group with no sections in the active language is omitted.

Collections and Docs navigation describe the configuration.

Active entries in the Docs sidebar and page TOC use text highlighting. Blog and author post lists use the same centered width as articles. Headings, descriptions and separators align within that width.

On the homepage, Blog and Downloads, the header separator appears after scrolling. Docs and Reader show it immediately. Without JavaScript, the separator remains visible on every page.

Reader keeps one chapter sequence

reader.html renders chapter pages and section introductions. One sequence controls the chapter list and Previous/Next links. By default, it contains the root introduction, direct pages in Zola order, then subsection introductions and descendants. Transparent sections contribute their content without adding an introduction of their own.

An explicit reading_order can place introductions and chapters in another order. Entries must be unique and belong to the book. Missing primary-language files fail the build. Untranslated entries are omitted from that language's sequence. Filenames containing _index are treated as ordinary chapter files unless the filename itself starts with _index..

Reader and Docs include a compact TOC on narrower screens. Edit links remain available below the content when the desktop panel is hidden. The print stylesheet removes navigation, announcements and controls, wraps code, and includes every tab panel with its label. Printing covers the current chapter. Whole-book PDF and EPUB export are outside this release.

See Reader for a root section, first chapter and explicit ordering example.

Small template changes use slots

Sites can replace header brand, navigation or tools separately. Shared page slots cover headings, extra heading content, metadata and actions. Sidebar, footer and icon slots cover the remaining common extension points.

A custom icon added through partials/icon.html works in content and footer links. A missing footer icon falls back to the link name. Linked cards use a heading link, allowing ordinary links in the Markdown body without nested anchors.

Base blocks also expose additions to the head, main landmark and body. layout_scripts belongs to a layout. extra_scripts adds site script tags after theme and layout tags. Use defer on dependent classic scripts. Theme templates keep ordinary inheritance paths, so site overrides continue to participate in Zola's lookup rules.

CSS tokens control colors, fonts and widths. Overrides loaded after the theme stylesheet apply in light, dark and system mode. Public slots and component arguments are listed in Extension API. partials/devlab/ and components/internal/ contain their implementation.

Community cards

devlab.people renders a grid of centered profiles with avatars or initials, names, optional nicknames and social links. Each profile can include a role, biography and a support action below the card body. Cards use authored records in the site's front matter or configuration and require no JavaScript.

Profile, social and support destinations use the shared route resolver, including the deployment prefix and active language for local links. A missing name or incomplete support action stops the build with an explanatory error.

The Community cards guide includes a complete page example. The People reference lists its fields.

Bundled SVG icons

Interface icons use Tabler Icons 3.48.0. Service logos use Simple Icons 16.34.0. The default header mark and favicon use a terminal symbol. SVG files are bundled with the theme and inherit the surrounding text color. Their licenses and source mappings are included in the repository.

The icon catalog shows every built-in icon. Sites can add their own icons through the existing partials/icon.html slot.

Translations use one interface catalog

English, German and Russian interface labels live in theme.toml. Sites can override individual keys or add another language. Controls and their accessible names use the same resolved catalog. Downloads use its nested downloads table, with optional overrides from the selected data file.

Content still needs its own translations. The switcher and hreflang metadata link to existing translated pages and sections. Missing translated collection roots remove that language's collection link. Zola language configuration also sets the translated site title, description, taxonomies and search index.

Search loads the active language's generated index on first interaction. German and Russian load the matching stemmer support and language modules before the index. Other indexed languages can supply ordered plugin paths. See Languages and Search configuration.

Single downloads lists one product and its files by release channel. Catalog lists several products with detail pages, search, support and vendor filters, sorting and result counts. Both layouts read an explicit TOML data file.

Product, channel and support IDs are validated during the build. A file becomes downloadable when its URL is present. Its maturity status does not enable the link. Preview and planned artifacts can therefore appear before files exist. Checksum and signature links are optional and require an enabled download. Each product can replace shared mirrors and override verification fields. Catalog counts include only enabled files, and download labels distinguish architecture and version. The theme does not query release APIs or invent verification files.

Single downloads, Catalog and the data reference cover the two layouts.

Setup starts with two site files

The installation guide links a local theme checkout or pins a published revision. Quick start then creates zola.toml and content/_index.md. Search, feeds and specialized layouts are added when the site needs them. Standalone starter projects are removed. Examples sit beside the settings or components they explain.

The supported API is documented directly. Retired configuration keys stop the build with an upgrade message. The v0.8 migration guide maps the old homepage and reading settings to blocks and collections. Parallel label tables and fixed homepage rendering are removed. Current configuration uses ordered landing blocks, named collections, explicit navigation destinations and the interface catalog.

A site build requires Zola 0.23.6 or newer. There is no frontend build step. Copy, tabs and diagrams load on pages that use them. Download layouts load their shared controls. Static navigation and content remain readable without JavaScript.

The publishing guide covers metadata, feeds, cache settings and host policies.

Publication and release checks

Blog lists and articles link to tag archives. Description text takes precedence in lists, with a plain-text summary fallback. Dated articles link to their adjacent posts. Author profiles require non-empty names and supply their display name and role to page metadata.

The Blog guide walks through the first post, authors, tags and feeds. Deployment covers uploading public/ and checking live routes. The release tag is published separately. Until it exists, the installation guide and Download page provide a repository checkout. The demo build enables versioned archive URLs only after verifying that the local and published tag point to the same commit and both archives are available.

DevLab Theme v0.8.0

2026-09-19T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.8.0 is about composition. Authors can build landing sections and plans from reusable Markdown blocks, readers get a table of contents on long posts, and code examples can name the file they belong to. The release also settles the theme's own layout so sites stop patching it in Sass.

This release raises the minimum Zola version to 0.23.6 and explicitly escapes plain-text component fields when invoked from Markdown. Review overrides that put HTML in titles, labels or profile text: those fields now display it literally. Markdown bodies remain supported. Blog tables of contents are enabled by default. The theme still builds with Zola alone.

Card grids

devlab.cards arranges devlab.card children in a responsive grid. A card can link somewhere, carry an icon and a status tag, and hold Markdown:

Install

Pin a release tag and enable the theme in zola.toml.

Content components

Recipes for card grids, timelines and overview icons.

External

Codeberg

Source code, issues and release tags.

A linked card adds a trailing arrow, an absolute HTTP(S) destination switches it to the external-link marker, and a static card omits the arrow entirely. Docs overview cards gained the same icon slot through an optional [extra] icon in section or page front matter, so a documentation landing page no longer needs hand-written markup.

Status timelines

devlab.timeline presents a plan as ordered stages. Each stage declares a status and can add a date and a custom label:

Done2026-08
Bring-up
UART, bootloader, kernel, Device Tree and internal storage.
In progress2026-09
Hardware validation
Network, USB, wireless, display, audio and sensors.
PlannedQ4 2026
Preview
Test image with known limitations and pinned component versions.
Release
Supported
Regression matrix on a release candidate before the stable release.

Supported statuses are done, active, planned and blocked. An unknown value falls back to planned. The state is carried by the badge text as well as the marker colour, so a plan still reads without colour.

Blog tables of contents

Long posts now render a table of contents. On wide screens the article stays centered and the scrollable table of contents sits at the viewport edge. Below that width it collapses into a disclosure above the body. Both versions highlight the current section as the reader scrolls.

The Blog also uses a wider canvas than before, which puts that space to work without stretching the reading measure. Set devlab.blog.show_toc = false to publish posts without a table of contents. Posts with fewer than two headings stay unchanged.

Code blocks that name their file

Zola already carries the name annotation of a fenced block into the rendered HTML. DevLab now shows it as the block title and demotes the language to a supporting chip:

1make -j"$(nproc)"

The toolbar reads the caption from Zola's data-name attribute and keeps it outside the copied source. The toolbar also prints readable language labels, which turns Zola's internal syntax names into Shell, Text and similar.

Syntax colors now follow the code block's own --color-pre-scheme token. A site can use dark code blocks on a light page without getting light-theme syntax colors on the dark background. Set this token alongside --color-pre-bg and --color-pre-fg in custom palettes.

Nested Docs navigation, breadcrumbs and previous/next links now preserve the current language. Blog author links use Zola's taxonomy URLs, including author names with spaces. Feed discovery follows feed_filenames, and author feed links use the first configured file with an accessible, configurable label.

Footer links used to collapse to an icon whenever one was configured. devlab.footer.show_link_names = true renders every link as its icon plus the visible name and shows the configured group label as a heading. The compact footer in the Docs sidebar and mobile panel follows the same setting, and icon-only links remain the default.

Content media and narrow tables

Content images had no theme rules at all: an oversized image could leave the column. Images are now constrained to the content width, figure images and captions are styled, and table cells tighten on narrow screens next to the existing horizontal scroll. The theme also ships a visually-hidden utility.

A quieter default

The release also removes rough edges that consumer sites were working around in their own Sass:

A callout keeps the author's title casing instead of capitalizing every word, and an unknown type falls back to info with a readable label.
Docs pages without headings no longer reserve an empty table of contents column.
Docs overview cards use the full content column instead of stopping at a fixed width, and step lists keep their spacing against the following block.
Blog article titles no longer break at a narrow character limit.

If your site patched any of these, the override can go.

Previously on the development branch

Three features that were available only on main now ship in a tagged release: the dismissible announcement banner, reusable community cards and Blog author profiles. Sites that waited for a tag can adopt them without tracking the development branch.

Upgrading from v0.7.0

Update the pinned theme tag to v0.8.0 using Install and update after the tag is published.
Upgrade Zola to 0.23.6 or newer. Review component overrides: titles, labels and profile text are plain text, while component bodies can still contain Markdown.
Posts with at least two headings now render a table of contents. Set devlab.blog.show_toc = false to opt out.
Review footer links. Icon-only links are unchanged. Enable show_link_names only when the labels should be visible.
Add name= to fenced blocks whose file or path matters at a glance. Existing blocks render as before.
Remove site-owned Sass that duplicates content images, figure captions, narrow tables, callout casing, the Docs table of contents or Blog title width.
Run zola check and zola build, then inspect the new components at a narrow viewport and with a keyboard.

The complete component contracts live in Tera components, the new recipes in Content components, and every setting in the configuration reference.

Compatibility

DevLab Theme v0.8.0 requires Zola 0.23.6 or newer. Theme consumers still build with Zola alone: Node.js and npm are not runtime or site-build requirements, and the bundled diagram renderer does not depend on a remote service.

DevLab Theme v0.7.0

2026-09-01T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.7.0 focuses on the daily work around technical content. Maintainers can connect a Docs page to its source, writers gain reusable structures for commands and architecture, and readers get clearer code examples without adding a frontend build step to the site.

The new features are additive. Existing v0.6.0 content continues to render, page provenance remains opt-in and pages that do not use diagrams do not download the diagram renderer.

Documentation connected to its source

Docs pages can now show an authored update date, copy their current URL and link directly to contribution or issue workflows:

[extra.devlab.docs.page_actions]
show_last_updated = true
show_copy_link = true
edit_url = "https://codeberg.org/acme/project/_edit/main/content/"
report_url = "https://codeberg.org/acme/project/issues/new"
date_format = "%Y-%m-%d"

The update date is rendered only when a page defines Zola's native updated field. DevLab does not substitute a build timestamp or publication date. The edit link appends the real source-relative path, while the icon-only Copy link control preserves an active heading fragment when the Clipboard API is available. Editing lives beside the table of contents on wide screens, and the feedback destination closes the article as a dedicated discussion card.

Every action can be enabled independently. Omitting the complete table keeps the previous page footer unchanged.

Commands that keep their context

Tabs now support an optional synchronization key. Groups sharing the key remember the selected value and update together, which is useful when one guide repeats operating-system, package-manager or deployment choices.

Unix

zola serve

Windows

zola.exe serve

Without JavaScript, every panel remains readable. With enhancement enabled, the control follows the horizontal tabs keyboard pattern, mirrors arrow behavior in RTL layouts and stores only the selected value.

Project structure without hand-drawn connectors

The new file-tree components replace fragile ASCII layouts with semantic folders and files. Folders use the browser's native disclosure control and remain collapsible without JavaScript.

Release workspace

devlab-theme
- theme.tomlRelease metadata
- content
  - docsProduct documentation
  - blogRelease notes
- THIRD_PARTY_NOTICES.mdVendored dependency notices

Compact badges complement the tree when a status belongs inside a sentence: Release Stable API Beta Migration Not required.

Badge text carries the meaning independently of color, and folder or file names use automatic text direction for mixed-language documentation.

Architecture as authored content

devlab.diagram turns a compact Mermaid-compatible source into a responsive SVG that follows the active DevLab palette:

Release authoring flowSource content becomes checked documentation and then a tagged release.

The self-contained renderer is bundled with the theme and makes no font or CDN request. Its cost is isolated to pages that contain a diagram: approximately 1.6 MB minified or 495 KB gzip. The component provides a visible caption, an accessible description and a source fallback when rendering is unavailable.

Flowcharts, state, sequence, class, ER and XY diagrams are supported. Diagram input should remain trusted, repository-authored content rather than visitor input.

Code blocks with a deliberate hierarchy

Fenced code now renders as a composed panel with a language toolbar, an icon-only Copy control, clearer line numbers and a visible highlighted-line treatment. Copy feedback changes the icon while retaining localized accessible labels and a polite live announcement.

1fn release(version: &str) {
2    check_site();
3    publish_tag(version);
4}

Long lines scroll inside the panel instead of widening the page. Only blocks that actually overflow enter the keyboard tab order, and copied text continues to exclude visual line numbers.

Upgrading from v0.6.0

Update the pinned theme tag to v0.7.0 using Install and update after the tag is published.
Keep Zola 0.23.4. This release does not change the current Zola target.
Add devlab.docs.page_actions only when the site has real source and feedback destinations.
Replace hand-written command switches, file trees or architecture drawings gradually. Existing Markdown does not require conversion.
Review site-owned Sass overrides that target code blocks, Docs page footers or component internals.
Account for the diagram payload before adding diagrams to frequently visited pages.
Run zola check and zola build, then inspect interactive components with a keyboard and at a narrow viewport.

The complete syntax and parameter contracts live in Tera components, while page actions are documented in the configuration reference.

Compatibility

DevLab Theme v0.7.0 targets Zola 0.23.4. Theme consumers still build with Zola alone: Node.js and npm are not runtime or site-build requirements, and the checked-in diagram renderer does not depend on a remote service.

DevLab Theme v0.6.0

2026-08-31T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.6.0 gives the homepage, Docs, Blog and Downloads shared CSS tokens for typography, spacing and colors. It adds an optional homepage image and revises the layouts at desktop and mobile widths.

The release keeps DevLab Zola-native and dependency-free. It does not change the devlab.* content component syntax or require a content migration from v0.5.0.

One visual foundation

Typography, spacing, radii, shadows, motion and surface roles now share a compact set of CSS custom properties. Components use the same scale for hierarchy, focus states and interaction feedback in light and dark modes.

Borders and shadows distinguish raised surfaces. Accent colors identify actions, current navigation and status.

For update-safe customization, continue to use the public CSS tokens documented in Brand and colors before overriding individual component selectors.

Optional homepage image

The wide homepage now has a composed hero, stronger responsive spacing and an optional product preview. Configure the preview in homepage front matter:

[extra]
home_layout = "wide"
home_hero_image = "/images/project-docs-preview.png"
home_hero_image_alt = "Project documentation with sidebar navigation and an on-page table of contents."

When the image is omitted, the hero returns to a centered text composition. Feature summaries, the learn-more section, workflow and final call to action use the same layout rhythm while remaining independently optional.

Homepage configuration still works globally or in content/_index.md. Local values take priority, and an explicitly empty feature array can hide its corresponding card or point collection. See the homepage configuration reference for the complete inheritance rules.

Documentation built around reading

The Docs overview, sidebar, article hierarchy, table of contents and previous or next navigation now have clearer separation without turning every region into a card. Section identity stays visible, long-form content keeps a comfortable measure and navigation remains useful on smaller screens.

Breadcrumbs and adjacent-page links continue to follow the same language-aware documentation tree introduced in v0.5.0. This release changes their presentation, not their routing contract.

Blog layout and pagination

The Blog index places metadata in a separate column on larger screens. Titles, summaries, release badges and article headers use the shared spacing and type tokens.

The starter Blog configuration now displays five posts per page:

+++
title = "Blog"
sort_by = "date"
paginate_by = 5
template = "blog.html"
page_template = "blog-page.html"
+++

This is a documented default for new sites, not a forced theme setting. Existing sites keep their own paginate_by value, and omitting it still renders all posts on one page.

Downloads with a visible release path

The Downloads page separates its introduction, status, channels and verification guidance into successive sections. Each channel retains its own download action.

Status and verification blocks share the new surface and type scales, and the layout adapts from a broad release overview to a single-column mobile flow. The underlying Downloads configuration remains unchanged.

Upgrading from v0.5.0

Update the pinned theme tag to v0.6.0 using Install and update.
Keep Zola 0.23.4. This release does not change the current Zola target.
Optionally add home_hero_image and a meaningful home_hero_image_alt to a wide homepage.
Review site-owned Sass and template overrides, especially rules that target homepage, Docs, Blog or Downloads internals.
Choose the Blog page size explicitly if the new-site example of five posts does not fit the publication.
Run zola check and zola build, then inspect the four primary surfaces in light, dark and narrow layouts.

No authored component syntax migration is required.

Compatibility

DevLab Theme v0.6.0 targets Zola 0.23.4. It has no Node.js, npm or external frontend runtime dependency.

DevLab Theme v0.5.0

2026-08-21T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.5.0 brings the documentation interface onto one language-aware routing model and targets Zola 0.23.4. Docs navigation, local links, search and layout direction now follow explicit contracts instead of relying on assumptions that only hold for a single-language site.

This release does not provide a translation catalog for authored content or every theme-owned string. It supplies the routing, partial-translation and RTL foundations that a multilingual site needs while keeping interface labels configurable through the existing settings.

One language-aware route model

Local header, mobile-menu, homepage, CTA, footer, feed and Docs links now resolve for the active Zola language. External URLs, protocol-relative URLs, email and telephone links, fragments and query-only references remain unchanged.

Docs also handle partial translations deliberately. A missing translated Docs root hides that language's Docs destinations. When the translated root exists, untranslated curated sectors are skipped, and a Docs destination without any renderable navigation items stays a direct link instead of opening an empty mobile panel. The default-language configuration remains strict, so a missing configured Docs section still stops the build.

Content components cannot infer a page's language by themselves. Pass the active language when a card contains a local link that should follow translated routes:

{% <devlab.card title="Fast setup" href="@/docs/getting-started/_index.md" content_lang={lang}> %}
Open the translated guide.
{% </devlab.card> %}

Explicit right-to-left languages

Sites can list the active language codes that should render right-to-left:

[extra.devlab.i18n]
rtl_languages = ["ar", "he"]

DevLab sets the document direction from this list. The drawer, header, Docs sidebar, table of contents, overview cards, pagination and content components use logical layout properties and mirror their directional indicators in RTL. Inline and fenced code remain isolated as left-to-right content so technical punctuation keeps its intended order.

Unlisted languages continue to use ltr. Codes may name the default language as well as languages configured under Zola's [languages] table.

When extra.devlab.docs.navigation curates the top-level documentation sectors, previous and next links now use that same scope and order. Pages below omitted sectors remain published but no longer reappear through pagination.

Within each selected sector, navigation follows the content tree depth first: direct pages come before subsection pages. Duplicate page paths are removed in first-occurrence order, preventing repeated or overlapping manifest entries from creating pagination loops. Keep manifest entries unique and non-overlapping anyway, because the sidebar and root catalog render each configured top-level sector. Breadcrumbs continue to represent the real content hierarchy independently of the curated top level.

Translated Docs roots, nested sections, breadcrumbs, catalogs and pagination now resolve Zola's language-specific source paths without appending a language suffix twice.

An explicit search index contract

DevLab's bundled search adapter consumes Zola's JavaScript Elasticlunr index. New and upgraded sites should state that format explicitly:

build_search_index = true

[search]
index_format = "elasticlunr_javascript"
include_title = true
include_description = true
include_content = true

An explicitly configured incompatible format now hides the search control, omits its scripts and removes search-specific guidance from the 404 page. If the field is absent, search continues to work only while Zola's active default produces the supported format.

Current Zola target

DevLab v0.5.0 targets Zola 0.23.4. The CI build downloads the official GNU archive, verifies its SHA-256 checksum and checks the reported version before building the site. The theme follows the current Zola release rather than promising a compatibility range across older or newer versions.

No authored component syntax migration is required from v0.4.0, but the Zola update is required.

Upgrading from v0.4.0

Install Zola 0.23.4 and confirm it with zola --version.
Add search.index_format = "elasticlunr_javascript" when search is enabled.
List every active RTL language under extra.devlab.i18n.rtl_languages. Leave the array empty for an LTR-only site.
Pass content_lang={lang} to cards whose local links should follow translated content routes.
Review curated previous and next links, and keep Docs manifest entries unique and non-overlapping.
Review site-owned template and Sass overrides that assume physical left or right positioning.
Update the pinned theme tag to v0.5.0 using Install and update.
Run zola check and zola build, then inspect Docs navigation, search and local links in every configured language.

Sites that remain single-language and left-to-right need no new i18n configuration.

Compatibility

DevLab Theme v0.5.0 targets Zola 0.23.4. It has no Node.js, npm or external frontend runtime dependency.

DevLab Theme v0.4.0

2026-08-06T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.4.0 moves completely to Zola 0.23.1 and Tera 2. It deliberately drops compatibility with earlier Zola versions: the template engine was rewritten, macros disappeared, shortcodes were removed from Zola, and Markdown bodies are now Tera templates before they are rendered as Markdown.

This is a real breaking release rather than a compatibility shim. In return, the theme now has one component system for layouts and authored content, clearer build failures and less theme-specific syntax.

One global component API

All reusable content now lives in templates/components.html and uses a namespaced Tera 2 API:

devlab.card
devlab.callout
devlab.details
devlab.steps
devlab.icon

Components are registered globally and need no import. Block components accept Markdown bodies:

{% <devlab.callout type="tip" title="Tera 2"> %}
The component body supports **Markdown**.
{% </devlab.callout> %}

Inline components use a self-closing tag:

{{<devlab.icon name="github" label="GitHub" />}}

The complete API and live examples are in Tera components.

Required content migration

Old shortcode calls do not build on Zola 0.23. Replace them before upgrading:

Before	Now
`card(...)` / `end`	`devlab.card` block component
`callout(...)` / `end`	`devlab.callout` block component
`details(...)` / `end`	`devlab.details` block component
`steps()` / `end`	`devlab.steps` block component
`icon(...)`	self-closing `devlab.icon` component

Zola 0.23 also evaluates Tera inside fenced code blocks. Wrap literal template examples in matching Tera raw/endraw blocks. Files that must never execute Tera can instead be listed under skip_content_templating, but pages using DevLab components must remain templated.

Required template migration

Site-owned overrides must follow the Tera 2 migration rules:

replace macro declarations, template imports, and namespace::call() invocations with components.
pass named test arguments, such as value is starting_with(pat="/docs/").
replace recursive includes with recursive components.
use square brackets for array indexes.
review stricter undefined-value access and renamed or removed filters.

DevLab's own recursive Docs navigation, section catalogs, table of contents, pagination helpers, cards, links and icons are all Tera 2 components now. No compatibility macros remain in the theme.

Language-aware internals

Content lookups now pass the active lang to get_page and get_section, using the canonical content paths required by Zola 0.23. Search loads search_index.<lang>.js automatically unless extra.devlab.search.index explicitly overrides the filename.

The active Zola language also supplies the document's lang attribute. Interface strings remain configurable through the existing label fields. This release does not claim complete translation coverage.

Cleaner component assets

SVG fragments now live under templates/components/icons/, and every fragment is explicitly excluded from keyboard focus. The public icon component keeps decorative icons hidden from assistive technology and adds an accessible name only when label is present.

The CI build downloads the official Zola 0.23.1 musl archive and verifies its SHA-256 digest before extraction. Both the theme metadata and documentation now require 0.23.1.

Upgrading from v0.3.1

Install Zola 0.23.1.
Convert every DevLab shortcode call to the matching devlab.* component.
Protect literal Tera examples in Markdown with raw blocks.
Migrate any site-owned template overrides from macros and Tera 1 syntax.
Update the pinned theme tag to v0.4.0 using Install and update.
Run zola check and a production zola build with the site's real base URL.
Review Docs navigation, component output, search, feeds and custom overrides.

The upstream breaking changes are documented in the Zola 0.23 changelog and the Tera 2 migration guide.

Compatibility

DevLab Theme v0.4.0 requires Zola 0.23.1 or newer. It has no Node.js, npm or external frontend runtime dependency.

DevLab Theme v0.3.1

2026-07-23T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.3.1 is a focused follow-up to v0.3.0. Most of the work happened inside Docs: section landings are easier to scan, navigation controls have one clear purpose and a project can choose which documentation sectors belong in the primary interface.

The release also tightens the surrounding layout and makes the footer a real customization surface without changing the Zola-native build.

Documentation without synthetic waypoints

The global Docs link already opens the documentation landing page, and each section title already has an authored landing of its own. DevLab no longer inserts synthetic links named Overview between those destinations.

Section titles are now ordinary landing links. A separate chevron button expands or collapses descendants when they exist. The split keeps navigation concise and gives each control one job: the title navigates, while the chevron discloses.

Without JavaScript, every descendant remains visible and every landing remains reachable. After initialization, inactive branches collapse, saved open branches keep their state and the branch containing the current page opens so its active link stays in view.

Curate the sectors, derive the tree

extra.devlab.docs.navigation is a new optional manifest for selecting and ordering the top-level sectors shared by the desktop sidebar, mobile Docs panel and root catalog:

[extra.devlab.docs]
section = "docs/_index.md"
path = "/docs/"
navigation = [
  { section = "docs/getting-started/_index.md" },
  { section = "docs/guides/_index.md" },
  { section = "docs/reference/_index.md" },
]

The manifest names only the top level. Titles, descriptions, links, pages and child sections still come from Zola content, so authors do not maintain a second copy of the complete tree. Omitting the manifest or leaving it empty preserves automatic top-level discovery.

Landing pages now reveal the hierarchy one level at a time. The Docs root presents the selected sectors, while a sector presents its direct pages and direct child sections as compact cards. Deeper entries stay on their own parent landing instead of flooding every higher-level page. The root introduction remains before its catalog, and authored text after a card group now has enough space to read as a new block.

See Docs navigation for the complete content and configuration contract.

A stricter visual frame

The header, Docs sidebar and table of contents now use one quiet border color to define their areas consistently. The header separator is inset, so the line does not change sticky offsets or add a hidden pixel to the layout.

Overview entries use smaller responsive cards without decorative arrows. This keeps attention on titles and descriptions and brings dense section pages closer to the restrained visual language used by Hextra without copying its Hugo-specific structure.

The footer follows the same system. Its copyright stays geometrically centered, while an optional note and project links can occupy the side regions. Narrow screens and compact Docs contexts stack the same content into a centered column.

[extra.devlab.footer]
note = "Documentation for the Acme platform."
links = [
  { name = "Codeberg", path = "https://codeberg.org/acme/docs", icon = "codeberg" },
  { name = "Atom feed", path = "/atom.xml", icon = "rss" },
]

For markup beyond the structured fields, a site can replace only partials/footer-content.html. The theme keeps ownership of the separator, responsive layout and compact mode. The available fields and icon names are documented in Brand and colors.

Smaller reliability improvements

Search reports an unavailable state when its library or generated index cannot load, instead of leaving an unhandled failure.
Generic taxonomy list and term routes now use complete theme layouts.
Blog dates accept extra.devlab.blog.date_format, with the existing day-first display retained as the default.
Docs and navigation scripts load only when their rendered interfaces need them.

Upgrading from v0.3.0

Most sites can update without moving content or changing their existing extra.devlab.* configuration. The new Docs manifest, footer fields and Blog date format are opt-in.

One interface contract changed deliberately: docs_overview_label is no longer read because generated Overview links no longer exist. An older configuration can leave the field in place without breaking the build, but it has no effect. Create a real page or section titled Overview when that destination belongs in the information architecture.

Review site-owned CSS, copied templates or JavaScript that targets the previous Docs navigation or overview markup. A full partials/footer.html override still works and must continue to handle footer_compact. New customizations should prefer the smaller partials/footer-content.html boundary.

Before updating a pinned installation:

Read the changes above and review site-owned Docs or footer overrides.
Select v0.3.1 using Install and update.
Run zola check and zola build.
Check the Docs root, one section landing and one deep page at desktop and mobile widths.
Verify search, the mobile menu, the footer and both color modes.

Compatibility

DevLab Theme v0.3.1 requires Zola 0.22.1 or newer. It remains Zola-native and does not require Node.js, npm or an external frontend runtime.

DevLab Theme v0.3.0

2026-07-18T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.3.0 replaces the demo's flat documentation list with nested section navigation. It also adds regular page and section layouts, makes download cards reusable, and documents how site overrides survive theme updates.

Documentation that keeps its shape

The Demo documentation now uses the recursive Zola section tree already supported by DevLab instead of presenting its guides as one flat list. Nested groups start closed for a first-time visitor, remember the reader's choices locally and share that state between the desktop sidebar and mobile Docs panel. The current page keeps its active state without forcing a reader's closed group back open.

On this page follows the same idea. Third-level headings sit below their second-level parent, and scrolling opens the branch that contains the active heading without turning the parent into a non-clickable control.

The compact footer now belongs at the bottom of Docs navigation, where it remains available without interrupting the article. Breadcrumbs and previous/next links are still rendered by Zola, so essential reading paths do not depend on JavaScript. The complete behavior is described in Docs navigation.

Room for the rest of the project

Not every page is documentation or a release post. DevLab now includes regular page.html and section.html layouts for project pages, directories and small collections. Generic sections can show their Markdown introduction, child sections, direct pages and pagination without borrowing a Docs or Blog template. See Content layouts for the content model.

Downloads has also grown from a Demo-specific page into a reusable distribution layout. A project can publish any number of release channels, leave planned artifacts unavailable, add a release summary and link existing checksums or signatures. The front matter contract remains documented in Download cards.

The header mark is now owned by the site. A new installation starts with a text-only brand, while projects that want a mark can use the built-in triangle or provide their own image.

Fewer hidden rules

The documentation is now grouped into Getting started, Guides, Customization and Reference. It explains pinned installation and updates, every supported configuration field, CSS tokens, template extension hooks and the maintenance cost of replacing a partial. The goal is to keep project-owned files outside themes/devlab-theme/, where an update cannot silently overwrite them. Start with the Customization overview.

README and the project screenshot now show the same interface that the documentation describes, rather than an earlier flat-navigation Demo.

Upgrading from v0.2.1

The structured global configuration under extra.devlab.* remains valid. Most sites can keep their navigation, Docs, Blog, search, appearance, SEO and homepage settings unchanged.

There are three deliberate changes worth checking before switching the pinned tag.

Move Downloads front matter

The earlier flat Downloads fields are no longer read. Release data now belongs to the section-scoped extra.downloads tables:

`v0.2.1` section field	`v0.3.0` section field
`extra.status_label`	`extra.downloads.eyebrow` and `extra.downloads.status.label`
`extra.channels_label`	`extra.downloads.channels_label`
`extra.download_unavailable_label`	`extra.downloads.unavailable_label`
`extra.iso_channels`	`extra.downloads.channels`
`extra.status_title`, `extra.status_description`, `extra.status_items`	`extra.downloads.status.title`, `extra.downloads.status.description`, `extra.downloads.status.items`
`extra.checksum_label`, `extra.checksum_title`, `extra.checksum_description`	`extra.downloads.verification.label`, `extra.downloads.verification.title`, `extra.downloads.verification.description`

Channel fields such as name, status, description, url and button_label keep their meaning. Verification links are new in v0.3.0. Status and verification blocks render only when they have a non-empty title, so incomplete data no longer leaves an empty placeholder.

No compatibility aliases are retained for the old Downloads fields. Move the values before updating the theme.

Choose the header mark explicitly

The built-in triangle is no longer shown by default. Add this if the site should keep the previous DevLab mark:

[extra.devlab.brand]
show_logo_mark = true
logo_mark_path = ""

Set logo_mark_path to a site-owned image for a custom mark, or leave show_logo_mark = false for the new text-only default.

Review site-owned overrides

On Docs routes, partials/footer.html is now rendered inside the desktop sidebar and mobile Docs panel with footer_compact = true, rather than below the article. A site-level footer replacement should support that compact context.

Also review copied layouts, partials, CSS or JavaScript that depend on the previous Downloads markup, Blog pagination classes, Docs navigation or TOC structure. These implementation details changed even though their public behavior remains familiar.

The Demo documentation itself moved from a flat list into nested sections without redirects. Saved links to Quick start, Guides or Reference pages may need updating. Consumer sites keep their own content routes and are not required to copy the Demo hierarchy.

Before publishing the update

Read the changes above and keep project customizations outside the theme directory.
Update the pinned theme tag using Install and update.
Run zola check and zola build.
Check the routes the site actually enables: Home, Docs, Blog and Downloads.
On Docs, verify nested groups, remembered state, On this page, the mobile panel and the compact footer.
Check search, published and unavailable download actions, and both color modes.

Sites upgrading from a version older than v0.2.1 should first follow the structured configuration migration in the v0.2.1 release notes.

Compatibility

DevLab Theme v0.3.0 requires Zola 0.22.1 or newer. Building a site requires no Node.js pipeline or external content service.

DevLab Theme v0.2.1

2026-07-13T18:47:02+05:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.2.1 tightens the v0.2 foundation with more predictable optional features, safer links and fewer compatibility branches.

Breaking configuration change

DevLab Theme v0.2.1 removes the flat configuration aliases retained from 0.1.x. Sites already using extra.devlab.* require no changes. Sites still using flat fields under [extra] must update them before upgrading. Otherwise those values are ignored and the affected features use their defaults.

Previous field	Structured field
`logo_text`, `footer_text`	`devlab.brand.logo_text`, `devlab.brand.footer_text`
`nav_links`	`devlab.navigation.links`
`docs_section`, `docs_path`, `get_started_path`	`devlab.docs.section`, `devlab.docs.path`, `devlab.docs.get_started_path`
`blog_path`	`devlab.blog.path`
`theme_default`, `theme_toggle`	`devlab.appearance.default_mode`, `devlab.appearance.show_toggle`
`search_index`	`devlab.search.index`
`og_image`	`devlab.seo.og_image`

Existing home_* homepage fields, extra.labels and interface labels remain unchanged.

Highlights

Navigation can be empty or contain only the sections a site actually uses. Search and the color-mode toggle remain independent.
Docs navigation, overview trees and previous or next links now pass through transparent sections without exposing structural placeholders.
Mobile anchor targets stay visible below the sticky header, and drawer transitions no longer interfere with focus restoration.
Internal paths still respect Zola's base URL, while absolute, protocol-relative, fragment, query, email and telephone links keep their original form.
Code blocks preserve their layout without JavaScript, including long lines and copy-button spacing.
Page and section title overrides once again flow into the final document title without duplicating SEO logic.
Tagged installation examples are pinned to the release, and CI verifies that a release tag matches theme.toml.

Compatibility

DevLab Theme v0.2.1 requires Zola 0.22.1 or newer and remains fully Zola-native: no Node.js, npm or external frontend runtime is required.

DevLab Theme v0.2.0

2026-07-13T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.2.0 establishes the foundation for a maintainable Zola-native documentation theme without adding a frontend toolchain.

Highlights

A calm surface system replaces the experimental liquid-glass treatment.
The documentation workspace now uses a full-height sidebar, readable article column and compact table of contents.
Previous and next documentation links are rendered by Zola and work without JavaScript, including across nested sections.
Mobile navigation manages focus, keeps keyboard navigation inside the drawer and restores focus after closing.
Search exposes an accessible combobox and listbox contract with live result feedback.
Template extension hooks allow custom metadata, CSS, scripts and body integrations without copying base.html.
Structured extra.devlab settings become the primary configuration contract while 0.1.x flat fields remain supported.
Blog pagination, release badges and published or updated metadata turn Blog into a practical Updates channel.
Copy feedback is announced to assistive technology and interface transitions respect reduced-motion preferences.

Compatibility

Existing 0.1.x configuration continues to work. New sites should use the structured groups documented under extra.devlab.

The DevLab v0.2.0 templates can build with Zola 0.22.0 when a site uses config.toml or passes --config zola.toml explicitly. This repository and its documentation use zola.toml, whose automatic discovery starts with Zola 0.22.1. The supported native workflow is therefore Zola 0.22.1 or newer: zola check followed by zola build.

DevLab Theme v0.1.2

2026-07-04T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.1.2 is a small polish release for page navigation.

Before

Blog posts did not show where they belonged, while documentation pages already had breadcrumbs. On mobile, documentation previous/next links also took too much space and stacked into large blocks.

After

Breadcrumbs now use one shared template and work for both documentation pages and blog posts.

Documentation previous/next links are more compact on mobile. They stay readable, but no longer take over the bottom of the page.

Sites without a blog or without documentation still build normally.

DevLab Theme v0.1.1

2026-07-03T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.1.1 is a small hotfix for documentation navigation.

Before

Documentation groups had to be listed by hand in section frontmatter. Nested folders could exist in content/docs/, but the sidebar, breadcrumbs and previous/next links did not understand them as one navigation tree.

After

The docs navigation now follows the Zola section structure automatically.

Create a folder with _index.md, add pages inside it, and the theme will render it as an expandable group. Nested sections work the same way, and breadcrumbs plus previous/next links follow the same tree.

No manual page list is needed for regular documentation navigation.

DevLab Theme v0.1.0

2026-06-30T00:00:00+00:00

This article describes its original release. Configuration examples may use retired settings. For v0.9, follow the upgrade guide and the current reference.

DevLab Theme v0.1.0 is the first public preview release of a developer-focused Zola theme for documentation sites, technical blogs and project pages.

Highlights

Documentation layout with sidebar, table of contents, breadcrumbs and previous/next navigation
Blog layout
Client-side search
Light, dark and system color modes
SEO metadata
Atom feed autodiscovery
SVG favicon
Custom 404 page
Configurable homepage
Callout and card shortcodes
Code block headers with copy buttons
Mobile navigation
Optional docs and blog sections for clean external Zola sites

Requirements

Zola 0.22.0 or newer

Installation

Install the theme as a Git submodule:

git submodule add https://codeberg.org/RiPetitor/devlab-theme themes/devlab-theme
git submodule update --init --recursive

Enable it in your Zola config:

theme = "devlab-theme"

Notes

This is an early public release. The theme is suitable for testing, personal documentation sites and small technical projects.

Planned future work includes additional shortcodes, tags and taxonomies, Mermaid, KaTeX, multilingual support and CI checks.

DevLab Theme 0.0.1 release candidate

2026-06-06T00:00:00+00:00

DevLab Theme is a modern Zola theme for developers, documentation sites and technical blogs.

The 0.0.1 release candidate turns the project from a local demo into a small theme package that can be installed in a separate Zola site.

Release candidate

This version is ready for final validation. Before tagging v0.0.1, the theme should be checked in this repository and installed once in a clean external Zola site.

What is included

The release candidate focuses on the workflows a documentation theme needs on day one:

documentation layout with desktop sidebar and table of contents
single mobile menu with a documentation panel
grouped and collapsible docs navigation
docs breadcrumbs and previous/next links
client-side search
light and dark color modes
callout and card shortcodes
code block headers with language labels and copy buttons
theme metadata, MIT license and fallback [extra] defaults

Install preview

Install the theme under a Zola site's themes/ directory:

git clone https://codeberg.org/RiPetitor/devlab-theme themes/devlab-theme

Enable the theme and the optional search index:

theme = "devlab-theme"
compile_sass = true
build_search_index = true

The theme is designed to work without a frontend framework or build tool beyond Zola's built-in Sass and search index support.

Validation before tagging

The final 0.0.1 tag should be cut after these checks:

run zola check
run zola build
review light and dark modes
review desktop and mobile documentation navigation
review mobile menu open, close, backdrop click, Escape and link-click states
review search results and empty search state
review code block language labels and Copy button states
install the repository as themes/devlab-theme in a clean external Zola site

Next direction

After 0.0.1, the theme can move toward more polished documentation ergonomics: richer code block metadata, more content components, better search presentation and a small set of real-world example pages.

DevLab

DevLab v0.9.0: layouts, collections and extension slots

Layouts follow content settings

Landing pages use ordered blocks

Manuals and books have named collections

Reading navigation and page widths

Reader keeps one chapter sequence

Small template changes use slots

Community cards

Bundled SVG icons

Translations use one interface catalog

Downloads share a data format

Setup starts with two site files

Publication and release checks

DevLab Theme v0.8.0

Card grids

Install→

Content components→

Codeberg

Status timelines

Bring-up

Hardware validation

Preview

Supported

Blog tables of contents

Code blocks that name their file

Navigation and feed fixes

Footer links with names

Content media and narrow tables

A quieter default

Previously on the development branch

Upgrading from v0.7.0

Compatibility

DevLab Theme v0.7.0

Documentation connected to its source

Commands that keep their context

Project structure without hand-drawn connectors

Architecture as authored content

Code blocks with a deliberate hierarchy

Upgrading from v0.6.0

Compatibility

DevLab Theme v0.6.0

One visual foundation

Optional homepage image

Documentation built around reading

Blog layout and pagination

Downloads with a visible release path

Upgrading from v0.5.0

Compatibility

DevLab Theme v0.5.0

One language-aware route model

Explicit right-to-left languages

Docs navigation follows one scope

An explicit search index contract

Current Zola target

Upgrading from v0.4.0

Compatibility

DevLab Theme v0.4.0

One global component API

Required content migration

Required template migration

Language-aware internals

Cleaner component assets

Upgrading from v0.3.1

Compatibility

DevLab Theme v0.3.1

Documentation without synthetic waypoints

Curate the sectors, derive the tree

A stricter visual frame

Smaller reliability improvements

Upgrading from v0.3.0

Compatibility

DevLab Theme v0.3.0

Documentation that keeps its shape

Room for the rest of the project

Fewer hidden rules

Upgrading from v0.2.1

Move Downloads front matter

Choose the header mark explicitly

Review site-owned overrides

Install

Content components