Organize pages using IDs about just-the-docs HOT 1 OPEN

There are a few operations that are quite tedious and error prone:

Right.

Overall, the main issue I think is relying on Page Title for organizing content, while it could be much easier having a dedicated Page ID and linking pages by ID. That's also how most CMS work and it would bring some benefits:

Switching to use page IDs for linking pages also has some significant drawbacks:

1. Requiring the use of page IDs would probably break almost all existing sites that use the theme.
2. Migrating a large site to use manually-chosen page IDs would surely be extremely tedious.
3. Ensuring site-wide uniqueness of page IDs could be problematic.

This theme generally tries to minimise breaking changes, so that existing sites can easily be upgraded to new releases and take advantage of the new features. Switching to require page IDs for linking pages would be a major breaking change.

Moreover, the source files of many websites may be organised systematically in much the same way as the navigation: the source files of pages with different parent pages are naturally stored in different directories. For such websites, the path to a source file is inherently a unique ID, and links between pages could be based directly on their paths – eliminating the need for parent, has_children, and grand_parent fields, as well as supporting unlimited navigation levels (see my comment in a discussion).

from just-the-docs.