Improve the block editor handbook table of content

[JustinyAhin]

Fix #28460.

The structure implemented for the handbook toc and folders in this PR can be found here https://gist.github.com/7084adee8abca28c8da8652ebbb1da6f.

[JustinyAhin]

@paaljoachim @mkaz are you able to help on this? When I'm trying to commit the changes to the toc.json file to the branch, I get this error

> node ./docs/tool/index.js && node ./bin/api-docs/update-api-docs.js

internal/fs/utils.js:307
    throw err;
    ^

Error: ENOENT: no such file or directory, open 'docs/designers-developers/glossary.md'
    at Object.openSync (fs.js:476:3)
    at Object.readFileSync (fs.js:377:35)
    at /Users/segbedji/dev/wp/gutenberg/docs/tool/manifest.js:75:29
    at Array.forEach (<anonymous>)
    at generateRootManifestFromTOCItems (/Users/segbedji/dev/wp/gutenberg/docs/tool/manifest.js:61:8)
    at /Users/segbedji/dev/wp/gutenberg/docs/tool/manifest.js:89:5
    at Array.forEach (<anonymous>)
    at generateRootManifestFromTOCItems (/Users/segbedji/dev/wp/gutenberg/docs/tool/manifest.js:61:8)
    at getRootManifest (/Users/segbedji/dev/wp/gutenberg/docs/tool/manifest.js:56:9)
    at Object.<anonymous> (/Users/segbedji/dev/wp/gutenberg/docs/tool/index.js:18:18) {
  errno: -2,
  syscall: 'open',
  code: 'ENOENT',
  path: 'docs/designers-developers/glossary.md'
}

I think it is related to the fact that I've changed the structure of the files and folders in the docs folder (see https://gist.github.com/7084adee8abca28c8da8652ebbb1da6f).

It seems like there's an unknown path which is provided to the function here

gutenberg/docs/tool/manifest.js

Line 59 in d8d2089

function generateRootManifestFromTOCItems( items, parent = null ) {

.

But I'm not able to go further in my exploration :(

[mkaz]

Error: ENOENT: no such file or directory, open 'docs/designers-developers/glossary.md'

Did you move the glossary file?

Moving files is going to be tricky and will produce a lot of duplicate content. The way the script works is it matches files in the toc.json and generates them to HTML and then will create a new post or update if it already exists. The test for existence is based on the file path. There is no clean up job, so all the old posts will still exist and need to be deleted by hand.

It looks like you moved files that are still listed in the toc.json.

[gziolo]

You will also have to update any path reference in other files if they link to the updated files.

[JustinyAhin]

@priethor I have done a big reorganization of the handbook structure based on what we discussed in the issue.
Could you look (here https://github.com/JustinyAhin/gutenberg/tree/block-editor-handbook-toc/docs) and let me know what you think?

also cc @annezazu

[priethor]

Nice work, @JustinyAhin ! 👌

After seeing the single file left under the "Explanation" folder, I'm circling back to your previous attempt, which had Architecture under "Explanation". This was in fact correct according to the documentation system reference, so the decision that I see needs to be made is how close to stick to that structure:

• If we follow it strictly, Architecture should be under Explanation, indeed, as well as the rest of "Getting started" except for the tutorials.
• If we don't follow it strictly, we can move the file under explanation to the Getting Started section, which in our case is acting as Explanation+Tutorials.

I don't have a strong bias towards any of the options, but I personally find it more intuitive to navigate a single "Introduction" or "Getting started" that contains anything I need to, well, get started, such as the high-level explanation and the "Tutorials".

cc @DaisyOlsen

[annezazu]

Whew, this was a bit tricky to review but did the best I could to cross compare, slowly skim through, and do some spot checks. One thing I noticed was that you're using "howto-guides" as the slug when everything else has a - in between each word ("how-to-guides"). It's minor but I find the latter to feel a bit cleaner and more consistent. Not a blocker though so am approving this!

[mkaz]

Since the restructuring is changing file locations and not just organizing the table of contents this change will require a corresponding ticket with meta to clean up all the old files. We probably could just delete all the old handbook files and have the new publishing create new ones.

One caveat, with the restructuring all the URLs this will also probably break external links and poor for SEO. I'm not sure what our options would be for setting up redirects, we may want to check in meta for that also

[priethor]

Hi @JustinyAhin . Great to see this move forward! 🎉

While testing the handbook, I noticed there are 2 top-level pages called "Getting Started". The one at the bottom of the ToC seems more like a "Getting Started to Contribute", as it starts by saying:

The following guide is for setting up your local environment to contribute to the Gutenberg project.

Should we move that page's content to the contributor section and reorganize its descendant pages under the first "Getting Started" page?