3.1 – rootPath and scope

Two options, two questions:

• rootPath — from which folder does the navigation count at all? The default is the site root.
• scope — which folder below it is shown, depending on the page you are on?

What is shown is always the children of the chosen folder, not the folder itself. To have it as a header above, use showScopeRoot (3.2).

rootPath

options:
  rootPath: docs

The navigation starts at docs: its top level is guides, Intro and Setup. docs, docs/, /docs/index and docs.md mean the same. If the folder does not exist — or everything in it is hidden — the navigation stays empty, and the build says so once.

On pages outside rootPath, here blog/first-post, the navigation does not appear at all. That is hideOutsideRoot (3.2).

scope

scope	Shown are the children of …
root (default)	rootPath — the same on every page
section	the first-level folder below rootPath that contains the page
parent	the folder that contains the page
current	the folder that is the page — or, for an ordinary page, its folder

The difference between parent and current only shows on folder pages. Side by side, without rootPath:

Current page	root	section	parent	current
index (start page)	root	nothing	root	root
docs/index	root	docs	root	docs
docs/02-setup	root	docs	docs	docs
docs/guides/index	root	docs	docs	docs/guides
docs/guides/alpha	root	docs	docs/guides	docs/guides

The table was checked against the plugin’s functions, not derived from the description.

When to use which

• root for everything that looks the same on every page: menu bar, sitemap, explorer replacement.
• section for a sidebar that shows only the current section. The start page has no section, so it stays empty there — the right column of this website shows exactly that.
• parent for “this page’s neighbours”. On a folder page those are the neighbouring folders.
• current for “what is in here”. On a folder page those are its children.

Together with rootPath

section counts the first level below rootPath. With rootPath: docs the section of docs/guides/alpha is therefore docs/guides.

parent on the folder page of rootPath itself shows its children: the folder above would lie outside, so the navigation takes rootPath.

Pages that are not in the tree

If the current page is hidden — tag page, navHide, an exclude pattern — or written in another language than the tree, the tree does not know it. Then:

scope	Result
root	The navigation appears, just without a marked entry.
section, parent, current	The navigation does not appear — without a page there is no reference folder.

That is not a bug but a tool: a German chapter navigation with language: de does not contain the English pages, and so no German navigation appears on English pages (8.3).