Configuration recipes

Start from the working site in Quick start, then apply only the recipes that match your project. These examples favor a configuration you can understand six months later over a file containing every available option.

Turn on search

DevLab uses the index generated by Zola. Enable the compatible format and then enable the theme interface:

build_search_index = true

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

[extra.devlab.search]
enabled = true
index = ""

Restart zola serve after changing index settings. The empty index value selects search_index.<language>.js automatically.

Add Blog or Updates

First add Blog to the existing navigation array and configure its route:

[extra.devlab.navigation]
links = [
  { name = "Home", path = "/" },
  { name = "Docs", kind = "docs" },
  { name = "Updates", kind = "blog" },
]

[extra.devlab.blog]
path = "/blog/"
date_format = "%Y-%m-%d"

Create content/blog/_index.md:

+++
title = "Updates"
description = "Release notes and engineering articles."
sort_by = "date"
paginate_by = 5
template = "blog.html"
page_template = "blog-page.html"
+++

Then create a dated post such as content/blog/hello.md:

+++
title = "Hello from Acme"
description = "What we are building and why."
date = 2026-09-01
+++

This is the first project update.

The Blog link appears only when devlab.blog.path is non-empty. The route itself still comes from the content section.

When posts should credit recurring writers, define each profile once and reference it by key. Follow Blog authors after the basic section is working.

Announce a release

Once a post is published, point readers to it from a notice above the header:

[extra.devlab.announcement]
show = true
key = "acme-release-1.0"
message = "Acme 1.0 is available"
path = "/blog/acme-1-0/"
dismissible = true

Replace the destination with an existing post on your site. Closing is saved in the reader's browser when storage is available. Keep key stable for wording fixes and change it for a new announcement; set show = false to remove the banner for everyone.

This feature is available since v0.8.0. Follow Release announcements for the optional prefix, labels, link behavior and preview workflow.

Add Downloads

Downloads is a regular navigation destination, so add it to the complete navigation array:

[extra.devlab.navigation]
links = [
  { name = "Home", path = "/" },
  { name = "Docs", kind = "docs" },
  { name = "Updates", kind = "blog" },
  { name = "Downloads", path = "/downloads/" },
]

The release channels, status and verification links live in content/downloads/_index.md, not in the global configuration. Continue with the Downloads guide for the copy-ready front matter.

Simplify Docs navigation

The main Docs pieces can be controlled independently:

[extra.devlab.docs]
section = "docs/_index.md"
path = "/docs/"
get_started_path = "/docs/getting-started/"
show_breadcrumbs = true
show_toc = true
show_pagination = true

Change only the relevant boolean to false:

An Edit this page URL remains independent of heading navigation. On wide screens it still appears in the right-side action area when configured.

Change the project identity

Text, the optional mark and footer content belong to the site configuration:

[extra.devlab.brand]
logo_text = "Acme"
footer_text = "Acme Project"
show_logo_mark = true
logo_mark_path = "/images/acme-mark.svg"

[extra.devlab.footer]
show = true
note = "Built in the open by the Acme community."
links_label = "Project links"
links = [
  { name = "Source", path = "https://codeberg.org/acme/acme", icon = "codeberg" },
  { name = "Atom feed", path = "/atom.xml", icon = "rss" },
]

Leave logo_mark_path empty to use DevLab's built-in geometric mark. Set show_logo_mark = false for a text-only header.

Hide the footer or search interface

These switches remove the interface and its unnecessary enhancement code rather than hiding it with CSS:

[extra.devlab.footer]
show = false

[extra.devlab.search]
enabled = false

search.enabled = false does not prevent Zola from building an index for a different integration.

Check the result

After every recipe, run:

zola check
zola build

Then inspect only the routes affected by the change. If you need a setting that is not covered here, continue with the Configuration reference, where every supported field and default is listed.