Fix broken links to the block editor developer handbook (#29663)

* Fix broken links to the block editor developer handbook

* Rename developer documentation page title to how-to guides

* Add block variations documentation to reference guide

* Add a title to full-site-editing-templates.md

* Update slug for contributors/develop and contributors/document

* Fix broken relatives links with /designers-developers/ base path

* Rename /contributors/code/getting-started

Rename /contributors/code/getting-started to /contributors/code/getting-started-with-code-contribution.

This is done to avoid having two handbook pages with the same slug, because this results in some confusion when the pages are generated.

Also, replace all the occurence of the first with the second.

* Update the structure of the documentation "Getting Started"

CONTRIBUTING.md

@@ -4,13 +4,13 @@ Welcome to WordPress' Gutenberg project! We hope you join us in creating the fut
 
 ## How can I contribute?
 
-To learn all about contributing to the Gutenberg project, see the [Contributor Guide](/docs/contributors/readme.md). The handbook includes all the details you need to get setup and start shaping the future of web publishing.
+To learn all about contributing to the Gutenberg project, see the [Contributor Guide](/docs/contributors/README.md). The handbook includes all the details you need to get setup and start shaping the future of web publishing.
 
-- Code? See the [developer section](/docs/contributors/develop.md).
+- Code? See the [developer section](/docs/contributors/code/code.md).
 
-- Design? See the [design section](/docs/contributors/design.md).
+- Design? See the [design section](/docs/contributors/design/design.md).
 
-- Documentation? See the [documentation section](/docs/contributors/document.md).
+- Documentation? See the [documentation section](/docs/contributors/documentation/documentation.md).
 
 - Triage? We need help reviewing existing issues to make sure they’re relevant and actionable. Triage is an important contribution because it allows us to work on the highest priority issues. To learn more, please see the [triaging issues section](docs/contributors/triage.md).
 

README.md

@@ -35,7 +35,7 @@ Get hands on: check out the [block editor live demo](https://wordpress.org/guten
 
 Extending and customizing is at the heart of the WordPress platform, this is no different for the Gutenberg project. The editor and future products can be extended by third-party developers using plugins.
 
-Review the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references.
+Review the [Create a Block tutorial](/docs/getting-started/tutorials/create-block/README.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references.
 
 ### Contribute to Gutenberg
 

docs/README.md

@@ -22,21 +22,21 @@ The Editor offers rich new value to users with visual, drag-and-drop creation to
 
 ### Create a Block Tutorial
 
-[Learn how to create your first block](/docs/getting-started/tutorials/create-block/readme.md) for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all what you need to know to get started with the block editor.
+[Learn how to create your first block](/docs/getting-started/tutorials/create-block/README.md) for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all what you need to know to get started with the block editor.
 
 ### Develop for the block editor
 
 Whether you want to extend the functionality of the block editor, or create a plugin based on it, [see the developer documentation](/docs/how-to-guides/README.md) to find all the information about the basic concepts you need to get started, the block editor APIs and its architecture.
 
-- [Gutenberg Architecture](/docs/architecture/readme.md)
+- [Gutenberg Architecture](/docs/explanations/architecture/README.md)
 - [Block Style Variations](/docs/reference-guides/filters/block-filters.md#block-style-variations)
 - [Creating Block Patterns](/docs/reference-guides/block-api/block-patterns.md)
-- [Theming for the Block Editor](/docs/how-to-guides/themes/readme.md)
-- [Block API Reference](/docs/reference-guides/block-api/readme.md)
+- [Theming for the Block Editor](/docs/how-to-guides/themes/README.md)
+- [Block API Reference](/docs/reference-guides/block-api/README.md)
 - [Block Editor Accessibility](/docs/reference-guides/accessibility.md)
 - [Internationalization](/docs/how-to-guides/internationalization.md)
 
 ### Contribute to the block editor
 
-Everything you need to know to [start contributing to the block editor](/docs/contributors/readme.md) . Whether you are interested in the design, code, triage, documentation, support or internationalization of the block editor, you will find here guides to help you.
+Everything you need to know to [start contributing to the block editor](/docs/contributors/README.md) . Whether you are interested in the design, code, triage, documentation, support or internationalization of the block editor, you will find here guides to help you.
 

docs/contributors/README.md

@@ -8,11 +8,11 @@ Gutenberg is a sub-project of Core WordPress. Please see the [Core Contributor H
 
 Find the section below based on what you are looking to contribute:
 
-- **Code?** See the [developer section](/docs/contributors/develop.md).
+- **Code?** See the [developer section](/docs/contributors/code/code.md).
 
-- **Design?** See the [design section](/docs/contributors/design.md).
+- **Design?** See the [design section](/docs/contributors/design/design.md).
 
-- **Documentation?** See the [documentation section](/docs/contributors/document.md)
+- **Documentation?** See the [documentation section](/docs/contributors/documentation/documentation.md)
 
 - **Triage Support?** See the [triaging issues section](/docs/contributors/triage.md)
 

docs/contributors/accessibility-testing.md

@@ -4,7 +4,7 @@ This is a guide on how to test accessibility on Gutenberg. This is a living docu
 
 ## Getting Started
 
-Make sure you have set up your local environment following the instructions on [Getting Started](/docs/contributors/code/getting-started.md).
+Make sure you have set up your local environment following the instructions on [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md).
 
 ## Keyboard Testing
 

docs/contributors/code/develop.md → docs/contributors/code/code.md

@@ -16,7 +16,7 @@ Browse [the issues list](https://github.com/wordpress/gutenberg/issues) to find
 
 ## Contributor Resources
 
-* [Getting Started](/docs/contributors/code/getting-started.md) documents getting your development environment setup, this includes your test site and developer tools suggestions.
+* [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md) documents getting your development environment setup, this includes your test site and developer tools suggestions.
 * [Git Workflow](/docs/contributors/code/git-workflow.md) documents the git process for deploying changes using pull requests.
 * [Coding Guidelines](/docs/contributors/code/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
 * [Testing Overview](/docs/contributors/code/testing-overview.md) for PHP and JavaScript development in Gutenberg.

docs/contributors/code/coding-guidelines.md

@@ -472,6 +472,6 @@ For class components, there is no recommendation for documenting the props of th
 We use
 [`phpcs` (PHP_CodeSniffer)](https://github.com/squizlabs/PHP_CodeSniffer) with the [WordPress Coding Standards ruleset](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) to run a lot of automated checks against all PHP code in this project. This ensures that we are consistent with WordPress PHP coding standards.
 
-The easiest way to use PHPCS is [local environment](/docs/contributors/code/getting-started.md#local-environment). Once that's installed, you can check your PHP by running `npm run lint-php`.
+The easiest way to use PHPCS is [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment). Once that's installed, you can check your PHP by running `npm run lint-php`.
 
 If you prefer to install PHPCS locally, you should use `composer`. [Install `composer`](https://getcomposer.org/download/) on your computer, then run `composer install`. This will install `phpcs` and `WordPress-Coding-Standards` which you can then run via `composer lint`.

docs/contributors/code/getting-started.md → docs/contributors/code/getting-started-with-code-contribution.md

@@ -1,12 +1,12 @@
-# Getting Started
+# Getting Started With Code Contribution
 
-The following guide is for setting up your local environment to contribute to the Gutenberg project. There is significant overlap between an environment to contribute and an environment used to extend the WordPress block editor. You can review the [Development Environment tutorial](/docs/getting-started/tutorials/devenv/readme.md) for additional setup information.
+The following guide is for setting up your local environment to contribute to the Gutenberg project. There is significant overlap between an environment to contribute and an environment used to extend the WordPress block editor. You can review the [Development Environment tutorial](/docs/getting-started/tutorials/devenv/README.md) for additional setup information.
 
 ## Development Tools (Node)
 
 Gutenberg is a JavaScript project and requires [Node.js](https://nodejs.org/). The project is built using the latest active LTS release of node, and the latest version of NPM. See the [LTS release schedule](https://github.com/nodejs/Release#release-schedule) for details.
 
-We recommend using the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) since it is the easiest way to install and manage node for macOS, Linux, and Windows 10 using WSL2. See [our Development Tools guide](/docs/getting-started/tutorials/devenv/readme.md#development-tools) or the Nodejs site for additional installation instructions.
+We recommend using the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) since it is the easiest way to install and manage node for macOS, Linux, and Windows 10 using WSL2. See [our Development Tools guide](/docs/getting-started/tutorials/devenv/README.md#development-tools) or the Nodejs site for additional installation instructions.
 
 After installing Node, you can build Gutenberg by running the following from within the cloned repository:
 
@@ -34,7 +34,7 @@ The [wp-env package](/packages/env/README.md) was developed with the Gutenberg p
 
 By default, `wp-env` can run in a plugin directory to create and run a WordPress environment, mounting and activating the plugin automatically. You can also configure `wp-env` to use existing installs, multiple plugins, or themes. See the [wp-env package](/packages/env/README.md#wp-envjson) for complete documentation.
 
-If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`. See the [Development Environment tutorial for additional details](/docs/getting-started/tutorials/devenv/readme.md).
+If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`. See the [Development Environment tutorial for additional details](/docs/getting-started/tutorials/devenv/README.md).
 
 Once Docker is installed and running: To install WordPress, run the following from within the cloned gutenberg directory:
 

docs/contributors/code/native-mobile.md

@@ -4,7 +4,7 @@ Intertwined with the web codepaths, the Gutenberg repo also includes the [React
 
 ## Running Gutenberg Mobile on Android and iOS
 
-For instructions on how to run the **Gutenberg Mobile Demo App** on Android or iOS, see [Getting Started for the React Native based Mobile Gutenberg](/docs/contributors/code/getting-started-native-mobile.md)
+For instructions on how to run the **Gutenberg Mobile Demo App** on Android or iOS, see [Getting Started for the React Native based Mobile Gutenberg](/docs/contributors/code/getting-started-with-code-contribution-native-mobile.md)
 
 Also, the mobile client is packaged and released via the [official WordPress apps](https://wordpress.org/mobile/). Even though the build pipeline is slightly different then the mobile demo apps and lives in its own repo for now ([here's the native mobile repo](https://github.com/wordpress-mobile/gutenberg-mobile)), the source code itself is taken directly from this repo and the "web" side codepaths.
 
@@ -21,7 +21,7 @@ Our tooling isn't as good yet as we'd like to and it's hard to have a good aware
 If you encounter a failed Android/iOS test on your pull request, we recommend the following steps:
 
 1. Re-running the failed GitHub Action job ([guide for how to re-run](https://docs.github.com/en/actions/configuring-and-managing-workflows/managing-a-workflow-run#viewing-your-workflow-history)) - This should fix failed tests the majority of the time. Cases where you need to re-run tests for a pass should go down in the near future as flakiness in tests is actively being worked on. See the following GitHub issue for updated info on known failures: https://github.com/WordPress/gutenberg/issues/23949
-2. You can check if the test is failing locally by following the steps to run the E2E test on your machine from the [mobile getting started guide](/docs/contributors/code/getting-started-native-mobile.md#ui-tests), with even more relevant info in the [relevant directory README.md](https://github.com/WordPress/gutenberg/tree/HEAD/packages/react-native-editor/__device-tests__#running-the-tests-locally)
+2. You can check if the test is failing locally by following the steps to run the E2E test on your machine from the [mobile getting started guide](/docs/contributors/code/getting-started-with-code-contribution-native-mobile.md#ui-tests), with even more relevant info in the [relevant directory README.md](https://github.com/WordPress/gutenberg/tree/HEAD/packages/react-native-editor/__device-tests__#running-the-tests-locally)
 3. In addition to reading the logs from the E2E test, you can download a video recording from the Artifacts section of the GitHub job that may have additional useful information.
 4. Check if any changes in your PR would require corresponding changes to `.native.js` versions of files.
 5. Lastly, if you're stuck on a failing mobile test, feel free to reach out to contributors on Slack in the #mobile or #core-editor chats in the WordPress Core Slack, [free to join](https://make.wordpress.org/chat/).

docs/contributors/code/testing-overview.md

@@ -23,15 +23,15 @@ Tests for JavaScript use [Jest](https://jestjs.io/) as the test runner and its A
 
 It should be noted that in the past, React components were unit tested with [Enzyme](https://github.com/airbnb/enzyme). However, for new tests, it is preferred to use React Testing Library (RTL) and over time old tests should be refactored to use RTL too (typically when working on code that touches an old test).
 
-Assuming you've followed the [instructions](/docs/contributors/code/getting-started.md) to install Node and project dependencies, tests can be run from the command-line with NPM:
+Assuming you've followed the [instructions](/docs/contributors/code/getting-started-with-code-contribution.md) to install Node and project dependencies, tests can be run from the command-line with NPM:
 
 ```
 npm test
 ```
 
 Linting is static code analysis used to enforce coding standards and to avoid potential errors. This project uses [ESLint](http://eslint.org/) and [TypeScript's JavaScript type-checking](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html) to capture these issues. While the above `npm test` will execute both unit tests and code linting, code linting can be verified independently by running `npm run lint`. Some JavaScript issues can be fixed automatically by running `npm run lint-js:fix`.
 
-To improve your developer workflow, you should setup an editor linting integration. See the [getting started documentation](/docs/contributors/code/getting-started.md) for additional information.
+To improve your developer workflow, you should setup an editor linting integration. See the [getting started documentation](/docs/contributors/code/getting-started-with-code-contribution.md) for additional information.
 
 To run unit tests only, without the linter, use `npm run test-unit` instead.
 
@@ -386,7 +386,7 @@ Contributors to Gutenberg will note that PRs include continuous integration E2E
 
 End-to-end tests use [Puppeteer](https://github.com/puppeteer/puppeteer) as a headless Chromium driver, and are otherwise still run by a [Jest](https://jestjs.io/) test runner.
 
-If you're using the built-in [local environment](/docs/contributors/code/getting-started.md#local-environment), you can run the e2e tests locally using this command:
+If you're using the built-in [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment), you can run the e2e tests locally using this command:
 
 ```bash
 npm run test-e2e
@@ -454,7 +454,7 @@ Every core block is required to have at least one set of fixture files for its m
 
 ## PHP Testing
 
-Tests for PHP use [PHPUnit](https://phpunit.de/) as the testing framework. If you're using the built-in [local environment](/docs/contributors/code/getting-started.md#local-environment), you can run the PHP tests locally using this command:
+Tests for PHP use [PHPUnit](https://phpunit.de/) as the testing framework. If you're using the built-in [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment), you can run the PHP tests locally using this command:
 
 ```bash
 npm run test-php

docs/contributors/documentation/document.md → docs/contributors/documentation/documentation.md

@@ -67,7 +67,7 @@ This way they will be properly handled in all three aforementioned contexts.
 
 Use the full directory and filename from the Gutenberg repository, not the published path; the Block Editor Handbook creates short URLs—you can see this in the tutorials section. Likewise, the `readme.md` portion is dropped in the handbook, but should be included in links.
 
-An example, the link to this page is: `/docs/contributors/document.md`
+An example, the link to this page is: `/docs/contributors/documentation/documentation.md`
 
 ### Code Examples
 
@@ -96,7 +96,7 @@ The preferred format for code examples is ESNext, this should be the default vie
 
 ### Editor Config
 
-You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](/docs/contributors/code/getting-started.md) for complete details.
+You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](/docs/contributors/code/getting-started-with-code-contribution.md) for complete details.
 
 An example config for using Visual Studio Code and the Prettier extensions:
 

docs/explanations/architecture/README.md

@@ -2,12 +2,12 @@
 
 Let’s look at the big picture and the architectural and UX principles of the block editor and the Gutenberg repository.
 
-- [Key Concepts](/docs/architecture/key-concepts.md)
-- [Data Format And Data Flow](/docs/architecture/data-flow.md)
-- [Understand the repository folder structure](/docs/architecture/folder-structure.md).
-- [Modularity and WordPress Packages](/docs/architecture/modularity.md).
-- [Block Editor Performance](/docs/architecture/performance.md).
+- [Key Concepts](/docs/explanations/architecture/key-concepts.md)
+- [Data Format And Data Flow](/docs/explanations/architecture/data-flow.md)
+- [Understand the repository folder structure](/docs/contributors/folder-structure.md).
+- [Modularity and WordPress Packages](/docs/explanations/architecture/modularity.md).
+- [Block Editor Performance](/docs/explanations/architecture/performance.md).
 - What are the decision decisions behind the Data Module?
-- [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/architecture/automated-testing.md)
-- [What's the difference between the different editor packages? What's the purpose of each package?](/docs/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package)
-- [Template and template parts flows](/docs/architecture/fse-templates.md)
+- [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/explanations/architecture/automated-testing.md)
+- [What's the difference between the different editor packages? What's the purpose of each package?](/docs/explanations/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package)
+- [Template and template parts flows](/docs/explanations/architecture/fse-templates.md)