3.1 – rootPath und scope

Zwei Optionen, zwei Fragen:

• rootPath — ab welchem Ordner zählt die Navigation überhaupt? Vorgabe ist die Wurzel der Site.
• scope — welcher Ordner darunter wird gezeigt, abhängig von der Seite, auf der man steht?

Gezeigt werden immer die Kinder des gewählten Ordners, nicht der Ordner selbst. Wer ihn als Kopfzeile darüber haben will, nimmt showScopeRoot (3.2).

rootPath

options:
  rootPath: docs

Die Navigation beginnt bei docs: Ihre oberste Ebene sind anleitungen, Einstieg und Setup. docs, docs/, /docs/index und docs.md meinen dasselbe. Gibt es den Ordner nicht — oder ist alles darin ausgeblendet —, bleibt die Navigation leer, und der Bau meldet es einmal.

Auf Seiten außerhalb von rootPath, hier blog/erster-beitrag, erscheint die Navigation gar nicht. Das regelt hideOutsideRoot (3.2).

scope

scope	Gezeigt werden die Kinder von …
root (Vorgabe)	rootPath — auf jeder Seite dasselbe
section	dem Ordner der ersten Ebene unter rootPath, in dem die Seite liegt
parent	dem Ordner, in dem die Seite liegt
current	dem Ordner, der die Seite ist — oder, bei einer gewöhnlichen Seite, ihrem Ordner

Der Unterschied zwischen parent und current zeigt sich nur auf Ordnerseiten. Im direkten Vergleich, ohne rootPath:

Aktuelle Seite	root	section	parent	current
index (Startseite)	Wurzel	nichts	Wurzel	Wurzel
docs/index	Wurzel	docs	Wurzel	docs
docs/02-setup	Wurzel	docs	docs	docs
docs/anleitungen/index	Wurzel	docs	docs	docs/anleitungen
docs/anleitungen/alpha	Wurzel	docs	docs/anleitungen	docs/anleitungen

Die Tabelle ist gegen die Funktionen des Plugins geprüft, nicht aus der Beschreibung abgeleitet.

Wann welcher

• root für alles, was auf jeder Seite gleich aussieht: Menüleiste, Sitemap, Explorer-Ersatz.
• section für eine Seitenspalte, die nur den aktuellen Bereich zeigt. Auf der Startseite gibt es keinen Bereich, dort bleibt sie leer — die rechte Spalte dieser Website zeigt genau das.
• parent für „die Nachbarn dieser Seite“. Auf einer Ordnerseite sind das die Nachbarordner.
• current für „was liegt hier drin“. Auf einer Ordnerseite sind das ihre Kinder.

Mit rootPath zusammen

section zählt die erste Ebene unter rootPath. Mit rootPath: docs ist der Bereich von docs/anleitungen/alpha also docs/anleitungen.

parent auf der Ordnerseite von rootPath selbst zeigt deren Kinder: Der Ordner darüber läge außerhalb, also nimmt die Navigation rootPath.

Seiten, die nicht im Baum stehen

Ist die aktuelle Seite ausgeblendet — Tag-Seite, navHide, ein exclude-Muster — oder in einer anderen Sprache geschrieben als der Baum, kennt der Baum sie nicht. Dann gilt:

scope	Ergebnis
root	Die Navigation erscheint, nur ohne markierten Eintrag.
section, parent, current	Die Navigation erscheint nicht — ohne Seite kein Bezugsordner.

Das ist kein Fehler, sondern ein Werkzeug: Eine deutsche Kapitelnavigation mit language: de enthält die englischen Seiten nicht, und so erscheint auf englischen Seiten keine deutsche Navigation (8.3).