Add at property for positioning navigation items

[dan-lee]

Summary

• Add at property to navigation items for positioning into plugin-generated navigation
• Support label/index/negative index path targeting ("Users/0", "Users/-1", "Users/Get User")
• Position options: "before" or "after" target item

Example

{
  type: "doc",
  file: "api-users/overview",
  icon: "table-of-contents",
  at: { path: "Users/0", position: "before" }
}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
zudoku-cosmo-cargo	Ready	Preview	Jan 29, 2026 10:00am
zudoku-dev	Ready	Preview	Jan 29, 2026 10:00am

[github-actions]

Preview build of published Zudoku package for commit 8cd07fa.

See the deployment at: https://403510ff.cosmocargo-public-package.pages.dev

Note

This is a preview of the Cosmo Cargo example using the Zudoku package published to a local registry to ensure it'll be working when published to the public NPM registry.

Last updated: 2026-01-29T10:02:23.650Z

[Copilot]

Pull request overview

This PR adds an at property to navigation items for positioning custom items into plugin-generated navigation (like OpenAPI endpoints) at runtime. The implementation supports flexible path targeting using labels, positive/negative indices, or mixed paths, with "before" or "after" positioning options.

Changes:

• Adds at property with path-based targeting and position options to navigation schemas
• Implements path matching and item repositioning logic with comprehensive test coverage
• Integrates positioned items into the navigation context and filters them from display
• Updates pagination in OperationList to fall back to navigation-based prev/next links
• Minor styling adjustments to navigation items for improved visual consistency

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/zudoku/src/lib/navigation/positionItems.ts	Core positioning logic - extracts, removes, and reinserts items based on at property
packages/zudoku/src/lib/navigation/pathMatcher.ts	Path matching utility supporting label/index/negative index targeting
packages/zudoku/src/lib/navigation/positionItems.test.ts	Comprehensive test coverage for positioning scenarios
packages/zudoku/src/lib/navigation/pathMatcher.test.ts	Test coverage for path matching edge cases
packages/zudoku/src/config/validators/InputNavigationSchema.ts	Adds AtPosition schema for input validation
packages/zudoku/src/config/validators/NavigationSchema.ts	Adds at property to output types
packages/zudoku/src/lib/components/context/ZudokuContext.ts	Integrates positioned items into navigation context with memoization
packages/zudoku/src/lib/components/navigation/utils.ts	Updates shouldShowItem to filter positioned items; refactors to object parameter
packages/zudoku/src/lib/components/navigation/NavigationItem.tsx	Updates to use refactored shouldShowItem
packages/zudoku/src/lib/components/TopNavigation.tsx	Updates to use refactored shouldShowItem
packages/zudoku/src/lib/components/MobileTopNavigation.tsx	Updates to use refactored shouldShowItem
packages/zudoku/src/lib/components/navigation/NavigationWrapper.tsx	Removes gap-1 for more compact navigation
packages/zudoku/src/lib/plugins/openapi/OperationList.tsx	Adds fallback navigation using usePrevNext hook
examples/cosmo-cargo/zudoku.config.tsx	Example usage of at property
examples/cosmo-cargo/pages/api-shipments/getting-started.mdx	Example MDX file for positioned doc
docs/pages/docs/configuration/navigation.mdx	Comprehensive documentation with examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dan-lee]

Superseded by #1949