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
Docs: include example of serialized blocks in "language" doc. #3005
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It looks good to me. I have some minor comments about spacing. It could have another review from someone more familiar with the block HTML representation.
docs/language.md
Outdated
@@ -81,6 +81,24 @@ This has dramatic implications for how simple and performant we can make our par | |||
|
|||
_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](../reference/attributes) for details. | |||
|
|||
## The Anatomy of a Serialized Block | |||
|
|||
When blocks are saved to the content after the editing session, the different attributes—depending on the nature of the block—are serialized to these explicit comment delimiters. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see we use —
in a few places, why we avoid spaces around this delimiter?
docs/language.md
Outdated
@@ -81,6 +81,24 @@ This has dramatic implications for how simple and performant we can make our par | |||
|
|||
_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](../reference/attributes) for details. | |||
|
|||
## The Anatomy of a Serialized Block | |||
|
|||
When blocks are saved to the content after the editing session, the different attributes—depending on the nature of the block—are serialized to these explicit comment delimiters. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The word "different" feels out of place here. Should we drop it, or be more specific about those attributes which are serialized in the delimiters?
Adding a small section towards the end showing how blocks might be saved.