Add more stable mechanism for ordering files/folders

Problem

The current way of ordering files and folders is by prefixing numbers to it.

While this solution has the advantage of being very simple, it has some drawbacks (TLDR: high coupling between filenames, display names and ordering):

instability in the links if any re-ordering is required
- The urls relies on the file/dir names. This may break internal links and external references to the site.
directory display names
- Directories relies on the filename for the display name (which shows in the website). Currently, some pretty re-formating of underscore produce reasonable display names, but filenames should be as immutable as possible and decoupled form display names (as it is with files, which uses the h1 header of the file).

Alternatives

All of these solutions could be homegrown or plugin-based. It requires some research.

1) Use metadata-defined permalink

I'm not sure if it is possible, but if we can define the link using a "permalink" metadata field (for files and directories) we wouldn't have the unstable-link issue anymore and could continue ordering by rename.

This seems the simplest solution, as it won't require an implementation-level ordering mechanism (of parsing ordering metadata and sorting files)

2) Implicit metadata ordering

Use metadata to handle display names and ordering.

For files ordering: use an order field in the frontmatter, which will be used to sort the files.
For dirs ordering: use a custom meta.yml file with a similar order (for sorting the dir itself in its parent)
For dirs display name: use title (for the display name) in this same meta.yml file.

3) Explicit metadata ordering

An alternative for ordering is creating an explicit index in the meta.yml, listing the order of the filenames. This can be flexible so it doesn't mean to just include those, but to prioritize this ordering and then sort the rest lexigraphically.

$ ls
meta.yml
spam.md
eggs.md
foo.md
bar.md

$ cat meta.yml
title: Name of the dir
ordering:
- foo.md
- bar.md

Final ordering:

- foo.md
- bar.md
- eggs.md # not excluded because ommited from meta.yml
- spam.md # sorted lexicographically

pulp / pulp-docs