Merge master

.travis.yml

@@ -19,11 +19,6 @@ cache:
     - $HOME/.npm
 
 before_install:
-  - |
-    git diff --name-only $TRAVIS_COMMIT_RANGE | grep -qvE '(\.md$)' || {
-      echo "Only docs were updated, stopping build process."
-      exit
-    }
   - nvm install && nvm use
   - npm install npm -g
 

CONTRIBUTING.md

@@ -104,11 +104,11 @@ For example, `add/gallery-block` means you're working on adding a new gallery bl
 
 You can pick among all the <a href="https://github.com/WordPress/gutenberg/issues">tickets</a>, or some of the ones labelled <a href="https://github.com/WordPress/gutenberg/labels/Good%20First%20Issue">Good First Issue</a>.
 
-The workflow is documented in greater detail in the [repository management](./docs/reference/repository-management.md) document.
+The workflow is documented in greater detail in the [repository management](./docs/contributors/repository-management.md) document.
 
 ## Testing
 
-Gutenberg contains both PHP and JavaScript code, and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](./docs/reference/testing-overview.md).
+Gutenberg contains both PHP and JavaScript code, and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](./docs/contributors/testing-overview.md).
 
 ## Managing packages
 
@@ -238,7 +238,7 @@ Choose the correct version based on `CHANGELOG.md` files, confirm your choices a
 
 ## How Designers Can Contribute
 
-If you'd like to contribute to the design or front-end, feel free to contribute to tickets labelled <a href="https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3ADesign">Design</a>. We could use your thoughtful replies, mockups, animatics, sketches, doodles. Proposed changes are best done as minimal and specific iterations on the work that precedes it so we can compare. If you use <a href="https://www.sketchapp.com/">Sketch</a>, you can grab <a href="https://cloudup.com/cMPXM8Va2cy">the source file for the mockups</a> (updated April 6th).
+If you'd like to contribute to the design or front-end, feel free to contribute to tickets labelled [Needs Design](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Design%22) or [Needs Design Feedback](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3A"Needs+Design+Feedback%22). We could use your thoughtful replies, mockups, animatics, sketches, doodles. Proposed changes are best done as minimal and specific iterations on the work that precedes it so we can compare. If you use <a href="https://www.sketchapp.com/">Sketch</a>, you can grab <a href="https://cloudup.com/cMPXM8Va2cy">the source file for the mockups</a> (updated April 6th).
 
 ## Contribute to the Documentation
 

CONTRIBUTORS.md

@@ -119,3 +119,5 @@ This list is manually curated to include valuable contributions by volunteers th
 | @luehrsen | @luehrsen |
 | @getsource | @mikeschroder |
 | @greatislander | @greatislander |
+| @sharazghouri | @sharaz |
+| @jakeparis | |

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" />

docs/reference/scripts.md → docs/contributors/scripts.md

@@ -50,13 +50,12 @@ The editor also uses some popular third-party packages and scripts. Plugin devel
 | [React](https://reactjs.org) | react  | React is a JavaScript library for building user interfaces |
 | [React Dom](https://reactjs.org/docs/react-dom.html) | react-dom | Serves as the entry point to the DOM and server renderers for React, intended to be paired with React |
 | [Moment](https://momentjs.com/) | moment| Parse, validate, manipulate, and display dates and times in JavaScript |
-| [TinyMCE Lists](https://www.tiny.cloud/docs/plugins/lists/) | tinymce-latest-lists| The `lists` plugin allows you to add numbered and bulleted lists to TinyMCE |
 | [Lodash](https://lodash.com) | lodash| Lodash is a JavaScript library which provides utility functions for common programming tasks |
 
 ## Polyfill Scripts
 
 The editor also provides polyfills for certain features that may not be available in all modern browsers.
-It is recommened to use the main `wp-polyfill` script handle which takes care of loading all the below mentioned polyfills.  
+It is recommened to use the main `wp-polyfill` script handle which takes care of loading all the below mentioned polyfills.
 
 | Script Name | Handle | Description |
 |-------------|--------|-------------|

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.

docs/design/block-design.md → docs/designers-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.
 

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.

docs/designers-developers/developers/backwards-compatibility/README.md

@@ -0,0 +1 @@
+# Backwards Compatibility

docs/reference/deprecated.md → docs/designers-developers/developers/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

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).

docs/block-api/deprecated-blocks.md → docs/designers-developers/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.