From 8e0b3f0b33208c68ef0c68625045f0163ac3678a Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Mon, 29 Jun 2020 10:02:17 +0900 Subject: [PATCH 01/22] Rough document outline. --- .../submitting-to-block-directory.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md new file mode 100644 index 00000000000000..aa78a6bc1c1d09 --- /dev/null +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -0,0 +1,88 @@ +#Share your Gutenberg Block with the World +So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory. + +Need help building a block? Check out our block tutorials to get started. + +**Contents**: +1. Help users understand your block +2. Analyze your plugin +3. Zip & Submit + + +## Step 1: Help users understand your block +Providing straightforward, easy to understand block information is important to the block directory and our end users. + +**Guidelines**: + +- Name your block based on what it does +- Clearly describe what your block does +- Add Keywords for all contexts +- Choose the right category + +### Name your block based on what it does +Users typically search the block directory within gutenberg and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it’s needed. + +**Not So Good**: WebTeam5 Image Works +**Good**: Responsive Image Slider + + +**Question**: What happens when there are multiple blocks with similar names? +TODO + +### Clearly describe what your block does +The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block’s description within Gutenberg where space can be limited. Try to keep it short and concise. + +**Not So Good**: The best way to show images on your website using jQuery and CSS. +**Good**: An easy to use, responsive, Image gallery block. + +**Note**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is! + +### Add Keywords for broader context +Keywords add extra context to your block and make it more likely to be found in the inserter. + +Examples for an Image Slider block: +- slider +- carousel +- gallery + +[Read more]() about keywords. + +### Choose the right category +Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. + +**Possible Values**: +- Common +- Formatting +- Layout +- Widgets +- embed + +[Read more]() about categories. + +Wondering where to input all this information? Read the next section :) + + +## Step 2: Analyze your plugin + +The `block.json` file lives in the root folder of your block and provides the Block Directory and Gutenberg important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. + +Double check that the following is true for your block: +`editorScript` is pointing to the JavaScript bundle that includes all the code used in the editor. +`editorStyle` is pointing to the CSS bundle that includes all the css used in the editor. +`script` is pointing to the JavaScript bundle that includes all the code used on the website. +`style` is pointing to the CSS bundle that includes all the code used on the website. +I have included example data (Optional, but useful) + +Although it isn’t necessary that you have both an `editorScript/editorStyle` and `script/style` listed in your `block.json` we encourage the separation of code used for editing and code used for displaying your block in order to keep both interfaces running quickly. + +The `block.json` file also contains other important properties. Take a look at an example block.json file for reference. + + +## Step 3: Zip & Submit +The community is ecstatic you made it this far! Time to submit your plugin! + +Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md) + +TODO - ADD MORE STUFF HERE + + From dba7465f845f6fb01118e7558bdfca630f52961e Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Mon, 29 Jun 2020 10:40:27 +0900 Subject: [PATCH 02/22] A few updates. --- .../submitting-to-block-directory.md | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index aa78a6bc1c1d09..31cd6d257d5615 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -1,8 +1,6 @@ #Share your Gutenberg Block with the World So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory. -Need help building a block? Check out our block tutorials to get started. - **Contents**: 1. Help users understand your block 2. Analyze your plugin @@ -15,27 +13,27 @@ Providing straightforward, easy to understand block information is important to **Guidelines**: - Name your block based on what it does -- Clearly describe what your block does +- Clearly describe your block - Add Keywords for all contexts - Choose the right category ### Name your block based on what it does -Users typically search the block directory within gutenberg and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it’s needed. +Users typically search the block directory within gutenberg and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. **Not So Good**: WebTeam5 Image Works -**Good**: Responsive Image Slider +**Good**: Responsive Image Slider by WebTeam5 +**Question: What happens when there are multiple blocks with similar names?** +Try your best to make your block's name functional and unique to make it stand out. Look for applicable synonyms or include a prefix if necessary. -**Question**: What happens when there are multiple blocks with similar names? -TODO -### Clearly describe what your block does -The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block’s description within Gutenberg where space can be limited. Try to keep it short and concise. +### Clearly describe your block +The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within Gutenberg where space can be limited. Try to keep it short and concise. **Not So Good**: The best way to show images on your website using jQuery and CSS. **Good**: An easy to use, responsive, Image gallery block. -**Note**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is! +**Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is! ### Add Keywords for broader context Keywords add extra context to your block and make it more likely to be found in the inserter. @@ -45,7 +43,7 @@ Examples for an Image Slider block: - carousel - gallery -[Read more]() about keywords. +[Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords. ### Choose the right category Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. @@ -57,7 +55,7 @@ Gutenberg allows you to indicate which category your block fits in. Choosing the - Widgets - embed -[Read more]() about categories. +[Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) about categories. Wondering where to input all this information? Read the next section :) @@ -67,15 +65,15 @@ Wondering where to input all this information? Read the next section :) The `block.json` file lives in the root folder of your block and provides the Block Directory and Gutenberg important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. Double check that the following is true for your block: -`editorScript` is pointing to the JavaScript bundle that includes all the code used in the editor. -`editorStyle` is pointing to the CSS bundle that includes all the css used in the editor. -`script` is pointing to the JavaScript bundle that includes all the code used on the website. -`style` is pointing to the CSS bundle that includes all the code used on the website. +`editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**. +`editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. +`script` is pointing to the JavaScript bundle that includes all the code used on the **website**. +`style` is pointing to the CSS bundle that includes all the code used on the **website**. I have included example data (Optional, but useful) Although it isn’t necessary that you have both an `editorScript/editorStyle` and `script/style` listed in your `block.json` we encourage the separation of code used for editing and code used for displaying your block in order to keep both interfaces running quickly. -The `block.json` file also contains other important properties. Take a look at an example block.json file for reference. +The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#registering-a-block-type) file for reference. ## Step 3: Zip & Submit From 4d267fa455a7efed1104dc74985987fce6614143 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 30 Jun 2020 14:30:49 +0900 Subject: [PATCH 03/22] Update categories. --- .../create-block/submitting-to-block-directory.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 31cd6d257d5615..0c5f987e6b279f 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -49,11 +49,11 @@ Examples for an Image Slider block: Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. **Possible Values**: -- Common -- Formatting -- Layout -- Widgets -- embed +- Text +- Media +- Design +- Widgets +- Embeds [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) about categories. From 815f43d939b3e9b6fa839a2cb0a3e9690feb7679 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 30 Jun 2020 14:36:32 +0900 Subject: [PATCH 04/22] Lowercase the categories. --- .../create-block/submitting-to-block-directory.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 0c5f987e6b279f..24f9df1d357a47 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -49,11 +49,11 @@ Examples for an Image Slider block: Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. **Possible Values**: -- Text -- Media -- Design -- Widgets -- Embeds +- text +- media +- design +- widgets +- embeds [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) about categories. From e2b5a06a5a0942dab33966ea62be232f20521f33 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Wed, 1 Jul 2020 09:03:48 +0900 Subject: [PATCH 05/22] Fix embed category. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 24f9df1d357a47..4d9dfa00c9e54c 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -53,7 +53,7 @@ Gutenberg allows you to indicate which category your block fits in. Choosing the - media - design - widgets -- embeds +- embed [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) about categories. From 0a3ed501549b334f92d4fbad2c97df6d669b3554 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Wed, 1 Jul 2020 09:07:19 +0900 Subject: [PATCH 06/22] Prefer 'block editor' to 'gutenberg'. --- .../create-block/submitting-to-block-directory.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 4d9dfa00c9e54c..0317c0d76b764b 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -1,4 +1,4 @@ -#Share your Gutenberg Block with the World +#Share your Block with the World So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory. **Contents**: @@ -18,7 +18,7 @@ Providing straightforward, easy to understand block information is important to - Choose the right category ### Name your block based on what it does -Users typically search the block directory within gutenberg and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. +Users typically search the block directory within the block editor and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. **Not So Good**: WebTeam5 Image Works **Good**: Responsive Image Slider by WebTeam5 @@ -28,7 +28,7 @@ Try your best to make your block's name functional and unique to make it stand o ### Clearly describe your block -The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within Gutenberg where space can be limited. Try to keep it short and concise. +The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within the block editor where space can be limited. Try to keep it short and concise. **Not So Good**: The best way to show images on your website using jQuery and CSS. **Good**: An easy to use, responsive, Image gallery block. @@ -46,7 +46,7 @@ Examples for an Image Slider block: [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords. ### Choose the right category -Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. +You have the ability to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the block menu. **Possible Values**: - text @@ -62,7 +62,7 @@ Wondering where to input all this information? Read the next section :) ## Step 2: Analyze your plugin -The `block.json` file lives in the root folder of your block and provides the Block Directory and Gutenberg important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. +The `block.json` file lives in the root folder of your block and provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. Double check that the following is true for your block: `editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**. From 6661c0a0714a1b7554f62cdc4b0863f09ffc22fb Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Wed, 1 Jul 2020 09:08:23 +0900 Subject: [PATCH 07/22] Includes example data. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 0317c0d76b764b..41daaa28587889 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -69,7 +69,7 @@ Double check that the following is true for your block: `editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. `script` is pointing to the JavaScript bundle that includes all the code used on the **website**. `style` is pointing to the CSS bundle that includes all the code used on the **website**. -I have included example data (Optional, but useful) +Includes example data (Optional, but useful) Although it isn’t necessary that you have both an `editorScript/editorStyle` and `script/style` listed in your `block.json` we encourage the separation of code used for editing and code used for displaying your block in order to keep both interfaces running quickly. From bb9631d75a652eac693e67d191b8f8dd54718e3e Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Wed, 1 Jul 2020 09:10:55 +0900 Subject: [PATCH 08/22] Change sentence and capital case 'block editor'. --- .../tutorials/create-block/submitting-to-block-directory.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 41daaa28587889..71bddf69bc8cf8 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -18,7 +18,7 @@ Providing straightforward, easy to understand block information is important to - Choose the right category ### Name your block based on what it does -Users typically search the block directory within the block editor and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. +Users typically search the block directory within the Block Editor and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. **Not So Good**: WebTeam5 Image Works **Good**: Responsive Image Slider by WebTeam5 @@ -28,7 +28,7 @@ Try your best to make your block's name functional and unique to make it stand o ### Clearly describe your block -The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within the block editor where space can be limited. Try to keep it short and concise. +The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within the Block Editor where space can be limited. Try to keep it short and concise. **Not So Good**: The best way to show images on your website using jQuery and CSS. **Good**: An easy to use, responsive, Image gallery block. @@ -46,7 +46,7 @@ Examples for an Image Slider block: [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords. ### Choose the right category -You have the ability to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the block menu. +The Block Editor allows you to indicate the category your block belongs in, making it easier for users to locate your block in the menu. **Possible Values**: - text From f70084f8810d584582a788f48f96af8852fa10c2 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Wed, 1 Jul 2020 09:11:16 +0900 Subject: [PATCH 09/22] update the intro sentence. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 71bddf69bc8cf8..f6e68a5b5b23e2 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -1,5 +1,5 @@ #Share your Block with the World -So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory. +So you've created an awesome block? Care to share? **Contents**: 1. Help users understand your block From 717d26ca668676630014a19bb895a7bf218f15ca Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Thu, 2 Jul 2020 14:46:19 +0900 Subject: [PATCH 10/22] Fix formatting. --- .../create-block/submitting-to-block-directory.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index f6e68a5b5b23e2..b87997e94bf2c8 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -1,4 +1,5 @@ -#Share your Block with the World +# Share your Block with the World + So you've created an awesome block? Care to share? **Contents**: @@ -6,8 +7,8 @@ So you've created an awesome block? Care to share? 2. Analyze your plugin 3. Zip & Submit - ## Step 1: Help users understand your block + Providing straightforward, easy to understand block information is important to the block directory and our end users. **Guidelines**: @@ -18,6 +19,7 @@ Providing straightforward, easy to understand block information is important to - Choose the right category ### Name your block based on what it does + Users typically search the block directory within the Block Editor and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. **Not So Good**: WebTeam5 Image Works @@ -26,8 +28,8 @@ Users typically search the block directory within the Block Editor and do so in **Question: What happens when there are multiple blocks with similar names?** Try your best to make your block's name functional and unique to make it stand out. Look for applicable synonyms or include a prefix if necessary. - ### Clearly describe your block + The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within the Block Editor where space can be limited. Try to keep it short and concise. **Not So Good**: The best way to show images on your website using jQuery and CSS. @@ -36,6 +38,7 @@ The description really helps to communicate what your block does.The quicker a u **Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is! ### Add Keywords for broader context + Keywords add extra context to your block and make it more likely to be found in the inserter. Examples for an Image Slider block: @@ -46,6 +49,7 @@ Examples for an Image Slider block: [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords. ### Choose the right category + The Block Editor allows you to indicate the category your block belongs in, making it easier for users to locate your block in the menu. **Possible Values**: @@ -59,7 +63,6 @@ The Block Editor allows you to indicate the category your block belongs in, maki Wondering where to input all this information? Read the next section :) - ## Step 2: Analyze your plugin The `block.json` file lives in the root folder of your block and provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. @@ -77,6 +80,7 @@ The `block.json` file also contains other important properties. Take a look at a ## Step 3: Zip & Submit + The community is ecstatic you made it this far! Time to submit your plugin! Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md) From c14048c01b1199667229c32bce57fd8608188bdf Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Thu, 2 Jul 2020 15:02:41 +0900 Subject: [PATCH 11/22] Fix the submit sections. --- .../tutorials/create-block/submitting-to-block-directory.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index b87997e94bf2c8..c2e4ef261e3c5b 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -83,8 +83,7 @@ The `block.json` file also contains other important properties. Take a look at a The community is ecstatic you made it this far! Time to submit your plugin! -Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md) +Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. -TODO - ADD MORE STUFF HERE From 488745c77045d6c6f8a7b00f97ff2474dbf788a9 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Mon, 6 Jul 2020 09:25:37 +0900 Subject: [PATCH 12/22] Remove empty lines. --- .../tutorials/create-block/submitting-to-block-directory.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index c2e4ef261e3c5b..22bd8a86918f02 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -83,7 +83,4 @@ The `block.json` file also contains other important properties. Take a look at a The community is ecstatic you made it this far! Time to submit your plugin! -Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. - - - +Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. \ No newline at end of file From 34203f17fb389dd668124496f1f51a4b7de9ac02 Mon Sep 17 00:00:00 2001 From: Kelly Dwan Date: Thu, 9 Jul 2020 18:29:53 -0400 Subject: [PATCH 13/22] Use more contextual link text --- .../create-block/submitting-to-block-directory.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index c2e4ef261e3c5b..1d557fec614394 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -46,7 +46,7 @@ Examples for an Image Slider block: - carousel - gallery -[Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords. +[Read more about keywords.](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) ### Choose the right category @@ -59,7 +59,7 @@ The Block Editor allows you to indicate the category your block belongs in, maki - widgets - embed -[Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) about categories. +[Read more about categories.](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#category) Wondering where to input all this information? Read the next section :) @@ -83,7 +83,6 @@ The `block.json` file also contains other important properties. Take a look at a The community is ecstatic you made it this far! Time to submit your plugin! -Take a few moments to read the block guidelines (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. - +Take a few moments to read [the block guidelines](https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. From cb7e2e6f82e3f499fad1c3c70513897afa98e45c Mon Sep 17 00:00:00 2001 From: Kelly Dwan Date: Thu, 9 Jul 2020 18:30:34 -0400 Subject: [PATCH 14/22] Update block.json description --- .../submitting-to-block-directory.md | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 1d557fec614394..fd438e0912b90f 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -64,18 +64,32 @@ The Block Editor allows you to indicate the category your block belongs in, maki Wondering where to input all this information? Read the next section :) ## Step 2: Analyze your plugin +Each block in your plugin should have a corresponding `block.json` file. This file provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. -The `block.json` file lives in the root folder of your block and provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. +Block plugins submitted to the Block Directory can contain mutliple blocks only if they are children of a single parent/ancestor. There should only be one main block. For example, a list block can contain list-item blocks. Children blocks must set the `parent` property in their `block.json` file. Double check that the following is true for your block: -`editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**. -`editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. -`script` is pointing to the JavaScript bundle that includes all the code used on the **website**. -`style` is pointing to the CSS bundle that includes all the code used on the **website**. -Includes example data (Optional, but useful) + +- `editorScript` is pointing to the JavaScript bundle that includes all the code used in the **editor**. +- `editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. +- `script` is pointing to the JavaScript bundle that includes all the code used on the **website**. +- `style` is pointing to the CSS bundle that includes all the code used on the **website**. Although it isn’t necessary that you have both an `editorScript/editorStyle` and `script/style` listed in your `block.json` we encourage the separation of code used for editing and code used for displaying your block in order to keep both interfaces running quickly. +The most basic `block.json` you need looks like this. + +```json +{ + "name": "plugin-slug/image-slider", + "title": "Responsive Image Slider", + "description": "A responsive and easy to use image gallery block.", + "keywords": [ "slider", "carousel", "gallery" ], + "category": "media", + "editorScript": "file:./dist/editor.js", +} +``` + The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#registering-a-block-type) file for reference. From dd80b7ee66e0b773bdf54fe6e118a65bbdc7eaa5 Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Thu, 9 Jul 2020 21:01:23 -0500 Subject: [PATCH 15/22] update anchor link for keywords --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index fd438e0912b90f..2425539dcc9a1b 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -46,7 +46,7 @@ Examples for an Image Slider block: - carousel - gallery -[Read more about keywords.](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) +[Read more about keywords.](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keywords) ### Choose the right category From b1f80724eddcf9dff1af58ee5323460b11ff53b3 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:29:18 +0900 Subject: [PATCH 16/22] Replace paragraphs based on feedback. --- .../tutorials/create-block/submitting-to-block-directory.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 22bd8a86918f02..abf78c29d71ff8 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -9,7 +9,7 @@ So you've created an awesome block? Care to share? ## Step 1: Help users understand your block -Providing straightforward, easy to understand block information is important to the block directory and our end users. +It is important to the Block Directory and our end users to provide easy to understand information on how your block was created. **Guidelines**: @@ -74,7 +74,7 @@ Double check that the following is true for your block: `style` is pointing to the CSS bundle that includes all the code used on the **website**. Includes example data (Optional, but useful) -Although it isn’t necessary that you have both an `editorScript/editorStyle` and `script/style` listed in your `block.json` we encourage the separation of code used for editing and code used for displaying your block in order to keep both interfaces running quickly. +We encourage the separation of code by using both editorScript/editorStyle and script/style files listed in your block.json to keep the backend and frontend interfaces running smoothly. Even though only one file is required. The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#registering-a-block-type) file for reference. From 5bbfa00f355897ce0432fb27761b9a57f745d9ca Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:30:41 +0900 Subject: [PATCH 17/22] Update block directory references to be capital case. --- .../tutorials/create-block/submitting-to-block-directory.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index abf78c29d71ff8..29363c3504b992 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -20,7 +20,7 @@ It is important to the Block Directory and our end users to provide easy to unde ### Name your block based on what it does -Users typically search the block directory within the Block Editor and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. +Users typically search the Block Directory within the Block Editor and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. **Not So Good**: WebTeam5 Image Works **Good**: Responsive Image Slider by WebTeam5 @@ -35,7 +35,7 @@ The description really helps to communicate what your block does.The quicker a u **Not So Good**: The best way to show images on your website using jQuery and CSS. **Good**: An easy to use, responsive, Image gallery block. -**Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is! +**Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The Block Directory will provide metrics to let users know how awesome your block is! ### Add Keywords for broader context From 4e8e184fd9a91b020d635b02c0df69a6855d7dbb Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:31:15 +0900 Subject: [PATCH 18/22] Update example copy. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 29363c3504b992..8f610310a75e7b 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -33,7 +33,7 @@ Try your best to make your block's name functional and unique to make it stand o The description really helps to communicate what your block does.The quicker a user understands how your block will help them, the more likely it is a user will use your block. Users will be reading your block's description within the Block Editor where space can be limited. Try to keep it short and concise. **Not So Good**: The best way to show images on your website using jQuery and CSS. -**Good**: An easy to use, responsive, Image gallery block. +**Good**: A responsive image gallery block. **Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The Block Directory will provide metrics to let users know how awesome your block is! From 2657763a5dc3cfa30ef447f28f64ecf5e38543ba Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:33:34 +0900 Subject: [PATCH 19/22] Update copy that points to example block.json. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index a1c384d985cde5..282827af6d7a98 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -77,7 +77,7 @@ Double check that the following is true for your block: We encourage the separation of code by using both editorScript/editorStyle and script/style files listed in your block.json to keep the backend and frontend interfaces running smoothly. Even though only one file is required. -The most basic `block.json` you need looks like this. +Here is an example of a basic block.json file. ```json { From c429c19d34fe8fcbec438c8708afe8b2032181cc Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:34:06 +0900 Subject: [PATCH 20/22] Update again. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 282827af6d7a98..5270703d53f581 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -95,7 +95,7 @@ The `block.json` file also contains other important properties. Take a look at a ## Step 3: Zip & Submit -The community is ecstatic you made it this far! Time to submit your plugin! +The community is thankful for your contribution. It is time to submit your plugin. Take a few moments to read [the block guidelines](https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. From f05681966604f690a62e6fe45b63cb6361f903ed Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:45:25 +0900 Subject: [PATCH 21/22] Update last property. --- .../tutorials/create-block/submitting-to-block-directory.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 5270703d53f581..63352decb05c75 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -97,6 +97,5 @@ The `block.json` file also contains other important properties. Take a look at a The community is thankful for your contribution. It is time to submit your plugin. -Take a few moments to read [the block guidelines](https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and navigate over to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. - +Go through [the block guidelines](https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md). Create a zip file of your block and go to the [block plugin validator](https://wordpress.org/plugins/developers/block-plugin-validator/) and upload your plugin. From b0e47b7ee78e6885fc046e4f60f73aec66d38323 Mon Sep 17 00:00:00 2001 From: dufresnesteven Date: Tue, 21 Jul 2020 14:47:56 +0900 Subject: [PATCH 22/22] Change example callout. --- .../tutorials/create-block/submitting-to-block-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md index 63352decb05c75..bccf86150ea99c 100644 --- a/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md +++ b/docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md @@ -90,7 +90,7 @@ Here is an example of a basic block.json file. } ``` -The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#registering-a-block-type) file for reference. +The `block.json` file also contains other important properties. Take a look at an [example block.json](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#registering-a-block-type) for additional properties to be included in the block.json file. ## Step 3: Zip & Submit