ZAP 003 - Navigation as content¶

14-19 min read · 2,938 words · View in Zensical Spark

Navigation can currently be defined either explicitly within the configuration or it can be derived from the folder structure and Markdown files (their content or metadata). In the MkDocs ecosystem, plugins like awesome-nav and literate-nav are popular. They allow the definition of navigation structure and titles to be separated from the project configuration, making it easier for authors to control the navigation and allowing teams to divide up the responsibility for overall configuration and for different parts of the navigation.

In this ZAP, we explore the opportunities, pain points and unmet needs that could be addressed by taking up the concept of "navigation as content" in Zensical, as outlined in our roadmap.

Problem statement¶

In (Material for) MkDocs, the navigation is either configured in the mkdocs.yml or derived from the content. When defining the navigation in the mkdocs.yml, it is mixed in with a slew of other configuration options. Some of these are technical in nature, such as references to Python functions for generating slugs or icons, markdown extensions and their various parameters, or feature toggles for the theme. This makes it somewhat daunting for non-technical people to modify the navigation definition.

Another issue is that as the site of a project grows, a single configuration file may become difficult to navigate. Because indentation is significant, mistakes can easily break the configuration.

In some organizations, the configuration and the top level navigation structure may be defined and controlled by one team, while content may be created by another. It would be desirable for organizations to be able to reflect their workflows and ownership of the different parts of a project in a separation of files if not repositories.

Finally, having navigation co-located with the content will make editing and version control easier and change logs more meaningful. Changes to the configuration file will mean that the overall configuration has changed as changes to the navigation reflecting changes in content or information architecture are separated out.

Purpose¶

The purpose of this ZAP is to understand the different use cases for "navigation as content". It is not intended to specify candidate solutions at this stage. We will develop those in separate ZAPs as we first wish to focus on the problem space before thinking about possible solution. This allows us to develop alternative proposals we can then weigh against each other before the move on to implementation.