Proposal: control ordering of topics in wiki sidebar via number prefixes of md file and folder names

[mi-hol]

Issue:

Currently sequence of topic is not optimal for new users because topic are sorted by alphabetic md file name.

The topic "What to put into this section" should be the first topic from my view

Example:

Solution Proposal:

Use number prefixes for md file names as explained in linked section of Docusaurus user manual

Please comment, in case it gets agreed, I'll create the PRs to implement the change proposal.

[karniv00l]

Use number prefixes for md file names as explained in linked section of Docusaurus user manual

I disagree on that method

Preferred one: https://docusaurus.io/docs/sidebar/autogenerated#autogenerated-sidebar-metadata

[mi-hol]

@karniv00l thanks for your comment.

1. Are you aware of the pros and specifically cons of both approaches (as they are not listed in docusaurus manual)?
2. Do you happen to know what happens when some docs have embedded metadata while others do not?

[mi-hol]

Biggest con for metadata driven approach is the lacking visibility in all "context view" UIs (i.e. FileManagers, GH navigation views).
The metadata approach is therefore violating the highly successful WYSIWIG concept.
This violation creates a big acceptance and adherence hurdle for users.

As I advocate to prioritize useability over other aspects of computing this is my reason for suggesting the numbered prefix approach

[nmschulte]

I personally like the metadata approach, but agree about the visibility concern @mi-hol.

One other drawback I found to the metedata approach is that it doesn't allow [that I've found] to order a page ahead of a sub-collection; i.e. https://github.com/FOME-Tech/wiki/pull/112/files#diff-0680335692b35ee37c48aa5714aa9ee62c208379da7f6c338d94215cfe83b573R2 has no effect to put the page above the two directories.

[karniv00l]

Ok either way is fine with me

[OrchardPerformance]

As long as it's easy to implement, functional and works across all pages then I am not enough of an expert to have any fixed opinion.

If there is a better way than the current method, make a guide and we can start using it.

[mi-hol]

first step of "guide" in PR #119

[OrchardPerformance]

It seems the only concern is the replacement of links when changing a pages location, something that find and replace should be able to cope with.
I think VSCode allows you to do that across a whole open project?

[mi-hol]

Use number prefixes for md file names as explained in linked section of Docusaurus user manual

I disagree on that method

from PR #125 we understand now that below statement in Docusaurus manual
"Updating a number prefix can be annoying, as it can require updating multiple existing Markdown links:"
is incorrect!.
This means the effort to convert FOME wiki files to numbered prefix approach is low

I preserved this knowhow via below comment in \wiki\docs\01-Welcome-to-FOME.md

[//]: # (Docusaurus 2.4.1 requires a root doc/page to have a "slug: /" directive, otherwise 404 is assumed as a welcome message)
[//]: # (also numbered prefixes are NOT to be used in links, because Docusaurus 2.4.1 matches them automatically )

[karniv00l]

I preserved this knowhow via below comment in \wiki\docs\01-Welcome-to-FOME.md

Instead, we could add/extend a section about making internal and external links (and how they differ, and what is not recommended and why) in https://github.com/FOME-Tech/wiki/blob/master/docs/Quick-page.md

[mi-hol]

Instead, we could add/extend a section about making internal and external links (and how they differ, and what is not recommended and why)

ok, will add this section after PR #125 is merged. Simon seems out, hence a PR backlog has build up.