Principle:Dagster io Dagster Documentation Site Navigation
| Knowledge Sources | |
|---|---|
| Domains | Documentation, Information_Architecture |
| Last Updated | 2026-02-10 12:30 GMT |
Overview
Design principle for organizing documentation into a hierarchical, browsable sidebar navigation that guides users through conceptually grouped content.
Description
Documentation Site Navigation is the practice of structuring a documentation site's content into a multi-level hierarchy of categories and pages, typically rendered as a collapsible sidebar. The goal is to enable users to discover relevant content through progressive disclosure: top-level categories represent broad domains (e.g., "Build", "Deploy", "Integrate"), while nested items refine the scope. This principle addresses the challenge of making large documentation sets (hundreds or thousands of pages) navigable without requiring users to rely solely on search.
Usage
Apply this principle when designing or restructuring the navigation of a documentation site with more than a handful of pages. It is especially relevant when the documentation covers multiple distinct domains (user guides, API reference, deployment, integrations) that serve different user personas (developers, operators, contributors).
Theoretical Basis
The core mechanism is hierarchical categorization with auto-discovery:
- Define top-level categories that represent user tasks or domains (Build, Automate, Deploy, etc.)
- Use directory-based auto-generation where possible so new pages are automatically included
- Provide explicit overrides for ordering, external links, and cross-cutting categories
- Support multiple independent sidebars for distinct content areas (guides vs. API vs. deployment)
Pseudo-code Logic:
# Abstract algorithm for sidebar resolution
sidebar = {}
for section in defined_sections:
items = []
for item in section.items:
if item.type == "autogenerated":
items += discover_pages(item.dirName)
elif item.type == "category":
items.append(resolve_category(item))
elif item.type == "link":
items.append(external_link(item.href))
sidebar[section.name] = items