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 chapter navigation (the _nav.md convention, or folders.query.nav_file) and stack renders the sidebar and prev/next links; config.header_nav and config.bottom_nav control the header and footer. See the theme README for configuration details.
Convention: Directory Entry Pages and _nav.md
These rules work out of the box, with no special configuration:
Directory entry order: the theme template matching the requested URL ->
index.md->_index.md-> the first page of the sibling_nav. Entry fallback does not walk up to ancestor_navfiles. Theqs.nav_fileused for the sidebar and prev/next links can walk up ancestors. A_navfile itself is never rendered as page content. A directory default page is only recognized asindex.md/_index.md/slug: index(a same-namedfoo/foo.mdis no longer treated as the entry page).
| Scenario | Opening the directory URL (e.g. /docs/) | Sidebar / prev-next |
|---|---|---|
The theme has a matching template (e.g. paper's home / index.html) | The requested URL is handed to the theme template | A _nav can still be injected into the sidebar |
No matching template, but index.md / _index.md exists | That entry page is rendered (index.md wins over _index.md) | If the ancestor chain has a _nav.md (or nav_file is set explicitly), the engine injects it and the theme can display it |
No template, no entry page, and this directory has _nav.md plus chapters | The first chapter in that nav that resolves to page content in the site is rendered | Yes |
No template, no entry page, only an ancestor _nav (none in this directory) | No directory entry (it will not jump to the first chapter of the whole book) | An ancestor _nav is still injected when other pages are opened |
No template, no candidate content page, no usable sibling _nav | No directory entry | None |
Notes:
_nav.mddescribes structure only; it is never rendered as page content.- Entry vs. navigation: when a
_navserves as the directory entry, only sibling files count; an article in a subdirectory inheriting an ancestor_navonly affects the sidebar (written toqs.nav_file) and does not change what you see when you open that subdirectory's URL. - A directory entry tries to render the theme template first; it falls back to
index/ a sibling_navonly when the page does not exist (themes mid-upgrade can still be recognized by their missing-page message). A genuine template error fails outright instead of being masked by the entry fallback. - Navigation discovery (
qs): an explicitfolders.*.query.nav_filewins; otherwise_nav.mdis looked up up the ancestor chain starting from the current directory (keep one book at the root and chapters in subdirectories). - Only the conventional nav file name
_nav.mdis supported (SUMMARY.mdis not auto-detected). - Articles in subdirectories also inherit ancestor
_navfiles, which are written to the page'sqs.nav_filefor the theme to read (an existing explicit configuration is not overwritten).
Book TOC File
Place a _nav.md in the content directory (or the book root) and organize chapters with a list of internal links:
# 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.
Overriding in everkm.yaml (Optional)
Most sites only need a _nav.md at the book root. Write folders.query.nav_file when you want a custom path, or want to share one navigation file across directories:
folders:
"/docs/":
template: book.html
query:
nav_file: /docs/_nav.md
stack: true
query Field | Description |
|---|---|
nav_file | Optional. Path to the chapter TOC Markdown (absolute path within the site). Takes precedence over the _nav.md convention |
stack | Theme-specific: switches book layout (e.g., youlog's header + sidebar), see theme-youlog |
When no navigation source is found, 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="[[./_nav.md]]") | json_encode }}
{{ nav_path(from_file="[[./_nav.md]]") }}
{{ nav_indicator(from_file="[[./_nav.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.