diff --git a/packages/block-serialization-default-parser/README.md b/packages/block-serialization-default-parser/README.md index 8c35f3f52d65d..254d8f7bdcd19 100644 --- a/packages/block-serialization-default-parser/README.md +++ b/packages/block-serialization-default-parser/README.md @@ -1,6 +1,6 @@ # Block Serialization Default Parser -This library contains the default block serialization parser implementations for WordPress documents. It provides native PHP and JavaScript parsers that implement the [specification](../../docs/grammar.md) from [`@wordpress/block-serialization-spec-parser`](../block-serialization-spec-parser/README.md) and which normally operates on the document stored in `post_content`. +This library contains the default block serialization parser implementations for WordPress documents. It provides native PHP and JavaScript parsers that implement the [specification](/docs/contributors/grammar.md) from [`@wordpress/block-serialization-spec-parser`](/packages/block-serialization-spec-parser/README.md) and which normally operates on the document stored in `post_content`. ## Installation diff --git a/packages/block-serialization-spec-parser/README.md b/packages/block-serialization-spec-parser/README.md index 8de72e547276f..e4750b42cdfda 100644 --- a/packages/block-serialization-spec-parser/README.md +++ b/packages/block-serialization-spec-parser/README.md @@ -1,6 +1,6 @@ # Block Serialization Spec Parser -This library contains the grammar file (`grammar.pegjs`) for WordPress posts which is a block serialization [_specification_](../../docs/grammar.md) which is used to generate the actual _parser_ which is also bundled in this package. +This library contains the grammar file (`grammar.pegjs`) for WordPress posts which is a block serialization [_specification_](/docs/contributors/grammar.md) which is used to generate the actual _parser_ which is also bundled in this package. PEG parser generators are available in many languages, though different libraries may require some translation of this grammar into their syntax. For more information see: diff --git a/packages/blocks/README.md b/packages/blocks/README.md index fe7d7b9dced3a..380ea9b9b9da4 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -1,18 +1,10 @@ # Blocks -"Block" is the abstract term used to describe units of markup that, composed -together, form the content or layout of a webpage. The idea combines concepts -of what in WordPress today we achieve with shortcodes, custom HTML, and embed -discovery into a single consistent API and user experience. +"Block" is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. -For more context, refer to -[_What Are Little Blocks Made Of?_](https://make.wordpress.org/design/2017/01/25/what-are-little-blocks-made-of/) -from the -[Make WordPress Design](https://make.wordpress.org/design/) -blog. +For more context, refer to [_What Are Little Blocks Made Of?_](https://make.wordpress.org/design/2017/01/25/what-are-little-blocks-made-of/) from the [Make WordPress Design](https://make.wordpress.org/design/) blog. -The following documentation outlines steps you as a developer will need to -follow to add your own custom blocks to WordPress's editor interfaces. +The following documentation outlines steps you as a developer will need to follow to add your own custom blocks to WordPress's editor interfaces. ## Installation @@ -26,14 +18,9 @@ _This package assumes that your code will run in an **ES2015+** environment. If ## Getting Started -If you're not already accustomed to working with JavaScript in your WordPress -plugins, you may first want to reference the guide on -[_Including CSS & JavaScript_](https://developer.wordpress.org/themes/basics/including-css-javascript/) -in the Theme Handbook. +If you're not already accustomed to working with JavaScript in your WordPress plugins, you may first want to reference the guide on [_Including CSS & JavaScript_](https://developer.wordpress.org/themes/basics/including-css-javascript/) in the Theme Handbook. -At a minimum, you will need to enqueue scripts for your block as part of a -`enqueue_block_editor_assets` action callback, with a dependency on the -`wp-blocks` and `wp-element` script handles: +At a minimum, you will need to enqueue scripts for your block as part of a `enqueue_block_editor_assets` action callback, with a dependency on the `wp-blocks` and `wp-element` script handles: ```php

Code is Poetry.

diff --git a/packages/components/src/menu-item/README.md b/packages/components/src/menu-item/README.md index 76cff639fce51..eacd6770f7aaf 100644 --- a/packages/components/src/menu-item/README.md +++ b/packages/components/src/menu-item/README.md @@ -1,6 +1,6 @@ # MenuItem -MenuItem is a component which renders a button intended to be used in combination with the [DropdownMenu component](../dropdown-menu). +MenuItem is a component which renders a button intended to be used in combination with the [DropdownMenu component](/packages/components/src/dropdown-menu/README.md). ## Usage @@ -23,7 +23,7 @@ const MyMenuItem = withState( { ## Props -MenuItem supports the following props. Any additional props are passed through to the underlying [Button](../button) or [IconButton](../icon-button) component. +MenuItem supports the following props. Any additional props are passed through to the underlying [Button](/packages/components/src/button/README.md) or [IconButton](/packages/components/src/icon-button/README.md) component. ### `children` @@ -57,14 +57,14 @@ Refer to documentation for [`label`](#label). - Type: `string` - Required: No -Refer to documentation for [IconButton's `icon` prop](../icon-button/README.md#icon). +Refer to documentation for [IconButton's `icon` prop](/packages/components/src/icon-button/README.md#icon). ### `shortcut` - Type: `string` - Required: No -Refer to documentation for [Shortcut's `shortcut` prop](../shortcut/README.md#shortcut). +Refer to documentation for [Shortcut's `shortcut` prop](/packages/components/src/shortcut/README.md#shortcut). ### `role` diff --git a/packages/components/src/tooltip/README.md b/packages/components/src/tooltip/README.md index bf155161fd0d6..f3f702a6b486d 100644 --- a/packages/components/src/tooltip/README.md +++ b/packages/components/src/tooltip/README.md @@ -36,7 +36,7 @@ The direction in which the tooltip should open relative to its parent node. Spec The element to which the tooltip should anchor. -__NOTE:__ You must pass only a single child. Tooltip renders itself as a clone of `children` with a [`Popover`](../popover) added as an additional child. +__NOTE:__ You must pass only a single child. Tooltip renders itself as a clone of `children` with a [`Popover`](/packages/components/src/popover/README.md) added as an additional child. - Type: `Element` - Required: Yes diff --git a/packages/core-data/README.md b/packages/core-data/README.md index f2b61d9157315..8470bbda78a94 100644 --- a/packages/core-data/README.md +++ b/packages/core-data/README.md @@ -1,8 +1,8 @@ # Core Data -Core Data is a [data module](../data) intended to simplify access to and manipulation of core WordPress entities. It registers its own store and provides a number of selectors which resolve data from the WordPress REST API automatically, along with dispatching action creators to manipulate data. +Core Data is a [data module](/packages/data/README.md) intended to simplify access to and manipulation of core WordPress entities. It registers its own store and provides a number of selectors which resolve data from the WordPress REST API automatically, along with dispatching action creators to manipulate data. -Used in combination with features of the data module such as [`subscribe`](https://github.com/WordPress/gutenberg/tree/master/packages/data#subscribe-function) or [higher-order components](https://github.com/WordPress/gutenberg/tree/master/packages/data#higher-order-components), it enables a developer to easily add data into the logic and display of their plugin. +Used in combination with features of the data module such as [`subscribe`](/packages/data/README.md#subscribe-function) or [higher-order components](/packages/data/README.md#higher-order-components), it enables a developer to easily add data into the logic and display of their plugin. ## Installation diff --git a/packages/data/README.md b/packages/data/README.md index 2c911ccf4cf8f..630d30ef9df6c 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -131,13 +131,13 @@ The `resolvers` option should be passed as an object where each key is the name ### `controls` -_**Note:** Controls are an opt-in feature, enabled via `use` (the [Plugins API](https://github.com/WordPress/gutenberg/tree/master/packages/data/src/plugins))._ +_**Note:** Controls are an opt-in feature, enabled via `use` (the [Plugins API](/packages/data/src/plugins/README.md))._ A **control** defines the execution flow behavior associated with a specific action type. This can be particularly useful in implementing asynchronous data flows for your store. By defining your action creator or resolvers as a generator which yields specific controlled action types, the execution will proceed as defined by the control handler. The `controls` option should be passed as an object where each key is the name of the action type to act upon, the value a function which receives the original action object. It should returns either a promise which is to resolve when evaluation of the action should continue, or a value. The value or resolved promise value is assigned on the return value of the yield assignment. If the control handler returns undefined, the execution is not continued. -Refer to the [documentation of `@wordpress/redux-routine`](https://github.com/WordPress/gutenberg/tree/master/packages/redux-routine/) for more information. +Refer to the [documentation of `@wordpress/redux-routine`](/packages/redux-routine/README.md) for more information. ## Data Access and Manipulation @@ -225,7 +225,7 @@ registerStore( 'my-shop', { ### Higher-Order Components -A higher-order component is a function which accepts a [component](https://github.com/WordPress/gutenberg/tree/master/packages/element) and returns a new, enhanced component. A stateful user interface should respond to changes in the underlying state and updates its displayed element accordingly. WordPress uses higher-order components both as a means to separate the purely visual aspects of an interface from its data backing, and to ensure that the data is kept in-sync with the stores. +A higher-order component is a function which accepts a [component](/packages/element/README.md) and returns a new, enhanced component. A stateful user interface should respond to changes in the underlying state and updates its displayed element accordingly. WordPress uses higher-order components both as a means to separate the purely visual aspects of an interface from its data backing, and to ensure that the data is kept in-sync with the stores. #### `withSelect( mapSelectToProps: Function ): Function` @@ -406,7 +406,7 @@ registry.registerGenericStore( 'custom-data', createCustomStore() ); The data module shares many of the same [core principles](https://redux.js.org/introduction/three-principles) and [API method naming](https://redux.js.org/api-reference) of [Redux](https://redux.js.org/). In fact, it is implemented atop Redux. Where it differs is in establishing a modularization pattern for creating separate but interdependent stores, and in codifying conventions such as selector functions as the primary entry point for data access. -The [higher-order components](#higher-order-components) were created to complement this distinction. The intention with splitting `withSelect` and `withDispatch` — where in React Redux they are combined under `connect` as `mapStateToProps` and `mapDispatchToProps` arguments — is to more accurately reflect that dispatch is not dependent upon a subscription to state changes, and to allow for state-derived values to be used in `withDispatch` (via [higher-order component composition](https://github.com/WordPress/gutenberg/tree/master/packages/compose)). +The [higher-order components](#higher-order-components) were created to complement this distinction. The intention with splitting `withSelect` and `withDispatch` — where in React Redux they are combined under `connect` as `mapStateToProps` and `mapDispatchToProps` arguments — is to more accurately reflect that dispatch is not dependent upon a subscription to state changes, and to allow for state-derived values to be used in `withDispatch` (via [higher-order component composition](/packages/compose/README.md)). Specific implementation differences from Redux and React Redux: diff --git a/packages/edit-post/README.md b/packages/edit-post/README.md index a150193a78a61..48e54d76ae36e 100644 --- a/packages/edit-post/README.md +++ b/packages/edit-post/README.md @@ -18,11 +18,11 @@ _This package assumes that your code will run in an **ES2015+** environment. If Extending the editor UI can be accomplished with the `registerPlugin` API, allowing you to define all your plugin's UI elements in one place. -Refer to [the plugins module documentation](../plugins/) for more information. +Refer to [the plugins module documentation](/packages/plugins/README.md) for more information. ## Plugin Components -The following components can be used with the `registerPlugin` ([see documentation](../plugins)) API. +The following components can be used with the `registerPlugin` ([see documentation](/packages/plugins/README.md)) API. They can be found in the global variable `wp.editPost` when defining `wp-edit-post` as a script dependency. ### `PluginBlockSettingsMenuItem` @@ -249,7 +249,7 @@ const MyButtonMoreMenuItem = () => ( #### Props -`PluginMoreMenuItem` supports the following props. Any additional props are passed through to the underlying [MenuItem](../components/src/menu-item) component. +`PluginMoreMenuItem` supports the following props. Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. ##### href diff --git a/packages/editor/src/components/autocompleters/README.md b/packages/editor/src/components/autocompleters/README.md index a802c02f75dba..d7c039e01b22a 100644 --- a/packages/editor/src/components/autocompleters/README.md +++ b/packages/editor/src/components/autocompleters/README.md @@ -1,4 +1,4 @@ Autocompleters ============== -The Autocompleter interface is documented [here](../../components/autocomplete/README.md) with the `Autocomplete` component in `@wordpress/components`. +The Autocompleter interface is documented [here](/packages/components/src/autocomplete/README.md) with the `Autocomplete` component in `@wordpress/components`. diff --git a/packages/editor/src/components/media-upload/README.md b/packages/editor/src/components/media-upload/README.md index 1dc11cb2a37ed..1fdeed671bd1e 100644 --- a/packages/editor/src/components/media-upload/README.md +++ b/packages/editor/src/components/media-upload/README.md @@ -20,7 +20,7 @@ addFilter( ); ``` -You can check how this component is implemented for the edit post page using `wp.media` module in [edit-post](../../../../edit-post/src/hooks/components/media-upload/index.js). +You can check how this component is implemented for the edit post page using `wp.media` module in [edit-post](https://github.com/WordPress/gutenberg/tree/master/packages/edit-post/src/hooks/components/media-upload/index.js). ## Usage diff --git a/packages/element/README.md b/packages/element/README.md index 0154d2762859b..cca88dff95240 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -47,9 +47,9 @@ Refer to the [official React Quick Start guide](https://reactjs.org/docs/hello-w ## Why React? -At the risk of igniting debate surrounding any single "best" front-end framework, the choice to use any tool should be motivated specifically to serve the requirements of the system. In modeling the concept of a [block](../../blocks/README.md), we observe the following technical requirements: +At the risk of igniting debate surrounding any single "best" front-end framework, the choice to use any tool should be motivated specifically to serve the requirements of the system. In modeling the concept of a [block](/packages/blocks/README.md), we observe the following technical requirements: -- An understanding of a block in terms of its underlying values (in the [random image example](../blocks/README.md#example), a category) +- An understanding of a block in terms of its underlying values (in the [random image example](/packages/blocks/README.md#example), a category) - A means to describe the UI of a block given these values At its most basic, React provides a simple input / output mechanism. __Given a set of inputs ("props"), a developer describes the output to be shown on the page.__ This is most elegantly observed in its [function components](https://reactjs.org/docs/components-and-props.html#functional-and-class-components). React serves the role of reconciling the desired output with the current state of the page. diff --git a/packages/i18n/README.md b/packages/i18n/README.md index f1d6857b2a813..5e57b0f4cb806 100644 --- a/packages/i18n/README.md +++ b/packages/i18n/README.md @@ -27,7 +27,7 @@ Note that you will not need to specify [domain](https://codex.wordpress.org/I18n ## Build -You can use the [WordPress i18n babel plugin](../babel-plugin-makepot/README.md) to generate a `.pot` file containing all your localized strings. +You can use the [WordPress i18n babel plugin](/packages/babel-plugin-makepot/README.md) to generate a `.pot` file containing all your localized strings. The package also includes a `pot-to-php` script used to generate a php files containing the messages listed in a `.pot` file. This is useful to trick WordPress.org translation strings discovery since at the moment, WordPress.org is not capable of parsing strings directly from JavaScript files. diff --git a/packages/notices/README.md b/packages/notices/README.md index 1091435266540..a32e69725b39c 100644 --- a/packages/notices/README.md +++ b/packages/notices/README.md @@ -18,7 +18,7 @@ _This package assumes that your code will run in an **ES2015+** environment. If When imported, the notices module registers a data store on the `core/notices` namespace. -For more information about consuming from a data store, refer to [the `@wordpress/data` documentation on _Data Access and Manipulation_](https://wordpress.org/gutenberg/handbook/packages/packages-data/#data-access-and-manipulation). +For more information about consuming from a data store, refer to [the `@wordpress/data` documentation on _Data Access and Manipulation_](/packages/data/README.md#data-access-and-manipulation). For a full list of actions and selectors available in the `core/notices` namespace, refer to the [_Notices Data_ Handbook page](https://wordpress.org/gutenberg/handbook/packages/packages-data/packages-data-core-edit-post/). diff --git a/packages/plugins/README.md b/packages/plugins/README.md index 4d4afd5896b19..a4ace1daf8f3c 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -29,7 +29,7 @@ This method takes two arguments: or an element (or function returning an element) if you choose to render your own SVG. - `render`: A component containing the UI elements to be rendered. -See [the edit-post module documentation](/packages/edit-post/) for available components. +See [the edit-post module documentation](/packages/edit-post/README.md) for available components. _Example:_ {% codetabs %} diff --git a/packages/viewport/README.md b/packages/viewport/README.md index 9f15a3a6d8e33..08e2d33fb748f 100644 --- a/packages/viewport/README.md +++ b/packages/viewport/README.md @@ -1,6 +1,6 @@ # Viewport -Viewport is a module for responding to changes in the browser viewport size. It registers its own [data module](https://github.com/WordPress/gutenberg/tree/master/packages/data), updated in response to browser media queries on a standard set of supported breakpoints. This data and the included higher-order components can be used in your own modules and components to implement viewport-dependent behaviors. +Viewport is a module for responding to changes in the browser viewport size. It registers its own [data module](/packages/data/README.md), updated in response to browser media queries on a standard set of supported breakpoints. This data and the included higher-order components can be used in your own modules and components to implement viewport-dependent behaviors. ## Installation