Navigation Ordering

​

Overview

1. _meta.yaml files in directories - Explicit ordering
2. Front matter sidebarPosition - Per-file ordering
3. Default patterns - Common documentation conventions

​

Using _meta.yaml

​

Basic Usage

# packages/my-package/docs/_meta.yaml
order:
  - introduction
  - quickstart
  - setup
  - essentials      # directories listed by name
  - advanced
  - internals
  - upgrade
  - cli_tools
# @doctest id="140c"

​

Key Points

• List items without file extensions (use quickstart not quickstart.md)
• Directories are listed by name (same as files)
• Items not in the list appear after listed items, sorted by defaults
• The order key contains an array of item names

​

Example Structure

packages/instructor/docs/
├── _meta.yaml              # Controls root ordering
├── introduction.md
├── quickstart.md
├── setup.md
├── essentials/
│   ├── _meta.yaml          # Controls essentials/ ordering
│   ├── usage.md
│   ├── validation.md
│   └── modes.md
└── advanced/
    └── ...
// @doctest id="235c"

order:
  - introduction
  - quickstart
  - setup
  - essentials
  - advanced
# @doctest id="93fb"

order:
  - usage
  - validation
  - modes
# @doctest id="ee23"

​

Using Front Matter

---
title: 'My Page'
sidebarPosition: 5
---

# My Page Content
# @doctest id="4c6a"

​

Supported Keys

• sidebarPosition (Mintlify style)
• sidebar_position (Docusaurus style)

​

Default Ordering

​

Files (in order)

​

Directories (in order)

​

Consistency Across Formats

​

Best Practices

1. Use _meta.yaml for sections - When you have multiple files in a directory, create a _meta.yaml to ensure consistent ordering
2. Start with defaults - The default ordering handles common patterns well; only add _meta.yaml when you need specific ordering
3. List important items first - Put introductory content at the top of your order list
4. Group related content - Use directories to group related pages, then order directories logically
5. Keep unlisted items - You don’t need to list every file; unlisted items appear after listed ones

​

Troubleshooting

​

Order not applied

• Ensure _meta.yaml is in the correct directory (same level as the files it orders)
• Check YAML syntax is valid
• Verify item names match filenames exactly (without extension)

​

Mixed ordering

• Listed items appear first (in list order)
• Unlisted items appear after (sorted by defaults, then alphabetically)

​

Regenerate documentation

composer docs gen:mintlify
composer docs gen:mkdocs
# @doctest id="e696"