How can I change the order of the articles in the navigation?

How can I change the order of the articles in the navigation?
Thanks for feedback.


I am not sure if ordering is supported natively in Stoplight but I am using a workaround which is to rename your articles like

Since the articles in the navigation bar are sorted alphabetically, you can add a numeric prefix to your file names so that they appear in the order you want them to.

This is the workaround I already tried.
I just thought there is a “real” Stoplight method. But it definitely works. Thank you very much :slight_smile:

Cheers, Ngoc

Hey there, yeah we’ve been going MVP with the latest generation of tooling, creating what people ask for in the order of preference. Ordering is on the roadmap, it’s something I want too, but we’re just using file name ordering for now. :raised_hands:

It appears that tags on paths and models also generate navigation elements but again there needs to be some way to order these. For example our paths are tagged based on object type, but then all of our models we tag with “model” and want them to appear at the very bottom of the list.

Just dropping the note here that whatever solution is implemented to order MD files there should be similar consideration given to the order of Paths and Resources

+1 for @greg suggestion to order the API reference, I too have tagged my paths and models so they fall into the same category.

I would like to place all my models at the top followed by the paths in an order of my choosing, rather than alphebetaically. That way I could organise by CRUD; create an item, retrieve an item, update an item, delete an item, just like Stripe for example

Are there any timelines on when this could be implemented? I can see the docs ordering is in the short term on your roadmap (, does this include ordering the reference too?

Hey there! Custom ordering for the docs sidebar has progress to In Progress, so please subscribe to the roadmap card to get an update when it’s available.

1 Like

Awesome, thanks for the update @philsturgeon, but does this also include ordering the API reference too or just the docs?


We consider the Docs “Table of Contents” to be articles, operations, and models, so not just articles.

Exciting stuff, thanks for clearing that up Phil.