diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 799c90da66229..576e78b27a3ee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,11 +2,13 @@
Thank you for thinking about contributing to WordPress' Gutenberg project! If you're unsure of anything, know that you're đŻ welcome to submit an issue or pull request on any topic. The worst that can happen is that you'll be politely directed to the best location to ask your question or to change something in your pull request. We appreciate any sort of contribution and don't want a wall of rules to get in the way of that.
-As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](/CODE_OF_CONDUCT.md).
-Before contributing, we encourage you to read our [Contributing Policy](CONTRIBUTING.md) (you're here already!) and our [Handbook](https://wordpress.org/gutenberg/handbook/). If you have any questions on any of these, please open an issue so we can help clarify them.
+Before contributing, we encourage you to review the [Contributor Handbook](https://wordpress.org/gutenberg/handbook/contributors/). If you have any questions, please ask, either in Slack or open an issue in GitHub so we can help clarify.
-All WordPress projects are [licensed under the GPLv2+](LICENSE.md), and all contributions to Gutenberg will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.
+All WordPress projects are [licensed under the GPLv2+](/LICENSE.md), and all contributions to Gutenberg will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.
+
+This document covers the technical details around setup, and submitting your contribution to the Gutenberg project.
## Getting Started
@@ -60,7 +62,7 @@ Welcome to...
```
The WordPress installation should be available at `http://localhost:8888` (**Username**: `admin`, **Password**: `password`).
-Inside the "docker" directory, you can use any docker command to interact with your containers. If this port is in use, you can override it in your `docker-compose.override.yml` file. If you're running [e2e tests](https://wordpress.org/gutenberg/handbook/reference/testing-overview/#end-to-end-testing), this change will be used correctly.
+Inside the "docker" directory, you can use any docker command to interact with your containers. If this port is in use, you can override it in your `docker-compose.override.yml` file. If you're running [e2e tests](/docs/contributors/testing-overview.md#end-to-end-testing), this change will be used correctly.
To bring down this local WordPress instance later run:
```
@@ -104,137 +106,17 @@ For example, `add/gallery-block` means you're working on adding a new gallery bl
You can pick among all the tickets, or some of the ones labelled Good First Issue.
-The workflow is documented in greater detail in the [repository management](./docs/contributors/repository-management.md) document.
+The workflow is documented in greater detail in the [repository management](/docs/contributors/repository-management.md) document.
## Testing
-Gutenberg contains both PHP and JavaScript code and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](./docs/contributors/testing-overview.md).
+Gutenberg contains both PHP and JavaScript code and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](/docs/contributors/testing-overview.md).
## Managing Packages
-This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm].
-
-### Creating a New Package
-
-When creating a new package, you need to provide at least the following:
-
-1. `package.json` based on the template:
- ```json
- {
- "name": "@wordpress/package-name",
- "version": "1.0.0-beta.0",
- "description": "Package description.",
- "author": "The WordPress Contributors",
- "license": "GPL-2.0-or-later",
- "keywords": [
- "wordpress"
- ],
- "homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/package-name/README.md",
- "repository": {
- "type": "git",
- "url": "https://github.com/WordPress/gutenberg.git"
- },
- "bugs": {
- "url": "https://github.com/WordPress/gutenberg/issues"
- },
- "main": "build/index.js",
- "module": "build-module/index.js",
- "react-native": "src/index",
- "dependencies": {
- "@babel/runtime": "^7.0.0"
- },
- "publishConfig": {
- "access": "public"
- }
- }
- ```
- This assumes that your code is located in the `src` folder and will be transpiled with `Babel`.
-2. `.npmrc` file which disables creating `package-lock.json` file for the package:
- ```
- package-lock=false
- ```
-3. `README.md` file containing at least:
- - Package name
- - Package description
- - Installation details
- - Usage example
- - `Code is Poetry` logo (`
`)
-
-### Maintaining Changelogs
-
-Maintaining dozens of npm packages is difficultâit can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. All packages should follow the [Semantic Versioning (`semver`) specification](https://semver.org/).
-
-The developer who proposes a change (pull request) is responsible for choosing the correct version increment (`major`, `minor`, or `patch`) according to the following guidelines:
-
-- Major version X (X.y.z | X > 0) should be changed with any backward incompatible/"breaking" change. This will usually occur at the final stage of deprecating and removing of a feature.
-- Minor version Y (x.Y.z | x > 0) should be changed when you add functionality or change functionality in a backward compatible manner. It must be incremented if any public API functionality is marked as deprecated.
-- Patch version Z (x.y.Z | x > 0) should be incremented when you make backward compatible bug fixes.
-
-When in doubt, refer to [Semantic Versioning specification](https://semver.org/).
-
-_Example:_
-
-```md
-## v1.2.2 (Unreleased)
-
-### Bug Fix
-
-- ...
-- ...
-```
-
-- If you need to add something considered a bug fix, you add the item to `Bug Fix` section and leave the version as 1.2.2.
-- If it's a new feature, you add the item to `New Feature` section and change version to 1.3.0.
-- If it's a breaking change you want to introduce, add the item to `Breaking Change` section and bump the version to 2.0.0.
-- If you struggle to classify a change as one of the above, then it might be not necessary to include it.
-
-The version bump is only necessary if one of the following applies:
- - There are no other unreleased changes.
- - The type of change you're introducing is incompatible (more severe) than the other unreleased changes.
-
-### Releasing Packages
-
-Lerna automatically releases all outdated packages. To check which packages are outdated and will be released, type `npm run publish:check`.
-
-If you have the ability to publish packages, you _must_ have [2FA enabled](https://docs.npmjs.com/getting-started/using-two-factor-authentication) on your [npm account][npm].
-
-#### Before Releasing
-
-Confirm that you're logged in to [npm], by running `npm whoami`. If you're not logged in, run `npm adduser` to login.
-
-If you're publishing a new package, ensure that its `package.json` file contains the correct `publishConfig` settings:
-
-```json
-{
- "publishConfig": {
- "access": "public"
- }
-}
-```
-
-You can check your package configs by running `npm run lint-pkg-json`.
-
-#### Development Release
-
-Run the following command to release a dev version of the outdated packages, replacing `123456` with your 2FA code. Make sure you're using a freshly generated 2FA code, rather than one that's about to timeout. This is a little cumbersome but helps to prevent the release process from dying mid-deploy.
-
-```bash
-NPM_CONFIG_OTP=123456 npm run publish:dev
-```
-
-Lerna will ask you which version number you want to choose for each package. For a `dev` release, you'll more likely want to choose the "prerelease" option. Repeat the same for all the outdated packages and confirm your version updates.
-
-Lerna will then publish to [npm], commit the `package.json` changes and create the git tags.
-
-#### Production Release
-
-To release a production version for the outdated packages, run the following command, replacing `123456` with your (freshly generated, as above) 2FA code:
-
-```bash
-NPM_CONFIG_OTP=123456 npm run publish:prod
-```
+This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm]. This enforces certain steps in the workflow which are described in details in [packages](/packages/README.md) documentation.
-Choose the correct version based on `CHANGELOG.md` files, confirm your choices and let Lerna do its magic.
+Maintaining dozens of npm packages is difficultâit can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. As a contributor you should add an entry to the aforementioned file each time you contribute adding production code as described in [Maintaining Changelogs](/packages/README.md#maintaining-changelogs) section.
## How Can Designers Contribute?
@@ -242,17 +124,17 @@ If you'd like to contribute to the design or front-end, feel free to contribute
## Contribute to the Documentation
-Documentation is automatically synced from master to the [Gutenberg Documentation Website](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
+Please see the [Documentation section](/docs/contributors/document.md) of the Contributor Handbook.
-To add a new documentation page, you'll have to create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder and add an item to the [root-manifest.json](https://github.com/WordPress/gutenberg/blob/master/docs/root-manifest.json).
+Documentation is automatically synced from `master` to the [Gutenberg Handbook](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
### `@wordpress/component`
-If you're contributing to the documentation of any component from the `@wordpress/component` package, take a look at its [guidelines for contributing](./packages/components/CONTRIBUTING.md).
+If you're contributing to the documentation of any component from the `@wordpress/component` package, take a look at its [guidelines for contributing](/packages/components/CONTRIBUTING.md).
## Reporting Security Issues
-Please see [SECURITY.md](./SECURITY.md).
+Please see [SECURITY.md](/SECURITY.md).
## Localizing Gutenberg Plugin
diff --git a/bin/generate-public-grammar.js b/bin/generate-public-grammar.js
index a049d1674f36d..c56ec4398a894 100755
--- a/bin/generate-public-grammar.js
+++ b/bin/generate-public-grammar.js
@@ -93,7 +93,7 @@ function flatten( expression ) {
fs.writeFileSync(
path.join( __dirname, '..', 'docs', 'grammar.md' ), `
-# The Gutenberg block grammar
+# Block Grammar
${ flatten( grammar ) }
` );
diff --git a/docs/contributors/coding-guidelines.md b/docs/contributors/coding-guidelines.md
index c47fda1ab070a..1b4524ffcf9ac 100644
--- a/docs/contributors/coding-guidelines.md
+++ b/docs/contributors/coding-guidelines.md
@@ -102,76 +102,30 @@ If an API must be exposed but is clearly not intended to be supported into the f
export { __unstableDoAction } from './api';
```
-### Variable Naming
+### Objects
-Gutenberg inherits [WordPress' naming conventions of camel-casing](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#naming-conventions):
-
->Variable and function names should be full words, using camel case with a lowercase first letter. This is an area where this standard differs from the WordPress PHP coding standards.
->
->Constructors intended for use with `new` should have a capital first letter (UpperCamelCase).
-
-However, Gutenberg is more specific about its handling of abbreviations, acronyms, constants, and the ES2015 class construct.
-
-#### Abbreviations and Acronyms
-
-[*Abbreviations*](https://en.wikipedia.org/wiki/Abbreviation) must be written as camel case, with an initial capitalized letter followed by lowercase letters.
-
-[*Acronyms*](https://en.wikipedia.org/wiki/Acronym) must be written with each of its composing letters capitalized. This is intended to reflect that each letter of the acronym is a proper word in its expanded form.
-
-If an abbreviation or an acronym occurs at the start of a variable name, it must be written to respect the camelcase naming rules covering the first letter of a variable or class definition. For variable assignment, this means writing the abbreviation entirely as lowercase. For class definitions, its initial letter should be capitalized.
-
-**Examples:**
-
-```js
-// "Id" is an abbreviation of "Identifier":
-const userId = 1;
-
-// "DOM" is an acronym of "Document Object Model":
-const currentDOMDocument = window.document;
-
-// Acronyms and abbreviations at the start of a variable name are consistent
-// with camelcase rules covering the first letter of a variable or class.
-const domDocument = window.document;
-class DOMDocument {}
-class IdCollection {}
-```
-
-#### Class Definition
-
-A [`class` definition](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) must use the UpperCamelCase convention, regardless of whether it is intended to be used with `new` construction.
-
-**Example:**
+When possible, use [shorthand notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#New_notations_in_ECMAScript_2015) when defining object property values:
```js
-class Earth {
- static addHuman( human ) {
- Earth.humans.push( human );
- }
-
- static getHumans() {
- return Earth.humans;
- }
-}
-
-Earth.humans = [];
-```
-
-All `@wordpress/element` Components, including stateless function components, should be named using Class Definition naming rules, both for consistency and to reflect the fact that a component may need to be transitioned from a function to a class without breaking compatibility.
-
-**Examples:**
+const a = 10;
-```js
-class MyComponent extends Component {}
+// Bad:
+const object = {
+ a: a,
+ performAction: function() {
+ // ...
+ },
+};
-function MyComponent() {}
+// Good:
+const object = {
+ a,
+ performAction() {
+ // ...
+ },
+};
```
-#### Constants
-
-An exception to camel case is made for constant values which are never intended to be reassigned or mutated. Such variables must use the [SCREAMING_SNAKE_CASE convention](https://en.wikipedia.org/wiki/Snake_case).
-
-In almost all cases, a constant should be defined in the top-most scope of a file. It is important to note that [JavaScript's `const` assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) is conceptually more limited than what is implied here, where a value assigned by `const` in JavaScript can in-fact be mutated, and is only protected against reassignment. A constant as defined in these coding guidelines applies only to values which are expected to never change, and is a strategy for developers to communicate intent more so than it is a technical restriction.
-
### Strings
String literals should be declared with single-quotes *unless* the string itself contains a single-quote that would need to be escapedâin that case: use a double-quote. If the string contains a single-quote *and* a double-quote, you can use ES6 template strings to avoid escaping the quotes.
diff --git a/docs/contributors/copy-guide.md b/docs/contributors/copy-guide.md
index 5e0066a689604..e5505e30f3acb 100644
--- a/docs/contributors/copy-guide.md
+++ b/docs/contributors/copy-guide.md
@@ -1,4 +1,4 @@
-# Gutencopy Guidelines
+# Copy Guidelines
## Longer Text
Guidelines for writing multi-line/step instructions or narrative introductions/orientation to pages or features.
@@ -8,7 +8,7 @@ This will obviously vary quite a lot depending on the context, but here are some
#### ONE: Contractions are your friends!
Theyâre more conversational, and a simple way to make text sound friendlier and less formal. (And they save a bit of space as well: a win-win.)
-#### TWO: Cut phrases that inflate your word count without actually adding meaning.
+#### TWO: Cut phrases that inflate your word count without actually adding meaning.
This happens frequently in two specific instances. First, when writing in the passive voice:
> This block can be used to display single images.
@@ -25,7 +25,7 @@ Does it or doesnât it? Weâre making this software: weâre allowed to be dec
> The gallery block displays multiple images in an elegant layout.
-We also all do this a lot with the phrase âallows you to.â
+We also all do this a lot with the phrase âallows you to.â
> Preformatted text allows you to keep your tabs and line breaks.
@@ -33,9 +33,9 @@ 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.â
+#### 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â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.â
@@ -43,7 +43,7 @@ Itâs also safer and more helpful to be specific. âEasyâ and âsimpleâ a
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,7 +51,7 @@ 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!
@@ -60,7 +60,7 @@ GOOD:
> * 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.
@@ -101,7 +101,7 @@ If your list is more persuasive (e.g., trying to convince someone to use a featu
>* 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.
@@ -120,7 +120,7 @@ LESS GOOD:
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.
#### FOUR: Bold is sometimes your friend.
-Use it to focus readers on the key information in a bulleted list. This is especially useful when your bullets include some supplemental but ultimately secondary information.
+Use it to focus readers on the key information in a bulleted list. This is especially useful when your bullets include some supplemental but ultimately secondary information.
âKey informationâ is, well, key: bold draws the eye, so stick to the most vital piece of information in a given bullet:
@@ -136,7 +136,7 @@ On the flipside, bolding too many things creates visual confusion:
> * 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**.
@@ -148,7 +148,7 @@ The lack of words creates its own focus; you don't have to add any more.
## UI Descriptions
Guidelines for writing one-line feature descriptions, or short descriptions to clarify options.
-#### ONE: Clarity above all!
+#### 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.
#### TWO: Refer back to section one, and look out for those bulk-adding phrases.
@@ -187,7 +187,7 @@ And when something means everything, it actually means nothing. The more specifi
#### 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.
-Single lines of description can still be complete sentences.
+Single lines of description can still be complete sentences.
> List. Numbered or bulleted.
@@ -195,7 +195,7 @@ vs.
> Add a list, either numbered or bulleted.
-You can still use contractions.
+You can still use contractions.
> Add a list. We will provide formatting options.
@@ -203,7 +203,7 @@ vs.
> 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.
diff --git a/docs/contributors/design.md b/docs/contributors/design.md
index 7b037fd3a4c94..bd68ba060718e 100644
--- a/docs/contributors/design.md
+++ b/docs/contributors/design.md
@@ -1,4 +1,4 @@
-# Gutenberg Design Principles & Vision
+# Design Principles & Vision
This is a living document that outlines the design principles and patterns of the editor interface. Its aim is to explain the background of the design, inform future improvements, and help people design great blocks.
diff --git a/docs/contributors/develop.md b/docs/contributors/develop.md
new file mode 100644
index 0000000000000..97fa91aab0f78
--- /dev/null
+++ b/docs/contributors/develop.md
@@ -0,0 +1,11 @@
+# Developer Contributions
+
+Please see [CONTRIBUTING.md](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details on how to setup and make contributions to the Gutenberg repository.
+
+The following resources offer additional information for developers who wish to contribute to Gutenberg:
+
+* [Coding Guidelines](/docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
+* [Gutenberg Block Grammar](/docs/contributors/grammar.md)
+* [Testing Overview](/docs/contributors/testing-overview.md) for PHP and JavaScript development in Gutenberg.
+* [Scripts](/docs/contributors/scripts.md) a list of vendor and internal scripts available to plugin developers.
+* [Gutenberg Release Process](/docs/contributors/release.md) a checklist for the different type of releases for Gutenberg project.
diff --git a/docs/contributors/document.md b/docs/contributors/document.md
new file mode 100644
index 0000000000000..f51578d99e3c3
--- /dev/null
+++ b/docs/contributors/document.md
@@ -0,0 +1,34 @@
+# Documentation Contributions
+
+Documentation for Gutenberg is maintained in the `/docs/` directory in the same Gutenberg Github repository. The docs are published every 15 minutes to the [Gutenberg Handbook site](https://wordpress.org/gutenberg/handbook/).
+
+## New Document
+
+To add a new documentation page:
+
+1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder
+2. Add item to the [toc.json](https://github.com/WordPress/gutenberg/blob/master/docs/toc.json) hierarchy
+3. Update manifest.json by running `npm run docs:build`
+4. Commit manifest.json with other files updated
+
+## Using Links
+
+It's very likely that at some point you will want to link to other documentation pages. It's worth emphasizing that all documents can be browsed in different contexts:
+
+- Gutenberg Handbook
+- GitHub website
+- npm website
+
+To create links that work in all contexts, you should use absolute path links without the `https://github.com/WordPress/gutenberg` prefix. You can reference files using the following patterns:
+
+- `/docs/*.md`
+- `/packages/*/README.md`
+- `/packages/components/src/**/README.md`
+
+This way they will be properly handled in all three aforementioned contexts.
+
+## Resources
+
+* [Copy Guidelines](/docs/contributors/copy-guide.md) for writing instructions, documentations, or other contributions to Gutenberg project.
+
+* [Tone and Voice Guide](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/) from WordPress Documentation.
diff --git a/docs/contributors/grammar.md b/docs/contributors/grammar.md
index ac6015b9a2dc7..7d7e9bf73b8c0 100644
--- a/docs/contributors/grammar.md
+++ b/docs/contributors/grammar.md
@@ -1,5 +1,5 @@
-# The Gutenberg block grammar
+# Block Grammar
Block_Name = Namespaced_Block_Name
diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md
index 9df69e7ac58b6..208a1eaf707e1 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -1,8 +1,58 @@
# Outreach
-This will include talks, meetups and anything the community is doing to discuss, learn about, and contribute to Gutenberg. This is not an exhaustive list, if we are missing your event just let us know.
+This includes articles, talks, demos and anything the community is doing to discuss, learn about, and contribute to Gutenberg. This is not an exhaustive list; if we are missing your event or article, just let us know.
+
+## Articles
+
+A short list of useful articles around defining, extending, and contributing to Gutenberg.
+
+### Overviews of Gutenberg
+
+- [Gutenberg, or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/), MatĂas Ventura Bausero (October 2017)
+- [We Called It Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/), Matt Mullenweg (August 2017)
+- [How Gutenberg is Changing WordPress Development](https://riad.blog/2017/10/06/how-gutenberg-is-changing-wordpress-development/), Riad Benguella (October 2017)
+- [How Gutenberg Will Shape the Future of WordPress](https://www.linkedin.com/pulse/gutenberg-morten-rand-hendriksen/), Morten Rand-Henrikson (August 2017)
+
+### Extending Gutenberg
+
+- [With Gutenberg, what happens to my Custom Fields?](https://riad.blog/2017/12/11/with-gutenberg-what-happens-to-my-custom-fields/), Riad Benguella (December 2017)
+- [One thousand and one ways to extend Gutenberg today](https://riad.blog/2017/10/16/one-thousand-and-one-way-to-extend-gutenberg-today/), Riad Benguella (October 2017)
+- [Gutenberg Plugin Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate/), Ahmad Awais (August 2017)
+
+### Community Contribution
+
+- [Gutenberg Block Library](https://editorblockswp.com/library), Danny Cooper (August 2018)
+- [A zero-configuration developer toolkit for building WordPress Gutenberg block plugins](https://ahmadawais.com/create-guten-block-toolkit/), Ahmad Awais (January 2018)
+- [Contributing to Gutenberg Without Code](https://wordimpress.com/a-pot-stirrer-amongst-chefs-contributing-to-gutenberg-without-code/), Kevin Hoffman (August 2017)
+- [Testing Flow in Gutenberg: Instructions for how to contribute to usability testing](https://make.wordpress.org/test/2017/11/22/testing-flow-in-gutenberg/), Anna Harrison (November 2017)
+
+### Article Compilations
+
+- [Curated Collection of Gutenberg Articles, Plugins, Blocks, Tutorials, etc](http://gutenberghub.com/), By Munir Kamal
+- [Articles about Gutenberg](https://github.com/WordPress/gutenberg/issues/1419) (Github Issue thread with links)
+- [Gutenberg articles on ManageWP.org](https://managewp.org/search?q=gutenberg)
+- [Gutenberg Times](https://gutenbergtimes.com/category/updates/)
+
+## Talks
+
+Talks given about Gutenberg, including slides and videos as they are available.
+
+### Slides
+- [The new core WordPress editor](http://kimb.me/talk-bigwp-london-new-core-wordpress-editor/) at BigWP London (18. May 2017)
+- [Gutenberg Notes](http://haiku2.com/2017/09/bend-wordpress-meetup-gutenberg-notes/) at Bend WordPress Meetup (5. September 2017)
+- [Gutenberg and the Future of Content in WordPress](https://www.slideshare.net/andrewmduthie/gutenberg-and-the-future-of-content-in-wordpress) (20. September 2017)
+- [Head first into Gutenberg](https://speakerdeck.com/prtksxna/head-first-into-gutenberg) at the [WordPress Goa Meet-up](https://www.meetup.com/WordPressGoa/events/245275573/) (1. December 2017)
+- [Gutenberg : vers une approche plus fine du contenu](https://imathi.eu/2018/02/16/gutenberg-vers-une-approche-plus-fine-du-contenu/) at [WP Paris](https://wpparis.fr/) (8. February 2018)
+
+### Videos
+- [All `Gutenberg` tagged Talks at WordPress.tv](https://wordpress.tv/tag/gutenberg/)
+- 2018-Jun - [Beyond Gutenberg](https://wordpress.tv/2018/07/09/matias-ventura-beyond-gutenberg/) by MatĂas Ventura
+- 2018-Jun - [Anatomy of a block: Gutenberg design patterns](https://wordpress.tv/2018/07/08/tammie-lister-anatomy-of-a-block-gutenberg-design-patterns/) by Tammie Lister
+- 2017-Dec - [State of the Word 2017](https://wordpress.tv/2017/12/04/matt-mullenweg-state-of-the-word-2017/) by Matt Mullenweg (Gutenberg demo by MatĂas Ventura at 35:00)
+- [Gutenberg is Coming (Donât Be Afraid)](https://training.ithemes.com/webinar/gutenberg-is-coming-dont-be-afraid/) from iThemes Training
## Showcases or demonstrations:
+
https://wpleeds.co.uk/events/plugins-gutenberg-wordpress-leeds-july-2017/
http://kimb.me/talk-bigwp-london-new-core-wordpress-editor
@@ -13,15 +63,3 @@ https://www.meetup.com/WordPress-Melbourne/events/241543639
https://wpmeetups.de/termin/29-wp-meetup-stuttgart-gutenberg-editor-rueckblick-wordcamp-europe/
-## Testing events:
-https://www.meetup.com/Turku-WordPress-Meetup/events/241195076/
-
-https://www.meetup.com/Vancouver-WordPress-Meetup-Group/events/241575161/
-
-## Calls for testing:
-https://make.wordpress.org/test/2017/06/27/call-for-testing-gutenberg/
-
-http://www.wpswfl.org/new-wordpress-editor-gutenberg-early-beta-needs-testers/
-
-https://gutenberg.eastbaywp.com
-
diff --git a/docs/contributors/outreach/articles.md b/docs/contributors/outreach/articles.md
deleted file mode 100644
index fe4bce7e328a8..0000000000000
--- a/docs/contributors/outreach/articles.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Articles
-
-This includes useful articles for those wanting to run a meetup or promote Gutenberg.
-
-## Overviews of Gutenberg
-
-- [Gutenberg, or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/), MatĂas Ventura Bausero (October 2017)
-- [We Called It Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/), Matt Mullenweg (August 2017)
-- [How Gutenberg is Changing WordPress Development](https://riad.blog/2017/10/06/how-gutenberg-is-changing-wordpress-development/), Riad Benguella (October 2017)
-- [How Gutenberg Will Shape the Future of WordPress](https://www.linkedin.com/pulse/gutenberg-morten-rand-hendriksen/), Morten Rand-Henrikson (August 2017)
-
-## Extending Gutenberg
-
-- [With Gutenberg, what happens to my Custom Fields?](https://riad.blog/2017/12/11/with-gutenberg-what-happens-to-my-custom-fields/), Riad Benguella (December 2017)
-- [One thousand and one ways to extend Gutenberg today](https://riad.blog/2017/10/16/one-thousand-and-one-way-to-extend-gutenberg-today/), Riad Benguella (October 2017)
-- [Gutenberg Plugin Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate/), Ahmad Awais (August 2017)
-
-## Community Contribution
-
-- [Gutenberg Block Library](https://editorblockswp.com/library), Danny Cooper (August 2018)
-- [A zero-configuration developer toolkit for building WordPress Gutenberg block plugins](https://ahmadawais.com/create-guten-block-toolkit/), Ahmad Awais (January 2018)
-- [Contributing to Gutenberg Without Code](https://wordimpress.com/a-pot-stirrer-amongst-chefs-contributing-to-gutenberg-without-code/), Kevin Hoffman (August 2017)
-- [Testing Flow in Gutenberg: Instructions for how to contribute to usability testing](https://make.wordpress.org/test/2017/11/22/testing-flow-in-gutenberg/), Anna Harrison (November 2017)
-
-## Article Compilations
-
-- [Curated Collection of Gutenberg Articles, Plugins, Blocks, Tutorials, etc](http://gutenberghub.com/), By Munir Kamal
-- [Articles about Gutenberg](https://github.com/WordPress/gutenberg/issues/1419) (Github Issue thread with links)
-- [Gutenberg articles on ManageWP.org](https://managewp.org/search?q=gutenberg)
-- [Gutenberg Times](https://gutenbergtimes.com/category/updates/)
diff --git a/docs/contributors/outreach/meetups.md b/docs/contributors/outreach/meetups.md
deleted file mode 100644
index 58cd8bbb72c99..0000000000000
--- a/docs/contributors/outreach/meetups.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Meetups
-
-A list of meetups about Gutenberg so far:
-
-- [Gutenberg and the Future of WordPress](https://www.meetup.com/Vancouver-WordPress-Meetup-Group/events/241575161/), Vancouver, Canada
-- [Page builders and the upcoming Gutenberg Editor](https://www.meetup.com/Turku-WordPress-Meetup/events/241195076/), Turku, Finland
-- [Discussion about Gutenberg](https://www.facebook.com/events/278785795934302/), Andria, Italy
-- [Plugins and Gutenberg](https://wpleeds.co.uk/events/plugins-gutenberg-wordpress-leeds-july-2017/), Leeds, UK
-- [Gutenberg Introduction & Demo](https://www.meetup.com/WordPress-Melbourne/events/241543639/), Melbourne, Australia
-- [Gutenberg Editor & Review](https://wpmeetups.de/termin/29-wp-meetup-stuttgart-gutenberg-editor-rueckblick-wordcamp-europe/), WordCamp Europe
-- [Diving into Gutenberg by Tammie Lister](https://www.meetup.com/Big-Media-Enterprise-WordPress-London-Meetup/events/243302081/), London, UK
-- [What's New In WordPress 4.9 and Gutenberg 1.5](https://www.meetup.com/Tuscaloosa-WordPress-Meetup/events/244584939/), Tuscaloosa, Alabama, USA
-- [WordPress & JavaScript: Let's talk Gutenberg!](https://www.meetup.com/WordPress-Lahore/events/246446478/), Lahore, PK
-- [The state of Gutenberg](https://www.meetup.com/WP-Porto/events/245585131/), Porto, Portugal
-- [Discuss and learn about the new WordPress Editor : Gutenberg](https://www.meetup.com/Pune-WordPress-Knowledge-Exchange/events/248496830/), Pune, India
-- [An Introduction to Gutenberg](https://www.meetup.com/Okanagan-WordPress-Meetup/events/249167218/), Vernon, BC, Canada
-- [WordPress 5.0 - Gutenberg is upon us](https://www.meetup.com/WordPress-Perth/events/249490075/), Perth, Australia
diff --git a/docs/contributors/outreach/resources.md b/docs/contributors/outreach/resources.md
deleted file mode 100644
index 3c5dd598f6085..0000000000000
--- a/docs/contributors/outreach/resources.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Resources
-
-All resources here can be used by anyone. Feel free to use the decks to make your own talks or to use the gifs in your blog posts and other resources.
-
-## Slidedecks to use
-
-- v1: https://cloudup.com/cqEJppQ8m-5 : August 2017
-
-## Gif collection to use
-
-- https://cloudup.com/c9OKU3OJD9r
diff --git a/docs/contributors/outreach/talks.md b/docs/contributors/outreach/talks.md
deleted file mode 100644
index a21f9c468c481..0000000000000
--- a/docs/contributors/outreach/talks.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Talks
-
-Talks given about Gutenberg, including slides and videos as they are available.
-
-## Slides
-- [The new core WordPress editor](http://kimb.me/talk-bigwp-london-new-core-wordpress-editor/) at BigWP London (18. May 2017)
-- [Gutenberg Notes](http://haiku2.com/2017/09/bend-wordpress-meetup-gutenberg-notes/) at Bend WordPress Meetup (5. September 2017)
-- [Gutenberg and the Future of Content in WordPress](https://www.slideshare.net/andrewmduthie/gutenberg-and-the-future-of-content-in-wordpress) (20. September 2017)
-- [Head first into Gutenberg](https://speakerdeck.com/prtksxna/head-first-into-gutenberg) at the [WordPress Goa Meet-up](https://www.meetup.com/WordPressGoa/events/245275573/) (1. December 2017)
-- [Gutenberg : vers une approche plus fine du contenu](https://imathi.eu/2018/02/16/gutenberg-vers-une-approche-plus-fine-du-contenu/) at [WP Paris](https://wpparis.fr/) (8. February 2018)
-
-## Videos
-- [All `Gutenberg` tagged Talks at WordPress.tv](https://wordpress.tv/tag/gutenberg/)
-- 2018-Jun - [Beyond Gutenberg](https://wordpress.tv/2018/07/09/matias-ventura-beyond-gutenberg/) by MatĂas Ventura
-- 2018-Jun - [Anatomy of a block: Gutenberg design patterns](https://wordpress.tv/2018/07/08/tammie-lister-anatomy-of-a-block-gutenberg-design-patterns/) by Tammie Lister
-- 2017-Dec - [State of the Word 2017](https://wordpress.tv/2017/12/04/matt-mullenweg-state-of-the-word-2017/) by Matt Mullenweg (Gutenberg demo by MatĂas Ventura at 35:00)
-- [Gutenberg is Coming (Donât Be Afraid)](https://training.ithemes.com/webinar/gutenberg-is-coming-dont-be-afraid/) from iThemes Training
diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
index 1feaadfcbf5b9..e3979c229e25c 100644
--- a/docs/contributors/readme.md
+++ b/docs/contributors/readme.md
@@ -2,10 +2,17 @@
Welcome to the Gutenberg Project Contributors Guide.
-The following guidelines are in place to create consistency across the project and the numerous contributors. See also the [Contributing Documentation](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details around setup, and submitting your contributions.
+The following guidelines are in place to create consistency across the project and the numerous contributors. See the [Contributing Documentation](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details around setup, and submitting your contributions.
-* [Coding Guidelines](../../docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
-* [Copy Guidelines](../../docs/contributors/copy-guide.md)
-* [Design Principles & Vision](../../docs/contributors/design.md)
+## Philosophy
+
+* [Architecturial and UX Principles of Gutenberg](/docs/contributors/principles.md)
+
+## Sections
+
+The contributors guide has the following different sections by contribution type:
+
+* [Design Contributions](/docs/contributors/design.md)
+* [Developer Contributions](/docs/contributors/develop.md)
+* [Documentation Contributions](/docs/contributors/document.md)
-Please see the table of contents on the left side of the Gutenberg Handbook for the full list of contributor resources.
diff --git a/docs/contributors/repository-management.md b/docs/contributors/repository-management.md
index 132f46d0df1ed..d4e8df0ebf6aa 100644
--- a/docs/contributors/repository-management.md
+++ b/docs/contributors/repository-management.md
@@ -25,13 +25,17 @@ Any issues that are irrelevant or not actionable should be closed, because they
To better organize the issue backlog, all issues should have [one or more labels](https://github.com/WordPress/gutenberg/labels). Here are some you might commonly see:
-- [Accessibility](https://github.com/WordPress/gutenberg/labels/Accessibility) - Changes that impact accessibility and need corresponding review (e.g. markup changes).
+- [Needs Accessibility Feedback](https://github.com/WordPress/gutenberg/labels/Accessibility) - Changes that impact accessibility and need corresponding review (e.g. markup changes).
- [Needs Design Feedback](https://github.com/WordPress/gutenberg/labels/Needs%20Design%20Feedback) - Changes that modify the design or user experience in some way and need sign-off.
- [[Type] Bug](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Bug) - An existing feature is broken in some way.
- [[Type] Enhancement](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Enhancement) - Gutenberg would be better with this improvement added.
- [[Type] Plugin / Extension Conflict](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Plugin%20%2F%20Extension%20Conflict) - Documentation of a conflict between Gutenberg and a plugin or extension. The plugin author should be informed and provided documentation on how to address.
- [[Status] Needs More Info](https://github.com/WordPress/gutenberg/labels/%5BStatus%5D%20Needs%20More%20Info) - The issue needs more information in order to be actionable and relevant. Typically this requires follow-up from the original reporter.
+Workflow labels may be applied as needed and start with âNeedsâ. Ideally, each workflow label will have a group that follows it, such as the Accessibility Team for `Needs Accessibility Feedback`, the Testing Team for `Needs Testing`, etc.
+
+`Priority High` and `Priority OMGWTFBBQ` issues should have an assignee and/or be in an active milestone.
+
[Check out the label directory](https://github.com/WordPress/gutenberg/labels) for a listing of all labels.
### Milestones
diff --git a/docs/designers-developers/designers/block-design.md b/docs/designers-developers/designers/block-design.md
index 8b267c0d754da..3840c863dd487 100644
--- a/docs/designers-developers/designers/block-design.md
+++ b/docs/designers-developers/designers/block-design.md
@@ -17,7 +17,11 @@ Basic block settings wonât always make sense in the context of the placeholder
### The block sidebar should only be used for advanced, tertiary controls
-The sidebar is not visible by default on a small / mobile screen, and may also be collapsed in a desktop view. Therefore, it should not be relied on for anything that is necessary for the basic operation of the block. Pick good defaults, make important actions available in the block toolbar, and think of the sidebar as something that only power users may discover. In addition, use sections and headers in the block sidebar if there are more than a handful of options, in order to allow users to easily scan and understand the options available.
+The sidebar is not visible by default on a small / mobile screen, and may also be collapsed in a desktop view. Therefore, it should not be relied on for anything that is necessary for the basic operation of the block. Pick good defaults, make important actions available in the block toolbar, and think of the sidebar as something that most users should not need to open.
+
+In addition, use sections and headers in the block sidebar if there are more than a handful of options, in order to allow users to easily scan and understand the options available.
+
+Each block sidebar comes with an "Advanced" section by default. This area houses an "Additional CSS Class" field, and should be used to house other power user controls.
## Setup state vs. live preview state
@@ -112,6 +116,10 @@ Because the Drop Cap feature is not necessary for the basic operation of the blo
Check how your block looks, feels, and works on as many devices and screen sizes as you can.
+### Support Gutenberg's dark background editor scheme
+
+Check how your block looks with [dark backgrounds](/docs/designers-developers/developers/themes/theme-support.md#dark-backgrounds) in the editor.
+
## Examples
To demonstrate some of these practices, here are a few annotated examples of default Gutenberg blocks:
diff --git a/docs/designers-developers/developers/README.md b/docs/designers-developers/developers/README.md
index 860e6f3b07310..162c45fbcfa4e 100644
--- a/docs/designers-developers/developers/README.md
+++ b/docs/designers-developers/developers/README.md
@@ -6,40 +6,40 @@ The new editor is highly flexible, like most of WordPress. You can build custom
The editor is about blocks, and the main extensibility API 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/readme.md) is the best place to start.
+If you want to learn more about block creation, the [Blocks Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.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.
+Learn more in the [Block Filters](/docs/designers-developers/developers/filters/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.
+Refer to the [Plugins](/packages/plugins/README.md) and [Edit Post](/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.
+You can also filter certain aspects of the editor; this is documented on the [Editor Filters](/docs/designers-developers/developers/filters/editor-filters.md) page.
## Meta Boxes
-**Porting PHP meta boxes to blocks or sidebar plugins is highly encouraged!**
+Porting PHP meta boxes to blocks or sidebar plugins is highly encouraged, learn how through these [meta data tutorials](/docs/designers-developers/developers/tutorials/metabox/readme.md).
-Discover how [Meta Box](../../../docs/designers-developers/developers/backward-compatibility/meta-box.md) support works in the new editor.
+See how the new editor [supports existing Meta Boxes](/docs/designers-developers/developers/backward-compatibility/meta-box.md).
## 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).
+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.
+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.
+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/backward-compatibility/deprecations.md b/docs/designers-developers/developers/backward-compatibility/deprecations.md
index cf98cdb9fe1dd..fe1ca0b4a287e 100644
--- a/docs/designers-developers/developers/backward-compatibility/deprecations.md
+++ b/docs/designers-developers/developers/backward-compatibility/deprecations.md
@@ -2,6 +2,30 @@
The Gutenberg project's deprecation policy is intended to support backward 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.
+## 5.2.0
+
+- The PHP function `gutenberg_parse_blocks` has been removed. Use [`parse_blocks`](https://developer.wordpress.org/reference/functions/parse_blocks/) instead.
+- The PHP function `get_dynamic_blocks_regex` has been removed.
+- The PHP function `gutenberg_render_block` has been removed. Use [`render_block`](https://developer.wordpress.org/reference/functions/render_block/) instead.
+- The PHP function `strip_dynamic_blocks` has been removed. For use in excerpt preparation, consider [`excerpt_remove_blocks`](https://developer.wordpress.org/reference/functions/excerpt_remove_blocks/) instead.
+- The PHP function `strip_dynamic_blocks_add_filter` has been removed.
+- The PHP function `strip_dynamic_blocks_remove_filter` has been removed.
+- The PHP function `gutenberg_post_has_blocks` has been removed. Use [`has_blocks`](https://developer.wordpress.org/reference/functions/has_blocks/) instead.
+- The PHP function `gutenberg_content_has_blocks` has been removed. Use [`has_blocks`](https://developer.wordpress.org/reference/functions/has_blocks/) instead.
+- The PHP function `gutenberg_register_rest_routes` has been removed.
+- The PHP function `gutenberg_add_taxonomy_visibility_field` has been removed.
+- The PHP function `gutenberg_get_taxonomy_visibility_data` has been removed.
+- The PHP function `gutenberg_add_permalink_template_to_posts` has been removed.
+- The PHP function `gutenberg_add_block_format_to_post_content` has been removed.
+- The PHP function `gutenberg_add_target_schema_to_links` has been removed.
+- The PHP function `gutenberg_register_post_prepare_functions` has been removed.
+- The PHP function `gutenberg_silence_rest_errors` has been removed.
+- The PHP function `gutenberg_filter_post_type_labels` has been removed.
+- The PHP function `gutenberg_remove_wpcom_markdown_support` has been removed.
+- The PHP function `gutenberg_bulk_post_updated_messages` has been removed.
+- The PHP function `gutenberg_kses_allowedtags` has been removed.
+- The PHP function `gutenberg_add_responsive_body_class` has been removed.
+
## 4.5.0
- `Dropdown.refresh()` has been deprecated as the contained `Popover` is now automatically refreshed.
- `wp.editor.PostPublishPanelToggle` has been deprecated in favor of `wp.editor.PostPublishButton`.
diff --git a/docs/designers-developers/developers/backward-compatibility/meta-box.md b/docs/designers-developers/developers/backward-compatibility/meta-box.md
index 5403ebf674ac3..e6268e6924ea9 100644
--- a/docs/designers-developers/developers/backward-compatibility/meta-box.md
+++ b/docs/designers-developers/developers/backward-compatibility/meta-box.md
@@ -1,6 +1,6 @@
# Meta Boxes
-This is a brief document detailing how meta box support works in Gutenberg. With the superior developer and user experience of blocks, especially once block templates are available, **porting PHP meta boxes to blocks is highly encouraged!**
+This is a brief document detailing how meta box support works in Gutenberg. With the superior developer and user experience of blocks, especially once block templates are available, **porting PHP meta boxes to blocks is highly encouraged!** See the [Meta Block tutorial](/docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md) for how to store post meta data using blocks.
### Testing, Converting, and Maintaining Existing Meta Boxes
diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md
index 2a98c3bb5d397..9b01fe325c295 100644
--- a/docs/designers-developers/developers/data/data-core.md
+++ b/docs/designers-developers/developers/data/data-core.md
@@ -136,17 +136,50 @@ get back from the oEmbed preview API.
Is the preview for the URL an oEmbed link fallback.
-### hasUploadPermissions
+### hasUploadPermissions (deprecated)
-Return Upload Permissions.
+Returns whether the current user can upload media.
+
+Calling this may trigger an OPTIONS request to the REST API via the
+`canUser()` resolver.
+
+https://developer.wordpress.org/rest-api/reference/
+
+*Deprecated*
+
+Deprecated since 5.0. Callers should use the more generic `canUser()` selector instead of
+ `hasUploadPermissions()`, e.g. `canUser( 'create', 'media' )`.
*Parameters*
- * state: State tree.
+ * state: Data state.
*Returns*
-Upload Permissions.
+Whether or not the user can upload media. Defaults to `true` if the OPTIONS
+ request is being made.
+
+### canUser
+
+Returns whether the current user can perform the given action on the given
+REST resource.
+
+Calling this may trigger an OPTIONS request to the REST API via the
+`canUser()` resolver.
+
+https://developer.wordpress.org/rest-api/reference/
+
+*Parameters*
+
+ * state: Data state.
+ * action: Action to check. One of: 'create', 'read', 'update', 'delete'.
+ * resource: REST resource to check, e.g. 'media' or 'posts'.
+ * id: Optional ID of the rest resource to check.
+
+*Returns*
+
+Whether or not the user can perform the action,
+ or `undefined` if the OPTIONS request is still being made.
## Actions
@@ -213,4 +246,14 @@ Returns an action object used in signalling that Upload permissions have been re
*Parameters*
- * hasUploadPermissions: Does the user have permission to upload files?
\ No newline at end of file
+ * hasUploadPermissions: Does the user have permission to upload files?
+
+### receiveUserPermission
+
+Returns an action object used in signalling that the current user has
+permission to perform an action on a REST resource.
+
+*Parameters*
+
+ * key: A key that represents the action and REST resource.
+ * isAllowed: Whether or not the user can perform the action.
\ No newline at end of file
diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md
index 4f28cf17a9f18..cc4f71bb95540 100644
--- a/docs/designers-developers/developers/filters/block-filters.md
+++ b/docs/designers-developers/developers/filters/block-filters.md
@@ -261,8 +261,9 @@ Adding blocks is easy enough, removing them is as easy. Plugin or theme authors
```js
// my-plugin.js
-
-wp.blocks.unregisterBlockType( 'core/verse' );
+wp.domReady( function() {
+ wp.blocks.unregisterBlockType( 'core/verse' );
+} );
```
and load this script in the Editor
@@ -275,7 +276,7 @@ function my_plugin_blacklist_blocks() {
wp_enqueue_script(
'my-plugin-blacklist-blocks',
plugins_url( 'my-plugin.js', __FILE__ ),
- array( 'wp-blocks' )
+ array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' )
);
}
add_action( 'enqueue_block_editor_assets', 'my_plugin_blacklist_blocks' );
diff --git a/docs/grammar.md b/docs/grammar.md
new file mode 100644
index 0000000000000..1bbe77dc5ecf0
--- /dev/null
+++ b/docs/grammar.md
@@ -0,0 +1,6 @@
+
+# Block Grammar
+
+
';
- _e( 'Gutenberg requires WordPress 4.9.8 or later to function properly. Please upgrade WordPress before activating Gutenberg.', 'gutenberg' );
+ _e( 'Gutenberg requires WordPress 5.0.0 or later to function properly. Please upgrade WordPress before activating Gutenberg.', 'gutenberg' );
echo '
';
deactivate_plugins( array( 'gutenberg/gutenberg.php' ) );
@@ -186,17 +180,13 @@ function gutenberg_pre_init() {
// Strip '-src' from the version string. Messes up version_compare().
$version = str_replace( '-src', '', $wp_version );
- if ( version_compare( $version, '4.9.8', '<' ) ) {
+ if ( version_compare( $version, '5.0.0', '<' ) ) {
add_action( 'admin_notices', 'gutenberg_wordpress_version_notice' );
return;
}
require_once dirname( __FILE__ ) . '/lib/load.php';
- if ( function_exists( 'gutenberg_silence_rest_errors' ) ) {
- gutenberg_silence_rest_errors();
- }
-
add_filter( 'replace_editor', 'gutenberg_init', 10, 2 );
}
@@ -537,33 +527,29 @@ function gutenberg_add_admin_body_class( $classes ) {
* Adds attributes to kses allowed tags that aren't in the default list
* and that Gutenberg needs to save blocks such as the Gallery block.
*
+ * @deprecated 5.0.0
+ *
* @param array $tags Allowed HTML.
* @return array (Maybe) modified allowed HTML.
*/
function gutenberg_kses_allowedtags( $tags ) {
- if ( isset( $tags['img'] ) ) {
- $tags['img']['data-link'] = true;
- $tags['img']['data-id'] = true;
- }
+ _deprecated_function( __FUNCTION__, '5.0.0' );
+
return $tags;
}
-add_filter( 'wp_kses_allowed_html', 'gutenberg_kses_allowedtags', 10, 2 );
-
/**
* Adds the wp-embed-responsive class to the body tag if the theme has opted in to
* Gutenberg responsive embeds.
*
* @since 4.1.0
+ * @deprecated 5.0.0
*
* @param Array $classes Array of classes being added to the body tag.
* @return Array The $classes array, with wp-embed-responsive appended.
*/
function gutenberg_add_responsive_body_class( $classes ) {
- if ( current_theme_supports( 'responsive-embeds' ) ) {
- $classes[] = 'wp-embed-responsive';
- }
+ _deprecated_function( __FUNCTION__, '5.0.0' );
+
return $classes;
}
-
-add_filter( 'body_class', 'gutenberg_add_responsive_body_class' );
diff --git a/lib/blocks.php b/lib/blocks.php
index 0b11041d0576d..3419e81c8bb38 100644
--- a/lib/blocks.php
+++ b/lib/blocks.php
@@ -9,89 +9,20 @@
die( 'Silence is golden.' );
}
-if ( ! function_exists( 'register_block_type' ) ) {
- /**
- * Registers a block type.
- *
- * @since 0.1.0
- * @since 0.6.0 Now also accepts a WP_Block_Type instance as first parameter.
- *
- * @param string|WP_Block_Type $name Block type name including namespace, or alternatively a
- * complete WP_Block_Type instance. In case a WP_Block_Type
- * is provided, the $args parameter will be ignored.
- * @param array $args {
- * Optional. Array of block type arguments. Any arguments may be defined, however the
- * ones described below are supported by default. Default empty array.
- *
- * @type callable $render_callback Callback used to render blocks of this block type.
- * }
- * @return WP_Block_Type|false The registered block type on success, or false on failure.
- */
- function register_block_type( $name, $args = array() ) {
- return WP_Block_Type_Registry::get_instance()->register( $name, $args );
- }
-}
-
-if ( ! function_exists( 'unregister_block_type' ) ) {
- /**
- * Unregisters a block type.
- *
- * @since 0.1.0
- * @since 0.6.0 Now also accepts a WP_Block_Type instance as first parameter.
- *
- * @param string|WP_Block_Type $name Block type name including namespace, or alternatively a
- * complete WP_Block_Type instance.
- * @return WP_Block_Type|false The unregistered block type on success, or false on failure.
- */
- function unregister_block_type( $name ) {
- return WP_Block_Type_Registry::get_instance()->unregister( $name );
- }
-}
-
if ( ! function_exists( 'gutenberg_parse_blocks' ) ) {
/**
* Parses blocks out of a content string.
*
* @since 0.5.0
+ * @deprecated 5.0.0 parse_blocks()
*
* @param string $content Post content.
* @return array Array of parsed block objects.
*/
function gutenberg_parse_blocks( $content ) {
- /**
- * Filter to allow plugins to replace the server-side block parser
- *
- * @since 3.8.0
- *
- * @param string $parser_class Name of block parser class
- */
- $parser_class = apply_filters( 'block_parser_class', 'WP_Block_Parser' );
- // Load default block parser for server-side parsing if the default parser class is being used.
- if ( 'WP_Block_Parser' === $parser_class ) {
- require_once dirname( __FILE__ ) . '/../packages/block-serialization-default-parser/parser.php';
- }
- $parser = new $parser_class();
- return $parser->parse( $content );
- }
-}
-
-if ( ! function_exists( 'get_dynamic_block_names' ) ) {
- /**
- * Returns an array of the names of all registered dynamic block types.
- *
- * @return array Array of dynamic block names.
- */
- function get_dynamic_block_names() {
- $dynamic_block_names = array();
+ _deprecated_function( __FUNCTION__, '5.0.0', 'parse_blocks()' );
- $block_types = WP_Block_Type_Registry::get_instance()->get_all_registered();
- foreach ( $block_types as $block_type ) {
- if ( $block_type->is_dynamic() ) {
- $dynamic_block_names[] = $block_type->name;
- }
- }
-
- return $dynamic_block_names;
+ return parse_blocks( $content );
}
}
@@ -100,10 +31,13 @@ function get_dynamic_block_names() {
* Retrieve the dynamic blocks regular expression for searching.
*
* @since 3.6.0
+ * @deprecated 5.0.0
*
* @return string
*/
function get_dynamic_blocks_regex() {
+ _deprecated_function( __FUNCTION__, '5.0.0' );
+
$dynamic_block_names = get_dynamic_block_names();
$dynamic_block_pattern = (
'/).)*+)?}\s+)?(?\/)?-->/s',
+ '/).)*+)?}\s+)?(?P\/)?-->/s',
$this->document,
$matches,
PREG_OFFSET_CAPTURE,
diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 93591222faad9..1ec2b397bcea6 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -5,6 +5,14 @@
- `withFilters` has been optimized to avoid binding hook handlers for each mounted instance of the component, instead using a single centralized hook delegator.
- `withFilters` has been optimized to reuse a single shared component definition for all filtered instances of the component.
+### Bug Fixes
+
+- Resolves a conflict where two instance of Slot would produce an inconsistent or duplicated rendering output.
+
+### New Feature
+
+- `Dropdown` now has a `focusOnMount` prop which is passed directly to the contained `Popover`.
+
## 7.0.5 (2019-01-03)
## 7.0.4 (2018-12-12)
diff --git a/packages/components/src/button/index.native.js b/packages/components/src/button/index.native.js
index cd38fecd9ed2c..176498ecd113b 100644
--- a/packages/components/src/button/index.native.js
+++ b/packages/components/src/button/index.native.js
@@ -37,16 +37,16 @@ const styles = StyleSheet.create( {
fontWeight: 'bold',
fontSize: 13,
alignSelf: 'flex-end',
- marginLeft: marginLeft,
- marginBottom: marginBottom,
+ marginLeft,
+ marginBottom,
},
subscriptActive: {
color: 'white',
fontWeight: 'bold',
fontSize: 13,
alignSelf: 'flex-end',
- marginLeft: marginLeft,
- marginBottom: marginBottom,
+ marginLeft,
+ marginBottom,
},
} );
diff --git a/packages/components/src/color-palette/index.js b/packages/components/src/color-palette/index.js
index 5ab52f277df71..c70db00206f49 100644
--- a/packages/components/src/color-palette/index.js
+++ b/packages/components/src/color-palette/index.js
@@ -8,6 +8,7 @@ import { map } from 'lodash';
* WordPress dependencies
*/
import { __, sprintf } from '@wordpress/i18n';
+import Dashicon from '../dashicon';
/**
* Internal dependencies
@@ -26,7 +27,7 @@ export default function ColorPalette( { colors, disableCustomColors = false, val
return (
{ map( colors, ( { color, name } ) => {
- const style = { color: color };
+ const style = { color };
const itemClasses = classnames( 'components-color-palette__item', { 'is-active': value === color } );
return (
@@ -49,6 +50,7 @@ export default function ColorPalette( { colors, disableCustomColors = false, val
aria-pressed={ value === color }
/>
+ { value === color && }
