Troubleshooting

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

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

[extra]
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.

Entries in extra.nav_groups are page paths relative to content/:

[extra]
nav_groups = [
  { title = "Start", pages = ["docs/getting-started.md"] },
]

If a file is named content/docs/getting-started.md, the nav group entry should be docs/getting-started.md.

Search is rendered only when Zola search index generation is enabled:

build_search_index = true

[search]
include_title = true
include_description = true
include_content = true

The default generated index path is:

[extra]
search_index = "search_index.en.js"

If you use a different language or index filename, update extra.search_index.

Enable Zola's feed generator:

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

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

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

[extra]
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.

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 nav_links has kind = "docs":

[extra]
nav_links = [
  { name = "Docs", path = "/docs/", kind = "docs" },
]

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

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
+++