Reorganise documentation (#11817)

* Initial reworking; props @0aveRyan * Fixes for the manifest/generators * A few missed items and small formatting tweaks * Simplify/flatten the directory structure * Cheat my way around a merge conflict pt1 * fight the git powers * JSON version of TOC instead of YML * Ensure all files have good titles * Add a generator script and re-generate the root-manifest * Update docs/designers-developers/designers/block-design.md Co-Authored-By: chrisvanpatten <[email protected]> * Update docs/designers-developers/key-concepts.md Co-Authored-By: chrisvanpatten <[email protected]> * Get a handful of internal link references fixed * Another batch of internal links * Update docs/tool/manifest.js Co-Authored-By: chrisvanpatten <[email protected]> * Additional broken internal link fixes * A few more links * Revert use of lt/gt symbols in link * Fix more broken internal links * Remove docs generator * Broken manifest.json
WordPress · Nov 20, 2018 · c77cf74 · c77cf74
1 parent 5a8c012
commit c77cf74
Show file tree

Hide file tree

Showing 84 changed files with 634 additions and 674 deletions.
diff --git a/docs/reference/coding-guidelines.md → docs/contributors/coding-guidelines.md b/docs/reference/coding-guidelines.md → docs/contributors/coding-guidelines.md
diff --git a/docs/reference/copy-guide.md → docs/contributors/copy-guide.md b/docs/reference/copy-guide.md → docs/contributors/copy-guide.md
diff --git a/docs/design.md → docs/contributors/design.md b/docs/design.md → docs/contributors/design.md
diff --git a/docs/grammar.md → docs/contributors/grammar.md b/docs/grammar.md → docs/contributors/grammar.md
diff --git a/docs/reference/history.md → docs/contributors/history.md b/docs/reference/history.md → docs/contributors/history.md
diff --git a/docs/outreach.md → docs/contributors/outreach.md b/docs/outreach.md → docs/contributors/outreach.md
diff --git a/docs/outreach/articles.md → docs/contributors/outreach/articles.md b/docs/outreach/articles.md → docs/contributors/outreach/articles.md
diff --git a/docs/outreach/meetups.md → docs/contributors/outreach/meetups.md b/docs/outreach/meetups.md → docs/contributors/outreach/meetups.md
diff --git a/docs/outreach/resources.md → docs/contributors/outreach/resources.md b/docs/outreach/resources.md → docs/contributors/outreach/resources.md
diff --git a/docs/outreach/talks.md → docs/contributors/outreach/talks.md b/docs/outreach/talks.md → docs/contributors/outreach/talks.md
diff --git a/docs/principles.md → docs/contributors/principles.md b/docs/principles.md → docs/contributors/principles.md
diff --git a/docs/principles/the-block.md → docs/contributors/principles/the-block.md b/docs/principles/the-block.md → docs/contributors/principles/the-block.md
diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
diff --git a/docs/reference.md → docs/contributors/reference.md b/docs/reference.md → docs/contributors/reference.md
@@ -1,9 +1,9 @@
 # Reference
 
-- [Glossary](../docs/reference/glossary.md)
-- [Coding Guidelines](../docs/reference/coding-guidelines.md)
-- [Testing Overview](../docs/reference/testing-overview.md)
-- [Frequently Asked Questions](../docs/reference/faq.md)
+- [Glossary](../../docs/designers-developers/glossary.md)
+- [Coding Guidelines](../../docs/contributors/coding-guidelines.md)
+- [Testing Overview](../../docs/contributors/testing-overview.md)
+- [Frequently Asked Questions](../../docs/designers-developers/faq.md)
 
 ## Logo
 <img width="200" src="https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/final-g-wapuu-black.svg?sanitize=true" alt="Gutenberg Logo" />

diff --git a/docs/reference/release-screenshot.png → docs/contributors/release-screenshot.png b/docs/reference/release-screenshot.png → docs/contributors/release-screenshot.png
diff --git a/docs/reference/release.md → docs/contributors/release.md b/docs/reference/release.md → docs/contributors/release.md
diff --git a/docs/reference/repository-management.md → docs/contributors/repository-management.md b/docs/reference/repository-management.md → docs/contributors/repository-management.md
diff --git a/docs/reference/scripts.md → docs/contributors/scripts.md b/docs/reference/scripts.md → docs/contributors/scripts.md
diff --git a/docs/reference/testing-overview.md → docs/contributors/testing-overview.md b/docs/reference/testing-overview.md → docs/contributors/testing-overview.md
diff --git a/docs/data/README.md b/docs/data/README.md
diff --git a/docs/designers-developers/designers/README.md b/docs/designers-developers/designers/README.md
@@ -0,0 +1,3 @@
+# Designer Documentation
+
+For those designing blocks and other Block Editor integrations, this documentation will provide resources for creating beautiful and intuitive layouts.
diff --git a/docs/design/advanced-settings-do.png → ...designers/assets/advanced-settings-do.png b/docs/design/advanced-settings-do.png → ...designers/assets/advanced-settings-do.png
diff --git a/docs/design/block-controls-do.png → ...rs/designers/assets/block-controls-do.png b/docs/design/block-controls-do.png → ...rs/designers/assets/block-controls-do.png
diff --git a/docs/design/block-controls-dont.png → .../designers/assets/block-controls-dont.png b/docs/design/block-controls-dont.png → .../designers/assets/block-controls-dont.png
diff --git a/docs/design/block-descriptions-do.png → ...esigners/assets/block-descriptions-do.png b/docs/design/block-descriptions-do.png → ...esigners/assets/block-descriptions-do.png
diff --git a/docs/design/block-descriptions-dont.png → ...igners/assets/block-descriptions-dont.png b/docs/design/block-descriptions-dont.png → ...igners/assets/block-descriptions-dont.png
diff --git a/docs/design/blocks-do.png → ...developers/designers/assets/blocks-do.png b/docs/design/blocks-do.png → ...developers/designers/assets/blocks-do.png
diff --git a/docs/design/blocks-dont.png → ...velopers/designers/assets/blocks-dont.png b/docs/design/blocks-dont.png → ...velopers/designers/assets/blocks-dont.png
diff --git a/docs/design/placeholder-do.png → ...opers/designers/assets/placeholder-do.png b/docs/design/placeholder-do.png → ...opers/designers/assets/placeholder-do.png
diff --git a/docs/design/placeholder-dont.png → ...ers/designers/assets/placeholder-dont.png b/docs/design/placeholder-dont.png → ...ers/designers/assets/placeholder-dont.png
diff --git a/docs/design/block-design.md → ...ners-developers/designers/block-design.md b/docs/design/block-design.md → ...ners-developers/designers/block-design.md
@@ -27,39 +27,35 @@ A block should have a straightforward, short name so users can easily find it in
 
 Blocks should have an identifying icon, ideally using a single color. Try to avoid using the same icon used by an existing block. The core block icons are based on [Material Design Icons](https://material.io/tools/icons/). Look to that icon set, or to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration.
 
-![A screenshot of the Block Library with concise block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/blocks-do.png)
-
+![A screenshot of the Block Library with concise block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/blocks-do.png)
 **Do:**
 Use concise block names.
 
-![A screenshot of the Block Library with long, multi-line block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/blocks-dont.png)
-
+![A screenshot of the Block Library with long, multi-line block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/blocks-dont.png)
 **Don't:**
 Avoid long, multi-line block names.
 
 ### Block Description
 
 Every block should include a description in the “Block” tab of the Settings sidebar. This description should explain your block's function clearly. Keep it to a single sentence.
 
-![A screenshot of a short block description](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-descriptions-do.png)
-
+![A screenshot of a short block description](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-descriptions-do.png)
 **Do:**
 Use a short, simple, block description.
 
-![A screenshot of a long block description that includes branding](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-descriptions-dont.png)
-
+![A screenshot of a long block description that includes branding](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-descriptions-dont.png)
 **Don't:**
 Avoid long descriptions and branding.
 
 ### Placeholders
 
 If your block requires a user to configure some options before you can display it, you should provide an instructive placeholder state.
 
-![A screenshot of the Gallery block's placeholder](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/placeholder-do.png)
+![A screenshot of the Gallery block's placeholder](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/placeholder-do.png)
 **Do:**
 Provide an instructive placeholder state.
 
-![An example Gallery block placeholder but with intense, distracting colors and no instructions](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/placeholder-dont.png)
+![An example Gallery block placeholder but with intense, distracting colors and no instructions](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/placeholder-dont.png)
 **Don't:**
 Avoid branding and relying on the title alone to convey instructions.
 
@@ -69,19 +65,19 @@ When unselected, your block should preview its content as closely to the front-e
 
 When selected, your block may surface additional options like input fields or buttons to configure the block directly, especially when they are necessary for basic operation.
 
-![A Google Maps block with inline, always-accessible controls required for the block to function](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-controls-do.png)
+![A Google Maps block with inline, always-accessible controls required for the block to function](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-controls-do.png)
 **Do:**
 For controls that are essential the the operation of the block, provide them directly in inside the block edit view.
 
-![A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-controls-dont.png)
+![A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-controls-dont.png)
 **Don't:**
 Do not put controls that are essential to the block in the sidebar, or the block will appear non-functional to mobile users, or desktop users who have dismissed the sidebar.
 
 ### Advanced Block Settings
 
 The “Block” tab of the Settings Sidebar can contain additional block options and configuration. Keep in mind that a user can dismiss the sidebar and never use it. You should not put critical options in the Sidebar.
 
-![A screenshot of the paragraph block's advanced settings in the sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/advanced-settings-do.png)
+![A screenshot of the paragraph block's advanced settings in the sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/advanced-settings-do.png)
 **Do:**
 Because the Drop Cap feature is not necessary for the basic operation of the block, you can put it ub the Block tab as optional configuration.
 

diff --git a/docs/design/design-patterns.md → ...s-developers/designers/design-patterns.md b/docs/design/design-patterns.md → ...s-developers/designers/design-patterns.md
diff --git a/docs/design/design-resources.md → ...-developers/designers/design-resources.md b/docs/design/design-resources.md → ...-developers/designers/design-resources.md
diff --git a/docs/designers-developers/developers/README.md b/docs/designers-developers/developers/README.md
@@ -0,0 +1,45 @@
+# Developer Documentation
+
+Gutenberg is highly flexible, like most of WordPress. You can build custom blocks, modify the editor's appearance, add special plugins, and much more.
+
+## Creating Blocks
+
+Gutenberg is about blocks, and the main extensibility API of Gutenberg is the Block API. It allows you to create your own static blocks, dynamic blocks rendered on the server and also blocks capable of saving data to Post Meta for more structured content.
+
+If you want to learn more about block creation, the [Blocks Tutorial](../../../docs/designers-developers/developers/tutorials/block-tutorial/intro.md) is the best place to start.
+
+## Extending Blocks
+
+It is also possible to modify the behavior of existing blocks or even remove them completely using filters.
+
+Learn more in the [Block Filters](../../../docs/designers-developers/developers/reference/hooks/block-filters.md) section.
+
+## Extending the Editor UI
+
+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](https://github.com/WordPress/gutenberg/blob/master/packages/plugins/README.md) and [Edit Post](https://github.com/WordPress/gutenberg/blob/master/packages/edit-post/README.md) section for more information.
+
+You can also filter certain aspects of the editor; this is documented on the [Editor Filters](../../../docs/designers-developers/developers/reference/hooks/editor-filters.md) page.
+
+## Meta Boxes
+
+**Porting PHP meta boxes to blocks and Gutenberg plugins is highly encouraged!**
+
+Discover how [Meta Box](../../../docs/designers-developers/developers/backwards-compatibility/meta-box.md) support works in Gutenberg.
+
+## Theme Support
+
+By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults.
+
+There are some advanced block features which require opt-in support in the theme. See [theme support](../../../docs/designers-developers/developers/themes/theme-support.md).
+
+## Autocomplete
+
+Autocompleters within blocks may be extended and overridden. Learn more about the [autocomplete](../../../docs/designers-developers/developers/filters/autocomplete-filters.md) filters.
+
+## Block Parsing and Serialization
+
+Posts in the editor move through a couple of different stages between being stored in `post_content` and appearing in the editor. Since the blocks themselves are data structures that live in memory it takes a parsing and serialization step to transform out from and into the stored format in the database.
+
+Customizing the parser is an advanced topic that you can learn more about in the [Extending the Parser](../../../docs/designers-developers/developers/filters/parser-filters.md) section.
diff --git a/docs/designers-developers/developers/backwards-compatibility/README.md b/docs/designers-developers/developers/backwards-compatibility/README.md
@@ -0,0 +1 @@
+# Backwards Compatibility
diff --git a/docs/reference/deprecated.md → ...s/backwards-compatibility/deprecations.md b/docs/reference/deprecated.md → ...s/backwards-compatibility/deprecations.md
@@ -1,3 +1,5 @@
+# Deprecations
+
 Gutenberg's deprecation policy is intended to support backwards-compatibility for releases, when possible. The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.
 
 ## 4.5.0

diff --git a/docs/extensibility/meta-box.md → ...opers/backwards-compatibility/meta-box.md b/docs/extensibility/meta-box.md → ...opers/backwards-compatibility/meta-box.md
diff --git a/docs/designers-developers/developers/block-api/README.md b/docs/designers-developers/developers/block-api/README.md
@@ -0,0 +1,11 @@
+# Block API Reference
+
+Blocks are the fundamental element of the Gutenberg editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor.
+
+## Registering a block
+
+All blocks must be registered before they can be used in the editor. You can learn about block registration, and the available options, in the [block registration](block-api/block-registration.md) documentation.
+
+## Block `edit` and `save`
+
+The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](block-api/block-edit-save.md).
diff --git a/docs/extensibility/annotations.md → ...developers/block-api/block-annotations.md b/docs/extensibility/annotations.md → ...developers/block-api/block-annotations.md
diff --git a/docs/block-api/attributes.md → .../developers/block-api/block-attributes.md b/docs/block-api/attributes.md → .../developers/block-api/block-attributes.md
diff --git a/docs/block-api/deprecated-blocks.md → ...developers/block-api/block-deprecation.md b/docs/block-api/deprecated-blocks.md → ...developers/block-api/block-deprecation.md
@@ -9,9 +9,9 @@ A block can have several deprecated versions. A deprecation will be tried if a p
 
 Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form:
 
-- `attributes` (Object): The [attributes definition](../docs/block-api/attributes.md) of the deprecated form of the block.
-- `support` (Object): The [supports definition](../docs/block-api.md) of the deprecated form of the block.
-- `save` (Function): The [save implementation](../docs/block-api/block-edit-save.md) of the deprecated form of the block.
+- `attributes` (Object): The [attributes definition](../../../../docs/designers-developers/developers/block-api/block-attributes.md) of the deprecated form of the block.
+- `support` (Object): The [supports definition](../../../../docs/designers-developers/developers/block-api/block-registration.md) of the deprecated form of the block.
+- `save` (Function): The [save implementation](../../../../docs/designers-developers/developers/block-api/block-edit-save.md) of the deprecated form of the block.
 - `migrate` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, is expected to return either the attributes compatible with the deprecated block, or a tuple array of `[ attributes, innerBlocks ]`.
 - `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration. This is particularly useful in cases where a block is technically valid even once deprecated, and requires updates to its attributes or inner blocks.
 

diff --git a/docs/block-api/block-edit-save.md → ...s/developers/block-api/block-edit-save.md b/docs/block-api/block-edit-save.md → ...s/developers/block-api/block-edit-save.md
@@ -103,7 +103,7 @@ For most blocks, the return value of `save` should be an [instance of WordPress
 
 _Note:_ While it is possible to return a string value from `save`, it _will be escaped_. If the string includes HTML markup, the markup will be shown on the front of the site verbatim, not as the equivalent HTML node content. If you must return raw HTML from `save`, use `wp.element.RawHTML`. As the name implies, this is prone to [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) and therefore is discouraged in favor of a WordPress Element hierarchy whenever possible.
 
-For [dynamic blocks](../../docs/blocks/creating-dynamic-blocks.md), the return value of `save` could either represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. Alternatively, return a `null` (empty) value to save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site.
+For [dynamic blocks](../../../../docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md), the return value of `save` could either represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. Alternatively, return a `null` (empty) value to save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site.
 
 ### attributes
 
@@ -153,10 +153,10 @@ The two most common sources of block invalidations are:
 
 Before starting to debug, be sure to familiarize yourself with the validation step described above documenting the process for detecting whether a block is invalid. A block is invalid if its regenerated markup does not match what is saved in post content, so often this can be caused by the attributes of a block being parsed incorrectly from the saved content.
 
-If you're using [attribute sources](../../docs/block-api/attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`).
+If you're using [attribute sources](../../../../docs/designers-developers/developers/block-api/block-attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`).
 
 When a block is detected as invalid, a warning will be logged into your browser's developer tools console. The warning will include specific details about the exact point at which a difference in markup occurred. Be sure to look closely at any differences in the expected and actual markups to see where problems are occurring.
 
 **I've changed my block's `save` behavior and old content now includes invalid blocks. How can I fix this?**
 
-Refer to the guide on [Deprecated Blocks](../../docs/block-api/deprecated-blocks.md) to learn more about how to accommodate legacy content in intentional markup changes.
+Refer to the guide on [Deprecated Blocks](../../../../docs/designers-developers/developers/block-api/block-deprecations.md) to learn more about how to accommodate legacy content in intentional markup changes.
diff --git a/docs/block-api.md → ...evelopers/block-api/block-registration.md b/docs/block-api.md → ...evelopers/block-api/block-registration.md
@@ -1,8 +1,6 @@
-# Block API
+# Block Registration 
 
-Blocks are the fundamental element of the Gutenberg editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor. This document covers the main properties of block registration.
-
-## Register Block Type
+## `register_block_type`
 
 * **Type:** `Function`
 
@@ -466,6 +464,8 @@ parent: [ 'core/columns' ],
 
 #### supports (optional)
 
+*Some [block supports](#supports-optional) — for example, `anchor` or `className` — apply their attributes by adding additional props on the element returned by `save`. This will work automatically for default HTML tag elements (`div`, etc). However, if the return value of your `save` is a custom component element, you will need to ensure that your custom component handles these props in order for the attributes to be persisted.*
+
 * **Type:** `Object`
 
 Optional block extended support features. The following options are supported:
@@ -548,8 +548,4 @@ By default all blocks can be converted to a reusable block. If supports reusable
 // Don't allow the block to be converted into a reusable block.
 reusable: false,
 ```
-## Edit and Save
 
-The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](../docs/block-api/block-edit-save.md).
-
-*Some [block supports](#supports-optional) — for example, `anchor` or `className` — apply their attributes by adding additional props on the element returned by `save`. This will work automatically for default HTML tag elements (`div`, etc). However, if the return value of your `save` is a custom component element, you will need to ensure that your custom component handles these props in order for the attributes to be persisted.*
diff --git a/docs/templates.md → ...s/developers/block-api/block-templates.md b/docs/templates.md → ...s/developers/block-api/block-templates.md
diff --git a/docs/designers-developers/developers/data/README.md b/docs/designers-developers/developers/data/README.md
@@ -0,0 +1,10 @@
+# Data Module Reference
+
+ - [**core**: WordPress Core Data](../../docs/designers-developers/developers/data/data-core.md)
+ - [**core/annotations**: Annotations](../../docs/designers-developers/developers/data/data-core-annotations.md)
+ - [**core/blocks**: Block Types Data](../../docs/designers-developers/developers/data/data-core-blocks.md)
+ - [**core/editor**: The Editor’s Data](../../docs/designers-developers/developers/data/data-core-editor.md)
+ - [**core/edit-post**: The Editor’s UI Data](../../docs/designers-developers/developers/data/data-core-edit-post.md)
+ - [**core/notices**: Notices Data](../../docs/designers-developers/developers/data/data-core-notices.md)
+ - [**core/nux**: The NUX (New User Experience) Data](../../docs/designers-developers/developers/data/data-core-nux.md)
+ - [**core/viewport**: The Viewport Data](../../docs/designers-developers/developers/data/data-core-viewport.md)
diff --git a/docs/data/data-core-annotations.md → .../developers/data/data-core-annotations.md b/docs/data/data-core-annotations.md → .../developers/data/data-core-annotations.md
diff --git a/docs/data/data-core-blocks.md → ...opers/developers/data/data-core-blocks.md b/docs/data/data-core-blocks.md → ...opers/developers/data/data-core-blocks.md
diff --git a/docs/data/data-core-edit-post.md → ...rs/developers/data/data-core-edit-post.md b/docs/data/data-core-edit-post.md → ...rs/developers/data/data-core-edit-post.md
diff --git a/docs/data/data-core-editor.md → ...opers/developers/data/data-core-editor.md b/docs/data/data-core-editor.md → ...opers/developers/data/data-core-editor.md
diff --git a/docs/data/data-core-notices.md → ...pers/developers/data/data-core-notices.md b/docs/data/data-core-notices.md → ...pers/developers/data/data-core-notices.md
diff --git a/docs/data/data-core-nux.md → ...velopers/developers/data/data-core-nux.md b/docs/data/data-core-nux.md → ...velopers/developers/data/data-core-nux.md
diff --git a/docs/data/data-core-viewport.md → ...ers/developers/data/data-core-viewport.md b/docs/data/data-core-viewport.md → ...ers/developers/data/data-core-viewport.md
diff --git a/docs/data/data-core.md → ...s-developers/developers/data/data-core.md b/docs/data/data-core.md → ...s-developers/developers/data/data-core.md
diff --git a/docs/designers-developers/developers/filters/README.md b/docs/designers-developers/developers/filters/README.md
@@ -0,0 +1,7 @@
+# Filter Reference
+
+[Hooks](https://developer.wordpress.org/plugins/hooks/) are a way for one piece of code to interact/modify another piece of code. They provide one way for plugins and themes interact with Gutenberg, but they’re also used extensively by WordPress Core itself.
+
+There are two types of hooks: [Actions](https://developer.wordpress.org/plugins/hooks/actions/) and [Filters](https://developer.wordpress.org/plugins/hooks/filters/). In addition to PHP actions and filters, Gutenberg also provides a mechanism for registering and executing hooks in JavaScript. This functionality is also available on npm as the [@wordpress/hooks](https://www.npmjs.com/package/@wordpress/hooks) package, for general purpose use.
+
+You can also learn more about both APIs: [PHP](https://codex.wordpress.org/Plugin_API/) and [JavaScript](https://github.com/WordPress/packages/tree/master/packages/hooks).