Update the docs build script / files to implement redirects

[bph]

With the documentation expanding, the need to reorganize sections of the Block editor handbook might come up, that would also require to establish redirect rules for the WordPress site. In the sister meta trac issue: https://meta.trac.wordpress.org/ticket/6407 The manifest json is expanded to also hold the redirect information.

{
"title": "Block Filters",
"title": "Block Hooks",
"slug": "block-hooks",
"markdown_source": "../docs/reference-guides/hooks/block-hooks.md",
"parent": "hooks",
"redirect_from":["reference-guides/filters/block-filters"]
},

redirect_from = array of pages to redirect to the new page.

The manifest.json file is created automatically via the npm run docs:build script, that takes the information from the toc.json file.

[georgeh]

I'm not sure how best to represent this in toc.json. The current format is an array of objects, where the key is a Markdown file and the value is an array of more objects in the same format. docs/tool/manifest.js uses that to build manifest.json by looking for a Markdown H1 for the title.

My first thought is that there should be a reserved key __meta to set extra metadata about the file, such as redirect_from. So in the example above the toc.json line would be

{ 
    "docs/how-to-guides/format-api.md": [
        "__meta": {
            "redirect_from": ["reference-guides/filters/block-filters"]
        }
    ] 
},

This would allow us to include other metadata changes in the future, such as overrides for title, slugs, or even things like theme.

The other idea I had was to put the metadata as Frontmatter in the Markdown file itself. This has the advantage of putting the changes as close to the file itself and seems a more Markdown-native way to handle it.

[bangank36]

@bph I think this is handled by developer to submit the redirects to WordPress/wporg-developer
Take #54120 for example where the redirects are submitted into WordPress/wporg-developer#274

Old: https://developer.wordpress.org/block-editor/explanations/glossary/
New: https://developer.wordpress.org/block-editor/getting-started/glossary/

[bph]

Oh yes, i understand the current process. It feels very pedestrian to me. I had quite a few discussions with the meta team respectively @tellyworth and @dd32 how to automate the process of creating the redirects. you can read in the trac ticket linked. My discussion about this issues with @georgeh about how to implement the Gutenberg half of the automation is stuck in the beginning and didn't go anywhere. Maybe @ndiego could revitalize it.