Routing & Navigation
Learn how Metupy automatically maps Python files in your pages/ directory to URL routes and builds the sidebar navigation.
Directory-Driven Routing
Metupy scans the
pages/ directory recursively. Every Python file exporting a page instance is registered as a route automatically.1. File-to-Route Mapping
| File Path | Generated Route | Sidebar Placement |
|---|---|---|
pages/index.py | / | Root navigation link |
pages/getting_started.py | /getting_started | Root navigation link |
pages/guides/routing_pages.py | /guides/routing_pages | Under Guides group |
pages/reference/api_page.py | /reference/api_page | Under Reference group |
pages/docs/index.py | /docs | Under Docs group |
2. Creating a Page File
Every page script inside pages/ must instantiate a Page object and expose it as a variable named page:
pages/guides/routing_pages.py
from metupy.page import Page
from metupy.components_blueprint import Callout
# The title passed here sets the page_title used in browser tab and sidebar
page = Page(title="Custom Page Title")
page.title("Overview")
page.text("Content goes here...")
page += Callout(
title="Important",
message="The exported instance MUST be named <code>page</code> so engine.py can detect it during scan.",
type="warning"
)3. How Sidebar Grouping Works
Sidebar menus are generated automatically based on folder hierarchy without requiring manual navigation manifests:
- Root Pages: Files placed directly under
pages/(e.g.,pages/getting_started.py) render as standalone root navigation links. - Grouped Pages: Files placed inside subfolders (e.g.,
pages/guides/theming.py) are automatically grouped under a collapsible dropdown. - Automatic Title Formatting: Folder names with dashes or underscores are auto-formatted into titles (e.g.,
user_guidesbecomesUser Guides).
Index Route Trimming
If a file inside a subfolder is named
index.py (e.g., pages/installation/index.py), Metupy automatically trims /index to produce a clean route (/installation).