fix(content-docs): always sort autogenerated sidebar items by file/folder name by default

[Josh-Cena]

Motivation

Fix #6698

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

[netlify]

✔️ [V2]

🔨 Explore the source changes: e761d09

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/62205b5ec3934a0008a15563

😎 Browse the preview: https://deploy-preview-6700--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	50
🟢 Accessibility	100
🟢 Best practices	92
🟢 SEO	100
🟢 PWA	90

Lighthouse ran on https://deploy-preview-6700--docusaurus-2.netlify.app/

[github-actions]

Size Change: 0 B

Total Size: 789 kB

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	49.7 kB
website/build/assets/css/styles.********.css	105 kB
website/build/assets/js/main.********.js	597 kB
website/build/index.html	38.3 kB

_{compressed-size-action}

[Josh-Cena]

Okay, this is not easy to design... What should happen if some items have positions but others don't? Should we use file names, or customized labels if they exist? Should we be future-proof and take HTML items or link items into account?

[Josh-Cena]

This PR introduces slight behavior inconsistencies, but it's considered a bug fix and not a breaking change.

1. The doc items were previously sorted by IDs instead of file names, inconsistent with what the documentation promises. Since the vast majority did not configure a special ID for their doc, the two should be equivalent.
2. Before, the tests randomly resolved in a different order (I don't know if any other contributor had experienced the same), due to the async operations resolving in a different order. Now, everything is fully deterministic.

[slorber]

ok, that seems to work, comparing these 2 URLs I can see the change:

• https://deploy-preview-6700--docusaurus-2.netlify.app/tests/docs/category-links-generated-index-slug/
• https://docusaurus.io/tests/docs/category-links-generated-index-slug

Going to merge but 🤷‍♂️ I don't know if this is really useful. Why not sort by sidebar item label (if any) instead of source.

Also it's preferable to add a new test case instead of modifying test+snapshot+impl. It's complicated for me to review if everything changes at once, and hard to notice possible regressions

[Josh-Cena]

Also it's preferable to add a new test case instead of modifying test+snapshot+impl.

Existing test cases are actually bad, because they have colliding sidebar positions. I merely fixed them so that the snapshots stay the same. The only changed one was the undeterministic one

[Josh-Cena]

Why not sort by sidebar item label (if any) instead of source.

If we are starting from scratch I'd agree with that, but this "alphabetical order by file/folder name" has always been the behavior and documented, so I'd prefer to leave it as-is 😄

[slorber]

Thanks

Didn't know we documented this actually 😅