ZAP 005 - Navigation authoring experience¶

8-10 min read · 2,146 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 a scenario that shows a project making use of the additional degrees of freedom that our design provides.

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

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

# docs/reference/nav.toml
[sidebar]
items = [  
  { label = "Reference", 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.

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 existing partials. 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. Such a re-design will only be done once we move to a component system to replace the Jinja templates.