Docs - Include a couple of reference blocks

[danielbachhuber]

As a Gutenberg extender, it would be helpful to have at least a couple full-featured reference blocks to review.

When producing these reference blocks, it would be most effective to consider them from the perspective of the reader (e.g. "here's how to implement a shortcode as a block" and "here's how to implement a metabox as a block").

From wp-cli/scaffold-command#88 (comment)

[youknowriad]

We already have some ready to use blocks here https://github.com/WordPress/gutenberg-examples
And they are used in the create blocks tutorial.

We could use some more advanced examples though (like the meta block)

[NewJenk]

Yes, please include some advanced blocks, e.g. a menu block where the user selects a WP menu and the menu is then displayed.

[wpalchemist]

The blocks in the gutenberg-examples repo don't work, and neither does the code in the "create blocks" tutorial. The code examples are all out of date and need to be updated to keep up with Gutenberg development.

[youknowriad]

@wpalchemist True, We'd love some help from the community when possible of course. There's too much work to do and helping with the docs seems like a good way to start contributing.

[wpalchemist]

@youknowriad I would love to contribute here, but I don't know how to make any of those code examples work. There's a chicken-and-egg problem: I would be happy to write some documentation, but without any documentation, I don't have enough information to write anything. I've tried reading through the codebase to see if I can figure out what needs to go into the documentation, but it's really hard to just dive in there.

[youknowriad]

@wpalchemist I understand, we should try to keep the docs up to date while we update the API. I think we've successfully done this for most of the docs except the block examples which are harder to keep in sync.

I appreciate the intent though and if you ever feel adventurous and have questions about some "errors" in the examples or any other API, feel free to reach out (slack, github or whatever)

[mboynes]

@wpalchemist @youknowriad I fixed the examples in https://github.com/WordPress/gutenberg-examples. They still deviate from the create blocks tutorial, but at least they're working now.

[wpalchemist]

Thank you, @mboynes! That's very helpful! I'm hoping to have time in the next few weeks to work on the documents, but I have some other projects with deadlines so I'm not sure how much time I'll have.

[danielbachhuber]

Both the Gutenberg Examples and main wordpress/gutenberg/docs directories have a good set of examples to follow.