diff --git a/docs/block-api.md b/docs/block-api.md index 34bb7596f111b..5f9572ce8acf6 100644 --- a/docs/block-api.md +++ b/docs/block-api.md @@ -105,7 +105,7 @@ attributes: { }, ``` -* **See: [Attributes](https://wordpress.org/gutenberg/handbook/block-api/attributes/).** +* **See: [Attributes](../docs/block-api/attributes.md).** #### Transforms (optional) @@ -300,4 +300,4 @@ html: false, ## Edit and Save -The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](https://wordpress.org/gutenberg/handbook/block-edit-save/). +The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](../docs/block-api/block-edit-save.md). diff --git a/docs/attributes.md b/docs/block-api/attributes.md similarity index 100% rename from docs/attributes.md rename to docs/block-api/attributes.md diff --git a/docs/block-edit-save.md b/docs/block-api/block-edit-save.md similarity index 88% rename from docs/block-edit-save.md rename to docs/block-api/block-edit-save.md index 55a48b5bf8624..cb3c3780c2b41 100644 --- a/docs/block-edit-save.md +++ b/docs/block-api/block-edit-save.md @@ -105,7 +105,7 @@ For most blocks, the return value of `save` should be an [instance of WordPress _Note:_ While it is possible to return a string value from `save`, it _will be escaped_. If the string includes HTML markup, the markup will be shown on the front of the site verbatim, not as the equivalent HTML node content. If you must return raw HTML from `save`, use `wp.element.RawHTML`. As the name implies, this is prone to [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) and therefore is discouraged in favor of a WordPress Element hierarchy whenever possible. -For [dynamic blocks](https://wordpress.org/gutenberg/handbook/blocks/creating-dynamic-blocks/), the return value of `save` could either represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. Alternatively, return a `null` (empty) value to save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site. +For [dynamic blocks](../../docs/blocks/creating-dynamic-blocks.md), the return value of `save` could either represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. Alternatively, return a `null` (empty) value to save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site. ### attributes @@ -155,10 +155,10 @@ The two most common sources of block invalidations are: Before starting to debug, be sure to familiarize yourself with the validation step described above documenting the process for detecting whether a block is invalid. A block is invalid if its regenerated markup does not match what is saved in post content, so often this can be caused by the attributes of a block being parsed incorrectly from the saved content. -If you're using [attribute sources](https://wordpress.org/gutenberg/handbook/block-api/attributes/), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`). +If you're using [attribute sources](../../docs/block-api/attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`). When a block is detected as invalid, a warning will be logged into your browser's developer tools console. The warning will include specific details about the exact point at which a difference in markup occurred. Be sure to look closely at any differences in the expected and actual markups to see where problems are occurring. **I've changed my block's `save` behavior and old content now includes invalid blocks. How can I fix this?** -Refer to the guide on [Deprecated Blocks](https://wordpress.org/gutenberg/handbook/block-api/deprecated-blocks/) to learn more about how to accommodate legacy content in intentional markup changes. +Refer to the guide on [Deprecated Blocks](../../docs/block-api/deprecated-blocks.md) to learn more about how to accommodate legacy content in intentional markup changes. diff --git a/docs/deprecated-blocks.md b/docs/block-api/deprecated-blocks.md similarity index 100% rename from docs/deprecated-blocks.md rename to docs/block-api/deprecated-blocks.md diff --git a/docs/blocks-stylesheet.md b/docs/blocks/applying-styles-with-stylesheets.md similarity index 100% rename from docs/blocks-stylesheet.md rename to docs/blocks/applying-styles-with-stylesheets.md diff --git a/docs/blocks-controls.md b/docs/blocks/block-controls-toolbars-and-inspector.md similarity index 100% rename from docs/blocks-controls.md rename to docs/blocks/block-controls-toolbars-and-inspector.md diff --git a/docs/blocks-dynamic.md b/docs/blocks/creating-dynamic-blocks.md similarity index 100% rename from docs/blocks-dynamic.md rename to docs/blocks/creating-dynamic-blocks.md diff --git a/docs/blocks-scaffolding.md b/docs/blocks/generate-blocks-with-wp-cli.md similarity index 100% rename from docs/blocks-scaffolding.md rename to docs/blocks/generate-blocks-with-wp-cli.md diff --git a/docs/blocks-editable.md b/docs/blocks/introducing-attributes-and-editable-fields.md similarity index 97% rename from docs/blocks-editable.md rename to docs/blocks/introducing-attributes-and-editable-fields.md index 941e886204f3f..9566befb6aaf7 100644 --- a/docs/blocks-editable.md +++ b/docs/blocks/introducing-attributes-and-editable-fields.md @@ -100,7 +100,7 @@ registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', { ``` {% end %} -When registering a new block type, the `attributes` property describes the shape of the attributes object you'd like to receive in the `edit` and `save` functions. Each value is a [source function](../../block-api/attributes) to find the desired value from the markup of the block. +When registering a new block type, the `attributes` property describes the shape of the attributes object you'd like to receive in the `edit` and `save` functions. Each value is a [source function](../../docs/block-api/attributes.md) to find the desired value from the markup of the block. In the code snippet above, when loading the editor, we will extract the `content` value as the children of the paragraph element in the saved post's markup. diff --git a/docs/blocks-basic.md b/docs/blocks/writing-your-first-block-type.md similarity index 100% rename from docs/blocks-basic.md rename to docs/blocks/writing-your-first-block-type.md diff --git a/docs/extensibility.md b/docs/extensibility.md index ee1931cecbcac..9e3a33ebda8ea 100644 --- a/docs/extensibility.md +++ b/docs/extensibility.md @@ -25,13 +25,13 @@ wp.blocks.registerBlockType( 'mytheme/red-block', { } ); ``` -If you want to learn more about block creation, the [Blocks Tutorial](./blocks.md) is the best place to start. +If you want to learn more about block creation, the [Blocks Tutorial](../docs/blocks.md) is the best place to start. ## Extending Blocks It is also possible to modify the behavior of existing blocks or even remove them completely using filters. -Learn more in the [Extending Blocks](./extensibility/extending-blocks.md) section. +Learn more in the [Extending Blocks](../docs/extensibility/extending-blocks.md) section. ## Extending the Editor UI @@ -43,14 +43,14 @@ Refer to the [Plugins](https://github.com/WordPress/gutenberg/blob/master/plugin **Porting PHP meta boxes to blocks is highly encouraged!** -Discover how [Meta Box](./extensibility/meta-box.md) support works in Gutenberg. +Discover how [Meta Box](../docs/extensibility/meta-box.md) support works in Gutenberg. ## Theme Support By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults. -There are some advanced block features which require opt-in support in the theme. See [theme support](./extensibility/theme-support.md). +There are some advanced block features which require opt-in support in the theme. See [theme support](../docs/extensibility/theme-support.md). ## Autocomplete -Autocompleters within blocks may be extended and overridden. See [autocomplete](./extensibility/autocomplete.md). +Autocompleters within blocks may be extended and overridden. See [autocomplete](../docs/extensibility/autocomplete.md). diff --git a/docs/extensibility/extending-blocks.md b/docs/extensibility/extending-blocks.md index bbbb709350c81..c0579171bf3af 100644 --- a/docs/extensibility/extending-blocks.md +++ b/docs/extensibility/extending-blocks.md @@ -38,7 +38,7 @@ wp.hooks.addFilter( ); ``` -_Note:_ This filter must always be run on every page load, and not in your browser's developer tools console. Otherwise, a [block validation](https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#validation) error will occur the next time the post is edited. This is due to the fact that block validation occurs by verifying that the saved output matches what is stored in the post's content during editor initialization. So, if this filter does not exist when the editor loads, the block will be marked as invalid. +_Note:_ This filter must always be run on every page load, and not in your browser's developer tools console. Otherwise, a [block validation](../../docs/block-api/block-edit-save.md#validation) error will occur the next time the post is edited. This is due to the fact that block validation occurs by verifying that the saved output matches what is stored in the post's content during editor initialization. So, if this filter does not exist when the editor loads, the block will be marked as invalid. #### `blocks.getBlockDefaultClassName` diff --git a/docs/language.md b/docs/language.md index f8b1fbf0307d8..5a88f901bb81b 100644 --- a/docs/language.md +++ b/docs/language.md @@ -79,7 +79,7 @@ After running this through the parser we're left with a simple object we can man This has dramatic implications for how simple and performant we can make our parser. These explicit boundaries also protect damage in a single block from bleeding into other blocks or tarnishing the entire document. It also allows the system to identify unrecognized blocks before rendering them. -_N.B.:_ The defining aspect 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](../block-api/attributes) for details. +_N.B.:_ The defining aspect 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/block-api/attributes.md) for details. ## The Anatomy of a Serialized Block diff --git a/docs/manifest.json b/docs/manifest.json index f1630e0aec0e6..1130128687ab5 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -20,13 +20,13 @@ { "title": "Attributes", "slug": "attributes", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/attributes.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/block-api\/attributes.md", "parent": "block-api" }, { "title": "Edit and Save", "slug": "block-edit-save", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/block-edit-save.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/block-api\/block-edit-save.md", "parent": "block-api" }, { @@ -38,7 +38,7 @@ { "title": "Deprecated Blocks", "slug": "deprecated-blocks", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/deprecated-blocks.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/block-api\/deprecated-blocks.md", "parent": "block-api" }, { @@ -86,37 +86,37 @@ { "title": "Writing Your First Block Type", "slug": "writing-your-first-block-type", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-basic.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks\/writing-your-first-block-type.md", "parent": "blocks" }, { "title": "Applying Styles With Stylesheets", "slug": "applying-styles-with-stylesheets", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-stylesheet.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks\/applying-styles-with-stylesheets.md", "parent": "blocks" }, { "title": "Introducing Attributes and Editable Fields", "slug": "introducing-attributes-and-editable-fields", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-editable.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks\/introducing-attributes-and-editable-fields.md", "parent": "blocks" }, { "title": "Block Controls: Toolbars and Inspector", "slug": "block-controls-toolbars-and-inspector", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-controls.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks\/block-controls-toolbars-and-inspector.md", "parent": "blocks" }, { "title": "Creating dynamic blocks", "slug": "creating-dynamic-blocks", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-dynamic.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks\/creating-dynamic-blocks.md", "parent": "blocks" }, { "title": "Generate Blocks with WP-CLI", "slug": "generate-blocks-with-wp-cli", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-scaffolding.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks\/generate-blocks-with-wp-cli.md", "parent": "blocks" }, { @@ -128,55 +128,55 @@ { "title": "Glossary", "slug": "glossary", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/glossary.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/glossary.md", "parent": "reference" }, { "title": "Design Principles", "slug": "design-principles", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/design.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/design-principles.md", "parent": "reference" }, { "title": "History", "slug": "history", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/history.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/history.md", "parent": "reference" }, { "title": "Coding Guidelines", "slug": "coding-guidelines", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/coding-guidelines.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/coding-guidelines.md", "parent": "reference" }, { "title": "Testing Overview", "slug": "testing-overview", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/testing-overview.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/testing-overview.md", "parent": "reference" }, { "title": "Frequently Asked Questions", "slug": "faq", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/faq.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/faq.md", "parent": "reference" }, { "title": "Release Process", "slug": "release", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/release.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/release.md", "parent": "reference" }, { "title": "Deprecated Features", "slug": "deprecated", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/deprecated.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/deprecated.md", "parent": "reference" }, { "title": "Repository Management", "slug": "repository-management", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/repository-management.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/reference\/repository-management.md", "parent": "reference" }, { @@ -188,25 +188,25 @@ { "title": "Articles", "slug": "articles", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/articles.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/outreach\/docs\/articles.md", "parent": "outreach" }, { "title": "Meetups", "slug": "meetups", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/meetups.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/outreach\/meetups.md", "parent": "outreach" }, { "title": "Talks", "slug": "talks", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/talks.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/outreach\/talks.md", "parent": "outreach" }, { "title": "Resources", "slug": "resources", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/resources.md", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/outreach\/resources.md", "parent": "outreach" } ] diff --git a/docs/articles.md b/docs/outreach/articles.md similarity index 100% rename from docs/articles.md rename to docs/outreach/articles.md diff --git a/docs/meetups.md b/docs/outreach/meetups.md similarity index 100% rename from docs/meetups.md rename to docs/outreach/meetups.md diff --git a/docs/resources.md b/docs/outreach/resources.md similarity index 100% rename from docs/resources.md rename to docs/outreach/resources.md diff --git a/docs/talks.md b/docs/outreach/talks.md similarity index 100% rename from docs/talks.md rename to docs/outreach/talks.md diff --git a/docs/reference.md b/docs/reference.md index fe38f179d3286..043155e9f6512 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,7 +1,7 @@ # Reference -- [Glossary](./reference/glossary) -- [Design Principles](./reference/design-principles) -- [Coding Guidelines](./reference/coding-guidelines) -- [Testing Overview](./reference/testing-overview) -- [Frequently Asked Questions](./reference/faq) +- [Glossary](../docs/reference/glossary.md) +- [Design Principles](../docs/reference/design-principles.md) +- [Coding Guidelines](../docs/reference/coding-guidelines.md) +- [Testing Overview](../docs/reference/testing-overview.md) +- [Frequently Asked Questions](../docs/reference/faq.md) diff --git a/docs/coding-guidelines.md b/docs/reference/coding-guidelines.md similarity index 100% rename from docs/coding-guidelines.md rename to docs/reference/coding-guidelines.md diff --git a/docs/deprecated.md b/docs/reference/deprecated.md similarity index 100% rename from docs/deprecated.md rename to docs/reference/deprecated.md diff --git a/docs/design.md b/docs/reference/design-principles.md similarity index 100% rename from docs/design.md rename to docs/reference/design-principles.md diff --git a/docs/faq.md b/docs/reference/faq.md similarity index 96% rename from docs/faq.md rename to docs/reference/faq.md index 1d9a105c3d50a..88d181f954c88 100644 --- a/docs/faq.md +++ b/docs/reference/faq.md @@ -51,7 +51,7 @@ Gutenberg will work in modern browsers, and Internet Explorer 11. ## How do I make my own block? -The API for creating blocks is a crucial aspect of the project. We are working on improved documentation and tutorials. Check out the [Creating Block Types](https://wordpress.org/gutenberg/handbook/blocks/) section to get started. +The API for creating blocks is a crucial aspect of the project. We are working on improved documentation and tutorials. Check out the [Creating Block Types](../../docs/blocks.md) section to get started. ## Does Gutenberg involve editing posts/pages in the front-end? @@ -97,7 +97,7 @@ Blocks will be able to provide base structural CSS styles, and themes can add st Other features, like the new _wide_ and _full-wide_ alignment options, will simply be CSS classes applied to blocks that offer this alignment. We are looking at how a theme can opt in to this feature, for example using `add_theme_support`. -*See:* [Theme Support](https://wordpress.org/gutenberg/handbook/extensibility/theme-support/) +*See:* [Theme Support](../../docs/extensibility/theme-support.md) ## How will editor styles work? @@ -146,7 +146,7 @@ If you would like to contribute to the accessibility of Gutenberg, we can always ## Are there any design resources for Gutenberg? -Yes, primarily in [design principles](https://wordpress.org/gutenberg/handbook/reference/design-principles/) +Yes, primarily in [design principles](../../docs/reference/design-principles.md) We are still adding more documentation. @@ -156,7 +156,7 @@ Our approach—as outlined in [the technical overview introduction](https://make This also [gives us the flexibility](https://github.com/WordPress/gutenberg/issues/1516) to store those blocks that are inherently separate from the content stream (reusable pieces like widgets or small post type elements) elsewhere, and just keep token references for their placement. -We suggest you look at the [language of Gutenberg](../language/) to learn more about how this aspect of the project works. +We suggest you look at the [language of Gutenberg](../../docs/language.md) to learn more about how this aspect of the project works. ## How can I parse the post content back out into blocks in PHP or JS? In JS: diff --git a/docs/glossary.md b/docs/reference/glossary.md similarity index 100% rename from docs/glossary.md rename to docs/reference/glossary.md diff --git a/docs/history.md b/docs/reference/history.md similarity index 100% rename from docs/history.md rename to docs/reference/history.md diff --git a/docs/release.md b/docs/reference/release.md similarity index 100% rename from docs/release.md rename to docs/reference/release.md diff --git a/docs/repository-management.md b/docs/reference/repository-management.md similarity index 100% rename from docs/repository-management.md rename to docs/reference/repository-management.md diff --git a/docs/testing-overview.md b/docs/reference/testing-overview.md similarity index 98% rename from docs/testing-overview.md rename to docs/reference/testing-overview.md index ed301b3a567c7..303f5fa1522f3 100644 --- a/docs/testing-overview.md +++ b/docs/reference/testing-overview.md @@ -21,7 +21,7 @@ When writing tests consider the following: Tests for JavaScript use [Jest](http://facebook.github.io/jest/) as the test runner and its API for [globals](https://facebook.github.io/jest/docs/en/api.html) (`describe`, `test`, `beforeEach` and so on) [assertions](http://facebook.github.io/jest/docs/en/expect.html), [mocks](http://facebook.github.io/jest/docs/en/mock-functions.html), [spies](http://facebook.github.io/jest/docs/en/jest-object.html#jestspyonobject-methodname) and [mock functions](https://facebook.github.io/jest/docs/en/mock-function-api.html). If needed, you can also use [Enzyme](https://github.com/airbnb/enzyme) for React component testing. -Assuming you've followed the [instructions](../CONTRIBUTING.md) to install Node and project dependencies, tests can be run from the command-line with NPM: +Assuming you've followed the [instructions](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) to install Node and project dependencies, tests can be run from the command-line with NPM: ``` npm test