Side Navigation

Configure the side navigation menu for your Mordoc documentation site using sidenav.yaml.

6 min read

The side navigation provides the primary navigation structure for your documentation site. Configure it using the config/sidenav.yaml file to create a hierarchical menu with parent pages and child pages.

Configuration File

The navigation is defined in config/sidenav.yaml:

Yaml

- label: Home
  path: /

- label: Getting Started
  path: /get-started
  children:
    - label: Installation
      path: /get-started/installation
    - label: First Steps
      path: /get-started/first-steps

Each navigation item requires a label:

Yaml

- label: Overview
  path: /overview

Properties

Property	Type	Required	Description
`label`	string	✓	Display text for the navigation item
`path`	string	Conditional	URL path to the page
`children`	array	✗	Nested child navigation items

Page with Content

A navigation item that links to a specific page:

Yaml

- label: FAQ
  path: /faq

This links to content/en/faq.md.

Parent with Content and Children

A parent page that has its own content AND child pages:

Yaml

- label: Guides
  path: /guides
  children:
    - label: Beginner Guide
      path: /guides/beginner
    - label: Advanced Guide
      path: /guides/advanced

File structure:

content/en/
├── guides.md          # Parent page content
└── guides/
    ├── beginner.md    # Child page
    └── advanced.md    # Child page

Parent as Label Only

A parent that groups child pages but has no content of its own:

Yaml

- label: Prerequisites
  children:
    - label: Install Node.js
      path: /prerequisites/nodejs
    - label: Install Git
      path: /prerequisites/git

Notice: No path property on the parent. It's just a section label.

File structure:

content/en/
└── prerequisites/
    ├── nodejs.md
    └── git.md

Yaml

- label: API Reference
  path: /api
  children:
    - label: Authentication
      path: /api/authentication
    - label: Users
      path: /api/users
    - label: Projects
      path: /api/projects

Mordoc supports deep nesting:

Yaml

- label: Documentation
  path: /documentation
  children:
    - label: Getting Started
      path: /documentation/getting-started
      children:
        - label: Installation
          path: /documentation/getting-started/installation
        - label: Configuration
          path: /documentation/getting-started/configuration
    - label: Advanced
      path: /documentation/advanced

While deep nesting is supported, avoid going more than 3 levels deep for better user experience.

Path Mapping

Paths in sidenav.yaml map to markdown files in your content directory:

Navigation Path	Content File
`/`	`content/en/index.md`
`/guides`	`content/en/guides.md`
`/guides/intro`	`content/en/guides/intro.md`
`/api/reference`	`content/en/api/reference.md`

Rules:

Paths start with /
No .md extension
Match the content directory structure
Use lowercase with hyphens

Complete Example

Yaml

# Homepage
- label: Home
  path: /

# Single page
- label: Overview
  path: /overview

# Parent with content + children
- label: Get Started
  path: /get-started
  children:
    - label: Creating Project
      path: /get-started/creating-project
    - label: Project Structure
      path: /get-started/project-structure

# Parent as label only
- label: Prerequisites
  children:
    - label: Code Editor
      path: /prerequisites/code-editor
    - label: Node.js
      path: /prerequisites/nodejs
    - label: Git
      path: /prerequisites/git

# Multiple sections with nesting
- label: Syntax & Components
  children:
    - label: Headings
      path: /syntax-components/headings
    - label: Links
      path: /syntax-components/links
    - label: Images
      path: /syntax-components/images
    - label: Lists
      path: /syntax-components/lists
    - label: Tables
      path: /syntax-components/tables
    - label: Code Blocks
      path: /syntax-components/code-blocks
    - label: Callouts
      path: /syntax-components/callouts
    - label: Cards
      path: /syntax-components/cards

# Another section
- label: Configuration
  children:
    - label: Side Navigation
      path: /configuration/sidenav
    - label: Table of Contents
      path: /configuration/toc
    - label: Search
      path: /configuration/search
    - label: Branding
      path: /configuration/branding

# Simple footer pages
- label: Changelog
  path: /changelog

Active States

The current page is automatically highlighted in the navigation:

Current page has active styling
Parent of current page is expanded
Breadcrumb trail shows hierarchy

Expandable Sections

Parent items with children can be expanded/collapsed:

Click parent label to expand/collapse
Click child link to navigate
Automatically expand when child is active

On mobile devices:

Navigation becomes a slide-out menu
Hamburger icon toggles visibility
Touch-friendly tap targets
Scrollable menu for long lists

Best Practices

Do:

Group related content under common parents
Use clear, descriptive labels
Keep hierarchy shallow (2-3 levels)
Order items logically (beginner → advanced)

Don't:

Create deeply nested structures (4+ levels)
Use overly long labels
Include too many top-level items
Mix different organizational patterns

Label Naming

Good labels:

"Getting Started"
"API Reference"
"Configuration"
"Deployment Guide"

Poor labels:

"Click Here for Info"
"Page 1"
"Section A: Getting Started with Configuration"

Organizing Content

Yaml

# ✓ Good: Clear organization
- label: Guides
  children:
    - label: Beginner Guide
      path: /guides/beginner
    - label: Intermediate Guide
      path: /guides/intermediate
    - label: Advanced Guide
      path: /guides/advanced

# ✗ Poor: No clear organization
- label: Guide1
  path: /guide1
- label: Advanced Stuff
  path: /guide-advanced
- label: Start Here
  path: /start

Customize navigation appearance through configuration.

Edit config/styles/main.json:

Json

{
  "sidenav": {
    "width": "280px",
    "backgroundColor": "#ffffff",
    "textColor": "#4b5563",
    "activeColor": "#3b82f6",
    "hoverBackground": "#f3f4f6",
    "fontSize": "0.875rem",
    "itemPadding": "0.5rem 1rem",
    "indent": "1rem"
  }
}

Available Style Properties

Property	Description	Default
`width`	Sidebar width	`280px`
`backgroundColor`	Background color	`#ffffff`
`textColor`	Text color	`#4b5563`
`activeColor`	Active item color	`#3b82f6`
`hoverBackground`	Hover background	`#f3f4f6`
`fontSize`	Text size	`0.875rem`
`itemPadding`	Item padding	`0.5rem 1rem`
`indent`	Nested item indent	`1rem`

Common Patterns

Documentation Structure

Yaml

- label: Home
  path: /

- label: Introduction
  path: /introduction

- label: Getting Started
  children:
    - label: Installation
      path: /getting-started/installation
    - label: Quick Start
      path: /getting-started/quick-start
    - label: Tutorial
      path: /getting-started/tutorial

- label: Core Concepts
  children:
    - label: Architecture
      path: /concepts/architecture
    - label: Data Flow
      path: /concepts/data-flow
    - label: Best Practices
      path: /concepts/best-practices

- label: API Reference
  path: /api

- label: FAQ
  path: /faq

API Documentation

Yaml

- label: Overview
  path: /

- label: Quick Start
  path: /quick-start

- label: Authentication
  path: /authentication

- label: Endpoints
  children:
    - label: Users
      path: /endpoints/users
    - label: Projects
      path: /endpoints/projects
    - label: Files
      path: /endpoints/files

- label: SDKs
  children:
    - label: JavaScript
      path: /sdks/javascript
    - label: Python
      path: /sdks/python
    - label: Ruby
      path: /sdks/ruby

- label: Rate Limits
  path: /rate-limits

- label: Changelog
  path: /changelog

Product Documentation

Yaml

- label: Welcome
  path: /

- label: Installation
  children:
    - label: Windows
      path: /installation/windows
    - label: macOS
      path: /installation/macos
    - label: Linux
      path: /installation/linux

- label: Features
  children:
    - label: Dashboard
      path: /features/dashboard
    - label: Projects
      path: /features/projects
    - label: Reports
      path: /features/reports

- label: Settings
  path: /settings

- label: Troubleshooting
  path: /troubleshooting

- label: Support
  path: /support

For multilingual sites, create separate sidenav files:

config/
├── sidenav.yaml       # Default/English
├── sidenav.es.yaml    # Spanish
└── sidenav.fr.yaml    # French

Configure in config/site.json:

Json

{
  "languages": {
    "en": "sidenav.yaml",
    "es": "sidenav.es.yaml",
    "fr": "sidenav.fr.yaml"
  }
}

Troubleshooting

Check sidenav.yaml includes the page path
Verify path matches file location exactly
Ensure YAML syntax is correct (proper indentation)
Rebuild site: npm run build

Clear browser cache
Restart development server
Check for YAML syntax errors in console
Verify file is saved

Children Not Nesting

Check indentation (use 2 spaces per level)
Verify children: has a colon
Ensure child items are properly indented
Don't mix tabs and spaces

Path Not Found

Verify corresponding markdown file exists
Check path spelling and case
Ensure path starts with /
Match content directory structure

YAML is whitespace-sensitive. Use consistent indentation (2 spaces recommended) and avoid tabs.

Next Steps

Table of Contents - Configure the page TOC
Search - Set up search functionality
Branding - Customize logo and favicon

Side Navigation

Side Navigation

Configuration File

Basic Navigation Item

Properties

Navigation Patterns

Page with Content

Parent with Content and Children

Parent as Label Only

Nested Navigation

Two-Level Navigation

Multi-Level Navigation

Path Mapping

Complete Example

Navigation Behavior

Active States

Expandable Sections

Mobile Navigation

Best Practices

Navigation Structure

Label Naming

Organizing Content

Styling Navigation

Available Style Properties

Common Patterns

Documentation Structure

API Documentation

Product Documentation

Multi-Language Navigation

Troubleshooting

Page Not in Navigation

Navigation Not Updating

Children Not Nesting

Path Not Found

Next Steps