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

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 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.devlab.search]
index = "search_index.en.js"

If you use a different language or index filename, update extra.devlab.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.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.

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.

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