diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 9fe873dbb50e5..22ec9d8c002b3 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -1,7 +1,7 @@
# Documentation
-/docs @youknowriad @chrisvanpatten @mkaz @ajitbohra @nosolosw @notnownikki
-/docs/designers-developers/developers @youknowriad @gziolo @chrisvanpatten @mkaz @ajitbohra @nosolosw @notnownikki
-/docs/designers-developers/designers @youknowriad @chrisvanpatten @mkaz @ajitbohra @nosolosw @notnownikki
+/docs @youknowriad @chrisvanpatten @mkaz @ajitbohra @notnownikki
+/docs/designers-developers/developers @youknowriad @gziolo @chrisvanpatten @mkaz @ajitbohra @notnownikki
+/docs/designers-developers/designers @youknowriad @chrisvanpatten @mkaz @ajitbohra @notnownikki
# Data
/packages/api-fetch @youknowriad @aduth @nerrad @mmtr
@@ -28,23 +28,23 @@
/packages/edit-widgets @youknowriad
# Tooling
-/bin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
+/bin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
/docs/tool @youknowriad @gziolo @chrisvanpatten @mkaz @ajitbohra @nosolosw @notnownikki
/packages/babel-plugin-import-jsx-pragma @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
/packages/babel-plugin-makepot @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
/packages/babel-preset-default @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
-/packages/browserslist-config @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
-/packages/custom-templated-path-webpack-plugin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
+/packages/browserslist-config @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
+/packages/custom-templated-path-webpack-plugin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
/packages/docgen @nosolosw @mkaz @gziolo
/packages/e2e-test-utils @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
/packages/e2e-tests @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @talldan
-/packages/eslint-plugin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
+/packages/eslint-plugin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
/packages/jest-console @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
/packages/jest-preset-default @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
/packages/jest-puppeteer-axe @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
-/packages/library-export-default-webpack-plugin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
-/packages/npm-package-json-lint-config @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
-/packages/postcss-themes @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra
+/packages/library-export-default-webpack-plugin @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
+/packages/npm-package-json-lint-config @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
+/packages/postcss-themes @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw
/packages/scripts @youknowriad @gziolo @aduth @ntwb @nerrad @ajitbohra @nosolosw @mkaz
# UI Components
diff --git a/.travis.yml b/.travis.yml
index d0de440677a9f..dc51393e18fed 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -27,17 +27,40 @@ before_install:
jobs:
include:
- - name: JS unit tests
- env: WP_VERSION=latest
+ - name: Lint
before_install:
- nvm install --latest-npm
install:
- npm ci
script:
- - npm run build
- npm run lint
+
+ - name: Build artifacts
+ before_install:
+ - nvm install --latest-npm
+ install:
+ - npm ci
+ script:
- npm run check-local-changes
+
+ - name: License compatibility
+ before_install:
+ - nvm install --latest-npm
+ install:
+ - npm ci
+ script:
- npm run check-licenses
+
+ - name: JavaScript unit tests
+ before_install:
+ - nvm install --latest-npm
+ install:
+ - npm ci
+ script:
+ # It's not necessary to run the full build, since Jest can interpret
+ # source files with `babel-jest`. Some packages have their own custom
+ # build tasks, however. These must be run.
+ - npx lerna run build
- npm run test-unit -- --ci --maxWorkers=2 --cacheDirectory="$HOME/.jest-cache"
- name: PHP unit tests (Docker)
@@ -69,8 +92,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 0' < ~/.jest-e2e-tests )
- name: E2E tests (Admin with plugins) (2/4)
@@ -78,8 +101,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 1' < ~/.jest-e2e-tests )
- name: E2E tests (Admin with plugins) (3/4)
@@ -87,8 +110,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 2' < ~/.jest-e2e-tests )
- name: E2E tests (Admin with plugins) (4/4)
@@ -96,8 +119,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 3' < ~/.jest-e2e-tests )
- name: E2E tests (Author without plugins) (1/4)
@@ -105,8 +128,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 0' < ~/.jest-e2e-tests )
- name: E2E tests (Author without plugins) (2/4)
@@ -114,8 +137,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 1' < ~/.jest-e2e-tests )
- name: E2E tests (Author without plugins) (3/4)
@@ -123,8 +146,8 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 2' < ~/.jest-e2e-tests )
- name: E2E tests (Author without plugins) (4/4)
@@ -132,9 +155,10 @@ jobs:
install:
- ./bin/setup-local-env.sh
script:
- - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run build
+ - $( npm bin )/wp-scripts test-e2e --config=./packages/e2e-tests/jest.config.js --listTests > ~/.jest-e2e-tests
- npm run test-e2e -- --ci --cacheDirectory="$HOME/.jest-cache" --runTestsByPath $( awk 'NR % 4 == 3' < ~/.jest-e2e-tests )
+
allow_failures:
- name: PHP unit tests (PHP 5.3)
env: WP_VERSION=latest SWITCH_TO_PHP=5.3
diff --git a/assets/stylesheets/_mixins.scss b/assets/stylesheets/_mixins.scss
index 111f65dfc411b..8551c934d6edb 100644
--- a/assets/stylesheets/_mixins.scss
+++ b/assets/stylesheets/_mixins.scss
@@ -180,8 +180,8 @@
@mixin input-style__focus() {
color: $dark-gray-900;
- border-color: $blue-medium-500;
- box-shadow: 0 0 0 1px $blue-medium-500;
+ border-color: $blue-medium-focus;
+ box-shadow: 0 0 0 1px $blue-medium-focus;
// Windows High Contrast mode will show this outline, but not the box-shadow.
outline: 2px solid transparent;
diff --git a/bin/packages/watch.js b/bin/packages/watch.js
index ccfcc0b7dd85c..1add26a5677a7 100644
--- a/bin/packages/watch.js
+++ b/bin/packages/watch.js
@@ -27,7 +27,7 @@ const exists = ( filename ) => {
// and files with a suffix of .test or .spec (e.g. blocks.test.js),
// and deceitful source-like files, such as editor swap files.
const isSourceFile = ( filename ) => {
- return ! [ /\/(__tests__|test)\/.+.js$/, /.\.(spec|test)\.js$/ ].some( ( regex ) => regex.test( filename ) ) && /.\.(js|scss)$/.test( filename );
+ return ! [ /\/(__tests__|test)\/.+.js$/, /.\.(spec|test)\.js$/ ].some( ( regex ) => regex.test( filename ) ) && /.\.(js|json|scss)$/.test( filename );
};
const rebuild = ( filename ) => filesToBuild.set( filename, true );
diff --git a/docs/contributors/coding-guidelines.md b/docs/contributors/coding-guidelines.md
index bb763af00018b..ab3258f7f8b51 100644
--- a/docs/contributors/coding-guidelines.md
+++ b/docs/contributors/coding-guidelines.md
@@ -1,6 +1,6 @@
# Coding Guidelines
-This living document serves to prescribe coding guidelines specific to the Gutenberg editor project. Base coding guidelines follow the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/). The following sections outline additional patterns and conventions used in the Gutenberg project.
+This living document serves to prescribe coding guidelines specific to the Gutenberg project. Base coding guidelines follow the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/). The following sections outline additional patterns and conventions used in the Gutenberg project.
## CSS
diff --git a/docs/contributors/design.md b/docs/contributors/design.md
index bd68ba060718e..d71221003d378 100644
--- a/docs/contributors/design.md
+++ b/docs/contributors/design.md
@@ -8,7 +8,7 @@ This is a living document that outlines the design principles and patterns of th
### Goal of Gutenberg
-Gutenberg's all-encompassing goal is a post- and page-building experience that makes it easy to create rich layouts.
+Gutenberg's all-encompassing goal is a post- and page-building experience that makes it easy to create rich layouts. The block editor was the first product launched following this methodology for working with content.
From the [kickoff post](https://make.wordpress.org/core/2017/01/04/focus-tech-and-design-leads/):
@@ -18,13 +18,13 @@ We can extract a few key principles from this:
- **Authoring rich posts is a key strength of WordPress.**
- **Blocks will unify features and types of interaction under a single interface.** Users shouldn’t have to write shortcodes, custom HTML, or paste URLs to embed. Users only need to learn how the block works in order to use all of its features.
-- **Gutenberg makes core features more discoverable**, reducing hard-to-find “Mystery meat.” WordPress supports a large number of blocks and 30+ embeds. Let’s increase their visibility.
+- **Make core features more discoverable**, reducing hard-to-find “Mystery meat.” WordPress supports a large number of blocks and 30+ embeds. Let’s increase their visibility.
### Why
One thing that sets WordPress apart from other systems is that it allows users to create as rich a post layout as they can imagine — as long as they know HTML and CSS and build a custom theme.
-Gutenberg reshapes the editor into tool that allows users write rich posts and build beautiful layouts in a few clicks — no technical knowledge needed. WordPress will become a powerful and flexible content tool that’s accessible to all.
+Gutenberg reshapes the editor into a tool that allows users write rich posts and build beautiful layouts in a few clicks — no technical knowledge needed. WordPress will become a powerful and flexible content tool that’s accessible to all.
### Vision
diff --git a/docs/contributors/document.md b/docs/contributors/document.md
index f51578d99e3c3..31f372bc865cf 100644
--- a/docs/contributors/document.md
+++ b/docs/contributors/document.md
@@ -15,7 +15,7 @@ To add a new documentation page:
It's very likely that at some point you will want to link to other documentation pages. It's worth emphasizing that all documents can be browsed in different contexts:
-- Gutenberg Handbook
+- Block Editor Handbook
- GitHub website
- npm website
diff --git a/docs/contributors/history.md b/docs/contributors/history.md
index b38aacc43ecce..a0f05a9cb446a 100644
--- a/docs/contributors/history.md
+++ b/docs/contributors/history.md
@@ -4,7 +4,7 @@
There was a survey done: [https://make.wordpress.org/core/2017/04/07/editor-experience-survey-results/](https://make.wordpress.org/core/2017/04/07/editor-experience-survey-results/)
## Inspiration
-This includes a list of historical articles and influences on Gutenberg.
+This includes a list of historical articles and influences on the Gutenberg project.
- LivingDocs: [https://beta.livingdocs.io/articles](https://beta.livingdocs.io/articles)
- Parrot: [https://intenseminimalism.com/2017/parrot-an-integrated-site-builder-and-editor-concept-for-wordpress/](https://intenseminimalism.com/2017/parrot-an-integrated-site-builder-and-editor-concept-for-wordpress/)
diff --git a/docs/contributors/localizing.md b/docs/contributors/localizing.md
index c5b22e675d51e..66d8df9568296 100644
--- a/docs/contributors/localizing.md
+++ b/docs/contributors/localizing.md
@@ -6,4 +6,4 @@ A Global Translation Editor (GTE) or Project Translation Editor (PTE) with suita
Language packs are automatically generated once 95% of the plugin's strings are translated and approved for a locale.
-The eventual inclusion of Gutenberg into WordPress core means that more than 51% of WordPress installations running a translated WordPress installation will have Gutenberg's translated strings compiled into the core language pack as well.
+The inclusion of Gutenberg into WordPress core means that more than 51% of WordPress installations running a translated WordPress installation have Gutenberg's translated strings compiled into the core language pack as well.
diff --git a/docs/contributors/principles.md b/docs/contributors/principles.md
index c7a63be051bbc..8acedac095826 100644
--- a/docs/contributors/principles.md
+++ b/docs/contributors/principles.md
@@ -1,6 +1,6 @@
# Principles
-First, let’s look at the big picture. If the architectural and UX principles described here are activated at scale, how will Gutenberg improve and transform both users and creators experiences?
+First, let’s look at the big picture. If the architectural and UX principles described here are activated at scale, how will the Gutenberg project improve and transform both users and creators experiences?
How Gutenberg can transform the *user experience*:
diff --git a/docs/designers-developers/designers/design-patterns.md b/docs/designers-developers/designers/design-patterns.md
index d6fa0fd30f1e6..bf06df6da5e9d 100644
--- a/docs/designers-developers/designers/design-patterns.md
+++ b/docs/designers-developers/designers/design-patterns.md
@@ -2,7 +2,7 @@
## Basic Editor Interface
-Gutenberg’s general layout uses on a bar at the top, with content below.
+The block editor’s general layout uses on a bar at the top, with content below.
![Editor Interface](https://cldup.com/VWA_jMcIRw-3000x3000.png)
@@ -22,7 +22,7 @@ A selected block shows a number of contextual actions:
![Block Interface](https://cldup.com/3tQqIncKPB-3000x3000.png)
-The block interface has basic actions. Gutenberg aims for good, common defaults, so users should be able to create a complete document without actually needing the advanced actions in the Settings Sidebar.
+The block interface has basic actions. The block editor aims for good, common defaults, so users should be able to create a complete document without actually needing the advanced actions in the Settings Sidebar.
**The Block Toolbar** highlights commonly-used actions. The **Block Chip** lives in the block toolbar, and contains high-level controls for the selected block. It primarily allows users to transform a block into another type of compatible block. Some blocks also use the block chip to users to choose from a set of alternate block styles.
diff --git a/docs/designers-developers/designers/design-resources.md b/docs/designers-developers/designers/design-resources.md
index a6abc870dba11..a6bad10ef02f9 100644
--- a/docs/designers-developers/designers/design-resources.md
+++ b/docs/designers-developers/designers/design-resources.md
@@ -1,6 +1,6 @@
# Resources
-The [SketchPress](https://github.com/10up/SketchPress) project includes a library of Gutenberg design components helpful for designing and prototyping Gutenberg and Gutenberg blocks:
+The [SketchPress](https://github.com/10up/SketchPress) project includes a library of Gutenberg design components helpful for designing and prototyping:
[Download Sketch mockups & patterns files](https://github.com/10up/SketchPress)
diff --git a/docs/designers-developers/developers/backward-compatibility/meta-box.md b/docs/designers-developers/developers/backward-compatibility/meta-box.md
index e7350dadba7fb..dc8ce593eb856 100644
--- a/docs/designers-developers/developers/backward-compatibility/meta-box.md
+++ b/docs/designers-developers/developers/backward-compatibility/meta-box.md
@@ -1,12 +1,12 @@
# Meta Boxes
-This is a brief document detailing how meta box support works in Gutenberg. With the superior developer and user experience of blocks, especially once block templates are available, **porting PHP meta boxes to blocks is highly encouraged!** See the [Meta Block tutorial](/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md) for how to store post meta data using blocks.
+This is a brief document detailing how meta box support works in the block editor. With the superior developer and user experience of blocks, especially once block templates are available, **porting PHP meta boxes to blocks is highly encouraged!** See the [Meta Block tutorial](/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md) for how to store post meta data using blocks.
### Testing, Converting, and Maintaining Existing Meta Boxes
-Before converting meta boxes to blocks, it may be easier to test if a meta box works with Gutenberg, and explicitly mark it as such.
+Before converting meta boxes to blocks, it may be easier to test if a meta box works with the block editor, and explicitly mark it as such.
-If a meta box *doesn't* work with in Gutenberg, and updating it to work correctly is not an option, the next step is to add the `__block_editor_compatible_meta_box` argument to the meta box declaration:
+If a meta box *doesn't* work with the block editor, and updating it to work correctly is not an option, the next step is to add the `__block_editor_compatible_meta_box` argument to the meta box declaration:
```php
add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
@@ -30,11 +30,11 @@ add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
);
```
-When Gutenberg is used, this meta box will no longer be displayed in the meta box area, as it now only exists for backward compatibility purposes. It will continue to display correctly in the classic editor.
+When the block editor is used, this meta box will no longer be displayed in the meta box area, as it now only exists for backward compatibility purposes. It will continue to display correctly in the classic editor.
### Meta Box Data Collection
-On each Gutenberg page load, we register an action that collects the meta box data to determine if an area is empty. The original global state is reset upon collection of meta box data.
+On each block editor page load, we register an action that collects the meta box data to determine if an area is empty. The original global state is reset upon collection of meta box data.
See [`register_and_do_post_meta_boxes`](https://developer.wordpress.org/reference/functions/register_and_do_post_meta_boxes/).
@@ -48,7 +48,7 @@ Ideally, this could be done at instantiation of the editor and help simplify thi
### Redux and React Meta Box Management
-When rendering the Gutenberg Page, the meta boxes are rendered to a hidden div `#metaboxes`.
+When rendering the block editor, the meta boxes are rendered to a hidden div `#metaboxes`.
*The Redux store will hold all meta boxes as inactive by default*. When
`INITIALIZE_META_BOX_STATE` comes in, the store will update any active meta box areas by setting the `isActive` flag to `true`. Once this happens React will check for the new props sent in by Redux on the `MetaBox` component. If that `MetaBox` is now active, instead of rendering null, a `MetaBoxArea` component will be rendered. The `MetaBox` component is the container component that mediates between the `MetaBoxArea` and the Redux Store. *If no meta boxes are active, nothing happens. This will be the default behavior, as all core meta boxes have been stripped.*
@@ -71,10 +71,10 @@ This page mimics the `post.php` post form, so when it is submitted it will fire
### Common Compatibility Issues
-Most PHP meta boxes should continue to work in Gutenberg, but some meta boxes that include advanced functionality could break. Here are some common reasons why meta boxes might not work as expected in Gutenberg:
+Most PHP meta boxes should continue to work in the block editor, but some meta boxes that include advanced functionality could break. Here are some common reasons why meta boxes might not work as expected in the block editor:
- Plugins relying on selectors that target the post title, post content fields, and other metaboxes (of the old editor).
-- Plugins relying on TinyMCE's API because there's no longer a single TinyMCE instance to talk to in Gutenberg.
+- Plugins relying on TinyMCE's API because there's no longer a single TinyMCE instance to talk to in the block editor.
- Plugins making updates to their DOM on "submit" or on "save".
Please also note that if your plugin triggers a PHP warning or notice to be output on the page, this will cause the HTML document type (``) to be output incorrectly. This will cause the browser to render using "Quirks Mode", which is a compatibility layer that gets enabled when the browser doesn't know what type of document it is parsing. The block editor is not meant to work in this mode, but it can _appear_ to be working just fine. If you encounter issues such as *meta boxes overlaying the editor* or other layout issues, please check the raw page source of your document to see that the document type definition is the first thing output on the page. There will also be a warning in the JavaScript console, noting the issue.
diff --git a/docs/designers-developers/developers/block-api/block-annotations.md b/docs/designers-developers/developers/block-api/block-annotations.md
index 70df5b61e5d18..85a523904fd49 100644
--- a/docs/designers-developers/developers/block-api/block-annotations.md
+++ b/docs/designers-developers/developers/block-api/block-annotations.md
@@ -2,7 +2,7 @@
**Note: This API is experimental, that means it is subject to non-backward compatible changes or removal in any future version.**
-Annotations are a way to highlight a specific piece in a Gutenberg post. Examples of this include commenting on a piece of text and spellchecking. Both can use the annotations API to mark a piece of text.
+Annotations are a way to highlight a specific piece in a post created with the block editor. Examples of this include commenting on a piece of text and spellchecking. Both can use the annotations API to mark a piece of text.
## API
diff --git a/docs/designers-developers/developers/block-api/block-deprecation.md b/docs/designers-developers/developers/block-api/block-deprecation.md
index 3e5533289cc23..795a5951b2fd0 100644
--- a/docs/designers-developers/developers/block-api/block-deprecation.md
+++ b/docs/designers-developers/developers/block-api/block-deprecation.md
@@ -3,7 +3,7 @@
When updating static blocks markup and attributes, block authors need to consider existing posts using the old versions of their block. In order to provide a good upgrade path, you can choose one of the following strategies:
- Do not deprecate the block and create a new one (a different name)
- - Provide a "deprecated" version of the block allowing users opening these blocks in Gutenberg to edit them using the updated block.
+ - Provide a "deprecated" version of the block allowing users opening these in the block editor to edit them using the updated block.
A block can have several deprecated versions. A deprecation will be tried if a parsed block appears to be invalid, or if there is a deprecation defined for which its `isEligible` property function returns true.
diff --git a/docs/designers-developers/developers/block-api/block-edit-save.md b/docs/designers-developers/developers/block-api/block-edit-save.md
index fc69abc553e9f..362bc08e6bcce 100644
--- a/docs/designers-developers/developers/block-api/block-edit-save.md
+++ b/docs/designers-developers/developers/block-api/block-edit-save.md
@@ -197,11 +197,11 @@ const addListItem = ( newListItem ) => {
```
{% end %}
-Why do this? In JavaScript, arrays and objects are passed by reference, so this practice ensures changes won't affect other code that might hold references to the same data. Furthermore, Gutenberg follows the philosophy of the Redux library that [state should be immutable](https://redux.js.org/faq/immutable-data#what-are-the-benefits-of-immutability)—data should not be changed directly, but instead a new version of the data created containing the changes.
+Why do this? In JavaScript, arrays and objects are passed by reference, so this practice ensures changes won't affect other code that might hold references to the same data. Furthermore, the Gutenberg project follows the philosophy of the Redux library that [state should be immutable](https://redux.js.org/faq/immutable-data#what-are-the-benefits-of-immutability)—data should not be changed directly, but instead a new version of the data created containing the changes.
## Save
-The `save` function defines the way in which the different attributes should be combined into the final markup, which is then serialized by Gutenberg into `post_content`.
+The `save` function defines the way in which the different attributes should be combined into the final markup, which is then serialized into `post_content`.
{% codetabs %}
{% ES5 %}
diff --git a/docs/designers-developers/developers/block-api/block-registration.md b/docs/designers-developers/developers/block-api/block-registration.md
index c78263ed6cbb1..8a2d6c26a7dab 100644
--- a/docs/designers-developers/developers/block-api/block-registration.md
+++ b/docs/designers-developers/developers/block-api/block-registration.md
@@ -546,21 +546,21 @@ anchor: true,
customClassName: false,
```
-- `className` (default `true`): By default, Gutenberg adds a class with the form `.wp-block-your-block-name` to the root element of your saved markup. This helps having a consistent mechanism for styling blocks that themes and plugins can rely on. If for whatever reason a class is not desired on the markup, this functionality can be disabled.
+- `className` (default `true`): By default, the class `.wp-block-your-block-name` is added to the root element of your saved markup. This helps having a consistent mechanism for styling blocks that themes and plugins can rely on. If for whatever reason a class is not desired on the markup, this functionality can be disabled.
```js
// Remove the support for the generated className.
className: false,
```
-- `html` (default `true`): By default, Gutenberg will allow a block's markup to be edited individually. To disable this behavior, set `html` to `false`.
+- `html` (default `true`): By default, a block's markup can be edited individually. To disable this behavior, set `html` to `false`.
```js
// Remove support for an HTML mode.
html: false,
```
-- `inserter` (default `true`): By default, all blocks will appear in the Gutenberg inserter. To hide a block so that it can only be inserted programmatically, set `inserter` to `false`.
+- `inserter` (default `true`): By default, all blocks will appear in the inserter. To hide a block so that it can only be inserted programmatically, set `inserter` to `false`.
```js
// Hide this block from the inserter.
diff --git a/docs/designers-developers/developers/data/data-core-annotations.md b/docs/designers-developers/developers/data/data-core-annotations.md
index 0aaf9963ba48a..e71aefd27d212 100644
--- a/docs/designers-developers/developers/data/data-core-annotations.md
+++ b/docs/designers-developers/developers/data/data-core-annotations.md
@@ -1,8 +1,20 @@
-# **core/annotations**: Annotations
+# Annotations
+
+Namespace: `core/annotations`.
## Selectors
+
+
+Nothing to document.
+
+
## Actions
+
+
+Nothing to document.
+
+
diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md
index d152b4475f8b2..380b3366a64e0 100644
--- a/docs/designers-developers/developers/data/data-core-block-editor.md
+++ b/docs/designers-developers/developers/data/data-core-block-editor.md
@@ -1,8 +1,86 @@
-# **core/block-editor**: The Block Editor’s Data
+# The Block Editor’s Data
+
+Namespace: `core/block-editor`.
## Selectors
-### getBlockDependantsCacheBust
+
+
+# **canInsertBlockType**
+
+Determines if the given block type is allowed to be inserted into the block list.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _blockName_ `string`: The name of the block type, e.g.' core/paragraph'.
+- _rootClientId_ `?string`: Optional root client ID of block list.
+
+_Returns_
+
+- `boolean`: Whether the given block type is allowed to be inserted.
+
+# **getAdjacentBlockClientId**
+
+Returns the client ID of the block adjacent one at the given reference
+startClientId and modifier directionality. Defaults start startClientId to
+the selected block, and direction as next block. Returns null if there is no
+adjacent block.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _startClientId_ `?string`: Optional client ID of block from which to search.
+- _modifier_ `?number`: Directionality multiplier (1 next, -1 previous).
+
+_Returns_
+
+- `?string`: Return the client ID of the block, or null if none exists.
+
+# **getBlock**
+
+Returns a block given its client ID. This is a parsed copy of the block,
+containing its `blockName`, `clientId`, and current `attributes` state. This
+is not the block's registration settings, which must be retrieved from the
+blocks module registration store.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block client ID.
+
+_Returns_
+
+- `Object`: Parsed block object.
+
+# **getBlockAttributes**
+
+Returns a block's attributes given its client ID, or null if no block exists with
+the client ID.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block client ID.
+
+_Returns_
+
+- `?Object`: Block attributes.
+
+# **getBlockCount**
+
+Returns the number of blocks currently present in the post.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _rootClientId_ `?string`: Optional root client ID of block list.
+
+_Returns_
+
+- `number`: Number of blocks in the post.
+
+# **getBlockDependantsCacheBust**
Returns a new reference when the inner blocks of a given block client ID
change. This is used exclusively as a memoized selector dependant, relying
@@ -11,69 +89,128 @@ blocks defined as dependencies. This abuses mechanics of the selector
memoization to return from the original selector function only when
dependants change.
-*Parameters*
+_Parameters_
- * state: Editor state.
- * clientId: Block client ID.
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block client ID.
-### getBlockName
+_Returns_
-Returns a block's name given its client ID, or null if no block exists with
-the client ID.
+- `*`: A value whose reference will change only when inner blocks of the given block client ID change.
-*Parameters*
+# **getBlockHierarchyRootClientId**
- * state: Editor state.
- * clientId: Block client ID.
+Given a block client ID, returns the root of the hierarchy from which the block is nested, return the block itself for root level blocks.
-*Returns*
+_Parameters_
-Block name.
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block from which to find root client ID.
-### isBlockValid
+_Returns_
-Returns whether a block is valid or not.
+- `string`: Root client ID
+
+# **getBlockIndex**
-*Parameters*
+Returns the index at which the block corresponding to the specified client
+ID occurs within the block order, or `-1` if the block does not exist.
- * state: Editor state.
- * clientId: Block client ID.
+_Parameters_
-*Returns*
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block client ID.
+- _rootClientId_ `?string`: Optional root client ID of block list.
-Is Valid.
+_Returns_
-### getBlockAttributes
+- `number`: Index at which block exists in order.
-Returns a block's attributes given its client ID, or null if no block exists with
+# **getBlockInsertionPoint**
+
+Returns the insertion point, the index at which the new inserted block would
+be placed. Defaults to the last index.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+
+_Returns_
+
+- `Object`: Insertion point object with `rootClientId`, `index`.
+
+# **getBlockListSettings**
+
+Returns the Block List settings of a block, if any exist.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _clientId_ `?string`: Block client ID.
+
+_Returns_
+
+- `?Object`: Block settings of the block if set.
+
+# **getBlockMode**
+
+Returns the block's editing mode, defaulting to "visual" if not explicitly
+assigned.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block client ID.
+
+_Returns_
+
+- `Object`: Block editing mode.
+
+# **getBlockName**
+
+Returns a block's name given its client ID, or null if no block exists with
the client ID.
-*Parameters*
+_Parameters_
- * state: Editor state.
- * clientId: Block client ID.
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block client ID.
-*Returns*
+_Returns_
-Block attributes.
+- `string`: Block name.
-### getBlock
+# **getBlockOrder**
-Returns a block given its client ID. This is a parsed copy of the block,
-containing its `blockName`, `clientId`, and current `attributes` state. This
-is not the block's registration settings, which must be retrieved from the
-blocks module registration store.
+Returns an array containing all block client IDs in the editor in the order
+they appear. Optionally accepts a root client ID of the block list for which
+the order should be returned, defaulting to the top-level block order.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _rootClientId_ `?string`: Optional root client ID of block list.
-*Parameters*
+_Returns_
- * state: Editor state.
- * clientId: Block client ID.
+- `Array`: Ordered client IDs of editor blocks.
-*Returns*
+# **getBlockRootClientId**
-Parsed block object.
+Given a block client ID, returns the root block from which the block is
+nested, an empty string for top-level blocks, or null if the block does not
+exist.
+
+_Parameters_
+
+- _state_ `Object`: Editor state.
+- _clientId_ `string`: Block from which to find root client ID.
+
+_Returns_
-### getBlocks
+- `?string`: Root client ID, if exists
+
+# **getBlocks**
Returns all block objects for the current post being edited as an array in
the order they appear in the post.
@@ -81,1017 +218,1010 @@ the order they appear in the post.
Note: It's important to memoize this selector to avoid return a new instance
on each call
-*Parameters*
+_Parameters_
- * state: Editor state.
- * rootClientId: Optional root client ID of block list.
+- _state_ `Object`: Editor state.
+- _rootClientId_ `?String`: Optional root client ID of block list.
-*Returns*
+_Returns_
-Post blocks.
+- `Array