diff --git a/docs/contributors/README.md b/docs/contributors/README.md index 33255d778526f..ccf5611991732 100644 --- a/docs/contributors/README.md +++ b/docs/contributors/README.md @@ -18,7 +18,7 @@ Find the section below based on what you are looking to contribute: - **Internationalization?** See the [localizing and translating section](/docs/contributors/localizing.md) -### Repository Management +### Repository management The Gutenberg project uses GitHub for managing code and tracking issues. Please see the following sections for the project methodologies using GitHub. diff --git a/docs/contributors/accessibility-testing.md b/docs/contributors/accessibility-testing.md index 8012b5214764c..ded036e19cb5a 100644 --- a/docs/contributors/accessibility-testing.md +++ b/docs/contributors/accessibility-testing.md @@ -2,11 +2,11 @@ This is a guide on how to test accessibility on Gutenberg. This is a living document that can be improved over time with new approaches and techniques. -## Getting Started +## Getting started Make sure you have set up your local environment following the instructions on [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md). -## Keyboard Testing +## Keyboard testing In addition to mouse, make sure the interface is fully accessible for keyboard-only users. Try to interact with your changes using only the keyboard: @@ -18,7 +18,7 @@ If the elements can be focused using arrow keys, but not Tab or If the interaction is complex or confusing to you, consider that it's also going to impact keyboard-only users. -## Screen Reader Testing +## Screen reader testing According to the [WebAIM: Screen Reader User Survey #8 Results](https://webaim.org/projects/screenreadersurvey8/#usage), these are the most common screen reader and browser combinations: diff --git a/docs/contributors/code/README.md b/docs/contributors/code/README.md index caaa9221f240f..848aa8bc26bbd 100644 --- a/docs/contributors/code/README.md +++ b/docs/contributors/code/README.md @@ -14,7 +14,7 @@ The Gutenberg project uses GitHub for managing code and tracking issues. The mai Browse [the issues list](https://github.com/wordpress/gutenberg/issues) to find issues to work on. The [good first issue](https://github.com/wordpress/gutenberg/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) and [good first review](https://github.com/WordPress/gutenberg/pulls?q=is%3Aopen+is%3Apr+label%3A%22Good+First+Review%22) labels are good starting points. -## Contributor Resources +## Contributor resources - [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md) documents getting your development environment setup, this includes your test site and developer tools suggestions. - [Git Workflow](/docs/contributors/code/git-workflow.md) documents the git process for deploying changes using pull requests. diff --git a/docs/contributors/code/backward-compatibility.md b/docs/contributors/code/backward-compatibility.md index 96615fe793a50..ce0f58a079c75 100644 --- a/docs/contributors/code/backward-compatibility.md +++ b/docs/contributors/code/backward-compatibility.md @@ -61,7 +61,7 @@ deprecated( 'wp.components.ClipboardButton', { } ); ``` -## Dev Notes +## Dev notes Dev notes are [posts published on the make/core site](https://make.wordpress.org/core/tag/dev-notes/) prior to WordPress releases to inform third-party developers about important changes to the developer APIs, these changes can include: @@ -70,7 +70,7 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org - Unavoidable backward compatibility breakage, with reasoning and migration flows. - Important deprecations (even without breakage), with reasoning and migration flows. -### Dev Note Workflow +### Dev note workflow - When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. - If possible, add a comment to the PR explaining why the dev note is needed. diff --git a/docs/contributors/code/coding-guidelines.md b/docs/contributors/code/coding-guidelines.md index 53f0a0f8d1000..52fa92440b265 100644 --- a/docs/contributors/code/coding-guidelines.md +++ b/docs/contributors/code/coding-guidelines.md @@ -55,7 +55,7 @@ export default function Notice( { children, onRemove, isDismissible } ) { A component's class name should **never** be used outside its own folder (with rare exceptions such as [`_z-index.scss`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/base-styles/_z-index.scss)). If you need to inherit styles of another component in your own components, you should render an instance of that other component. At worst, you should duplicate the styles within your own component's stylesheet. This is intended to improve maintainability by isolating shared components as a reusable interface, reducing the surface area of similar UI elements by adapting a limited set of common components to support a varied set of use-cases. -#### SCSS File Naming Conventions for Blocks +#### SCSS file naming conventions for blocks The build process will split SCSS from within the blocks library directory into two separate CSS files when Webpack runs. @@ -75,7 +75,7 @@ In the Gutenberg project, we use [the ES2015 import syntax](https://developer.mo These separations are identified by multi-line comments at the top of a file which imports code from another file or source. -#### External Dependencies +#### External dependencies An external dependency is third-party code that is not maintained by WordPress contributors, but instead [included in WordPress as a default script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/#default-scripts-included-and-registered-by-wordpress) or referenced from an outside package manager like [npm](https://www.npmjs.com/). @@ -88,7 +88,7 @@ Example: import moment from 'moment'; ``` -#### WordPress Dependencies +#### WordPress dependencies To encourage reusability between features, our JavaScript is split into domain-specific modules which [`export`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) one or more functions or objects. In the Gutenberg project, we've distinguished these modules under top-level directories. Each module serve an independent purpose, and often code is shared between them. For example, in order to localize its text, editor code will need to include functions from the `i18n` module. @@ -101,7 +101,7 @@ Example: import { __ } from '@wordpress/i18n'; ``` -#### Internal Dependencies +#### Internal dependencies Within a specific feature, code is organized into separate files and folders. As is the case with external and WordPress dependencies, you can bring this code into scope by using the `import` keyword. The main distinction here is that when importing internal files, you should use relative paths specific to top-level directory you're working in. @@ -114,9 +114,9 @@ Example: import VisualEditor from '../visual-editor'; ``` -### Legacy Experimental APIs, Plugin-only APIs, and Private APIs +### Legacy experimental APIs, plugin-only APIs, and private APIs -#### Legacy Experimental APIs +#### Legacy experimental APIs Historically, Gutenberg has used the `__experimental` and `__unstable` prefixes to indicate that a given API is not yet stable and may be subject to change. This is a legacy convention which should be avoided in favor of the plugin-only API pattern or a private API pattern described below. @@ -352,7 +352,7 @@ const { privateValidateBlocks } = unlock( package1PrivateApis ); privateValidateBlocks( blocks, true ); ``` -#### Private React Component properties +#### Private React component properties To add an private argument to a stable component you'll need to prepare a stable and an private version of that component. @@ -517,7 +517,7 @@ alert( 'My name is ' + name + '.' ); alert( `My name is ${ name }.` ); ``` -### Optional Chaining +### Optional chaining [Optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) is a new language feature introduced in version 2020 of the ECMAScript specification. While the feature can be very convenient for property access on objects which are potentially null-ish (`null` or `undefined`), there are a number of common pitfalls to be aware of when using optional chaining. These may be issues that linting and/or type-checking can help protect against at some point in the future. In the meantime, you will want to be cautious of the following items: @@ -529,11 +529,11 @@ alert( `My name is ${ name }.` ); - Example: `document.body.classList.toggle( 'has-focus', nodeRef.current?.contains( document.activeElement ) );` may wrongly _add_ the class, since [the second argument is optional](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle). If `undefined` is passed, it would not unset the class as it would when `false` is passed. - Example: `` may inadvertently cause warnings in React by toggling between [controlled and uncontrolled inputs](https://reactjs.org/docs/uncontrolled-components.html). This is an easy trap to fall into when eagerly assuming that a result of `trim()` will always return a string value, overlooking the fact the optional chaining may have caused evaluation to abort earlier with a value of `undefined`. -### React Components +### React components It is preferred to implement all components as [function components](https://reactjs.org/docs/components-and-props.html), using [hooks](https://reactjs.org/docs/hooks-reference.html) to manage component state and lifecycle. With the exception of [error boundaries](https://reactjs.org/docs/error-boundaries.html), you should never encounter a situation where you must use a class component. Note that the [WordPress guidance on Code Refactoring](https://make.wordpress.org/core/handbook/contribute/code-refactoring/) applies here: There needn't be a concentrated effort to update class components in bulk. Instead, consider it as a good refactoring opportunity in combination with some other change. -## JavaScript Documentation using JSDoc +## JavaScript documentation using JSDoc Gutenberg follows the [WordPress JavaScript Documentation Standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/), with additional guidelines relevant for its distinct use of [import semantics](/docs/contributors/code/coding-guidelines.md#imports) in organizing files, the [use of TypeScript tooling](/docs/contributors/code/testing-overview.md#javascript-testing) for types validation, and automated documentation generation using [`@wordpress/docgen`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/docgen). @@ -542,7 +542,7 @@ For additional guidance, consult the following resources: - [JSDoc Official Documentation](https://jsdoc.app/index.html) - [TypeScript Supported JSDoc](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) -### Custom Types +### Custom types Define custom types using the [JSDoc `@typedef` tag](https://jsdoc.app/tags-typedef.html). @@ -577,7 +577,7 @@ Custom types can also be used to describe a set of predefined options. While the Note the use of quotes when defining a set of string literals. As in the [JavaScript Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/), single quotes should be used when assigning a string literal either as the type or as a [default function parameter](#nullable-undefined-and-void-types), or when [specifying the path](#importing-and-exporting-types) of an imported type. -### Importing and Exporting Types +### Importing and exporting types Use the [TypeScript `import` function](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#import-types) to import type declarations from other files or third-party dependencies. @@ -599,7 +599,7 @@ When considering which types should be made available from a WordPress package, In this snippet, the `@typedef` will support the usage of the previous example's `import('@wordpress/data')`. -#### External Dependencies +#### External dependencies Many third-party dependencies will distribute their own TypeScript typings. For these, the `import` semantics should "just work". @@ -609,7 +609,7 @@ If you use a [TypeScript integration](https://github.com/Microsoft/TypeScript/wi For packages which do not distribute their own TypeScript types, you are welcomed to install and use the [DefinitelyTyped](http://definitelytyped.org/) community-maintained types definitions, if one exists. -### Generic Types +### Generic types When documenting a generic type such as `Object`, `Function`, `Promise`, etc., always include details about the expected record types. @@ -659,7 +659,7 @@ Similar to the "Custom Types" advice concerning type unions and with literal val const BREAKPOINTS = { huge: 1440 /* , ... */ }; ``` -### Nullable, Undefined, and Void Types +### Nullable, undefined, and void types You can express a nullable type using a leading `?`. Use the nullable form of a type only if you're describing either the type or an explicit `null` value. Do not use the nullable form as an indicator of an optional parameter. @@ -731,7 +731,7 @@ When documenting a [function type](https://github.com/WordPress/gutenberg/blob/a */ ``` -### Documenting Examples +### Documenting examples Because the documentation generated using the `@wordpress/docgen` tool will include `@example` tags if they are defined, it is considered a best practice to include usage examples for functions and components. This is especially important for documented members of a package's public API. @@ -756,7 +756,7 @@ When documenting an example, use the markdown \`\`\` code block to */ ```` -### Documenting React Components +### Documenting React components When possible, all components should be implemented as [function components](https://reactjs.org/docs/components-and-props.html#function-and-class-components), using [hooks](https://reactjs.org/docs/hooks-intro.html) for managing component lifecycle and state. diff --git a/docs/contributors/code/getting-started-with-code-contribution.md b/docs/contributors/code/getting-started-with-code-contribution.md index 3de83d50268d8..c3282c0f8003d 100644 --- a/docs/contributors/code/getting-started-with-code-contribution.md +++ b/docs/contributors/code/getting-started-with-code-contribution.md @@ -183,7 +183,7 @@ If so, you need to instruct Apache to allow following such links: Tools like MAMP tend to configure MySQL to use ports other than the default 3306, often preferring 8889. This may throw off WP-CLI, which will fail after trying to connect to the database. To remedy this, edit `wp-config.php` and change the `DB_HOST` constant from `define( 'DB_HOST', 'localhost' )` to `define( 'DB_HOST', '127.0.0.1:8889' )`. -### On A Remote Server +### On a remote server You can use a remote server in development by building locally and then uploading the built files as a plugin to the remote server. @@ -203,7 +203,7 @@ You can launch Storybook by running `npm run storybook:dev` locally. It will ope You can also test Storybook for the current `trunk` branch on GitHub Pages: [https://wordpress.github.io/gutenberg/](https://wordpress.github.io/gutenberg/) -## Developer Tools +## Developer tools We recommend configuring your editor to automatically check for syntax and lint errors. This will help you save time as you develop by automatically fixing minor formatting issues. Here are some directions for setting up Visual Studio Code, a popular editor used by many of the core developers, these tools are also available for other editors. diff --git a/docs/contributors/code/git-workflow.md b/docs/contributors/code/git-workflow.md index eeeb68282c1cd..f2ad1345355de 100644 --- a/docs/contributors/code/git-workflow.md +++ b/docs/contributors/code/git-workflow.md @@ -73,7 +73,7 @@ Do not make a new pull request for updates; by pushing your change to your repos That’s it! Once approved and merged, your change will be incorporated into the main repository. 🎉 -## Branch Naming +## Branch naming You should name your branches using a prefixes and short description, like this: `[type]/[change]`. @@ -87,7 +87,7 @@ Suggested prefixes: For example, `add/gallery-block` means you're working on adding a new gallery block. -## Keeping Your Branch Up To Date +## Keeping your branch up to date When many different people are working on a project simultaneously, pull requests can go stale quickly. A "stale" pull request is one that is no longer up to date with the main line of development, and it needs to be updated before it can be merged into the project. @@ -105,7 +105,7 @@ git rebase trunk git push --force-with-lease origin your-branch-name ``` -## Keeping Your Fork Up To Date +## Keeping your fork up to date Working on pull request starts with forking the Gutenberg repository, your separate working copy. Which can easily go out of sync as new pull requests are merged into the main repository. Here your working repository is a `fork` and the main Gutenberg repository is `upstream`. When working on new pull request you should always update your fork before you do `git checkout -b my-new-branch` to work on a feature or fix. @@ -138,7 +138,7 @@ The above commands will update your `trunk` branch from _upstream_. To update an ## Miscellaneous -### Git Archeology +### Git archeology When looking for a commit that introduced a specific change, it might be helpful to ignore revisions that only contain styling or formatting changes. diff --git a/docs/contributors/code/react-native/getting-started-react-native.md b/docs/contributors/code/react-native/getting-started-react-native.md index 7b4dcca98027d..48dc0e81f260e 100644 --- a/docs/contributors/code/react-native/getting-started-react-native.md +++ b/docs/contributors/code/react-native/getting-started-react-native.md @@ -55,7 +55,7 @@ npm run native ios which will attempt to open your app in the iOS Simulator if you're on a Mac and have it installed. -### Running on Other iOS Device Simulators +### Running on other iOS device simulators To compile and run the app using a different device simulator, use the following, noting the double sets of `--` to pass the simulator option down to the `react-native` CLI. @@ -71,7 +71,7 @@ npm run native ios -- -- --simulator="iPhone Xs Max" To see a list of all of your available iOS devices, use `xcrun simctl list devices`. -### Customizing the Demo Editor +### Customizing the demo Editor By default, the Demo editor renders most of the supported core blocks. This is helpful to showcase the editor's capabilities, but can be distracting when focusing on a specific block or feature. One can customize the editor's initial state by leveraging the `native.block_editor_props` hook in a `packages/react-native-editor/src/setup-local.js` file. @@ -119,7 +119,7 @@ When you first open the project in Visual Studio, you will be prompted to instal One of the extensions we are using is the [React Native Tools](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native). This allows you to run the packager from VSCode or launch the application on iOS or Android. It also adds some debug configurations so you can set breakpoints and debug the application directly from VSCode. Take a look at the [extension documentation](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native) for more details. -## Unit Tests +## Unit tests Use the following command to run the test suite: @@ -137,11 +137,11 @@ npm run test:native:debug Then, open `chrome://inspect` in Chrome to attach the debugger (look into the "Remote Target" section). While testing/developing, feel free to sprinkle `debugger` statements anywhere in the code that you'd like the debugger to break. -## Writing and Running Unit Tests +## Writing and running unit tests This project is set up to use [jest](https://jestjs.io/) for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called `__tests__` or with the `.test.js` extension to have the files loaded by jest. See an example test [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/src/test/api-fetch-setup.test.js). The [jest documentation](https://jestjs.io/docs/getting-started) is also a wonderful resource, as is the [React Native testing tutorial](https://jestjs.io/docs/tutorial-react-native). -## End-to-End Tests +## End-to-end tests In addition to unit tests, the Mobile Gutenberg (MG) project relies upon end-to-end (E2E) tests to automate testing critical flows in an environment similar to that of an end user. We generally prefer unit tests due to their speed and ease of maintenance. However, assertions that require OS-level features (e.g. complex gestures, text selection) or visual regression testing (e.g. dark mode, contrast levels) we use E2E tests. diff --git a/docs/contributors/code/testing-overview.md b/docs/contributors/code/testing-overview.md index 8a2f6079b2419..3be1b6b935bff 100644 --- a/docs/contributors/code/testing-overview.md +++ b/docs/contributors/code/testing-overview.md @@ -17,7 +17,7 @@ When writing tests consider the following: - Does the test test what we think it is testing? Or are we introducing false positives/negatives? - Is it readable? Will other contributors be able to understand how our code behaves by looking at its corresponding test? -## JavaScript Testing +## JavaScript testing Tests for JavaScript use [Jest](https://jestjs.io/) as the test runner and its API for [globals](https://jestjs.io/docs/en/api.html) (`describe`, `test`, `beforeEach` and so on) [assertions](https://jestjs.io/docs/en/expect.html), [mocks](https://jestjs.io/docs/en/mock-functions.html), [spies](https://jestjs.io/docs/en/jest-object.html#jestspyonobject-methodname) and [mock functions](https://jestjs.io/docs/en/mock-function-api.html). If needed, you can also use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) for React component testing. @@ -90,7 +90,7 @@ describe( 'CheckboxWithLabel', () => { } ); ``` -### Setup and Teardown methods +### Setup and teardown methods The Jest API includes some nifty [setup and teardown methods](https://jestjs.io/docs/en/setup-teardown.html) that allow you to perform tasks _before_ and _after_ each or all of your tests, or tests within a specific `describe` block. @@ -507,7 +507,7 @@ Contributors to Gutenberg will note that PRs include continuous integration E2E There is an ongoing effort to add integration tests to the native mobile project using the [`react-native-testing-library`](https://testing-library.com/docs/react-native-testing-library/intro/) library. A guide to writing integration tests can be found [here](/docs/contributors/code/react-native/integration-test-guide.md). -## End-to-end Testing +## End-to-end testing Most existing End-to-end tests currently use [Puppeteer](https://github.com/puppeteer/puppeteer) as a headless Chromium driver to run the tests in `packages/e2e-tests`, and are otherwise still run by a [Jest](https://jestjs.io/) test runner. @@ -559,7 +559,7 @@ Then to run the tests, specify the base URL, username, and passwords for your si WP_BASE_URL=http://wp.test npm run test:e2e -- --wordpress-username=admin --wordpress-password=password ``` -### Scenario Testing +### Scenario testing If you find that end-to-end tests pass when run locally, but fail in GitHub Actions, you may be able to isolate a CPU- or network-bound race condition by simulating a slow CPU or network: @@ -587,15 +587,15 @@ OFFLINE=true npm run test:e2e See [Chrome docs: emulateNetworkConditions](https://chromedevtools.github.io/devtools-protocol/tot/Network#method-emulateNetworkConditions) -### Core Block Testing +### Core block testing Every core block is required to have at least one set of fixture files for its main save function and one for each deprecation. These fixtures test the parsing and serialization of the block. See [the integration tests fixtures readme](https://github.com/wordpress/gutenberg/blob/HEAD/test/integration/fixtures/blocks/README.md) for more information and instructions. -### Flaky Tests +### Flaky tests A test is considered to be **flaky** when it can pass and fail across multiple retry attempts without any code changes. We auto retry failed tests at most **twice** on CI to detect and report them to GitHub issues automatically under the [`[Type] Flaky Test`](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22%5BType%5D+Flaky+Test%22) label via [`report-flaky-tests`](https://github.com/WordPress/gutenberg/tree/trunk/packages/report-flaky-tests) GitHub action. Note that a test that failed three times in a row is not counted as a flaky test and will not be reported to an issue. -## PHP Testing +## PHP testing Tests for PHP use [PHPUnit](https://phpunit.de/) as the testing framework. If you're using the built-in [local environment](/docs/contributors/code/getting-started-with-code-contribution.md#local-environment), you can run the PHP tests locally using this command: @@ -620,7 +620,7 @@ To run unit tests only, without the linter, use `npm run test:unit:php` instead. [snapshot testing]: https://jestjs.io/docs/en/snapshot-testing.html [update snapshots]: https://jestjs.io/docs/en/snapshot-testing.html#updating-snapshots -## Performance Testing +## Performance testing To ensure that the editor stays performant as we add features, we monitor the impact pull requests and releases can have on some key metrics: diff --git a/docs/contributors/design/README.md b/docs/contributors/design/README.md index de390937244ed..abc077b8fdc07 100644 --- a/docs/contributors/design/README.md +++ b/docs/contributors/design/README.md @@ -8,7 +8,7 @@ The [Make WordPress Design blog](https://make.wordpress.org/design/) is the prim Real-time discussions for design take place in the `#design` channel in [Make WordPress Slack](https://make.wordpress.org/chat) (registration required). Weekly meetings for the Design team are on Wednesdays at 19:00UTC. -## How Can Designers Contribute? +## How can designers contribute? The Gutenberg project uses GitHub for managing code and tracking issues. The main repository is at: [https://github.com/WordPress/gutenberg](https://github.com/WordPress/gutenberg). diff --git a/docs/contributors/design/the-block.md b/docs/contributors/design/the-block.md index f35e17d019592..463d3eb9b9e1a 100644 --- a/docs/contributors/design/the-block.md +++ b/docs/contributors/design/the-block.md @@ -11,7 +11,7 @@ So, for example, a user can add an image, write its caption, change its width an - Users only need to learn one interface — the block — to add and edit everything on their site. Users shouldn’t have to write shortcodes, custom HTML, or understand hidden mechanisms to embed content. - Gutenberg makes core features more discoverable, reducing hard-to-find “Mystery meat.” WordPress supports a large number of blocks and 30+ embeds. Let’s increase their visibility. -## Building Blocks +## Building blocks What does this mean for designers and developers? The block structure plus the principle of direct manipulation mean thinking differently about how to design and develop WordPress components. Let’s take another look at the architecture of a block: diff --git a/docs/contributors/documentation/README.md b/docs/contributors/documentation/README.md index 397e7ad1e140c..7089bf5714168 100644 --- a/docs/contributors/documentation/README.md +++ b/docs/contributors/documentation/README.md @@ -64,7 +64,7 @@ To add a new document requires a working JavaScript development environment to b If you forget to run, `npm run docs:build` your PR will fail the static analysis check, since the `manifest.json` file is an uncommitted local change that must be committed. -### Documenting Packages +### Documenting packages Package documentation is generated automatically by the documentation tool by pulling the contents of the README.md file located in the root of the package. Sometimes however, it is preferable to split the contents of the README out into smaller, easier to read portions. diff --git a/docs/contributors/repository-management.md b/docs/contributors/repository-management.md index 9bce2d06fd156..e57f762a60539 100644 --- a/docs/contributors/repository-management.md +++ b/docs/contributors/repository-management.md @@ -55,7 +55,7 @@ Here are some milestones you might see: - [X.Y (Gutenberg)](https://github.com/WordPress/gutenberg/milestone/85): PRs targeted for the Gutenberg Plugin X.Y release. - [Future](https://github.com/WordPress/gutenberg/milestone/35): this is something that is confirmed by everyone as a good thing but doesn’t fall into other criteria. -### Triaging Issues +### Triaging issues To keep the issue list healthy, it needs to be triaged regularly. _Triage_ is the practice of reviewing existing issues to make sure they’re relevant, actionable, and have all the information they need. @@ -63,7 +63,7 @@ Anyone can help triage, although you’ll need contributor permission on the Gut See the [Triage Contributors guide](/docs/contributors/triage.md) for details. -## Pull Requests +## Pull requests Gutenberg follows a feature branch pull request workflow for all code and documentation changes. At a high-level, the process looks like this: @@ -86,7 +86,7 @@ Along with this process, there are a few important points to mention: - To make it far easier to merge your code, each pull request should only contain one conceptual change. Keeping contributions atomic keeps the pull request discussion focused on one topic and makes it possible to approve changes on a case-by-case basis. - Separate pull requests can address different items or todos from their linked issue, there’s no need for a single pull request to cover a single issue if the issue is non-trivial. -### Code Review +### Code review Every pull request goes through a manual code review, in addition to automated tests. The objectives for the code review are best thought of as: @@ -106,7 +106,7 @@ If you are not yet comfortable leaving a full review, try commenting on a PR. Qu If you struggle with getting a review, see: [How To Get Your Pull Request Reviewed?](/docs/contributors/code/how-to-get-your-pull-request-reviewed.md) -### Design Review +### Design review If your pull request impacts the design/UI, you need to label appropriately to alert design. To request a design review, add the [Needs Design Feedback](https://github.com/WordPress/gutenberg/labels/Needs%20Design%20Feedback) label to your PR. If there are any PRs that require an update to the design/UI, please use the [Figma Library Update](https://github.com/WordPress/gutenberg/labels/Figma%20Library%20Update) label. @@ -116,7 +116,7 @@ As a guide, changes that should be reviewed: - Anything that changes something visually. - If you just want design feedback on an idea or exploration. -### Merging Pull Requests +### Merging pull requests A pull request can generally be merged once it is: @@ -134,7 +134,7 @@ All members of the WordPress organization on GitHub have the ability to review a Most pull requests will be automatically assigned a release milestone, but please make sure your merged pull request was assigned one. Doing so creates the historical legacy of what code landed when, and makes it possible for all project contributors (even non-technical ones) to access this information. -### Closing Pull Requests +### Closing pull requests Sometimes, a pull request may not be mergeable, no matter how much additional effort is applied to it (e.g. out of scope). In these cases, it’s best to communicate with the contributor graciously while describing why the pull request was closed, this encourages productive future involvement. diff --git a/docs/contributors/triage.md b/docs/contributors/triage.md index 477c7d7dc8170..33275b8d3df01 100644 --- a/docs/contributors/triage.md +++ b/docs/contributors/triage.md @@ -48,7 +48,7 @@ When triaging, either one of the lists above or issues in general, work through - Check if the issue is missing some detail and see if you can fill in those details. For instance, if a bug report is missing visual detail, it’s helpful to reproduce the issue locally and upload a screenshot or GIF. - Consider adding the Good First Issue label if you believe this is a relatively easy issue for a first-time contributor to try to solve. -**Commonly Used Labels** +**Commonly used labels** Generally speaking, the following labels are very useful for triaging issues and will likely be the ones you use the most consistently. You can view all possible labels [here](https://github.com/WordPress/gutenberg/labels). @@ -61,7 +61,7 @@ Generally speaking, the following labels are very useful for triaging issues and | `Needs More Info` | When it’s not clear what the issue is or it would help to provide additional details. | | `Needs Testing` | When a new issue needs to be confirmed or old bugs seem like they are no longer relevant. | -**Determining Priority Labels** +**Determining priority labels** If you have enough knowledge about the report at hand and feel confident in doing so, you can consider adding priority. Note that it’s on purpose that no priority label infers a normal level. @@ -81,7 +81,7 @@ Issues are closed for the following reasons: - An issue that needs more information that the author of the issue hasn't responded to for 2+ weeks. - An item that is determined as unable to be fixed or is working as intended. -## Specific Triages +## Specific triages ### Release specific triage diff --git a/docs/explanations/architecture/README.md b/docs/explanations/architecture/README.md index 2cecdfd70e2d6..ec49318bb38cf 100644 --- a/docs/explanations/architecture/README.md +++ b/docs/explanations/architecture/README.md @@ -11,7 +11,7 @@ Let’s look at the big picture and the architectural and UX principles of the b - [Styles in the editor](/docs/explanations/architecture/styles.md). - [Performance](/docs/explanations/architecture/performance.md). -## Gutenberg Repository +## Gutenberg repository - [Modularity and WordPress Packages](/docs/explanations/architecture/modularity.md). - [Understand the repository folder structure](/docs/contributors/folder-structure.md). diff --git a/docs/explanations/architecture/data-flow.md b/docs/explanations/architecture/data-flow.md index e000cd33b4631..c594ceda70443 100644 --- a/docs/explanations/architecture/data-flow.md +++ b/docs/explanations/architecture/data-flow.md @@ -74,7 +74,7 @@ const columnsBlock = { }; ``` -## Serialization and Parsing +## Serialization and parsing ![Diagram](https://docs.google.com/drawings/d/1iuownt5etcih7rMMvPvh0Mny8zUA1Z28saxjxaWmfJ0/pub?w=1234&h=453) @@ -88,7 +88,7 @@ This is one end of the process. The other is how to recreate the collection of b They just happen, incidentally, to be stored inside of `post_content` in a way in which they require no transformation in order to be viewable by any legacy system. It's true that loading the stored HTML into a browser without the corresponding machinery might degrade the experience, and if it included dynamic blocks of content, the dynamic elements may not load, server-generated content may not appear, and interactive content may remain static. However, it at least protects against not being able to view block editor posts on themes and installations that are blocks-unaware, and it provides the most accessible way to the content. In other words, the post remains mostly intact even if the saved HTML is rendered as is. -### Delimiters and Parsing Expression Grammar +### Delimiters and parsing expression grammar We chose instead to try to find a way to keep the formality, explicitness, and unambiguity in the existing HTML syntax. Within the HTML there were a number of options. @@ -102,7 +102,7 @@ This has dramatic implications for how simple and performant we can make our par _N.B.:_ The defining aspects of blocks are their semantics and the isolation mechanism they provide: in other words, their identity. On the other hand, where their data is stored is a more liberal aspect. Blocks support more than just static local data (via JSON literals inside the HTML comment or within the block's HTML), and more mechanisms (_e.g._, global blocks or otherwise resorting to storage in complementary `WP_Post` objects) are expected. See [attributes](/docs/reference-guides/block-api/block-attributes.md) for details. -### The Anatomy of a Serialized Block +### The anatomy of a serialized block When blocks are saved to the content after the editing session, its attributes—depending on the nature of the block—are serialized to these explicit comment delimiters. @@ -118,7 +118,7 @@ A purely dynamic block that is to be server-rendered before display could look l ``` -## The Data Lifecycle +## The data lifecycle In summary, the block editor workflow parses the saved document to an in-memory tree of blocks, using token delimiters to help. During editing, all manipulations happen within the block tree. The process ends by serializing the blocks back to the `post_content`. diff --git a/docs/explanations/architecture/key-concepts.md b/docs/explanations/architecture/key-concepts.md index 3af2d6d87a077..1ba009f782314 100644 --- a/docs/explanations/architecture/key-concepts.md +++ b/docs/explanations/architecture/key-concepts.md @@ -12,7 +12,7 @@ The settings and content of a block can be customized in three main places: the Blocks are meant to be combined in different ways. Blocks are hierarchical in that a block can be nested within another block. Nested blocks and its container are also called _children_ and _parent_ respectively. For example, a _Columns_ block can be the parent block to multiple child blocks in each of its columns. The API that governs child block usage is named `InnerBlocks`. -### Data & Attributes +### Data and attributes Blocks understand content as attributes and are serializable to HTML. To this point, there is a new Block Grammar. Distilled, the block grammar is an HTML comment, either a self-closing tag or with a beginning tag and ending tag. In the main tag, depending on the block type and user customizations, there can be a JSON object. This raw form of the block is referred to as serialized. @@ -28,20 +28,20 @@ Each block contains Attributes or configuration settings, which can be sourced f More on [Data format and data flow](/docs/explanations/architecture/data-flow.md). -### Block Transforms +### Block transforms Blocks have the ability to be transformed into other block types. This allows basic operations like converting a paragraph into a heading, but also more intricate ones like multiple images becoming a gallery. Block transforms work for single blocks and for multi-block selections. Internal block variations are also possible transformation targets. -### Block Variations +### Block variations Given a block type, a block variation is a predefined set of its initial attributes. This API allows creating a single block from which multiple configurations are possible. Variations provide different possible interfaces, including showing up as entirely new blocks in the library, or as presets when inserting a new block. Read [the API documentation](/docs/reference-guides/block-api/block-registration.md#variations-optional) for more details. -**More on Blocks** +**More on blocks** - **[Block API](/docs/reference-guides/block-api/README.md)** - **[Tutorial: Building A Custom Block](/docs/getting-started/create-block/README.md)** -## Reusable Blocks +## Reusable blocks A reusable blocks is **an instance** of a block (or multiple blocks) that can be inserted and edited in multiples places, remaining in sync everywhere. If a reusable block is edited in one place, those changes are reflected across all posts and pages that block is used. Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page. diff --git a/docs/explanations/architecture/modularity.md b/docs/explanations/architecture/modularity.md index dc815d92174dd..f94f8ec7b9472 100644 --- a/docs/explanations/architecture/modularity.md +++ b/docs/explanations/architecture/modularity.md @@ -76,7 +76,7 @@ If you're using one of these stores to access and manipulate WordPress data in y These are packages used in development mode to help developers with daily tasks to develop, build and ship JavaScript applications, WordPress plugins and themes. They include tools for linting your codebase, building it, testing it... -## Editor Packages +## Editor packages ![Post Editor Modules Architecture](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/explanations/architecture/assets/modules.png) diff --git a/docs/explanations/architecture/performance.md b/docs/explanations/architecture/performance.md index b57a2bba1db61..e631ceb01fa70 100644 --- a/docs/explanations/architecture/performance.md +++ b/docs/explanations/architecture/performance.md @@ -10,7 +10,7 @@ To ensure the block editor stays performant across releases and development, we - **Typing Time:** The time it takes for the browser to respond while typing on the editor. - **Block Selection Time:** The time it takes for the browser to respond after a user selects block. (Inserting a block is also equivalent to selecting a block. Monitoring the selection is sufficient to cover both metrics). -## Key Performance Decisions and Solutions +## Key performance decisions and solutions **Data Module Async Mode** diff --git a/docs/explanations/architecture/styles.md b/docs/explanations/architecture/styles.md index a8a5af72fec76..d62171a062205 100644 --- a/docs/explanations/architecture/styles.md +++ b/docs/explanations/architecture/styles.md @@ -1,30 +1,8 @@ -## Styles in the editor +# Styles in the Editor This document introduces the main concepts related to styles that affect the user content in the block editor. It points to the relevant reference guides and tutorials for readers to dig deeper into each one of the ideas presented. It's aimed to block authors and people working in the block editor project. -1. [HTML and CSS](#html-and-css) -2. [Block styles](#block-styles) - -- [From UI controls to HTML markup](#from-ui-controls-to-html-markup) -- [Block Supports API](#block-supports-api) -- [Current limitations of the Block Supports API](#current-limitations-of-the-block-supports-api) - -3. [Global styles](#global-styles) - -- [Gather data](#gather-data) -- [Consolidate data](#consolidate-data) -- [From data to styles](#from-data-to-styles) -- [Current limitations of the Global Styles API](#current-limitations-of-the-global-styles-api) - -4. [Layout styles](#layout-styles) - -- [Base layout styles](#base-layout-styles) -- [Individual layout styles](#individual-layout-styles) -- [Available layout types](#available-layout-types) -- [Targeting layout or container blocks from themes](#targeting-layout-or-container-blocks-from-themes) -- [Opting out of generated layout styles](#opting-out-of-generated-layout-styles) - -### HTML and CSS +## HTML and CSS By creating a post in the block editor the user is creating a number of artifacts: a HTML document plus a number of CSS stylesheets, either embedded in the document or external. @@ -42,7 +20,7 @@ The stylesheets loaded in the front end include: - **User**. Some of the user actions in the editor will generate style content. This is the case for features such as duotone, layout, or link color. - **Other**. WordPress and plugins can also enqueue stylesheets. -### Block styles +## Block styles Since the introduction of the block editor in WordPress 5.0, there were tools for the users to "add styles" to specific blocks. By using these tools, the user would attach new classes or inline styles to the blocks, modifying their visual aspect. @@ -67,7 +45,7 @@ This is what we refer to as "user-provided block styles", also know as "local st The ability to modify a block state coupled with the fact that a block can live within any other block (think of a paragraph within a group), creates a vast amount of potential states and style possibilities. -#### From UI controls to HTML markup +### From UI controls to HTML markup If you follow the [block tutorial](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/) you can learn up about the different parts of the [block API](https://developer.wordpress.org/block-editor/reference-guides/block-api/) presented here in more detail and also build your own block. This is an introduction to the general concepts of how a block can let users edit its state. @@ -80,7 +58,7 @@ To build an experience like the one described above a block author needs a few p In essence, these are the essential mechanics a block author needs to care about for their block to be able to be styled by the user. While this can be done completely manually, there's an API that automates this process for common style needs: block supports. -#### Block Supports API +### Block Supports API [Block Supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) is an API that allows a block to declare what features it supports. By adding some info to their [block.json file](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/), the block tells the system what kind of actions a user can do to it. @@ -108,7 +86,7 @@ Besides the benefit of having to do less work to achieve the same results, there - the block will use the UI controls other blocks use for the same styles, creating a more coherent user experience - the UI controls in use by the block will be automatically updated as they are improved, without the block author having to do anything -#### Current limitations of the Block Supports API +### Current limitations of the Block Supports API While the Block Supports API provides value, it also comes with some limitations a block author needs to be aware of. To better visualize what they are, let's run with the following example of a table block: @@ -182,7 +160,7 @@ To enable for a _single_ property only, you may use an array to declare which pr Support for this feature was [added in this PR](https://github.com/WordPress/gutenberg/pull/36293). -### Global styles +## Global styles Global Styles refers to a mechanism that generates site-wide styles. Unlike the block styles described in the previous section, these are not serialized into the post content and are not attached to the block HTML. Instead, the output of this system is a new stylesheet with id `global-styles-inline-css`. @@ -198,19 +176,19 @@ The process of generating the stylesheet has, in essence, three steps: 2. Consolidate data: the structured information from different origins -WordPress defaults, theme, and user- is normalized and merged into a single structure. 3. Convert data into a stylesheet: convert the internal representation into CSS style rules and enqueue them as a stylesheet. -#### Gather data +### Gather data The data can come from three different origins: WordPress defaults, the active theme, or the user. All three of them use the same [`theme.json` format](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/). Data from WordPress and the active theme is retrieved from the corresponding `theme.json` file. Data from the user is pulled from the database, where it's stored after the user saves the changes they did via the global styles sidebar in the site editor. -#### Consolidate data +### Consolidate data The goal of this phase is to build a consolidated structure. There are two important processes going on in this phase. First, the system needs to normalize all the incoming data, as different origins may be using different versions of the `theme.json` format. For example, a theme may be using [v1](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-v1/) while the WordPress base is using [the latest version](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/). Second, the system needs to decide how to merge the input into a single structure. This will be the focus of the following sections. -##### Styles +#### Styles Different parts of the incoming `theme.json` structure are treated differently. The data present in the `styles` section is blended together following this logic: user data overrides theme data, and theme data overrides WordPress data. @@ -266,7 +244,7 @@ The result after the consolidation would be: } ``` -##### Settings +#### Settings The `settings` section works differently than styles. Most of the settings are only used to configure the editor and have no effect on the global styles. Only a few of them are part of the resulting stylesheet: the presets. @@ -332,11 +310,11 @@ The result after the consolidation would be: } ``` -#### From data to styles +### From data to styles The last phase of generating the stylesheet is converting the consolidated data into CSS style rules. -##### Styles to CSS rules +#### Styles to CSS rules The `styles` section can be thought of as a structured representation of CSS rules, each chunk representing a CSS rule: @@ -405,7 +383,7 @@ p { } ``` -##### Settings to CSS rules +#### Settings to CSS rules From the `settings` section, all the values of any given presets will be converted to a CSS Custom Property that follows this naming structure: `--wp--preset---`. The selectors follow the same rules described in the styles section above. @@ -483,29 +461,29 @@ In addition to the CSS Custom Properties, all presets but duotone generate CSS c .wp-block-site-title .has-foreground-border-color { border-color: var(--wp--preset--color--foreground) !important; } ``` -#### Current limitations of the Global Styles API +### Current limitations of the Global Styles API -##### 1. **Setting a different CSS selector for blocks requires server-registration** +#### 1. **Setting a different CSS selector for blocks requires server-registration** By default, the selector assigned to a block is `.wp-block-`. However, blocks can change this should they need. They can provide a CSS selector via the `__experimentalSelector` property in its `block.json`. If blocks do this, they need to be registered in the server using the `block.json`, otherwise, the global styles code doesn't have access to that information and will use the default CSS selector for the block. -##### 2. **Can't target different HTML nodes for different styles** +#### 2. **Can't target different HTML nodes for different styles** Every chunk of styles can only use a single selector. This is particularly relevant if the block is using `__experimentalSkipSerialization` to serialize the different style properties to different nodes other than the wrapper. See "Current limitations of blocks supports" for more. -##### 3. **Only a single property per block** +#### 3. **Only a single property per block** Similarly to block supports, there can be only one instance of any style in use by the block. For example, the block can only have a single font size. See related "Current limitations of block supports". -##### 4. **Only blocks using block supports are shown in the Global Styles UI** +#### 4. **Only blocks using block supports are shown in the Global Styles UI** The global styles UI in the site editor has a screen for per-block styles. The list of blocks is generated dynamically using the block supports from the `block.json` of blocks. If a block wants to be listed there, it needs to use the block supports mechanism. -### Layout styles +## Layout styles In addition to styles at the individual block level and in global styles, there is the concept of layout styles that are output for both blocks-based and classic themes. @@ -513,7 +491,7 @@ The layout block support outputs common layout styles that are shared between bl There are two primary places where Layout styles are output: -#### Base layout styles +### Base layout styles Base layout styles are those styles that are common to all blocks that opt in to a particular layout type. Examples of common base layout styling include setting `display: flex` for blocks that use the Flex layout type (such as Buttons and Social Icons), and providing default max-width for constrained layouts. @@ -521,14 +499,14 @@ Base layout styles are output from within [the main PHP class](https://github.co Common layout definitions are stored in [the core layout block support file](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/layout.php). -#### Individual layout styles +### Individual layout styles When a block that opts in to layout support is rendered, two things are processed and added to the output via [`layout.php`](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/layout.php): - Semantic class names are added to the block markup to indicate which layout settings are in use. For example, `is-layout-flow` is for blocks (such as Group) that use the default/flow layout, and `is-content-justification-right` is added when a user sets a block to use right justification. - Individual styles are generated for non-default layout values that are set on the individual block being rendered. These styles are attached to the block via a container class name using the form `wp-container-$id` where the `$id` is a [unique number](https://developer.wordpress.org/reference/functions/wp_unique_id/). -#### Available layout types +### Available layout types There are currently four layout types in use: @@ -539,7 +517,7 @@ There are currently four layout types in use: For controlling spacing between blocks, and enabling block spacing controls see: [What is blockGap and how can I use it?](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#what-is-blockgap-and-how-can-i-use-it). -#### Targeting layout or container blocks from themes +### Targeting layout or container blocks from themes The layout block support is designed to enable control over layout features from within the block and site editors. Where possible, try to use the features of the blocks to determine particular layout requirements rather than relying upon additional stylesheets. @@ -547,7 +525,7 @@ For themes that wish to target container blocks in order to add or adjust partic For targeting a block that uses a particular layout type, avoid targeting `wp-container-` as container classes may not always be present in the rendered markup. -##### Semantic class names +#### Semantic class names Work is currently underway to expand stable semantic classnames in Layout block support output. The task is being discussed in [this issue](https://github.com/WordPress/gutenberg/issues/38719). @@ -566,6 +544,6 @@ The current semantic class names that can be output by the Layout block support - `is-content-justification-space-between`: When a block explicitly sets `justifyContent` to `space-between`. - `is-nowrap`: When a block explicitly sets `flexWrap` to `nowrap`. -#### Opting out of generated layout styles +### Opting out of generated layout styles Layout styles output is switched on by default because the styles are required by core structural blocks. However, themes can opt out of generated block layout styles while retaining semantic class name output by using the `disable-layout-styles` block support. Such themes will be responsible for providing all their own layout styles. See [the entry under Theme Support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#disabling-base-layout-styles). diff --git a/docs/explanations/user-interface/block-design.md b/docs/explanations/user-interface/block-design.md index 5df99b5398867..e3a7b84bfa583 100644 --- a/docs/explanations/user-interface/block-design.md +++ b/docs/explanations/user-interface/block-design.md @@ -64,7 +64,7 @@ Group toolbar controls in logical segments. Don't add a segment for each. ![A screenshot comparing a block toolbar with good vs. bad toolbar segment groupings.](https://make.wordpress.org/design/files/2021/03/docs__block-toolbar-do-dont.png) -### Block Identification +### Block identification A block should have a straightforward, short name so users can easily find it in the block library. A block named "YouTube" is easy to find and understand. The same block, named "Embedded Video (YouTube)", would be less clear and harder to find in the block library. @@ -84,7 +84,7 @@ Use concise block names. **Don't:** Avoid long, multi-line block names. -### Block Description +### Block description Every block should include a description that clearly explains the block's function. The description will display in the Settings Sidebar. @@ -116,7 +116,7 @@ Provide an instructive placeholder state. **Don't:** Avoid branding and relying on the title alone to convey instructions. -### Selected and Unselected States +### Selected and unselected states When unselected, your block should preview its content as closely to the front-end output as possible. @@ -130,7 +130,7 @@ For controls that are essential for the operation of the block, provide them dir **Don't:** Do not put controls that are essential to the block in the sidebar, otherwise the block will appear non-functional to mobile users or desktop users who have dismissed the sidebar. -### Advanced Block Settings +### Advanced block settings The “Block” tab of the Settings Sidebar can contain additional block options and configuration. Keep in mind that a user can dismiss the sidebar and never use it. You should not put critical options in the Sidebar. @@ -156,11 +156,11 @@ The most basic unit of the editor. The Paragraph block is a simple input field. ![Paragraph block](https://cldup.com/HVJe5bGZ8H-3000x3000.png) -### Placeholder: +#### Placeholder - Simple placeholder text that reads “Type / to choose a block”. The placeholder disappears when the block is selected. -### Selected state: +#### Selected state - Block Toolbar: Has a switcher to perform transformations to headings, etc. - Block Toolbar: Has basic text alignments @@ -172,11 +172,11 @@ Basic image block. ![Image block placeholder](https://cldup.com/w6FNywNsj1-3000x3000.png) -### Placeholder: +#### Placeholder - A generic gray placeholder block with options to upload an image, drag and drop an image directly on it, or pick an image from the media library. -### Selected state: +#### Selected state - Block Toolbar: Alignments, including wide and full-width if the theme supports it. - Block Toolbar: Edit Image, to open the Media Library @@ -185,7 +185,7 @@ Basic image block. ![Image Block](https://cldup.com/6YYXstl_xX-3000x3000.png) -### Block settings: +#### Block settings - Has description: “They're worth 1,000 words! Insert a single image.” - Has options for changing or adding alt text and adding additional custom CSS classes. @@ -196,18 +196,18 @@ _Future improvements to the Image block could include getting rid of the media m ![Latest Post Block](https://cldup.com/8lyAByDpy_-3000x3000.png) -### Placeholder: +#### Placeholder Has no placeholder as it works immediately upon insertion. The default inserted state shows the last 5 posts. -### Selected state: +#### Selected state - Block Toolbar: Alignments - Block Toolbar: Options for picking list view or grid view _Note that the Block Toolbar does not include the Block Chip in this case, since there are no similar blocks to switch to._ -### Block settings: +#### Block settings - Has description: “Display a list of your most recent posts.” - Has options for post order, narrowing the list by category, changing the default number of posts to show, and showing the post date. diff --git a/docs/getting-started/devenv/get-started-with-create-block.md b/docs/getting-started/devenv/get-started-with-create-block.md index 3a2c6607b82cf..2d46dd18cffe5 100644 --- a/docs/getting-started/devenv/get-started-with-create-block.md +++ b/docs/getting-started/devenv/get-started-with-create-block.md @@ -4,7 +4,7 @@ Custom blocks for the Block Editor in WordPress are typically registered using p The package is designed to help developers quickly set up a block development environment following WordPress best practices. -## Quick Start +## Quick start ### Installation diff --git a/docs/getting-started/devenv/get-started-with-wp-scripts.md b/docs/getting-started/devenv/get-started-with-wp-scripts.md index 6416adc081e70..b6271620514df 100644 --- a/docs/getting-started/devenv/get-started-with-wp-scripts.md +++ b/docs/getting-started/devenv/get-started-with-wp-scripts.md @@ -123,7 +123,7 @@ To help developers improve the quality of their code, `wp-scripts` comes pre-con Regularly linting and formatting your code ensures it's functional, clear, and maintainable for yourself and other developers. -### Running Tests +### Running tests Beyond just writing code, verifying its functionality is crucial. `wp-scripts` includes [Jest](https://jestjs.io/), a JavaScript testing framework, and both end-to-end and unit testing scripts: diff --git a/docs/getting-started/fundamentals/javascript-in-the-block-editor.md b/docs/getting-started/fundamentals/javascript-in-the-block-editor.md index 9dc542a5a24c9..daaddd707c315 100644 --- a/docs/getting-started/fundamentals/javascript-in-the-block-editor.md +++ b/docs/getting-started/fundamentals/javascript-in-the-block-editor.md @@ -2,7 +2,7 @@ A JavaScript Build Process is recommended for most cases when working with Javascript for the Block Editor. With a build process, you'll be able to work with ESNext and JSX (among others) syntaxes and features in your code while producing code ready for the majority of the browsers. -## JavaScript Build Process +## JavaScript build process ["ESNext"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/JavaScript_technologies_overview#standardization_process) is a dynamic name that refers to Javascript's latest syntax and features. ["JSX"](https://react.dev/learn/writing-markup-with-jsx) is a custom syntax extension to JavaScript, created by React project, that allows you to write JavaScript using a familiar HTML tag-like syntax. diff --git a/docs/how-to-guides/README.md b/docs/how-to-guides/README.md index c0a2bd7f1fe6f..152f8ce6184ae 100644 --- a/docs/how-to-guides/README.md +++ b/docs/how-to-guides/README.md @@ -2,13 +2,13 @@ The new editor 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 +## Creating blocks 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](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md) ( 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, see the [Create a Block tutorial](/docs/getting-started/create-block/README.md) for the best place to start. -## Extending Blocks +## Extending blocks It is also possible to modify the behavior of existing blocks or even remove them completely using filters. @@ -24,11 +24,11 @@ Refer to the [Plugins](/packages/plugins/README.md) and [Edit Post](/packages/ed You can also filter certain aspects of the editor; this is documented on the [Editor Filters](/docs/reference-guides/filters/editor-filters.md) page. -## Meta Boxes +## Meta boxes Porting PHP meta boxes to blocks or sidebar plugins is highly encouraged, learn how in the [meta box](/docs/how-to-guides/metabox.md) and [sidebar plugin](/docs/how-to-guides/plugin-sidebar-0.md) guides. -## Theme Support +## 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. @@ -38,7 +38,7 @@ There are some advanced block features which require opt-in support in the theme Autocompleters within blocks may be extended and overridden. Learn more about the [autocomplete](/docs/reference-guides/filters/autocomplete-filters.md) filters. -## Block Parsing and Serialization +## 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. diff --git a/docs/how-to-guides/accessibility.md b/docs/how-to-guides/accessibility.md index 75458d6690cab..bdf9c977b5cf4 100644 --- a/docs/how-to-guides/accessibility.md +++ b/docs/how-to-guides/accessibility.md @@ -4,7 +4,7 @@ Accessibility documentation for developers working on the Gutenberg Project. For more information on accessibility and WordPress see the [Make WordPress Accessibility Handbook](https://make.wordpress.org/accessibility/handbook/) and the [Accessibility Team section](https://make.wordpress.org/accessibility/). -## Landmark Regions +## Landmark regions It is a best practice to include ALL content on the page in landmarks, so that screen reader users who rely on them to navigate from section to section do not lose track of content. diff --git a/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md index 9dc7f1f324743..94d4ea67d8cf9 100644 --- a/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md +++ b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md @@ -36,7 +36,7 @@ registerBlockType( 'gutenberg-examples/example-06', { } ); ``` -## Allowed Blocks +## Allowed blocks Using the `allowedBlocks` property, you can define the set of blocks allowed in your InnerBlock. This restricts the blocks that can be included only to those listed, all other blocks will not show in the inserter. @@ -56,7 +56,7 @@ By default, `InnerBlocks` expects its blocks to be shown in a vertical list. A v Specifying this prop does not affect the layout of the inner blocks, but results in the block mover icons in the child blocks being displayed horizontally, and also ensures that drag and drop works correctly. -## Default Block +## Default block By default `InnerBlocks` opens a list of permitted blocks via `allowedBlocks` when the block appender is clicked. You can modify the default block and its attributes that are inserted when the initial block appender is clicked by using the `defaultBlock` property. For example: @@ -93,7 +93,7 @@ const MY_TEMPLATE = [ Use the `templateLock` property to lock down the template. Using `all` locks the template completely so no changes can be made. Using `insert` prevents additional blocks from being inserted, but existing blocks can be reordered. See [templateLock documentation](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/inner-blocks/README.md#templatelock) for additional information. -### Post Template +### Post template Unrelated to `InnerBlocks` but worth mentioning here, you can create a [post template](https://developer.wordpress.org/block-editor/developers/block-api/block-templates/) by post type, that preloads the block editor with a set of blocks. @@ -109,7 +109,7 @@ add_action( 'init', function() { } ); ``` -## Using Parent and Ancestor Relationships in Blocks +## Using parent and ancestor relationships in blocks A common pattern for using InnerBlocks is to create a custom block that will be only be available if its parent block is inserted. This allows builders to establish a relationship between blocks, while limiting a nested block's discoverability. Currently, there are two relationships builders can use: `parent` and `ancestor`. The differences are: @@ -118,7 +118,7 @@ A common pattern for using InnerBlocks is to create a custom block that will be The key difference between `parent` and `ancestor` is `parent` has finer specificity, while an `ancestor` has greater flexibility in its nested hierarchy. -### Defining Parent Block Relationship +### Defining parent block relationship An example of this is the Column block, which is assigned the `parent` block setting. This allows the Column block to only be available as a nested direct descendant in its parent Columns block. Otherwise, the Column block will not be available as an option within the block inserter. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column). @@ -133,7 +133,7 @@ When defining a direct descendent block, use the `parent` block setting to defin } ``` -### Defining Ancestor Block Relationship +### Defining an ancestor block relationship An example of this is the Comment Author Name block, which is assigned the `ancestor` block setting. This allows the Comment Author Name block to only be available as a nested descendant in its ancestral Comment Template block. Otherwise, the Comment Author Name block will not be available as an option within the block inserter. See [Comment Author Name code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/comment-author-name). @@ -150,7 +150,7 @@ When defining a descendent block, use the `ancestor` block setting. This prevent } ``` -## Using a React Hook +## Using a React hook You can use a react hook called `useInnerBlocksProps` instead of the `InnerBlocks` component. This hook allows you to take more control over the markup of inner blocks areas. diff --git a/docs/how-to-guides/feature-flags.md b/docs/how-to-guides/feature-flags.md index 49fb8ba487edf..5855f93f8ed9f 100644 --- a/docs/how-to-guides/feature-flags.md +++ b/docs/how-to-guides/feature-flags.md @@ -8,7 +8,7 @@ The `process.env.IS_GUTENBERG_PLUGIN` is an environment variable whose value 'fl When the codebase is built for the plugin, this variable will be set to `true`. When building for WordPress core, it will be set to `false` or `undefined`. -## Basic Use +## Basic usage ### Exporting features @@ -69,7 +69,7 @@ if ( undefined ) { // Wepack has replaced `process.env.IS_GUTENBERG_PLUGIN` with `undefined` evaluates to `false` so the plugin-only feature will not be executed. -### Dead Code Elimination +### Dead code elimination For production builds, webpack ['minifies'](https://en.wikipedia.org/wiki/Minification_(programming)) the code, removing as much unnecessary JavaScript as it can. @@ -97,8 +97,8 @@ if ( undefined ) { In this case, the minification process will remove the entire `if` statement including the body, ensuring plugin-only code is not included in WordPress core build. -## FAQ +## Frequently asked questions -#### Why shouldn't I assign the result of an expression involving `IS_GUTENBERG_PLUGIN` to a variable, e.g. `const isMyFeatureActive = process.env.IS_GUTENBERG_PLUGIN === 2`? +### Why shouldn't I assign the result of an expression involving `IS_GUTENBERG_PLUGIN` to a variable, e.g. `const isMyFeatureActive = process.env.IS_GUTENBERG_PLUGIN === 2`? Introducing complexity may prevent webpack's minifier from identifying and therefore eliminating dead code. Therefore it is recommended to use the examples in this document to ensure your feature flag functions as intended. For further details, see the [Dead Code Elimination](#dead-code-elimination) section. diff --git a/docs/how-to-guides/format-api.md b/docs/how-to-guides/format-api.md index 00e1b82675c00..fe989575f8b00 100644 --- a/docs/how-to-guides/format-api.md +++ b/docs/how-to-guides/format-api.md @@ -173,7 +173,7 @@ registerFormatType( 'my-custom-format/sample-output', { } ); ``` -### Step5: Add a button outside of the dropdown (Optional) +### Step 5: Add a button outside of the dropdown (Optional) Using the `RichTextToolbarButton` component, the button is added to the default dropdown menu. You can add the button directly to the toolbar by using the `BlockControls` component. @@ -220,7 +220,7 @@ If you run into errors: - Confirm the JavaScript is loading in the editor. - Check for any console error messages. -## Additional Resources +## Additional resources Reference documentation used in this guide: diff --git a/docs/how-to-guides/internationalization.md b/docs/how-to-guides/internationalization.md index 08ce46edb3f58..cd341f1b9c6c5 100644 --- a/docs/how-to-guides/internationalization.md +++ b/docs/how-to-guides/internationalization.md @@ -1,6 +1,6 @@ # Internationalization -## What is Internationalization? +## What is internationalization? Internationalization is the process to provide multiple language support to software, in this case WordPress. Internationalization is often abbreviated as **i18n**, where 18 stands for the number of letters between the first _i_ and the last _n_. @@ -87,11 +87,11 @@ This is all you need to make your plugin JavaScript code translatable. When you set script translations for a handle WordPress will automatically figure out if a translations file exists on translate.wordpress.org, and if so ensure that it's loaded into `wp.i18n` before your script runs. With translate.wordpress.org, plugin authors also do not need to worry about setting up their own infrastructure for translations and can rely on a global community with dozens of active locales. Read more about [WordPress Translations](https://make.wordpress.org/meta/handbook/documentation/translations/). -## Provide Your Own Translations +## Provide your own translations You can create and ship your own translations with your plugin, if you have sufficient knowledge of the language(s) you can ensure the translations are available. -### Create Translation File +### Create the translation file The translation files must be in the JED 1.x JSON format. @@ -204,7 +204,7 @@ This will generate the JSON file `myguten-eo-[md5].json` with the contents: } ``` -### Load Translation File +### Load the translation file The final part is to tell WordPress where it can look to find the translation file. The `wp_set_script_translations` function accepts an optional third argument that is the path it will first check for translations. For example: @@ -220,12 +220,12 @@ WordPress will check for a file in that path with the format `${domain}-${locale Using `make-json` automatically names the file with the md5 hash, so it is ready as-is. You could rename the file to use the handle instead, in which case the file name would be `myguten-eo-myguten-script.json`. -### Test Translations +### Test translations You will need to set your WordPress installation to Esperanto language. Go to Settings > General and change your site language to Esperanto. With the language set, create a new post, add the block, and you will see the translations used. -### Filtering Translations +### Filtering translations The outputs of the translation functions (`__()`, `_x()`, `_n()`, and `_nx()`) are filterable, see [i18n Filters](/docs/reference-guides/filters/i18n-filters.md) for full information. diff --git a/docs/how-to-guides/metabox.md b/docs/how-to-guides/metabox.md index e0402b1180c1c..b1baac1f25585 100644 --- a/docs/how-to-guides/metabox.md +++ b/docs/how-to-guides/metabox.md @@ -8,7 +8,7 @@ The block editor does support most existing meta boxes, see [the backward compat If you are interested in working with the post meta outside the editor, check out the [Sidebar Tutorial](/docs/how-to-guides/sidebar-tutorial/plugin-sidebar-0.md). -### Use Blocks to Store Meta +### Use blocks to store meta Typically, blocks store attribute values in the serialized block HTML. However, you can also create a block that saves its attribute values as post meta, that can be accessed programmatically anywhere in your template. @@ -35,7 +35,7 @@ A [complete meta-block example](https://github.com/WordPress/block-development-e 3. [Use Post Meta Data](#step-3-use-post-meta-data) 4. [Finishing Touches](#step-4-use-block-templates-optional) -### Step 1: Register Meta Field +### Step 1: Register meta field A post meta field is a WordPress object used to store extra data about a post. You need to first register a new meta field prior to use. See Managing [Post Metadata](https://developer.wordpress.org/plugins/metadata/managing-post-metadata/) to learn more about post meta. @@ -58,7 +58,7 @@ function myguten_register_post_meta() { add_action( 'init', 'myguten_register_post_meta' ); ``` -### Step 2: Add Meta Block +### Step 2: Add meta block With the meta field registered in the previous step, next create a new block to display the field value to the user. @@ -114,11 +114,11 @@ You could also confirm the data is saved by checking the database table `wp_post **Troubleshooting**: Be sure to build your code between changes, you updated the PHP code from Step 1, and JavaScript files are enqueued. Check the build output and developer console for errors. -### Step 3: Use Post Meta Data +### Step 3: Use post meta data You can use the post meta data stored in the last step in multiple ways. -#### Use Post Meta in PHP +#### Use post meta in PHP The first example uses the value from the post meta field and appends it to the end of the post content wrapped in a `H4` tag. @@ -134,7 +134,7 @@ function myguten_content_filter( $content ) { add_filter( 'the_content', 'myguten_content_filter' ); ``` -#### Use Post Meta in Block +#### Use post meta in a block You can also use the post meta data in other blocks. For this example the data is loaded at the end of every Paragraph block when it is rendered, ie. shown to the user. You can replace this for any core or custom block types as needed. @@ -157,7 +157,7 @@ register_block_type( 'core/paragraph', array( ) ); ``` -### Step 4: Use Block Templates (optional) +### Step 4: Use block templates (optional) One problem using a meta block is the block is easy for an author to forget, since it requires being added to each post. You solve this by using [block templates](/docs/reference-guides/block-api/block-templates.md). A block template is a predefined list of block items per post type. Templates allow you to specify a default initial state for a post type. @@ -181,9 +181,9 @@ You can also add other block types in the array, including placeholders, or even This guide showed how using blocks you can read and write to post meta. See the section below for backward compatibility with existing meta boxes. -## Backward Compatibility +## Backward compatibility -### Testing, Converting, and Maintaining Existing Meta Boxes +### Testing, converting, and maintaining existing meta boxes Before converting meta boxes to blocks, it may be easier to test if a meta box works with the block editor, and explicitly mark it as such. @@ -213,7 +213,7 @@ add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback', When the block editor is used, this meta box will no longer be displayed in the meta box area, as it now only exists for backward compatibility purposes. It will display as before in the classic editor. -### Meta Box Data Collection +### Meta box data collection On each block editor page load, we register an action that collects the meta box data to determine if an area is empty. The original global state is reset upon collection of meta box data. @@ -227,14 +227,14 @@ Then each location for this particular type of meta box is checked for whether i Ideally, this could be done at instantiation of the editor and help simplify this flow. However, it is not possible to know the meta box state before `admin_enqueue_scripts`, where we are calling `initializeEditor()`. This will have to do, unless we want to move `initializeEditor()` to fire in the footer or at some point after `admin_head`. With recent changes to editor bootstrapping this might now be possible. Test with ACF to make sure. -### Redux and React Meta Box Management +### Redux and React meta box management When rendering the block editor, the meta boxes are rendered to a hidden div `#metaboxes`. _The Redux store will hold all meta boxes as inactive by default_. When `INITIALIZE_META_BOX_STATE` comes in, the store will update any active meta box areas by setting the `isActive` flag to `true`. Once this happens React will check for the new props sent in by Redux on the `MetaBox` component. If that `MetaBox` is now active, instead of rendering null, a `MetaBoxArea` component will be rendered. The `MetaBox` component is the container component that mediates between the `MetaBoxArea` and the Redux Store. _If no meta boxes are active, nothing happens. This will be the default behavior, as all core meta boxes have been stripped._ -#### MetaBoxArea Component +#### MetaBoxArea component When the component renders it will store a reference to the meta boxes container and retrieve the meta boxes HTML from the prefetch location. @@ -250,7 +250,7 @@ This url is automatically passed into React via a `_wpMetaBoxUrl` global variabl This page mimics the `post.php` post form, so when it is submitted it will fire all of the normal hooks and actions, and have the proper global state to correctly fire any PHP meta box mumbo jumbo without needing to modify any existing code. On successful submission, React will signal a `handleMetaBoxReload` to remove the updating overlay. -### Common Compatibility Issues +### Common compatibility issues Most PHP meta boxes should continue to work in the block editor, but some meta boxes that include advanced functionality could break. Here are some common reasons why meta boxes might not work as expected in the block editor: diff --git a/docs/how-to-guides/notices/README.md b/docs/how-to-guides/notices/README.md index 4b9a32c664a96..d52004b7e4845 100644 --- a/docs/how-to-guides/notices/README.md +++ b/docs/how-to-guides/notices/README.md @@ -73,7 +73,7 @@ To better understand the specific code example above: Check out the [_Loading JavaScript_](/docs/how-to-guides/javascript/loading-javascript.md) tutorial for a primer on how to load your custom JavaScript into the block editor. -## Learn More +## Learn more The block editor offers a complete API for generating notices. The official documentation is a great place to review what's possible. diff --git a/docs/how-to-guides/platform/README.md b/docs/how-to-guides/platform/README.md index f63f8b6a5cbb1..2ed96d6c83d87 100644 --- a/docs/how-to-guides/platform/README.md +++ b/docs/how-to-guides/platform/README.md @@ -2,7 +2,7 @@ The Gutenberg Project is not only building a better editor for WordPress, but also creating a platform to build upon. This platform consists of a set of JavaScript packages and tools that you can use in your web application. [View the list of packages available on npm](https://www.npmjs.com/org/wordpress). -## UI Components +## UI components The [WordPress Components package](/packages/components/README.md) contains a set of UI components you can use in your project. See the [WordPress Storybook site](https://wordpress.github.io/gutenberg/) for an interactive guide to the available components and settings. @@ -26,7 +26,7 @@ function MyApp() { Many components include CSS to add style, you will need to include for the components to appear correctly. The component stylesheet can be found in `node_modules/@wordpress/components/build-style/style.css`, you can link directly or copy and include it in your project. -## Development Scripts +## Development scripts The [`@wordpress/scripts` package](/packages/scripts/README.md) is a collection of reusable scripts for JavaScript development — includes scripts for building, linting, and testing — all with no additional configuration files. diff --git a/docs/how-to-guides/plugin-sidebar-0.md b/docs/how-to-guides/plugin-sidebar-0.md index bf084680c3d1b..95bd26f7ee1f8 100644 --- a/docs/how-to-guides/plugin-sidebar-0.md +++ b/docs/how-to-guides/plugin-sidebar-0.md @@ -14,7 +14,7 @@ The tutorial assumes you have an existing plugin setup and are ready to add PHP ## Step-by-step guide -### Step 1: Get a Sidebar up and Running +### Step 1: Get a sidebar up and running The first step is to tell the editor that there is a new plugin that will have its own sidebar. Use the [registerPlugin](/packages/plugins/README.md), [PluginSidebar](/packages/edit-post/README.md#pluginsidebar), and [createElement](/packages/element/README.md) utilities provided by the `@wordpress/plugins`, `@wordpress/edit-post`, and `react` packages, respectively. @@ -168,7 +168,7 @@ Reload the editor and open the sidebar: This code doesn't let users store or retrieve data just yet, so the next steps will focus on how to connect it to the meta block field. -### Step 3: Register the Meta Field +### Step 3: Register the meta field To work with fields in the `post_meta` table, use the [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/). function to create a new field called `sidebar_plugin_meta_block_field`. @@ -194,7 +194,7 @@ The function will return an object containing the registered meta field you regi If the code returns `undefined` make sure your post type supports `custom-fields`. Either when [registering the post](https://developer.wordpress.org/reference/functions/register_post_type/#supports) or with [add_post_type_support function](https://developer.wordpress.org/reference/functions/add_post_type_support/). -### Step 4: Initialize the Input Control +### Step 4: Initialize the input control With the field available in the editor store, it can now be surfaced to the UI. We extract the input control to a function to keep the code clean as we add functionality. @@ -297,7 +297,7 @@ wp.data You can observe the content changing in the input component. -### Step 5: Update the Meta Field When the Input's Content Changes +### Step 5: Update the meta field when the input's content changes The last step is to update the meta field when the input content changes. The `useDispatch` function takes a store name as its only argument and returns methods that you can use to update the store, in this case we'll use `editPost` diff --git a/docs/how-to-guides/propagating-updates.md b/docs/how-to-guides/propagating-updates.md index ae5cb5f3b2a9a..5f2861a4e456c 100644 --- a/docs/how-to-guides/propagating-updates.md +++ b/docs/how-to-guides/propagating-updates.md @@ -40,7 +40,7 @@ It is not fool-proof because users can modify the class via the editor UI. Howe As the name suggests, these blocks are inherently synced across your site. Keep in mind that there are currently limitations with relying on reusable blocks to handle certain updates since content, HTML structure, and styles will all stay in sync when updates happen. If you require more nuance than that, this is a key element to factor in and a dynamic block might be a better approach. -### Template Parts and Templates +### Template parts and templates Because block themes allow users to directly edit templates and template parts, how changes are managed need to be adjusted in light of the greater access given to users. For context, when templates or template parts are changed by the user, the updated templates from the theme update don’t show for the user. Only new users of the theme or users who have not yet edited a template are experiencing the updated template. If users haven’t modified the files then the changes you make on the file system will be reflected on the user’s sites – you just need to update the files and they’ll get the changes. However if they have made changes to their templates then the only way you can update their templates is to: diff --git a/docs/manifest.json b/docs/manifest.json index 6b5ee58d4d6a5..22b2edc4abc4b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2130,7 +2130,7 @@ "parent": "architecture" }, { - "title": "Styles", + "title": "Styles in the Editor", "slug": "styles", "markdown_source": "../docs/explanations/architecture/styles.md", "parent": "architecture" diff --git a/docs/reference-guides/block-api/block-attributes.md b/docs/reference-guides/block-api/block-attributes.md index 35ec1c1e7c64e..cef32e5bb42fe 100644 --- a/docs/reference-guides/block-api/block-attributes.md +++ b/docs/reference-guides/block-api/block-attributes.md @@ -68,7 +68,7 @@ The saved HTML will contain the `title` and `size` in the comment delimiter, and If an attributes change over time then a [block deprecation](/docs/reference-guides/block-api/block-deprecation.md) can help migrate from an older attribute, or remove it entirely. -## Type Validation +## Type validation The `type` indicates the type of data that is stored by the attribute. It does not indicate where the data is stored, which is defined by the `source` field. @@ -86,7 +86,7 @@ The `type` field MUST be one of the following: Note that the validity of an `object` is determined by your `source`. For an example, see the `query` details below. -## Enum Validation +## Enum validation An attribute can be defined as one of a fixed set of values. This is specified by an `enum`, which contains an array of allowed values: @@ -100,7 +100,7 @@ _Example_: Example `enum`. } ``` -## Value Source +## Value source Attribute sources are used to define how the attribute values are extracted from saved post content. They provide a mechanism to map from the saved markup to a JavaScript representation of a block. @@ -430,7 +430,7 @@ function onChange( event ) { } ``` -## Default Value +## Default value A block attribute can contain a default value, which will be used if the `type` and `source` do not match anything within the block content. diff --git a/docs/reference-guides/block-api/block-context.md b/docs/reference-guides/block-api/block-context.md index 3ab3175a0d1b2..3541f632673d3 100644 --- a/docs/reference-guides/block-api/block-context.md +++ b/docs/reference-guides/block-api/block-context.md @@ -6,11 +6,11 @@ This is especially useful in full-site editing where, for example, the contents If you are familiar with [React Context](https://reactjs.org/docs/context.html), block context adopts many of the same ideas. In fact, the client-side block editor implementation of block context is a very simple application of React Context. Block context is also supported in server-side `render_callback` implementations, demonstrated in the examples below. -## Defining Block Context +## Defining block context Block context is defined in the registered settings of a block. A block can provide a context value, or consume a value it seeks to inherit. -### Providing Block Context +### Providing block context A block can provide a context value by assigning a `providesContext` property in its registered settings. This is an object which maps a context name to one of the block's own attribute. The value corresponding to that attribute value is made available to descendent blocks and can be referenced by the same context name. Currently, block context only supports values derived from the block's own attributes. This could be enhanced in the future to support additional sources of context values. @@ -32,7 +32,7 @@ For complete example, refer to the section below. As seen in the above example, it is recommended that you include a namespace as part of the name of the context key so as to avoid potential conflicts with other plugins or default context values provided by WordPress. The context namespace should be specific to your plugin, and in most cases can be the same as used in the name of the block itself. -### Consuming Block Context +### Consuming block context A block can inherit a context value from an ancestor provider by assigning a `usesContext` property in its registered settings. This should be assigned as an array of the context names the block seeks to inherit. @@ -45,7 +45,7 @@ registerBlockType('my-plugin/record-title', { ``` -## Using Block Context +## Using block context Once a block has defined the context it seeks to inherit, this can be accessed in the implementation of `edit` (JavaScript) and `render_callback` (PHP). It is provided as an object (JavaScript) or associative array (PHP) of the context values which have been defined for the block. Note that a context value will only be made available if the block explicitly defines a desire to inherit that value. diff --git a/docs/reference-guides/block-api/block-edit-save.md b/docs/reference-guides/block-api/block-edit-save.md index a8b6f9171bdef..3a833e3d5ce34 100644 --- a/docs/reference-guides/block-api/block-edit-save.md +++ b/docs/reference-guides/block-api/block-edit-save.md @@ -24,7 +24,7 @@ const blockSettings = { }; ``` -### block wrapper props +### Block wrapper props The first thing to notice here is the use of the `useBlockProps` React hook on the block wrapper element. In the example above, the block wrapper renders a "div" in the editor, but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block... the block wrapper element should apply props retrieved from the `useBlockProps` react hook call. The block wrapper element should be a native DOM element, like `
` and ``, or a React component that forwards any additional props to native DOM elements. Using a `` or `` component, for instance, would be invalid. diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index d023742092df1..f89257f52d044 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -61,7 +61,7 @@ Starting in WordPress 5.8 release, we recommend using the `block.json` metadata } ``` -## Benefits using the metadata file +## Benefits of using the metadata file The block definition allows code sharing between JavaScript, PHP, and other languages when processing block types stored as JSON, and registering blocks with the `block.json` metadata file provides multiple benefits on top of it. @@ -85,7 +85,7 @@ Check ` (JSX) within your save function instead of simply outputting the value with `

{ heading }

`. -### Unwanted Formatting Options Still Display +### Unwanted formatting options still display Before moving forward, consider if using the RichText component makes sense at all. Would it be better to use a basic `input` or `textarea` element? If you don't think any formatting should be possible, these HTML tags may make more sense. @@ -81,7 +81,7 @@ If you'd still like to use RichText, you can eliminate all of the formatting opt If you want to limit the formats allowed, you can specify using `allowedFormats` property in your code, see the example above or [the component documentation](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md#allowedformats-array) for details. -### Disable Specific Format Types in Editor +### Disable specific fromat types in Editor The RichText component uses formats to display inline elements, for example images within the paragraph block. If you just want to disable a format from the editor, you can use the `unregisterFormatType` function. For example to disable inline images, use: diff --git a/docs/reference-guides/theme-json-reference/README.md b/docs/reference-guides/theme-json-reference/README.md index 819e7d561cda0..92f6f77e298c0 100644 --- a/docs/reference-guides/theme-json-reference/README.md +++ b/docs/reference-guides/theme-json-reference/README.md @@ -4,7 +4,7 @@ This reference guide lists the settings and style properties defined in the them - [Version 2 (living reference)](/docs/reference-guides/theme-json-reference/theme-json-living.md) -## Older Versions +## Older versions - [Migrating to Newer Theme.json Versions](/docs/reference-guides/theme-json-reference/theme-json-migrations.md) - [Version 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) diff --git a/docs/reference-guides/theme-json-reference/styles-versions.md b/docs/reference-guides/theme-json-reference/styles-versions.md index 734c59c3d159c..0cbffdc6ebfe0 100644 --- a/docs/reference-guides/theme-json-reference/styles-versions.md +++ b/docs/reference-guides/theme-json-reference/styles-versions.md @@ -2,7 +2,7 @@ New styles options are integrated into theme.json on a regular basis. Knowing the style options available through theme.json or the styles editor at any given time can be challenging. To clarify, the table below indicates the WordPress version when each theme.json styles option became available and when a corresponding control was added to the user interface to allow management of the style from the Styles editor. -## Styles Keys +## Styles keys | Key | theme.json Since| Style Editor Since | | --- | :---: | :---: |