ZAP 004 - Modular navigation¶

16-20 min read · 4,067 words · View in Zensical Spark

This ZAP explores unmet needs for navigation structures beyond the single hierarchy that Zensical inherited from MkDocs. Our roadmap already outlines the need for a more modular navigation approach to significantly improve the degrees of freedom you have in designing information architectures and navigation structures that best suit your projects.

Problem statement¶

Zensical inherits the navigation logic from MkDocs, which arranges all pages into a single navigation hierarchy that can be defined explicitly or implicitly. The not_in_nav option in MkDocs provides a way to exclude pages from the sidebar navigation, but there is currently no way to define additional navigation elements that these pages could be part of, limiting the degrees of freedom available to authors.

A single navigation hierarchy can lead to poor UX on larger documentation sites. For example, the sheer number of options a user must choose from means they can lose the sense of place and feel lost. An approach that more accurately controls what is visible on the screen could help alleviate this problem, as could contextual and supplemental navigation elements that complement the main navigation.

In addition, the current approach leads to long build times and excessive page sizes as every page contains a link to every other page. These problems get exponentially worse as a documentation project grows. The idea behind the proposal to make the navigation in Zensical more modular is to address both the UX and the performance and page size problems that plague large projects. We seek to expand authors' options to design information architectures and navigation structures that suit their needs and the needs of their users.

Purpose¶

With this ZAP, we aim to identify use cases that illustrate clearly how modular navigation can help documentation teams achieve their aims. We seek to identify commonalities between them so we can produce design proposals that can reflect a large number of information architectures and that are desirable, viable, feasible, and usable.

We do not aim to change the fundamental design decision to render navigation as static content so that pages work without the use of JavaScript. The approach we take in Zensical is to work, as far as possible, with progressive enhancement, using JavaScript not for basic functionality but only to improve the user experience where possible.

This ZAP will have an impact on the authoring and user experience, as well as on the developer experience for writers of modules that rely on navigation data or manipulate it.