Since we wrote this extension to do the ordering, there's no reason we can't change it to read fromREADME.txt in each directory. We could have it look for something thatlooks like a comment to reST so it does nothing in the sphinx-gallery-processed reST without having to do anything extra.
Originally posted by@QuLogic in#24746 (comment)

I think it's a relatively good first issue following#25028 because each readme can be parsed into its respective gallery list. Steps involved are

1. figure out the reST comment notation that allows for easy specification of ordering + a consistent sentinel for placing unsorted files
2. write a parser that translates the set of comments into a list that preserves the order (including sentinel)
3. parse each file into its respective list in

   matplotlib/doc/sphinxext/gallery_order.py

   Line 48 inbe7ea76

   folder_lists= [examples_order,tutorials_order,plot_types_order]

4. add documentation on doing this ordering tohttps://github.com/matplotlib/matplotlib/blob/main/doc/devel/documenting_mpl.rst?plain=1#L933

Medium difficulty because some familiarity with sphinx would be helpful, but not strictly necessary. I think a medium to advanced version of this would be implementing a.. gallery-toccustom directive

And yes, down the line we should maybe spin a maintain docs page off from the writing docs page.

An alternative to using the readme is using a special purpose 'gallery_order' file#24746 (comment)