Skip to content


Programmatically generating the navigation#

Reference: mkdocs_gen_files.Nav#

An object representing MkDocs navigation, consisting of files under nested sequences of titles, which are treated like paths.

__setitem__(keys: str | tuple[str, ...], value: str) #

Add a link to a file (value) into the nav, under the sequence of titles (keys).

For example, writing nav["Foo", "Bar"] = "foo/" would mean creating a nav: {"Foo": {"Bar": "foo/"}}.

Then, writing nav["Foo", "Another"] = "" would merge with the existing sections where possible: {"Foo": {"Bar": "foo/", "Another": ""}}.

keys here can be any non-empty sequence of strings, it's just that Python implicitly creates a tuple from the comma-separated items in those square brackets.

items() -> Iterable[Item] #

Allows viewing the nav as a flattened sequence.

build_literate_nav(indentation: int | str = '') -> Iterable[str] #

Builds a file suitable for, as a sequence of lines to be written into a file.

For an example, see

Item dataclass #

An item in the navigation.

level: int instance-attribute #

The nestedness level of the item. 0 is the topmost level.

title: str instance-attribute #

The title of the item.

filename: str | None instance-attribute #

The path the item links to (or it can be a section index without a link).