Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganise documentation #11817

Merged
merged 22 commits into from Nov 20, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
fdf1591
Initial reworking; props @0aveRyan
chrisvanpatten Nov 19, 2018
01476c9
Fixes for the manifest/generators
chrisvanpatten Nov 19, 2018
44af175
A few missed items and small formatting tweaks
chrisvanpatten Nov 19, 2018
f0b5933
Simplify/flatten the directory structure
chrisvanpatten Nov 19, 2018
7631868
Cheat my way around a merge conflict pt1
chrisvanpatten Nov 19, 2018
19c45fe
fight the git powers
chrisvanpatten Nov 19, 2018
4b971ad
JSON version of TOC instead of YML
chrisvanpatten Nov 19, 2018
f059f9d
Ensure all files have good titles
chrisvanpatten Nov 20, 2018
982a1c0
Add a generator script and re-generate the root-manifest
chrisvanpatten Nov 20, 2018
2b9b6be
Update docs/designers-developers/designers/block-design.md
Nov 20, 2018
0899e99
Update docs/designers-developers/key-concepts.md
mcsf Nov 20, 2018
521e71b
Get a handful of internal link references fixed
chrisvanpatten Nov 20, 2018
90887df
Merge branch 'big/reorganise-docs' of github.com:WordPress/gutenberg …
chrisvanpatten Nov 20, 2018
228417f
Another batch of internal links
chrisvanpatten Nov 20, 2018
e6492a3
Update docs/tool/manifest.js
mcsf Nov 20, 2018
8838f71
Additional broken internal link fixes
chrisvanpatten Nov 20, 2018
9137200
Merge branch 'big/reorganise-docs' of github.com:WordPress/gutenberg …
chrisvanpatten Nov 20, 2018
f56e67e
A few more links
chrisvanpatten Nov 20, 2018
d7a1026
Revert use of lt/gt symbols in link
chrisvanpatten Nov 20, 2018
0912c33
Fix more broken internal links
chrisvanpatten Nov 20, 2018
a0a6349
Remove docs generator
chrisvanpatten Nov 20, 2018
f3b7273
Broken manifest.json
chrisvanpatten Nov 20, 2018
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Empty file added docs/contributors/readme.md
Empty file.
8 changes: 4 additions & 4 deletions docs/reference.md → docs/contributors/reference.md
@@ -1,9 +1,9 @@
# Reference

- [Glossary](../docs/reference/glossary.md)
- [Coding Guidelines](../docs/reference/coding-guidelines.md)
- [Testing Overview](../docs/reference/testing-overview.md)
- [Frequently Asked Questions](../docs/reference/faq.md)
- [Glossary](../../docs/designers-developers/glossary.md)
- [Coding Guidelines](../../docs/contributors/coding-guidelines.md)
- [Testing Overview](../../docs/contributors/testing-overview.md)
- [Frequently Asked Questions](../../docs/designers-developers/faq.md)

## Logo
<img width="200" src="https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/final-g-wapuu-black.svg?sanitize=true" alt="Gutenberg Logo" />
Expand Down
File renamed without changes.
File renamed without changes.
10 changes: 0 additions & 10 deletions docs/data/README.md

This file was deleted.

3 changes: 3 additions & 0 deletions docs/designers-developers/designers/README.md
@@ -0,0 +1,3 @@
# Designer Documentation

For those designing blocks and other Block Editor integrations, this documentation will provide resources for creating beautiful and intuitive layouts.
Expand Up @@ -27,39 +27,35 @@ A block should have a straightforward, short name so users can easily find it in

Blocks should have an identifying icon, ideally using a single color. Try to avoid using the same icon used by an existing block. The core block icons are based on [Material Design Icons](https://material.io/tools/icons/). Look to that icon set, or to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration.

![A screenshot of the Block Library with concise block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/blocks-do.png)

![A screenshot of the Block Library with concise block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/blocks-do.png)
**Do:**
Use concise block names.

![A screenshot of the Block Library with long, multi-line block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/blocks-dont.png)

![A screenshot of the Block Library with long, multi-line block names](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/blocks-dont.png)
**Don't:**
Avoid long, multi-line block names.

### Block Description

Every block should include a description in the “Block” tab of the Settings sidebar. This description should explain your block's function clearly. Keep it to a single sentence.

![A screenshot of a short block description](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-descriptions-do.png)

![A screenshot of a short block description](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-descriptions-do.png)
**Do:**
Use a short, simple, block description.

![A screenshot of a long block description that includes branding](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-descriptions-dont.png)

![A screenshot of a long block description that includes branding](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-descriptions-dont.png)
**Don't:**
Avoid long descriptions and branding.

### Placeholders

If your block requires a user to configure some options before you can display it, you should provide an instructive placeholder state.

![A screenshot of the Gallery block's placeholder](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/placeholder-do.png)
![A screenshot of the Gallery block's placeholder](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/placeholder-do.png)
**Do:**
Provide an instructive placeholder state.

![An example Gallery block placeholder but with intense, distracting colors and no instructions](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/placeholder-dont.png)
![An example Gallery block placeholder but with intense, distracting colors and no instructions](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/placeholder-dont.png)
**Don't:**
Avoid branding and relying on the title alone to convey instructions.

Expand All @@ -69,19 +65,19 @@ When unselected, your block should preview its content as closely to the front-e

When selected, your block may surface additional options like input fields or buttons to configure the block directly, especially when they are necessary for basic operation.

![A Google Maps block with inline, always-accessible controls required for the block to function](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-controls-do.png)
![A Google Maps block with inline, always-accessible controls required for the block to function](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-controls-do.png)
**Do:**
For controls that are essential the the operation of the block, provide them directly in inside the block edit view.

![A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-controls-dont.png)
![A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/block-controls-dont.png)
**Don't:**
Do not put controls that are essential to the block in the sidebar, or the block will appear non-functional to mobile users, or desktop users who have dismissed the sidebar.

### 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.

![A screenshot of the paragraph block's advanced settings in the sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/advanced-settings-do.png)
![A screenshot of the paragraph block's advanced settings in the sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/assets/advanced-settings-do.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just an observation that these are absolute links.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not happy with the way we're handling static assets right now but for now I would just leave it alone. Long term it would be nice to not even commit static assets to this repo.

**Do:**
Because the Drop Cap feature is not necessary for the basic operation of the block, you can put it ub the Block tab as optional configuration.

Expand Down
45 changes: 45 additions & 0 deletions docs/designers-developers/developers/README.md
@@ -0,0 +1,45 @@
# Developer Documentation

Gutenberg is highly flexible, like most of WordPress. You can build custom blocks, modify the editor's appearance, add special plugins, and much more.

## Creating Blocks

Gutenberg is about blocks, and the main extensibility API of Gutenberg is the Block API. It allows you to create your own static blocks, dynamic blocks rendered on the server and also blocks capable of saving data to Post Meta for more structured content.

If you want to learn more about block creation, the [Blocks Tutorial](../../../docs/designers-developers/developers/tutorials/block-tutorial/intro.md) is the best place to start.

## Extending Blocks

It is also possible to modify the behavior of existing blocks or even remove them completely using filters.

Learn more in the [Block Filters](../../../docs/designers-developers/developers/reference/hooks/block-filters.md) section.

## Extending the Editor UI

Extending the editor UI can be accomplished with the `registerPlugin` API, allowing you to define all your plugin's UI elements in one place.

Refer to the [Plugins](https://github.com/WordPress/gutenberg/blob/master/packages/plugins/README.md) and [Edit Post](https://github.com/WordPress/gutenberg/blob/master/packages/edit-post/README.md) section for more information.

You can also filter certain aspects of the editor; this is documented on the [Editor Filters](../../../docs/designers-developers/developers/reference/hooks/editor-filters.md) page.

## Meta Boxes

**Porting PHP meta boxes to blocks and Gutenberg plugins is highly encouraged!**

Discover how [Meta Box](../../../docs/designers-developers/developers/backwards-compatibility/meta-box.md) support works in Gutenberg.

## Theme Support

By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults.

There are some advanced block features which require opt-in support in the theme. See [theme support](../../../docs/designers-developers/developers/themes/theme-support.md).

## Autocomplete

Autocompleters within blocks may be extended and overridden. Learn more about the [autocomplete](../../../docs/designers-developers/developers/filters/autocomplete-filters.md) filters.

## Block Parsing and Serialization

Posts in the editor move through a couple of different stages between being stored in `post_content` and appearing in the editor. Since the blocks themselves are data structures that live in memory it takes a parsing and serialization step to transform out from and into the stored format in the database.

Customizing the parser is an advanced topic that you can learn more about in the [Extending the Parser](../../../docs/designers-developers/developers/filters/parser-filters.md) section.
@@ -0,0 +1 @@
# Backwards Compatibility
@@ -1,3 +1,5 @@
# Deprecations

Gutenberg's deprecation policy is intended to support backwards-compatibility for releases, when possible. The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.

## 4.5.0
Expand Down
11 changes: 11 additions & 0 deletions docs/designers-developers/developers/block-api/README.md
@@ -0,0 +1,11 @@
# Block API Reference

Blocks are the fundamental element of the Gutenberg editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor.

## Registering a block

All blocks must be registered before they can be used in the editor. You can learn about block registration, and the available options, in the [block registration](block-api/block-registration.md) documentation.

## Block `edit` and `save`

The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](block-api/block-edit-save.md).
Expand Up @@ -9,9 +9,9 @@ A block can have several deprecated versions. A deprecation will be tried if a p

Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form:

- `attributes` (Object): The [attributes definition](../docs/block-api/attributes.md) of the deprecated form of the block.
- `support` (Object): The [supports definition](../docs/block-api.md) of the deprecated form of the block.
- `save` (Function): The [save implementation](../docs/block-api/block-edit-save.md) of the deprecated form of the block.
- `attributes` (Object): The [attributes definition](../../../../docs/designers-developers/developers/block-api/block-attributes.md) of the deprecated form of the block.
- `support` (Object): The [supports definition](../../../../docs/designers-developers/developers/block-api/block-registration.md) of the deprecated form of the block.
- `save` (Function): The [save implementation](../../../../docs/designers-developers/developers/block-api/block-edit-save.md) of the deprecated form of the block.
- `migrate` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, is expected to return either the attributes compatible with the deprecated block, or a tuple array of `[ attributes, innerBlocks ]`.
- `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration. This is particularly useful in cases where a block is technically valid even once deprecated, and requires updates to its attributes or inner blocks.

Expand Down
Expand Up @@ -103,7 +103,7 @@ For most blocks, the return value of `save` should be an [instance of WordPress

_Note:_ While it is possible to return a string value from `save`, it _will be escaped_. If the string includes HTML markup, the markup will be shown on the front of the site verbatim, not as the equivalent HTML node content. If you must return raw HTML from `save`, use `wp.element.RawHTML`. As the name implies, this is prone to [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) and therefore is discouraged in favor of a WordPress Element hierarchy whenever possible.

For [dynamic blocks](../../docs/blocks/creating-dynamic-blocks.md), the return value of `save` could either represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. Alternatively, return a `null` (empty) value to save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site.
For [dynamic blocks](../../../../docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md), the return value of `save` could either represent a cached copy of the block's content to be shown only in case the plugin implementing the block is ever disabled. Alternatively, return a `null` (empty) value to save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site.

### attributes

Expand Down Expand Up @@ -153,10 +153,10 @@ The two most common sources of block invalidations are:

Before starting to debug, be sure to familiarize yourself with the validation step described above documenting the process for detecting whether a block is invalid. A block is invalid if its regenerated markup does not match what is saved in post content, so often this can be caused by the attributes of a block being parsed incorrectly from the saved content.

If you're using [attribute sources](../../docs/block-api/attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`).
If you're using [attribute sources](../../../../docs/designers-developers/developers/block-api/block-attributes.md), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`).

When a block is detected as invalid, a warning will be logged into your browser's developer tools console. The warning will include specific details about the exact point at which a difference in markup occurred. Be sure to look closely at any differences in the expected and actual markups to see where problems are occurring.

**I've changed my block's `save` behavior and old content now includes invalid blocks. How can I fix this?**

Refer to the guide on [Deprecated Blocks](../../docs/block-api/deprecated-blocks.md) to learn more about how to accommodate legacy content in intentional markup changes.
Refer to the guide on [Deprecated Blocks](../../../../docs/designers-developers/developers/block-api/block-deprecations.md) to learn more about how to accommodate legacy content in intentional markup changes.
@@ -1,8 +1,6 @@
# Block API
# Block Registration

Blocks are the fundamental element of the Gutenberg editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor. This document covers the main properties of block registration.

## Register Block Type
## `register_block_type`

* **Type:** `Function`

Expand Down Expand Up @@ -466,6 +464,8 @@ parent: [ 'core/columns' ],

#### supports (optional)

*Some [block supports](#supports-optional) — for example, `anchor` or `className` — apply their attributes by adding additional props on the element returned by `save`. This will work automatically for default HTML tag elements (`div`, etc). However, if the return value of your `save` is a custom component element, you will need to ensure that your custom component handles these props in order for the attributes to be persisted.*

* **Type:** `Object`

Optional block extended support features. The following options are supported:
Expand Down Expand Up @@ -548,8 +548,4 @@ By default all blocks can be converted to a reusable block. If supports reusable
// Don't allow the block to be converted into a reusable block.
reusable: false,
```
## Edit and Save

The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](../docs/block-api/block-edit-save.md).

*Some [block supports](#supports-optional) — for example, `anchor` or `className` — apply their attributes by adding additional props on the element returned by `save`. This will work automatically for default HTML tag elements (`div`, etc). However, if the return value of your `save` is a custom component element, you will need to ensure that your custom component handles these props in order for the attributes to be persisted.*
File renamed without changes.
10 changes: 10 additions & 0 deletions docs/designers-developers/developers/data/README.md
@@ -0,0 +1,10 @@
# Data Module Reference

- [**core**: WordPress Core Data](../../docs/designers-developers/developers/data/data-core.md)
- [**core/annotations**: Annotations](../../docs/designers-developers/developers/data/data-core-annotations.md)
- [**core/blocks**: Block Types Data](../../docs/designers-developers/developers/data/data-core-blocks.md)
- [**core/editor**: The Editor’s Data](../../docs/designers-developers/developers/data/data-core-editor.md)
- [**core/edit-post**: The Editor’s UI Data](../../docs/designers-developers/developers/data/data-core-edit-post.md)
- [**core/notices**: Notices Data](../../docs/designers-developers/developers/data/data-core-notices.md)
- [**core/nux**: The NUX (New User Experience) Data](../../docs/designers-developers/developers/data/data-core-nux.md)
- [**core/viewport**: The Viewport Data](../../docs/designers-developers/developers/data/data-core-viewport.md)
File renamed without changes.
7 changes: 7 additions & 0 deletions docs/designers-developers/developers/filters/README.md
@@ -0,0 +1,7 @@
# Filter Reference

[Hooks](https://developer.wordpress.org/plugins/hooks/) are a way for one piece of code to interact/modify another piece of code. They provide one way for plugins and themes interact with Gutenberg, but they’re also used extensively by WordPress Core itself.

There are two types of hooks: [Actions](https://developer.wordpress.org/plugins/hooks/actions/) and [Filters](https://developer.wordpress.org/plugins/hooks/filters/). In addition to PHP actions and filters, Gutenberg also provides a mechanism for registering and executing hooks in JavaScript. This functionality is also available on npm as the [@wordpress/hooks](https://www.npmjs.com/package/@wordpress/hooks) package, for general purpose use.

You can also learn more about both APIs: [PHP](https://codex.wordpress.org/Plugin_API/) and [JavaScript](https://github.com/WordPress/packages/tree/master/packages/hooks).