From d51b5ee95cad98892fd91bcab5e1e6755453d29e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 2 Aug 2018 09:47:33 +0200
Subject: [PATCH] Add docs

---
 edit-post/README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/edit-post/README.md b/edit-post/README.md
index af78b310c4fd76..f03ae16000e0c6 100644
--- a/edit-post/README.md
+++ b/edit-post/README.md
@@ -9,6 +9,88 @@ Refer to [the plugins module documentation](../plugins/) for more information.
 The following components can be used with the `registerPlugin` ([see documentation](../packages/plugins)) API.
 They can be found in the global variable `wp.editPost` when defining `wp-edit-post` as a script dependency.
 
+### `PluginBlockSettingsMenuItem`
+
+Renders a new item in the block settings menu.
+
+Example:
+
+{% codetabs %}
+
+{% ES5 %}
+```js
+var __ = wp.i18n.__;
+var PluginBlockSettingsMenuItem = wp.editPost.PluginBlockSettingsMenuItem;
+
+function doOnClick(){
+	// To be called when the user clicks the menu item.
+}
+
+function MyPluginBlockSettingsMenuItem() {
+	return el(
+		PluginBlockSettingsMenuItem,
+		{
+			allowedBlockNames: [ 'core/paragraph' ],
+			icon: 'dashicon-name',
+			label: __( 'Menu item text' ),
+			onClick: doOnClick,
+		}
+	);
+}
+```
+
+{% ESNext %}
+```jsx
+import { __ } from wp.i18n;
+import { PluginBlockSettingsMenuItem } from wp.editPost;
+
+const doOnClick = ( ) => {
+    // To be called when the user clicks the menu item.
+};
+
+const MyPluginBlockSettingsMenuItem = () => (
+    <PluginBlockSettingsMenuItem 
+		allowedBlockNames=[ 'core/paragraph' ]
+		icon='dashicon-name'
+		label=__( 'Menu item text' )
+		onClick={ doOnClick } />
+);
+```
+
+{% end %}
+
+#### Props
+
+##### allowedBlockNames
+
+An array containing a whitelist of block names for which the item should be shown. If this prop is not present the item will be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist.
+
+- Type: `Array`
+- Required: No
+- Default: Menu item is shown for any block
+
+##### icon
+
+The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label.
+
+- Type: `String` | `Element`
+- Required: No
+- Default: Menu item wil be rendered without icon
+
+##### label
+
+A string containing the menu item text.
+
+- Type: `String`
+- Required: Yes
+
+##### onClick
+
+The callback function to be executed when the user clicks the menu item.
+
+- Type: `function`
+- Required: Yes
+
 ### `PluginSidebar`
 
 Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar.