Troubleshooting

Fix common setup issues in a DevLab Theme site.

Use this page when the theme builds but a specific area is missing or empty.

Blog author credit is missing or plain

Authors come from the authors taxonomy. If a byline shows a plain key instead of a full profile, the key has no matching table in data/authors.toml — a typo such as authors = ["alxe"] degrades to a linked name instead of failing the build, so the site stays up but the credit is incomplete. Correct the post key or add the missing profile table.

When the post builds but no authors appear, confirm that the installed theme includes Blog author profiles; the feature is available since v0.8.0. Also check that authors is inside the post's [taxonomies] table (not [extra]) and is a non-empty array of strings, and that { name = "authors" } is registered in the site's taxonomies list. See Blog authors for the complete setup.

Announcement is missing or keeps returning

First confirm that the installed theme includes the announcement feature; it is available since v0.8.0. Then check show = true and a non-empty message in [extra.devlab.announcement].

If you already closed the notice, it stays hidden while its key matches the saved dismissal. Editing the text or toggling show does not reset that state. Preview with a temporary key, then restore the publication key before committing.

A missing close button means dismissible is false or key is empty. If closing works but the notice returns after navigation, check that the key remains the same and that the browser permits persistent storage. Closing requires JavaScript.

The announcement guide covers the complete configuration and publishing workflow.

Docs sidebar is empty

Check that the docs section exists at the path configured by extra.devlab.docs.section:

[extra.devlab.docs]
section = "docs/_index.md"

The file should exist as content/docs/_index.md.

Docs pages use the wrong layout

Set the docs section templates in content/docs/_index.md:

+++
template = "docs.html"
page_template = "doc-page.html"
+++

Without page_template = "doc-page.html", pages inside the docs section will not use the documentation layout.

A docs subsection is missing

Every docs directory that should appear as a navigation group needs an _index.md file:

content/docs/Linux/_index.md
content/docs/Linux/opensuse.md

Set the same docs templates on nested sections when they should render like docs pages:

+++
title = "Linux"
sort_by = "weight"
template = "docs.html"
page_template = "doc-page.html"
+++

If the subsection appears in the wrong place, check sort_by in the parent section and weight on pages or child sections.

Search does not appear

Search is rendered only when Zola search index generation is enabled with the JavaScript Elasticlunr format expected by DevLab:

build_search_index = true

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

An explicitly configured different search.index_format hides the search control and skips its scripts. Omitting the field remains compatible only while Zola's active default produces elasticlunr_javascript.

By default, DevLab loads search_index.<lang>.js for the active content language. Override it only when your generated filename is different:

[extra.devlab.search]
index = "custom-search-index.js"

Atom feed is missing

Enable Zola's feed generator:

generate_feeds = true
feed_filenames = ["atom.xml"]

Then run zola build and check that public/atom.xml exists.

Sharing image does not appear

og:image and twitter:image are rendered only when extra.devlab.seo.og_image is not empty:

[extra.devlab.seo]
og_image = "/images/social-preview.png"

Use an absolute URL or a path that exists in static/. Leave the value empty if you do not have a real preview image yet.

Code highlighting uses the wrong colors

Use the current Zola highlighting format:

[markdown]

[markdown.highlighting]
light_theme = "github-light"
dark_theme = "github-dark"

Older single-theme highlighting config will not match DevLab's light and dark modes as cleanly.

The mobile menu uses the docs navigation partial. Confirm that the docs link in extra.devlab.navigation.links has kind = "docs":

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

That marker tells the mobile menu which item should open the documentation panel.

Blog pages use the wrong layout

Set the blog section templates in content/blog/_index.md:

+++
template = "blog.html"
page_template = "blog-page.html"
+++

Blog posts should also include a date:

+++
title = "Hello DevLab"
date = 2026-06-01
+++