ZAP 005 - Navigation authoring experience¶

19-24 min read · 4,931 words · View in Zensical Spark

This ZAP is a design spike to explore first ideas for the new navigation authoring experience in Zensical. It is part of our work on modular navigation and builds on the previous explorations of page title handling in ZAP 001, navigation as content in ZAP 003, and modular navigation in ZAP 004. The design covers functionality known from the popular awesome-nav and literate-nav plugins. We outline scenarios that show projects making use of the additional degrees of freedom that our design provides.

# docs/nav.toml
[nav.tabs]
items = [
  { icon = "lucide/house", path = "index.md" },
  { icon = "lucide/map", path = "setup" },
  { icon = "lucide/book", path = "reference" },
]

# docs/setup/nav.toml
[nav.sidebar]
label = "Setup"
items = [
  { path = "**/{nav.toml,*.md}" },
]

# docs/reference/nav.toml
[nav.sidebar]
label = "Reference"
items = [
  { path = "**/*.md" },
]

The example shows a project with navigation consisting of a tab bar and a sidebar. The tab bar is defined in the top-level nav.toml and each section has a definition of the sidebar content in its own nav.toml. The sidebar is populated with entries matched by glob expressions. In the case of Setup, this can be overwritten with further nav.toml files in the subsections that define a specific ordering of entries, for example.

Sidebar navigation pruning¶

For large documentation sites, the single navigation hierarchy that MkDocs uses causes problems with the user experience as the hierarchy becomes difficult to navigate. Also, the static rendering of the navigation in each HTML file means that page sizes and build times increase exponentially. We are, therefore, considering various ways of pruning the main navigation hierarchy and give authors control (via nav.toml files) over how much of the hierarchy gets rendered in the sidebar for each section:

Figure 1: Navigation sidebar pruning

Navigation elements¶

At the same time, we consider supporting a larger number of navigation elements covering both within-hierarchy and out-of-hierarchy navigation. There are new navigation elements like a “fat footer”, “quicklinks”, and “related links” that we will support. Once we implement the component system, it will be much easier to implement custom navigation component as well.

Figure 2: Navigation elements overview

Problem statement¶

The design aims to increase degrees of freedom for authors with use cases that challenge the current ways of defining the navigation structure we inherited from MkDocs. We are looking for an authoring experience that follows the “batteries included” philosophy of Zensical. This means that the functionality described must be part of the core of Zensical and must be usable with only configuration, no customization required.

At the same time, authors should be able to move with ease from a simple single-hierarchy navigation to more sophisticated navigation structures consisting of a range of navigation elements reflecting more complex information-seeking behaviors and information architectures.

To achieve this, we need to challenge the design decision in MkDocs that there is only a single navigation hierarchy. We also distinguish between global and local navigation elements. This can improve the authoring and user experience, but also reduce page sizes and build times for large sites.

Purpose¶

The main purpose of this ZAP is to sketch out the authoring experience for navigation in Zensical. Of course, an improved authoring experience will also have an impact on the user experience, as increased degrees of freedom will enable authors to make better choices in their designs of the navigation.

We focus on designs that can be implemented with the existing templating system and with modest changes to the underlying codebase. This will serve as a base implementation, and we will expand the capabilities once we move to the component system. We also provide a migration path for navigation definitions in the MkDocs format.

This ZAP focuses on how navigation is configured. Where necessary, we add simple wireframe prototypes to show what a configuration will result in. The purpose of this ZAP is not to outline a visual design for navigation in Zensical.