Documentation for Template Block attributes

[grappler]

Issue Overview

In the template documentation there is no information what attributes can be used for the different blocks.

'template' => array(
    array( 'core/image', array(
        'align' => 'left',
    ) ),
),

https://wordpress.org/gutenberg/handbook/templates/

Possible Solution

The attributes can be found in the index.js of the the single blocks which can be found in https://github.com/WordPress/gutenberg/blob/master/blocks/library/

The path for the index.js would https://github.com/WordPress/gutenberg/blob/{block-name}/index.js

The current attributes for the paragraph block currently are

const {
    align,
    content,
    dropCap,
    placeholder,
    backgroundColor,
    textColor,
    width,
} = attributes;

which can be found here: https://github.com/WordPress/gutenberg/blob/v2.6.0/blocks/library/paragraph/index.js#L139-L145

Todos

• Documentation

[chrisvanpatten]

One thing we'd like to see is if there's a way to use a parser to document block attributes, because the workload of keeping these up to date over time would be really challenging.

Any way we can explore that option?

[ajitbohra]

We can automate it the way we are doing for documenting wp.data

[gziolo]

Now that almost all blocks contain block.json definition with attributes, it should be possible to auto-generate documentation with the list of available attributes, e.g.

https://github.com/WordPress/gutenberg/blob/master/packages/block-library/src/audio/block.json#L4-L37

@nosolosw, is that something @wordpress/docgen could cover as well?

[oandregal]

@gziolo There are parts of docgen that may be useful for this. However it is more of a JSDoc grammar processor, so perhaps relying directly on what docgen uses internally (espree) is a better route. With the existing settings and metadata info we already have for blocks it'd be doable to auto-generate documentation for them!

[jaschaio]

@gziolo is there a reason not all blocks contain a block.json yet? For some blocks I can get the possible attributes from the .json, for others I need to check within the index.js or edit.js – couldn't figure out why not all of them have a block.json

[gziolo]

@gziolo is there a reason not all blocks contain a block.json yet? For some blocks I can get the possible attributes from the .json, for others I need to check within the index.js or edit.js – couldn't figure out why not all of them have a block.json

There is no support for loading block.json in PHP so all blocks which use render_callback still define attributes on using register_block_type directly. I think also embeds aren't converted as they are pretty unique in the way the are defined. We will refactor them later this year.

[carolinan]

What can we do to move this forward?

[mtias]

@youknowriad's BlockBook is meant to cover the need of listing block attributes and their effect. There's a proposal to integrate it in the main project in #24152. Ideally we'd also run a public instance of it in the block directory or integrate this information there somehow.

[mkaz]

Closed in #36183