Docs - Block Templates

[BinaryMoon]

Hi - I'd like to see some docs on creating, and editing block templates. I've tried searching the handbook but can't find anything relevant. I found a few issues below that cover the things I think should be mentioned.

Register post type. Plus how to edit an existing post type (eg post/ jetpack-testimonial) to add a custom block template.
#3668

Template locking (and the different options)
#3686

Would also be nice to have a list of the available blocks and how to refer to them. By this I mean where does 'core/image' mentioned in the tickets above come from and how can I get the names of the other available blocks?

Is there an easy way to see what properties are available for each block type that can be changed in the block template settings? Can these be documented too?

[youknowriad]

Thanks for opening the ticket, we definitely need documentation for this.

Would also be nice to have a list of the available blocks and how to refer to them. By this I mean where does 'core/image' mentioned in the tickets above come from and how can I get the names of the other available blocks?

you can try this

wp.blocks.getBlockTypes()

Is there an easy way to see what properties are available for each block type that can be changed in the block template settings? Can these be documented too?

and for reach block, you'd see a name and a list of attributes you can use to define your block template settings.

Though, I don't think we should document the block attributes, these can change quickly and can be overriden with plugins. It's too premature but I think if we build documentation for those, it should be generated because too hard to keep in sync.

[BinaryMoon]

Thanks for the feedback Riad.

wp.blocks.getBlockTypes() - helps a lot. I'd suggest mentioning that as well, with a note on how to use it. Took me a little while to realise I could enter this on the console to get the list of properties.

it should be generated because too hard to keep in sync.

Makes absolute sense. The getBlockTypes command will help in the meantime.

I assume this issue will be updated as the doc is created. I'd be happy to proofread & test things from a non developers perspective.

For context I'm a themer who knows enough js and php to get in trouble - but I don't consider myself a programmer.

[youknowriad]

@BinaryMoon maybe you could help creating these docs ;) (see the docs folder, it's just markdown)

[BinaryMoon]

@youknowriad I would certainly consider helping. Do I just create a file or do I have to do something else to get it to show in the navigation? Are there naming conventions/ anything like that?

If you can set up the file I can fill out the bits I know.

[youknowriad]

@BinaryMoon just add a file maybe block-templates.md and you should add an entry to the manifest https://github.com/WordPress/gutenberg/blob/master/docs/manifest.json (it should be easy).

It doesn't have to be perfect, we can discuss in a PR and iterate. At least we'd have something :)

[BinaryMoon]

You need some docs for creating docs :)

[mtias]

I was going to start on this today. I'll loop you both on the PR.