Documentation sites and book-style sites need chapter tables of contents and previous/next navigation. everkm-publish provides navigation Markdown parsing and built-in functions like nav_tree; sidebar trees, prev/next buttons, header/footer links, and other UI elements require theme support -- custom themes must call the navigation functions and implement the layout themselves.
Theme Support
The official theme-youlog serves as the reference implementation: template: book combined with folders.query.nav_file and stack renders chapter TOC and prev/next navigation; config.header_nav and config.bottom_nav control the header and footer. See the theme README for configuration details.
Book TOC File
Place a navigation Markdown file in the content directory, commonly named _nav.md or SUMMARY.md. Use lists with internal links to organize chapters:
# User Guide
* [[quick-start]]
* [[dir-config]]
* [[everkm-markdown]]
# Advanced
* [[custom-template]]
List items use Everkm internal links [[page-name]] or [[path/file]]. Rules at Links and Inner Links.
Binding in everkm.yaml
Use folders.query.nav_file to tell the theme which navigation file to read:
folders:
"/docs/":
template: book.html
query:
nav_file: /docs/_nav.md
stack: true
query Field | Description |
|---|---|
nav_file | Path to the chapter TOC Markdown (absolute path within the site, e.g., /docs/_nav.md) |
stack | Theme-specific: switches book layout (e.g., youlog's header + sidebar), see theme-youlog |
When nav_file is not configured or the file does not exist, themes typically do not display the tree navigation or prev/next buttons.
Navigation Functions in Templates
Theme templates (Tera) or JsRender can call built-in functions to parse the same navigation file:
{{ nav_tree(from_file="[[./SUMMARY.md]]") | json_encode }}
{{ nav_path(from_file="[[./SUMMARY.md]]") }}
{{ nav_indicator(from_file="[[./SUMMARY.md]]") }}
from_file supports the [[...]] internal link syntax, consistent with body internal link rules. See Links and Inner Links, Built-in Functions, Built-in Functions, Built-in Functions.
Breadcrumbs
Site-level breadcrumbs are configured in folders.breadcrumbs, independent of the navigation tree:
folders:
"/docs/":
breadcrumbs:
- title: "@i18n:nav.docs"
url: /docs/
Merge rules at Directory Configuration.
Header and Footer Links
Site header and footer navigation are controlled by config.header_nav, config.bottom_nav, etc., written under config in everkm.yaml, and require the theme to read and render them. See the theme-youlog for an example.