diff --git a/.eslintrc.js b/.eslintrc.js
index 4f4bfa86ffb2ba..45fc4c94140f1c 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -165,6 +165,10 @@ module.exports = {
selector: 'CallExpression[callee.object.name="Math"][callee.property.name="random"]',
message: 'Do not use Math.random() to generate unique IDs; use withInstanceId instead. (If you’re not generating unique IDs: ignore this message.)',
},
+ {
+ selector: 'CallExpression[callee.name="withDispatch"] > :function > BlockStatement > :not(VariableDeclaration,ReturnStatement)',
+ message: 'withDispatch must return an object with consistent keys. Avoid performing logic in `mapDispatchToProps`.',
+ },
],
'react/forbid-elements': [ 'error', {
forbid: [
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index e3dd47a328047e..3a130f10d4ddf2 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -115,3 +115,7 @@ This list is manually curated to include valuable contributions by volunteers th
| @LukePettway | @luke_pettway |
| @pratikthink | @pratikthink |
| @amdrew | @sumobi |
+| @MaedahBatool | @MaedahBatool |
+| @luehrsen | @luehrsen |
+| @getsource | @mikeschroder |
+| @greatislander | @greatislander |
diff --git a/README.md b/README.md
index 2f662221785b79..1f8ae7ce5b83f3 100644
--- a/README.md
+++ b/README.md
@@ -6,27 +6,33 @@ Printing since 1440.

-This is the development hub for the editor focus in core. Gutenberg is the project name. If you want to use the latest release with your WordPress, download Gutenberg from the WordPress.org plugins repository. Conversations and discussions take place in #core-editor on the core WordPress Slack.
+This repo is the development hub for the editor focus in WordPress Core. `Gutenberg` is the project name.
-Discover more about the project here.
+## Getting started
+- **Download:** If you want to use the latest release with your WordPress site, download the latest release from the WordPress.org plugins repository.
+- **Discuss:** Conversations and discussions take place in `#core-editor` channel on the Making WordPress Slack.
+- **Contribute:** Development of Gutenberg happens in this GitHub repo. Get started by reading the contributing guidelines.
+- **Learn:** Discover more about the project on WordPress.org.
-Gutenberg is more than an editor. While the editor is the focus right now, the project will ultimately impact the entire publishing experience including customization (the next focus area).
+**Gutenberg is more than an editor.** While the project is currently focused on building the new editor for WordPress, it doesn't end there. This lays the groundwork for a new model for WordPress Core that will ultimately impact the entire publishing experience of the platform.
## Editing focus
-> The editor will create a new page- and post-building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery. — Matt Mullenweg
+> *The editor will create a new page- and post-building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.*
+>
+> — Matt Mullenweg
-One thing that sets WordPress apart from other systems is that it allows you to create as rich a post layout as you can imagine -- but only if you know HTML and CSS and build your own custom theme. By thinking of the editor as a tool to let you write rich posts and create beautiful layouts, we can transform WordPress into something users _love_, as opposed something they pick it because it's what everyone else uses.
+One thing that sets WordPress apart is that it allows you to create a post layout that's as rich as you can imagine—but only if you can build your own custom theme with HTML and CSS. By thinking of the editor as a tool that allows you to write rich posts **and** create beautiful layouts, we can transform WordPress into something users _love_, as opposed to something they choose because it happens to be what everyone else uses.
-Gutenberg looks at the editor as more than a content field, revisiting a layout that has been largely unchanged for almost a decade. This allows us to holistically design a modern editing experience and build a foundation for things to come.
+**Gutenberg is a new way forward.** It looks at the editor as more than a content field, revisiting a layout that has been largely unchanged for almost a decade. This project allows The WordPress Project to holistically design a modern editing experience and build a foundation for things to come.
Here's why we're looking at the whole editing screen, as opposed to just the content field:
-1. The block unifies multiple interfaces. If we add that on top of the existing interface, it would _add_ complexity, as opposed to removing it.
-2. By revisiting the interface, we can modernize the writing, editing, and publishing experience, with usability and simplicity in mind, benefitting both new and casual users.
-3. When singular block interface takes center stage, it demonstrates a clear path forward for developers to create premium blocks, superior to both shortcodes and widgets.
-4. Considering the whole interface lays a solid foundation for the next focus, full site customization.
-5. Looking at the full editor screen also gives us the opportunity to drastically modernize the foundation, and take steps towards a more fluid and JavaScript-powered future that fully leverages the WordPress REST API.
+1. **The block unifies multiple interfaces.** If Gutenberg added blocks on top of the existing interface, it would _add_ complexity, as opposed to removing it.
+2. **Simplified (and enhanced) editing.** By revisiting the interface, Gutenberg can modernize the writing, editing, and publishing experience, with usability and simplicity in mind, benefitting both new and casual users.
+3. **Better interface usability.** When singular block interface takes center stage, it demonstrates a clear path forward for developers to create premium blocks, superior to both shortcodes and widgets.
+4. **A fresh look at content creation.** Considering the whole interface lays a solid foundation for the next focus: full site customization.
+5. **Modern tooling.** Looking at the full editor screen also gives WordPress the opportunity to drastically modernize the foundation, and take steps towards a more fluid and JavaScript-powered future that fully leverages the WordPress REST API.

@@ -34,7 +40,7 @@ Here's why we're looking at the whole editing screen, as opposed to just the con
Blocks are the unifying evolution of what is now covered, in different ways, by shortcodes, embeds, widgets, post formats, custom post types, theme options, meta-boxes, and other formatting elements. They embrace the breadth of functionality WordPress is capable of, with the clarity of a consistent user experience.
-Imagine a custom “employee” block that a client can drag to an About page to automatically display a picture, name, and bio. A whole universe of plugins that all extend WordPress in the same way. Simplified menus and widgets. Users who can instantly understand and use WordPress -- and 90% of plugins. This will allow you to easily compose beautiful posts like this example.
+Imagine a custom `employee` block that a client can drag onto an `About` page to automatically display a picture, name, and bio of all the employees. Imagine a whole universe of plugins just as flexible, all extending WordPress in the same way. Imagine simplified menus and widgets. Users who can instantly understand and use WordPress—and 90% of plugins. This will allow you to easily compose beautiful posts like this example.
Check out the FAQ for answers to the most common questions about the project.
@@ -44,11 +50,12 @@ Posts are backwards compatible, and shortcodes will still work. We are continuou
## The stages of Gutenberg
-Gutenberg has three planned stages. The first, aimed for inclusion in WordPress 5.0, focuses on the post editing experience and the implementation of blocks. This initial phase focuses on a content-first approach. The use of blocks, as detailed above, allows you to focus on how your content will look without the distraction of other configuration options. This ultimately will help all users present their content in a way that is engaging, direct, and visual.
+Gutenberg has three planned stages.
+1) **The first, aimed for inclusion in WordPress 5.0, focuses on the post editing experience** and the implementation of blocks. This initial phase focuses on a content-first approach. The use of blocks, as detailed above, allows you to focus on how your content will look without the distraction of other configuration options. This ultimately will help all users present their content in a way that is engaging, direct, and visual. These foundational elements will pave the way forward.
+2) Planned for 2019, **The second stage focuses on overhauling The Customizer** and page templates.
+3) Ultimately, **full site customization** will be possible.
-These foundational elements will pave the way for stages two and three, planned for the next year, to go beyond the post into page templates and ultimately, full site customization.
-
-Gutenberg is a big change, and there will be ways to ensure that existing functionality (like shortcodes and meta-boxes) continue to work while allowing developers the time and paths to transition effectively. Ultimately, it will open new opportunities for plugin and theme developers to better serve users through a more engaging and visual experience that takes advantage of a toolset supported by core.
+**Gutenberg is a big change.** There will be ways to ensure that existing functionality (like shortcodes and meta-boxes) continue to work while allowing developers the time and paths to transition effectively. Ultimately, it will open new opportunities for plugin and theme developers to better serve users through a more engaging and visual experience that takes advantage of a toolset supported by core.
## Get involved
diff --git a/assets/stylesheets/_animations.scss b/assets/stylesheets/_animations.scss
index 7b14a7036e6d25..755161bc852ff5 100644
--- a/assets/stylesheets/_animations.scss
+++ b/assets/stylesheets/_animations.scss
@@ -1,78 +1,8 @@
-@keyframes fade-in {
- from {
- opacity: 0;
- }
- to {
- opacity: 1;
- }
+@mixin edit-post__loading-fade-animation {
+ animation: edit-post__loading-fade-animation 1.6s ease-in-out infinite;
}
-@mixin animate_fade {
- animation: animate_fade 0.1s ease-out;
- animation-fill-mode: forwards;
-}
-
-@mixin move_background {
- background-size: 28px 28px;
- animation: move_background 0.5s linear infinite;
-}
-
-@mixin loading_fade {
- animation: loading_fade 1.6s ease-in-out infinite;
-}
-
-@mixin slide_in_right {
- transform: translateX(+100%);
- animation: slide_in_right 0.1s forwards;
-}
-
-@mixin slide_in_top {
- transform: translateY(-100%);
- animation: slide_in_top 0.1s forwards;
-}
-
-@mixin fade_in($speed: 0.2s, $delay: 0s) {
- animation: fade-in $speed ease-out $delay;
- animation-fill-mode: forwards;
-}
-
-@keyframes editor_region_focus {
- from {
- box-shadow: inset 0 0 0 0 $blue-medium-400;
- }
- to {
- box-shadow: inset 0 0 0 4px $blue-medium-400;
- }
-}
-
-@mixin region_focus($speed: 0.2s) {
- animation: editor_region_focus $speed ease-out;
- animation-fill-mode: forwards;
-}
-
-@keyframes rotation {
- from {
- transform: rotate(0deg);
- }
- to {
- transform: rotate(360deg);
- }
-}
-
-@mixin animate_rotation($speed: 1s) {
- animation: rotation $speed infinite linear;
-}
-
-@keyframes modal-appear {
- from {
- margin-top: $grid-size * 4;
- }
- to {
- margin-top: 0;
- }
-}
-
-@mixin modal_appear() {
- animation: modal-appear 0.1s ease-out;
+@mixin edit-post__fade-in-animation($speed: 0.2s, $delay: 0s) {
+ animation: edit-post__fade-in-animation $speed ease-out $delay;
animation-fill-mode: forwards;
}
diff --git a/assets/stylesheets/_z-index.scss b/assets/stylesheets/_z-index.scss
index 39e1bb461d46b1..85b0099665715d 100644
--- a/assets/stylesheets/_z-index.scss
+++ b/assets/stylesheets/_z-index.scss
@@ -85,6 +85,7 @@ $z-layers: (
// Shows above edit post sidebar; Specificity needs to be higher than 3 classes.
".block-editor__container .components-popover.components-color-palette__picker.is-bottom": 100001,
+ ".edit-post-post-visibility__dialog.components-popover.is-bottom": 100001,
".components-autocomplete__results": 1000000,
diff --git a/docs/reference/coding-guidelines.md b/docs/contributors/coding-guidelines.md
similarity index 94%
rename from docs/reference/coding-guidelines.md
rename to docs/contributors/coding-guidelines.md
index dcc943b3288ae6..8264e765231048 100644
--- a/docs/reference/coding-guidelines.md
+++ b/docs/contributors/coding-guidelines.md
@@ -93,9 +93,13 @@ Exposed APIs that are still being tested, discussed and are subject to change sh
Example:
```js
-export {
- internalApi as __experimentalExposedApi
-} from './internalApi.js';
+export { __experimentalDoAction } from './api';
+```
+
+If an API must be exposed but is clearly not intended to be supported into the future, you may also use `__unstable` as a prefix to differentiate it from an experimental API. Unstable APIs should serve an immediate and temporary purpose. They should _never_ be used by plugin developers as they can be removed at any point without notice, and thus should be omitted from public-facing documentation. The inline code documentation should clearly caution their use.
+
+```js
+export { __unstableDoAction } from './api';
```
### Variable Naming
diff --git a/docs/reference/copy-guide.md b/docs/contributors/copy-guide.md
similarity index 66%
rename from docs/reference/copy-guide.md
rename to docs/contributors/copy-guide.md
index 6c0217472f66f3..5e0066a689604c 100644
--- a/docs/reference/copy-guide.md
+++ b/docs/contributors/copy-guide.md
@@ -33,17 +33,17 @@ Features don’t allow anyone to do anything; they’re just tools that do speci
> Preformatted text preserves your tabs and line breaks.
-The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps” -- they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up.
+The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps”—they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up.
#### THREE: Beware of “simple,” “easy,” and “just.”
-It is not for us to decide what is simple: it’s for the user to decide. If we say something is easy and the user doesn’t have an easy experience, it undermines their trust in us and what we’re building. Same goes for “just” -- many of us know to avoid “simple,” but still use “just” all the time. “Just click here.” “Just enter your username.” It’s the same thing: it implies that something will be no big deal, but we can’t know what the user will find to be a big deal.
+It is not for us to decide what is simple: it’s for the user to decide. If we say something is easy and the user doesn’t have an easy experience, it undermines their trust in us and what we’re building. Same goes for “just”—many of us know to avoid “simple,” but still use “just” all the time. “Just click here.” “Just enter your username.” It’s the same thing: it implies that something will be no big deal, but we can’t know what the user will find to be a big deal.
It’s also safer and more helpful to be specific. “Easy” and “simple” are shorthand for explanations that we haven’t written; whenever you see them, take a minute to think about what they’re standing in for. Maybe “It’s easy to add a block by hitting ‘enter’” really means “You can add more content to the page without taking your hands off the keyboard.” Great! Say the specific thing instead of relying on “easy.”
-This isn’t to say that you should banish these words from your vocabulary. You might want to write a tooltip describing how the cover image block now requires less configuration, or an email about how we’re building a tool for quick creation of custom blocks, and you could legitimately say that the cover image block has been simplified or that we’re working to make custom block creation easier -- there, the terms are descriptive and relative. But be on the lookout for ways you might be using (or overusing) them to make absolute claims that something is easy or simple, and use those as opportunities to be more specific and clear.
+This isn’t to say that you should banish these words from your vocabulary. You might want to write a tooltip describing how the cover image block now requires less configuration, or an email about how we’re building a tool for quick creation of custom blocks, and you could legitimately say that the cover image block has been simplified or that we’re working to make custom block creation easier—there, the terms are descriptive and relative. But be on the lookout for ways you might be using (or overusing) them to make absolute claims that something is easy or simple, and use those as opportunities to be more specific and clear.
#### FOUR: Look out for “we.”
-Any time text or instructions uses “we” a lot, it means the focus of the text is on the people behind the software and not the people using the software. Sometimes that’s what you actually want -- but it’s usually not. The focus should typically be on the user, what they need, and how they benefit rather than “what we did” or “what we want.”
+Any time text or instructions uses “we” a lot, it means the focus of the text is on the people behind the software and not the people using the software. Sometimes that’s what you actually want—but it’s usually not. The focus should typically be on the user, what they need, and how they benefit rather than “what we did” or “what we want.”
We’re the only ones that care about what we did or want; the user just wants software that works. If you see a lot of “we”s, think about whether you should reframe what you’re writing to focus on the benefits to and successes of the user.
@@ -51,25 +51,25 @@ We’re the only ones that care about what we did or want; the user just wants s
Guidelines for (duh) writing bulleted lists.
#### ONE: Keep sentence structures parallel across all bullets.
-Parallel structure makes lists easier to read quickly -- their predictability takes some cognitive load off the reader.
+Parallel structure makes lists easier to read quickly—their predictability takes some cognitive load off the reader.
GOOD:
-What can you do with this block? Lots of things!
-* Add a quote.
-* Highlight a link.
-* Display multiple images.
-* Create a bulleted list.
+> What can you do with this block? Lots of things!
+> * Add a quote.
+> * Highlight a link.
+> * Display multiple images.
+> * Create a bulleted list.
-Every bullet is a full sentence, and ends with a period. (If your list is a bunch of one- or two-word items, those can often just turn into a single regular sentence -- easier to read, and space-saving.) Every line begins with a verb that tells the user what the block can do. The subject of the sentence is always the user.
+Every bullet is a full sentence, and ends with a period. (If your list is a bunch of one- or two-word items, those can often just turn into a single regular sentence—easier to read, and space-saving.) Every line begins with a verb that tells the user what the block can do. The subject of the sentence is always the user.
A user can absorb this list quickly because once they read the first item, they understand how to read the rest and know what information they’ll find.
LESS GOOD:
-What can you do with this block? Lots of things!
-* You can add a quote.
-* Highlighting a link you love.
-* It displays multiple images. Nice for galleries!
-* Bulleted lists
+> What can you do with this block? Lots of things!
+> * You can add a quote.
+> * Highlighting a link you love.
+> * It displays multiple images. Nice for galleries!
+> * Bulleted lists
Here, every line has different phrasing (some start with a verb, some with a noun) and the subject of the sentence changes (sometimes it’s you, sometimes it’s the block). Some lines have added description, some don't. There’s an incomplete sentence, and punctuation is inconsistent.
@@ -77,10 +77,10 @@ Reading this list takes more work because the reader has to parse each bullet an
Note: this doesn't mean every bullet has to be super short and start with an action verb! “Predicable” doesn’t have to mean “simple.” It just means that each bullet should have the same sentence structure. This list would also be fine:
-What can you do with this block? Lots of things!
-* Try adding a quote. Sometimes someone else said things best!
-* Use it to highlight a link you love -- sharing links is the currency of the internet.
-* Create a gallery that displays multiple images, and show off your best photos.
+> What can you do with this block? Lots of things!
+> * Try adding a quote. Sometimes someone else said things best!
+> * Use it to highlight a link you love—sharing links is the currency of the internet.
+> * Create a gallery that displays multiple images, and show off your best photos.
Here, each bullet starts with a more user-focused verb and includes a piece of supplemental information for more interest. The punctuation varies a bit, which keeps the lines from feeling too formulaic, but since the basic structure of each is the same, they remain easy to read.
@@ -89,33 +89,33 @@ Do you have to start with a verb? No. But if you’re at a loss, you usually can
In a simple list that’s meant to be purely instructional (e.g., in UI copy where you just need the user to make a decision), it might be fine to start every bullet with the same verb:
-To continue, choose an action:
-Add a simple text block.
-Add a pullquote block.
-Add an image block.
+> To continue, choose an action:
+> * Add a simple text block.
+> * Add a pullquote block.
+> * Add an image block.
If your list is more persuasive (e.g., trying to convince someone to use a feature by listing its benefits) or includes multi-step instructions, you’ll want to vary your verbs to keep the reader engaged with more interesting language, as in the example above:
-What can you do with this block? Lots of things!
-* Try adding a quote. Sometimes someone else said things best!
-* Use it to highlight a link you love -- sharing links is the currency of the internet.
-* Create a gallery that displays multiple images, and show off your best photos.
+>What can you do with this block? Lots of things!
+>* Try adding a quote. Sometimes someone else said things best!
+>* Use it to highlight a link you love—sharing links is the currency of the internet.
+>* Create a gallery that displays multiple images, and show off your best photos.
-These aren’t hard-and-fast rules -- you might choose the use the same verb in a persuasive list to be more focused and powerful, for example. But they’re good starting places for solid lists.
+These aren’t hard-and-fast rules—you might choose the use the same verb in a persuasive list to be more focused and powerful, for example. But they’re good starting places for solid lists.
#### THREE: When something's clearly a list, you don't have to tell us it's a list.
GOOD:
-What can you do with this block? Lots of things!
-* Add a quote.
-* Highlight a link you love.
-* Display multiple images.
+> What can you do with this block? Lots of things!
+> * Add a quote.
+> * Highlight a link you love.
+> * Display multiple images.
LESS GOOD:
-What can you do with this block? Lots of things! Here are some examples of ways you can use it.
-* You can add a quote.
-* Highlighting a link you love.
-* It displays multiple images. Nice for galleries!
+> What can you do with this block? Lots of things! Here are some examples of ways you can use it.
+> * You can add a quote.
+> * Highlighting a link you love.
+> * It displays multiple images. Nice for galleries!
Find the balance between being as clear as possible and trusting a user. On one hand, we know that people don’t always read instructions; on the other, redundancy can make the user feel like we think they’re stupid.
@@ -124,24 +124,24 @@ Use it to focus readers on the key information in a bulleted list. This is espec
“Key information” is, well, key: bold draws the eye, so stick to the most vital piece of information in a given bullet:
-What can you do with this block? Lots of things!
-* Try adding a quote. Sometimes someone else said things best!
-* Use it to highlight a link you love -- sharing links is the currency of the internet.
-* Create a gallery that displays multiple images, and show off your best photos.
+>What can you do with this block? Lots of things!
+> * Try adding a **quote**. Sometimes someone else said things best!
+> * Use it to highlight a **link** you love—sharing links is the currency of the internet.
+> * Create a **gallery** that displays multiple images, and show off your best photos.
On the flipside, bolding too many things creates visual confusion:
-What can you do with this block? Lots of things!
-* Try adding a quote. Sometimes someone else said things best!
-* Use it to highlight a link you love -- sharing links is the currency of the internet.
-* Create a gallery that displays multiple images, and show off your best photos.
+> **What can you do with this block?** Lots of things!
+> * Try adding a **quote**. Sometimes someone else said things best!
+> * Use it to highlight a **link** you love—sharing **links** is the currency of the internet.
+> * Create a **gallery** that displays **multiple images**, and show off your best **photos**.
-When lists are short and basic, don't bother -- bolding just adds busy-ness.
+When lists are short and basic, don't bother—bolding just adds busy-ness.
-What can you do with this block? Lots of things!
-* Add a quote.
-* Highlight a link.
-* Display multiple images.
+> What can you do with this block? Lots of things!
+> * Add a **quote**.
+> * Highlight a **link**.
+> * Display multiple **images**.
The lack of words creates its own focus; you don't have to add any more.
@@ -149,20 +149,26 @@ The lack of words creates its own focus; you don't have to add any more.
Guidelines for writing one-line feature descriptions, or short descriptions to clarify options.
#### ONE: Clarity above all!
-If the user doesn't understand what using a particular option will result in, it doesn't matter how clever your pun is. Wordplay and idioms are frequently unclear, and easily misunderstood. If you use them at all, they should be as supplemental information -- never to explain the main idea -- and they should be something you’re fairly certain will be understandable to a pretty wide range of people.
+If the user doesn't understand what using a particular option will result in, it doesn't matter how clever your pun is. Wordplay and idioms are frequently unclear, and easily misunderstood. If you use them at all, they should be as supplemental information— never to explain the main idea—and they should be something you’re fairly certain will be understandable to a pretty wide range of people.
#### TWO: Refer back to section one, and look out for those bulk-adding phrases.
-Active voice is typically the better way to go, and cutting out the bulky phrasing is particularly important when you’ve got limited space and you need people to be able to make decisions and act.
+Active voice is typically the better way to go, and cutting out the bulky phrasing is particularly important when you’ve got limited space and you need people to be able to make decisions and act. Often you can shorten a UI instruction phrase to be both shorter and clearer:
-Another, UI instruction-particular phrase you can often tighten:
+> When you click X, Y happens.
-“When you click X, Y happens.” > “Click X do to Y.”
-“When you click the “settings” button, the pop-up will display the advanced settings that are available.” VS.
-“Click “settings” to access the advanced settings.”
+vs.
+
+> Click X to do Y.
+
+While it can feel like adding the extra words helps walk a user through the product, the extra words just serve to obscure the point being communicated:
-We sometimes think that adding the extra words helps the user feel like they’re being walked through the product, but most of the time, they really are just extra words.
+> When you click the “settings” button, the pop-up will display the advanced settings that are available.
+
+vs.
-Similar are “Once you do X…” or “If you want to do X.” Sometimes there are decision points where “If you want to do X” is entirely appropriate and needed because there are different paths the user can take based on their goal, but we often use it to mean “Here is a thing you can do,” which you can express more simply with something like “To do X…”
+> Click “settings” to access the advanced settings.
+
+Similar phrases are “Once you do X…” or “If you want to do X…” Sometimes there are decision points where “If you want to do X…” is entirely appropriate because there are different paths the user can take based on their goal. But, we often use it to mean “Here is a thing you can do,” which you can express more simply as: “To do X…”
#### THREE: Be specific.
When an action depends on the user having completed some prior action, be specific about what’s required and what happens next. We often default to “when you’re ready.”
@@ -170,50 +176,50 @@ Ready for what? Be specific about whatever the prerequisites are.
“When you’re ready” can mean:
-“When you want to add another block”
-“When you’re satisfied with your post”
-“After you’ve finished proofreading your post”
-“When you’d like to add a featured image”
-“After you’ve configured all the settings”
+* When you want to add another block”
+* When you’re satisfied with your post”
+* After you’ve finished proofreading your post”
+* When you’d like to add a featured image”
+* After you’ve configured all the settings”
And when something means everything, it actually means nothing. The more specific instructions are, the more useful they are, and the more trust the person following them will have in the product.
#### FOUR: This is still writing. It should have personality and interest.
-Clarity above all, yes, and space is often limited here -- but UI text can still be interesting to read.
+Clarity above all, yes, and space is often limited here—but UI text can still be interesting to read.
Single lines of description can still be complete sentences.
-List. Numbered or bulleted.
+> List. Numbered or bulleted.
vs.
-Add a list, either numbered or bulleted.
+> Add a list, either numbered or bulleted.
You can still use contractions.
-Add a list. We will provide formatting options.
+> Add a list. We will provide formatting options.
vs.
-Add a bulleted list -- we’ll give you some formatting options.
+> Add a bulleted list—we’ll give you some formatting options.
-You can still use punctuation -- em dashes, colons, semicolons -- to control the flow of your words, link ideas, and create pauses.
+You can still use punctuation—em dashes, colons, semicolons—to control the flow of your words, link ideas, and create pauses.
-List. Numbered or bulleted.
+> List. Numbered or bulleted.
vs.
-Add a list -- numbered or bulleted. Your choice!
+> Add a list—numbered or bulleted. Your choice!
You can still try to avoid jargon in favor of plain language.
-Add unordered or ordered list.
+> Add unordered or ordered list.
vs.
-Add a list, either numbered or bulleted.
+> Add a list, either numbered or bulleted.
-(And because it bears repeating: no wordplay, please! “Personality” can -- and in UI instructions, should -- be subtle. We’re talking about text that sounds like it was said by a human being, not forced attempts at whimsy.)
+(And because it bears repeating: no wordplay, please! “Personality” can—and in UI instructions, should—be subtle. We’re talking about text that sounds like it was said by a human being, not forced attempts at whimsy.)
#### FIVE: Pay attention to capitalization.
When it comes to headlines and subheads, there are two ways to capitalize:
@@ -224,24 +230,27 @@ In sentence case, only the first letter of the line is capitalized
Feature names and dashboard sections typically use title case (think “Site Stats” or “Recently Published”), whereas feature labels typically use sentence case (like “Show buttons on” or “Comment Likes are,” where “Likes” is capitalized because it’s the feature name, but the overall label is using sentence case).
-When you’re looking at a full page of UI copy, make sure you’re being consistent across all of it, and that all similar kinds of copy -- headlines, tooltips, buttons, etc. -- are using the same case.
+When you’re looking at a full page of UI copy, make sure you’re being consistent across all of it, and that all similar kinds of copy—headlines, tooltips, buttons, etc.—are using the same case.
## Error Messaging
Guidelines for writing error messages that are understandable and useful.
-#### ONE: Don’t ignore voice/tone in error messaging -- they communicate a lot.
+#### ONE: Don’t ignore voice/tone in error messaging—they communicate a lot.
Voice and tone can say as much as the individual words themselves. Error messages have to convey a significant amount of information and usually need to be fairly short, but try not to sacrifice tone, or to go too far in either a negative or positive direction.
-Let’s say someone’s trying to publish a post, but their user role doesn’t allow them to do that. Here are some ways we could -- but should not -- communicate that:
+Let’s say someone’s trying to publish a post, but their user role doesn’t allow them to do that. Here are some ways we could—but should not—communicate that:
> Your user role is incorrect.
-> Here, we sound distant and uncaring.
+
+Here, we sound distant and uncaring.
> Stop! You do not have permission to do this.
-> Here, we sound unnecessarily alarmist and stern.
+
+Here, we sound unnecessarily alarmist and stern.
> Oopsie, we can’t let you do that!
-> Here, we sound too cute.
+
+Here, we sound too cute.
We can stay direct, positive, and friendly, even in error messages. How? With tips two through four!
diff --git a/docs/design.md b/docs/contributors/design.md
similarity index 100%
rename from docs/design.md
rename to docs/contributors/design.md
diff --git a/docs/grammar.md b/docs/contributors/grammar.md
similarity index 100%
rename from docs/grammar.md
rename to docs/contributors/grammar.md
diff --git a/docs/reference/history.md b/docs/contributors/history.md
similarity index 100%
rename from docs/reference/history.md
rename to docs/contributors/history.md
diff --git a/docs/outreach.md b/docs/contributors/outreach.md
similarity index 100%
rename from docs/outreach.md
rename to docs/contributors/outreach.md
diff --git a/docs/outreach/articles.md b/docs/contributors/outreach/articles.md
similarity index 100%
rename from docs/outreach/articles.md
rename to docs/contributors/outreach/articles.md
diff --git a/docs/outreach/meetups.md b/docs/contributors/outreach/meetups.md
similarity index 100%
rename from docs/outreach/meetups.md
rename to docs/contributors/outreach/meetups.md
diff --git a/docs/outreach/resources.md b/docs/contributors/outreach/resources.md
similarity index 100%
rename from docs/outreach/resources.md
rename to docs/contributors/outreach/resources.md
diff --git a/docs/outreach/talks.md b/docs/contributors/outreach/talks.md
similarity index 100%
rename from docs/outreach/talks.md
rename to docs/contributors/outreach/talks.md
diff --git a/docs/principles.md b/docs/contributors/principles.md
similarity index 100%
rename from docs/principles.md
rename to docs/contributors/principles.md
diff --git a/docs/principles/the-block.md b/docs/contributors/principles/the-block.md
similarity index 100%
rename from docs/principles/the-block.md
rename to docs/contributors/principles/the-block.md
diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
new file mode 100644
index 00000000000000..e69de29bb2d1d6
diff --git a/docs/reference.md b/docs/contributors/reference.md
similarity index 67%
rename from docs/reference.md
rename to docs/contributors/reference.md
index 78ba03435973b2..2a4714d5e75a23 100644
--- a/docs/reference.md
+++ b/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
diff --git a/docs/reference/release-screenshot.png b/docs/contributors/release-screenshot.png
similarity index 100%
rename from docs/reference/release-screenshot.png
rename to docs/contributors/release-screenshot.png
diff --git a/docs/reference/release.md b/docs/contributors/release.md
similarity index 100%
rename from docs/reference/release.md
rename to docs/contributors/release.md
diff --git a/docs/reference/repository-management.md b/docs/contributors/repository-management.md
similarity index 100%
rename from docs/reference/repository-management.md
rename to docs/contributors/repository-management.md
diff --git a/docs/reference/scripts.md b/docs/contributors/scripts.md
similarity index 100%
rename from docs/reference/scripts.md
rename to docs/contributors/scripts.md
diff --git a/docs/reference/testing-overview.md b/docs/contributors/testing-overview.md
similarity index 100%
rename from docs/reference/testing-overview.md
rename to docs/contributors/testing-overview.md
diff --git a/docs/data/README.md b/docs/data/README.md
deleted file mode 100644
index ac44230651976e..00000000000000
--- a/docs/data/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Data Module Reference
-
- - [**core**: WordPress Core Data](../../docs/data/data-core.md)
- - [**core/annotations**: Annotations](../../docs/data/data-core-annotations.md)
- - [**core/blocks**: Block Types Data](../../docs/data/data-core-blocks.md)
- - [**core/editor**: The Editor’s Data](../../docs/data/data-core-editor.md)
- - [**core/edit-post**: The Editor’s UI Data](../../docs/data/data-core-edit-post.md)
- - [**core/notices**: Notices Data](../../docs/data/data-core-notices.md)
- - [**core/nux**: The NUX (New User Experience) Data](../../docs/data/data-core-nux.md)
- - [**core/viewport**: The Viewport Data](../../docs/data/data-core-viewport.md)
\ No newline at end of file
diff --git a/docs/designers-developers/designers/README.md b/docs/designers-developers/designers/README.md
new file mode 100644
index 00000000000000..362cf794885f20
--- /dev/null
+++ 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 b/docs/designers-developers/designers/assets/advanced-settings-do.png
similarity index 100%
rename from docs/design/advanced-settings-do.png
rename to docs/designers-developers/designers/assets/advanced-settings-do.png
diff --git a/docs/design/block-controls-do.png b/docs/designers-developers/designers/assets/block-controls-do.png
similarity index 100%
rename from docs/design/block-controls-do.png
rename to docs/designers-developers/designers/assets/block-controls-do.png
diff --git a/docs/design/block-controls-dont.png b/docs/designers-developers/designers/assets/block-controls-dont.png
similarity index 100%
rename from docs/design/block-controls-dont.png
rename to docs/designers-developers/designers/assets/block-controls-dont.png
diff --git a/docs/design/block-descriptions-do.png b/docs/designers-developers/designers/assets/block-descriptions-do.png
similarity index 100%
rename from docs/design/block-descriptions-do.png
rename to docs/designers-developers/designers/assets/block-descriptions-do.png
diff --git a/docs/design/block-descriptions-dont.png b/docs/designers-developers/designers/assets/block-descriptions-dont.png
similarity index 100%
rename from docs/design/block-descriptions-dont.png
rename to docs/designers-developers/designers/assets/block-descriptions-dont.png
diff --git a/docs/design/blocks-do.png b/docs/designers-developers/designers/assets/blocks-do.png
similarity index 100%
rename from docs/design/blocks-do.png
rename to docs/designers-developers/designers/assets/blocks-do.png
diff --git a/docs/design/blocks-dont.png b/docs/designers-developers/designers/assets/blocks-dont.png
similarity index 100%
rename from docs/design/blocks-dont.png
rename to docs/designers-developers/designers/assets/blocks-dont.png
diff --git a/docs/design/placeholder-do.png b/docs/designers-developers/designers/assets/placeholder-do.png
similarity index 100%
rename from docs/design/placeholder-do.png
rename to docs/designers-developers/designers/assets/placeholder-do.png
diff --git a/docs/design/placeholder-dont.png b/docs/designers-developers/designers/assets/placeholder-dont.png
similarity index 100%
rename from docs/design/placeholder-dont.png
rename to docs/designers-developers/designers/assets/placeholder-dont.png
diff --git a/docs/design/block-design.md b/docs/designers-developers/designers/block-design.md
similarity index 91%
rename from docs/design/block-design.md
rename to docs/designers-developers/designers/block-design.md
index 7849cf693b9303..ae6abaf4c8a37f 100644
--- a/docs/design/block-design.md
+++ b/docs/designers-developers/designers/block-design.md
@@ -27,11 +27,11 @@ 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.
-
+
**Do:**
-Use conise block names.
+Use concise block names.
-
+
**Don't:**
Avoid long, multi-line block names.
@@ -39,11 +39,11 @@ Avoid long, multi-line block names.
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.
-
+
**Do:**
Use a short, simple, block description.
-
+
**Don't:**
Avoid long descriptions and branding.
@@ -51,11 +51,11 @@ Avoid long descriptions and branding.
If your block requires a user to configure some options before you can display it, you should provide an instructive placeholder state.
-
+
**Do:**
Provide an instructive placeholder state.
-
+
**Don't:**
Avoid branding and relying on the title alone to convey instructions.
@@ -65,11 +65,11 @@ 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.
-
+
**Do:**
For controls that are essential the the operation of the block, provide them directly in inside the block edit view.
-
+
**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.
@@ -77,7 +77,7 @@ Do not put controls that are essential to the block in the sidebar, or the block
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.
-
+
**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 b/docs/designers-developers/designers/design-patterns.md
similarity index 100%
rename from docs/design/design-patterns.md
rename to docs/designers-developers/designers/design-patterns.md
diff --git a/docs/design/design-resources.md b/docs/designers-developers/designers/design-resources.md
similarity index 100%
rename from docs/design/design-resources.md
rename to docs/designers-developers/designers/design-resources.md
diff --git a/docs/designers-developers/developers/README.md b/docs/designers-developers/developers/README.md
new file mode 100644
index 00000000000000..e88dd2cd6b2ea1
--- /dev/null
+++ 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
new file mode 100644
index 00000000000000..bd453cba0e56a4
--- /dev/null
+++ b/docs/designers-developers/developers/backwards-compatibility/README.md
@@ -0,0 +1 @@
+# Backwards Compatibility
diff --git a/docs/reference/deprecated.md b/docs/designers-developers/developers/backwards-compatibility/deprecations.md
similarity index 99%
rename from docs/reference/deprecated.md
rename to docs/designers-developers/developers/backwards-compatibility/deprecations.md
index 13efe9f8940bdf..804f55c0a2c19a 100644
--- a/docs/reference/deprecated.md
+++ b/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
diff --git a/docs/extensibility/meta-box.md b/docs/designers-developers/developers/backwards-compatibility/meta-box.md
similarity index 100%
rename from docs/extensibility/meta-box.md
rename to docs/designers-developers/developers/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
new file mode 100644
index 00000000000000..1301449ecdf2c1
--- /dev/null
+++ 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 b/docs/designers-developers/developers/block-api/block-annotations.md
similarity index 100%
rename from docs/extensibility/annotations.md
rename to docs/designers-developers/developers/block-api/block-annotations.md
diff --git a/docs/block-api/attributes.md b/docs/designers-developers/developers/block-api/block-attributes.md
similarity index 100%
rename from docs/block-api/attributes.md
rename to docs/designers-developers/developers/block-api/block-attributes.md
diff --git a/docs/block-api/deprecated-blocks.md b/docs/designers-developers/developers/block-api/block-deprecation.md
similarity index 92%
rename from docs/block-api/deprecated-blocks.md
rename to docs/designers-developers/developers/block-api/block-deprecation.md
index 9f1e368aed6826..3fd500c1645417 100644
--- a/docs/block-api/deprecated-blocks.md
+++ b/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.
diff --git a/docs/block-api/block-edit-save.md b/docs/designers-developers/developers/block-api/block-edit-save.md
similarity index 87%
rename from docs/block-api/block-edit-save.md
rename to docs/designers-developers/developers/block-api/block-edit-save.md
index 4d4ee948e3ba4e..c6f4d603cc3085 100644
--- a/docs/block-api/block-edit-save.md
+++ b/docs/designers-developers/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 b/docs/designers-developers/developers/block-api/block-registration.md
similarity index 94%
rename from docs/block-api.md
rename to docs/designers-developers/developers/block-api/block-registration.md
index 01b2295b46de0b..9738ac482353b7 100644
--- a/docs/block-api.md
+++ b/docs/designers-developers/developers/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`
@@ -124,18 +122,18 @@ Block styles can be used to provide alternative styles to block. It works by add
// Register block styles.
styles: [
// Mark style as default.
- {
- name: 'default',
- label: __( 'Rounded' ),
- isDefault: true
+ {
+ name: 'default',
+ label: __( 'Rounded' ),
+ isDefault: true
},
- {
- name: 'outline',
- label: __( 'Outline' )
+ {
+ name: 'outline',
+ label: __( 'Outline' )
},
- {
- name: 'squared',
- label: __( 'Squared' )
+ {
+ name: 'squared',
+ label: __( 'Squared' )
},
],
```
@@ -413,6 +411,43 @@ transforms: {
```
{% end %}
+A prefix transform is a transform that will be applied if the user prefixes some text in e.g. the paragraph block with a given pattern and a trailing space.
+
+{% codetabs %}
+{% ES5 %}
+```js
+transforms: {
+ from: [
+ {
+ type: 'prefix',
+ prefix: '?',
+ transform: function( content ) {
+ return createBlock( 'my-plugin/question', {
+ content,
+ } );
+ },
+ },
+ ]
+}
+```
+{% ESNext %}
+```js
+transforms: {
+ from: [
+ {
+ type: 'prefix',
+ prefix: '?',
+ transform( content ) {
+ return createBlock( 'my-plugin/question', {
+ content,
+ } );
+ },
+ },
+ ]
+}
+```
+{% end %}
+
#### parent (optional)
@@ -429,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:
@@ -511,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 b/docs/designers-developers/developers/block-api/block-templates.md
similarity index 100%
rename from docs/templates.md
rename to docs/designers-developers/developers/block-api/block-templates.md
diff --git a/docs/designers-developers/developers/data/README.md b/docs/designers-developers/developers/data/README.md
new file mode 100644
index 00000000000000..5233753c1445e5
--- /dev/null
+++ 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)
\ No newline at end of file
diff --git a/docs/data/data-core-annotations.md b/docs/designers-developers/developers/data/data-core-annotations.md
similarity index 91%
rename from docs/data/data-core-annotations.md
rename to docs/designers-developers/developers/data/data-core-annotations.md
index f4f7d8cb5ff072..6600938219e0e9 100644
--- a/docs/data/data-core-annotations.md
+++ b/docs/designers-developers/developers/data/data-core-annotations.md
@@ -75,6 +75,16 @@ Removes an annotation with a specific ID.
* annotationId: The annotation to remove.
+### __experimentalUpdateAnnotationRange
+
+Updates the range of an annotation.
+
+*Parameters*
+
+ * annotationId: ID of the annotation to update.
+ * start: The start of the new range.
+ * end: The end of the new range.
+
### __experimentalRemoveAnnotationsBySource
Removes all annotations of a specific source.
diff --git a/docs/data/data-core-blocks.md b/docs/designers-developers/developers/data/data-core-blocks.md
similarity index 100%
rename from docs/data/data-core-blocks.md
rename to docs/designers-developers/developers/data/data-core-blocks.md
diff --git a/docs/data/data-core-edit-post.md b/docs/designers-developers/developers/data/data-core-edit-post.md
similarity index 92%
rename from docs/data/data-core-edit-post.md
rename to docs/designers-developers/developers/data/data-core-edit-post.md
index 93e658e91d4798..c12cf62a83d633 100644
--- a/docs/data/data-core-edit-post.md
+++ b/docs/designers-developers/developers/data/data-core-edit-post.md
@@ -89,6 +89,20 @@ Returns true if the publish sidebar is opened.
Whether the publish sidebar is open.
+### isEditorPanelRemoved
+
+Returns true if the given panel was programmatically removed, or false otherwise.
+All panels are not removed by default.
+
+*Parameters*
+
+ * state: Global application state.
+ * panelName: A string that identifies the panel.
+
+*Returns*
+
+Whether or not the panel is removed.
+
### isEditorPanelEnabled
Returns true if the given panel is enabled, or false otherwise. Panels are
@@ -301,6 +315,14 @@ Returns an action object used to open or close a panel in the editor.
* panelName: A string that identifies the panel to open or close.
+### removeEditorPanel
+
+Returns an action object used to remove a panel from the editor.
+
+*Parameters*
+
+ * panelName: A string that identifies the panel to remove.
+
### toggleFeature
Returns an action object used to toggle a feature flag.
diff --git a/docs/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md
similarity index 97%
rename from docs/data/data-core-editor.md
rename to docs/designers-developers/developers/data/data-core-editor.md
index 1517f5b5317cc0..25ea6598990d83 100644
--- a/docs/data/data-core-editor.md
+++ b/docs/designers-developers/developers/data/data-core-editor.md
@@ -398,6 +398,19 @@ the client ID.
Block name.
+### isBlockValid
+
+Returns whether a block is valid or not.
+
+*Parameters*
+
+ * state: Editor state.
+ * clientId: Block client ID.
+
+*Returns*
+
+Is Valid.
+
### getBlock
Returns a block given its client ID. This is a parsed copy of the block,
@@ -1058,6 +1071,30 @@ Returns true if the post is autosaving, or false otherwise.
Whether the post is autosaving.
+### isPreviewingPost
+
+Returns true if the post is being previewed, or false otherwise.
+
+*Parameters*
+
+ * state: Global application state.
+
+*Returns*
+
+Whether the post is being previewed.
+
+### getEditedPostPreviewLink
+
+Returns the post preview link
+
+*Parameters*
+
+ * state: Global application state.
+
+*Returns*
+
+Preview Link.
+
### getSuggestedPostFormat
Returns a suggested post format for the current post, inferred only if there
@@ -1142,6 +1179,19 @@ Items are returned ordered descendingly by their 'utility' and 'frecency'.
Items that appear in inserter.
+### hasInserterItems
+
+Determines whether there are items to show in the inserter.
+
+*Parameters*
+
+ * state: Editor state.
+ * rootClientId: Optional root client ID of block list.
+
+*Returns*
+
+Items that appear in inserter.
+
### __experimentalGetReusableBlock
Returns the reusable block with the given ID.
@@ -1602,7 +1652,7 @@ Returns an action object to save the post.
*Parameters*
* options: Options for the save.
- * options.autosave: Perform an autosave if true.
+ * options.isAutosave: Perform an autosave if true.
### mergeBlocks
@@ -1617,6 +1667,10 @@ Returns an action object used in signalling that two blocks should be merged
Returns an action object used in signalling that the post should autosave.
+*Parameters*
+
+ * options: Extra flags to identify the autosave.
+
### redo
Returns an action object used in signalling that undo history should
@@ -1802,8 +1856,4 @@ Returns an action object used to signal that post saving is unlocked.
*Parameters*
- * lockName: The lock name.
-
-### createNotice
-
-### fetchReusableBlocks
\ No newline at end of file
+ * lockName: The lock name.
\ No newline at end of file
diff --git a/docs/data/data-core-notices.md b/docs/designers-developers/developers/data/data-core-notices.md
similarity index 88%
rename from docs/data/data-core-notices.md
rename to docs/designers-developers/developers/data/data-core-notices.md
index b7ea283f02687f..5ae7f1fb000679 100644
--- a/docs/data/data-core-notices.md
+++ b/docs/designers-developers/developers/data/data-core-notices.md
@@ -32,6 +32,11 @@ Yields action objects used in signalling that a notice is to be created.
* options.isDismissible: Whether the notice can
be dismissed by user.
Defaults to `true`.
+ * options.speak: Whether the notice
+ content should be
+ announced to screen
+ readers. Defaults to
+ `true`.
* options.actions: User actions to be
presented with notice.
diff --git a/docs/data/data-core-nux.md b/docs/designers-developers/developers/data/data-core-nux.md
similarity index 100%
rename from docs/data/data-core-nux.md
rename to docs/designers-developers/developers/data/data-core-nux.md
diff --git a/docs/data/data-core-viewport.md b/docs/designers-developers/developers/data/data-core-viewport.md
similarity index 100%
rename from docs/data/data-core-viewport.md
rename to docs/designers-developers/developers/data/data-core-viewport.md
diff --git a/docs/data/data-core.md b/docs/designers-developers/developers/data/data-core.md
similarity index 89%
rename from docs/data/data-core.md
rename to docs/designers-developers/developers/data/data-core.md
index 5310fe2489c81e..2a98c3bb5d3974 100644
--- a/docs/data/data-core.md
+++ b/docs/designers-developers/developers/data/data-core.md
@@ -136,6 +136,18 @@ get back from the oEmbed preview API.
Is the preview for the URL an oEmbed link fallback.
+### hasUploadPermissions
+
+Return Upload Permissions.
+
+*Parameters*
+
+ * state: State tree.
+
+*Returns*
+
+Upload Permissions.
+
## Actions
### receiveUserQuery
@@ -193,4 +205,12 @@ Action triggered to save an entity record.
* kind: Kind of the received entity.
* name: Name of the received entity.
- * record: Record to be saved.
\ No newline at end of file
+ * record: Record to be saved.
+
+### receiveUploadPermissions
+
+Returns an action object used in signalling that Upload permissions have been received.
+
+*Parameters*
+
+ * hasUploadPermissions: Does the user have permission to upload files?
\ No newline at end of file
diff --git a/docs/designers-developers/developers/filters/README.md b/docs/designers-developers/developers/filters/README.md
new file mode 100644
index 00000000000000..9715e15885935c
--- /dev/null
+++ 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).
diff --git a/docs/extensibility/autocomplete.md b/docs/designers-developers/developers/filters/autocomplete-filters.md
similarity index 93%
rename from docs/extensibility/autocomplete.md
rename to docs/designers-developers/developers/filters/autocomplete-filters.md
index ee1f2bc945852e..2b9d60476de80a 100644
--- a/docs/extensibility/autocomplete.md
+++ b/docs/designers-developers/developers/filters/autocomplete-filters.md
@@ -1,7 +1,6 @@
-Autocomplete
-============
+# Autocomplete
-Gutenberg provides a `editor.Autocomplete.completers` filter for extending and overriding the list of autocompleters used by blocks.
+Gutenberg provides an `editor.Autocomplete.completers` filter for extending and overriding the list of autocompleters used by blocks.
The `Autocomplete` component found in `@wordpress/editor` applies this filter. The `@wordpress/components` package provides the foundational `Autocomplete` component that does not apply such a filter, but blocks should generally use the component provided by `@wordpress/editor`.
diff --git a/docs/extensibility/extending-blocks.md b/docs/designers-developers/developers/filters/block-filters.md
similarity index 88%
rename from docs/extensibility/extending-blocks.md
rename to docs/designers-developers/developers/filters/block-filters.md
index d00282e6b4665a..378241356578a0 100644
--- a/docs/extensibility/extending-blocks.md
+++ b/docs/designers-developers/developers/filters/block-filters.md
@@ -1,8 +1,4 @@
-# Extending Blocks (Experimental)
-
-[Hooks](https://developer.wordpress.org/plugins/hooks/) are a way for one piece of code to interact/modify another piece of code. They make up the foundation for how 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/). They were initially implemented in PHP, but for the purpose of Gutenberg they were ported to JavaScript and published to npm as [@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).
-
-## Modifying Blocks
+# Block Filters
To modify the behavior of existing blocks, Gutenberg exposes several APIs:
@@ -93,7 +89,7 @@ wp.hooks.addFilter(
);
```
-_Note:_ This filter must always be run on every page load, and not in your browser's developer tools console. Otherwise, a [block validation](../../docs/block-api/block-edit-save.md#validation) error will occur the next time the post is edited. This is due to the fact that block validation occurs by verifying that the saved output matches what is stored in the post's content during editor initialization. So, if this filter does not exist when the editor loads, the block will be marked as invalid.
+_Note:_ This filter must always be run on every page load, and not in your browser's developer tools console. Otherwise, a [block validation](../../../../docs/designers-developers/developers/block-api/block-edit-save.md#validation) error will occur the next time the post is edited. This is due to the fact that block validation occurs by verifying that the saved output matches what is stored in the post's content during editor initialization. So, if this filter does not exist when the editor loads, the block will be marked as invalid.
#### `blocks.getBlockDefaultClassName`
@@ -342,4 +338,3 @@ add_filter( 'block_categories', 'my_plugin_block_categories', 10, 2 );
```
You can also display an icon with your block category by setting an `icon` attribute. The value can be the slug of a [WordPress Dashicon](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element.
-
diff --git a/docs/designers-developers/developers/filters/editor-filters.md b/docs/designers-developers/developers/filters/editor-filters.md
new file mode 100644
index 00000000000000..1289b8241936ba
--- /dev/null
+++ b/docs/designers-developers/developers/filters/editor-filters.md
@@ -0,0 +1,18 @@
+# Editor Filters (Experimental)
+
+To modify the behavior of the editor experience, Gutenberg exposes the following Filters:
+
+### `editor.PostFeaturedImage.imageSize`
+
+Used to modify the image size displayed in the Post Featured Image component. It defaults to `'post-thumbnail'`, and will fail back to the `full` image size when the specified image size doesn't exist in the media object. It's modeled after the `admin_post_thumbnail_size` filter in the Classic Editor.
+
+_Example:_
+
+```js
+var withImageSize = function( size, mediaId, postId ) {
+ return 'large';
+};
+
+wp.hooks.addFilter( 'editor.PostFeaturedImage.imageSize', 'my-plugin/with-image-size', withImageSize );
+```
+
diff --git a/docs/extensibility/parser.md b/docs/designers-developers/developers/filters/parser-filters.md
similarity index 98%
rename from docs/extensibility/parser.md
rename to docs/designers-developers/developers/filters/parser-filters.md
index 7c1e5bc1be7c21..3acfb2489182db 100644
--- a/docs/extensibility/parser.md
+++ b/docs/designers-developers/developers/filters/parser-filters.md
@@ -1,4 +1,4 @@
-# Extending the Parser
+# Parser Filters
When the editor is interacting with blocks, these are stored in memory as data structures comprising a few basic properties and attributes. Upon saving a working post we serialize these data structures into a specific HTML structure and save the resultant string into the `post_content` property of the post in the WordPress database. When we load that post back into the editor we have to make the reverse transformation to build those data structures from the serialized format in HTML.
diff --git a/docs/designers-developers/developers/internationalization.md b/docs/designers-developers/developers/internationalization.md
new file mode 100644
index 00000000000000..602b7494880855
--- /dev/null
+++ b/docs/designers-developers/developers/internationalization.md
@@ -0,0 +1,33 @@
+# Internationalization
+
+## PHP
+
+WordPress has long offered a number of ways to create translatable strings in PHP.
+
+### Common methods
+
+- `__( $string_to_translate, $text_domain )` - translatable string wrapper, denoting translation namespace
+- `_e( $string_to_translate, $text_domain )` - transltable string wrapper, with echo to print.
+- `esc_html__( $string_to_translate, $text_domain )` - escapes and returns translation
+- `esc_html_e( $string_to_translate, $text_domain )` - escapes, translates, and prints
+- `_n( $singular, $plural, $number, $text_domain )` - Translatable singular/plural string, using %d to inject changing number digit.
+
+### More Resources
+
+- i18n for Developers - Covers numbers in translatable strings, best practices.
+- WP-CLI can be used to generate translation files.
+
+## JavaScript
+
+Historically, `wp_localize_script()` has been used to put server-side PHP data into a properly-escaped native JavaScript object.
+
+The new editor introduces a new approach to translating strings for the editor through a new package called `@wordpress/i18n` and a build tool for Babel called `@wordpress/babel-plugin-makepot` to create the necessary translation file (requires use of babel to compile code to extract the i18n methods).
+
+The new script package is registered with WordPress as `wp-i18n` and should be declared as a dependency during `wp_register_script()` and imported as a global off the Window object as `wp.i18n`.
+
+### Common methods in wp.i18n (may look similar)
+
+- `setLocaleData( data: Object, domain: string )` - Create new Jed instance providing translation data for a domain (probably writing this to the DOM in escaped in PHP function).
+- `__( stringToTranslate, textDomain )` - translatable string wrapper, denoting translation namespace
+- `_n( singular, plural, number, textDomain )` - Translatable singular/plural string, using %d to inject changing number digit.
+- `_x( singular, plural, number, textDomain )` - gettext equivalent for translation
diff --git a/docs/packages.md b/docs/designers-developers/developers/packages.md
similarity index 73%
rename from docs/packages.md
rename to docs/designers-developers/developers/packages.md
index ac767e389d18c9..cde5bf98553aeb 100644
--- a/docs/packages.md
+++ b/docs/designers-developers/developers/packages.md
@@ -1,4 +1,4 @@
-# packages
+# Packages
Gutenberg exposes a list of JavaScript packages and tools for WordPress development.
@@ -7,5 +7,3 @@ Gutenberg exposes a list of JavaScript packages and tools for WordPress developm
JavaScript packages are available as a registered script in WordPress and can be accessed using the `wp` global variable.
All the packages are also available on [npm](https://www.npmjs.com/org/wordpress) if you want to bundle them in your code.
-
-

Welcome to the world of blocks.
+ +``` + +Blocks can be static or dynamic. Static blocks contain rendered content and an object of Attributes used to re-render based on changes. Dynamic blocks require server-side data and rendering while the post content is being generated (rendering). + +Each block contains Attributes or configuration settings, which can be sourced from raw HTML in the content, via meta or other customizible origins. + +The Paragraph is the default Block. Instead of a new line upon typing return on a keyboard, try to think of it as an empty paragraph block (type / to trigger an autocompleting Slash Inserter -- /image will pull up Images as well as Instagram embeds). + +Users insert new blocks by clicking the plus button for the Block Inserter, typing / for the Slash Inserter or typing return for a blank Paragraph block. + +Blocks can be duplicated within content using the menu from the block's toolbar or via keyboard shortcut. + +Blocks can be made repeatable, shared across posts and post types and used multiple times in the same post. Changes in one place reflect everywhere that reusable block is used. + +Blocks can be limited or locked-in-place by Templates and custom code. + +#### More on Blocks + +- **Block API** +- **Block Styles** +- **Tutorial: Building A Custom Block** + +## Block Categories + +In the Block Inserter, the accordion-sorted, popup modal that shows a site's available blocks to users, each accordion title is a Block Category, which are either the defaults or customized by developers through Plugins or code. + +## Reusable Blocks + +Reusable Blocks are a way to share a block (or multiple blocks) as a reusable, repeatable piece of content. + +Any edits to a reusable block are made to every usage of a repeatable block. + +Reusable Blocks are stored as a hidden post type, and are dynamic blocks that "ref" or reference the post_id and return the post_content for that wp_block. + +## Templates At the core of Gutenberg lies the concept of the block. From a technical point of view, blocks both raise the level of abstraction from a single document to a collection of meaningful elements, and they replace ambiguity—inherent in HTML—with explicit structure. A post in Gutenberg is then a _collection of blocks_. @@ -8,7 +56,7 @@ This is true for content blocks. They are the way in which the user creates thei Content in WordPress is stored as HTML-like text in `post_content`. HTML is a robust document markup format and has been used to describe content as simple as unformatted paragraphs of text and as complex as entire application interfaces. Understanding HTML is not trivial; a significant number of existing documents and tools deal with technically invalid or ambiguous code. This code, even when valid, can be incredibly tricky and complicated to parse – and to understand. -The main point is to let the machines work at what they are good at, and optimize for the user and the document. The analogy with the printing press can be taken further in that what matters is the printed page, not the arrangement of metal type that originated it. As a matter of fact, the arrangement of type is a pretty inconvenient storage mechanism. The page is both the result _and_ the proper way to store the data. The metal type is just an instrument for publication and editing, but more ephemeral in nature. Exactly as our use of an object tree (e.g. JSON) in the editor. We have the ability to rebuild this structure from the printed page, as if we printed notations in the margins that allows a machine to know which [sorts](https://en.wikipedia.org/wiki/Sort_(typesetting)) (metal type) to assemble to recreate the page. +The main point is to let the machines work at what they are good at, and optimize for the user and the document. The analogy with the printing press can be taken further in that what matters is the printed page, not the arrangement of metal type that originated it. As a matter of fact, the arrangement of type is a pretty inconvenient storage mechanism. The page is both the result _and_ the proper way to store the data. The metal type is just an instrument for publication and editing, but more ephemeral in nature. Exactly as our use of an object tree (e.g. JSON) in the editor. We have the ability to rebuild this structure from the printed page, as if we printed notations in the margins that allows a machine to know which [sorts](
-
'; - echo __( 'Gutenberg requires WordPress 4.9.8 or later to function properly. Please upgrade WordPress before activating Gutenberg.', 'gutenberg' ); + _e( 'Gutenberg requires WordPress 4.9.8 or later to function properly. Please upgrade WordPress before activating Gutenberg.', 'gutenberg' ); echo '
';
- echo __( 'Gutenberg development mode requires files to be built. Run npm install to install dependencies, npm run build to build the files or npm run dev to build the files and watch for changes. Read the contributing file for more information.', 'gutenberg' );
+ _e( 'Gutenberg development mode requires files to be built. Run npm install to install dependencies, npm run build to build the files or npm run dev to build the files and watch for changes. Read the contributing file for more information.', 'gutenberg' );
echo '
${ content }
`, } ); @@ -100,7 +100,12 @@ export const settings = { }, { type: 'raw', - selector: 'blockquote', + isMatch: ( node ) => ( + node.nodeName === 'BLOCKQUOTE' && + // The quote block can only handle multiline paragraph + // content. + Array.from( node.childNodes ).every( ( child ) => child.nodeName === 'P' ) + ), schema: { blockquote: { children: { diff --git a/packages/block-library/src/separator/index.js b/packages/block-library/src/separator/index.js index f077d6533413de..adcc34297d2ff1 100644 --- a/packages/block-library/src/separator/index.js +++ b/packages/block-library/src/separator/index.js @@ -27,8 +27,7 @@ export const settings = { transforms: { from: [ { - type: 'pattern', - trigger: 'enter', + type: 'enter', regExp: /^-{3,}$/, transform: () => createBlock( 'core/separator' ), }, diff --git a/packages/block-library/src/style.scss b/packages/block-library/src/style.scss index 45618cc406b11a..9d9b2379696b2f 100644 --- a/packages/block-library/src/style.scss +++ b/packages/block-library/src/style.scss @@ -22,91 +22,94 @@ @import "./verse/style.scss"; @import "./video/style.scss"; -.has-pale-pink-background-color { +// Class names are doubled to increase specificity to assure colors take effect +// over another base class color. + +.has-pale-pink-background-color.has-pale-pink-background-color { background-color: #f78da7; } -.has-vivid-red-background-color { +.has-vivid-red-background-color.has-vivid-red-background-color { background-color: #cf2e2e; } -.has-luminous-vivid-orange-background-color { +.has-luminous-vivid-orange-background-color.has-luminous-vivid-orange-background-color { background-color: #ff6900; } -.has-luminous-vivid-amber-background-color { +.has-luminous-vivid-amber-background-color.has-luminous-vivid-amber-background-color { background-color: #fcb900; } -.has-light-green-cyan-background-color { +.has-light-green-cyan-background-color.has-light-green-cyan-background-color { background-color: #7bdcb5; } -.has-vivid-green-cyan-background-color { +.has-vivid-green-cyan-background-color.has-vivid-green-cyan-background-color { background-color: #00d084; } -.has-pale-cyan-blue-background-color { +.has-pale-cyan-blue-background-color.has-pale-cyan-blue-background-color { background-color: #8ed1fc; } -.has-vivid-cyan-blue-background-color { +.has-vivid-cyan-blue-background-color.has-vivid-cyan-blue-background-color { background-color: #0693e3; } -.has-very-light-gray-background-color { +.has-very-light-gray-background-color.has-very-light-gray-background-color { background-color: #eee; } -.has-cyan-bluish-gray-background-color { +.has-cyan-bluish-gray-background-color.has-cyan-bluish-gray-background-color { background-color: #abb8c3; } -.has-very-dark-gray-background-color { +.has-very-dark-gray-background-color.has-very-dark-gray-background-color { background-color: #313131; } -.has-pale-pink-color { +.has-pale-pink-color.has-pale-pink-color { color: #f78da7; } -.has-vivid-red-color { +.has-vivid-red-color.has-vivid-red-color { color: #cf2e2e; } -.has-luminous-vivid-orange-color { +.has-luminous-vivid-orange-color.has-luminous-vivid-orange-color { color: #ff6900; } -.has-luminous-vivid-amber-color { +.has-luminous-vivid-amber-color.has-luminous-vivid-amber-color { color: #fcb900; } -.has-light-green-cyan-color { +.has-light-green-cyan-color.has-light-green-cyan-color { color: #7bdcb5; } -.has-vivid-green-cyan-color { +.has-vivid-green-cyan-color.has-vivid-green-cyan-color { color: #00d084; } -.has-pale-cyan-blue-color { +.has-pale-cyan-blue-color.has-pale-cyan-blue-color { color: #8ed1fc; } -.has-vivid-cyan-blue-color { +.has-vivid-cyan-blue-color.has-vivid-cyan-blue-color { color: #0693e3; } -.has-very-light-gray-color { +.has-very-light-gray-color.has-very-light-gray-color { color: #eee; } -.has-cyan-bluish-gray-color { +.has-cyan-bluish-gray-color.has-cyan-bluish-gray-color { color: #abb8c3; } -.has-very-dark-gray-color { +.has-very-dark-gray-color.has-very-dark-gray-color { color: #313131; } @@ -128,6 +131,6 @@ } .has-larger-font-size, // not used now, kept because of backward compatibility. -.has-huge-font-size, { +.has-huge-font-size { font-size: 42px; } diff --git a/packages/block-library/src/video/edit.js b/packages/block-library/src/video/edit.js index 26039e79c85c3a..118bd117606685 100644 --- a/packages/block-library/src/video/edit.js +++ b/packages/block-library/src/video/edit.js @@ -19,6 +19,7 @@ import { InspectorControls, MediaPlaceholder, MediaUpload, + MediaUploadCheck, RichText, mediaUpload, } from '@wordpress/editor'; @@ -207,30 +208,32 @@ class VideoEdit extends Component { { value: 'none', label: __( 'None' ) }, ] } /> -This is an isolated component
+My notice text
+My second line of text
+My notice text
My second line of text
', + { + speak: false, + __unstableHTML: true, + isDismissible: true, + }, + ] ); + + // Verify all but `