Skip to content

Add "block-selectors" docs to TOC and manifest. - #49471

Merged
gziolo merged 2 commits into
trunkfrom
add-block-selector-docs
Apr 13, 2023
Merged

gziolo merged 2 commits into
trunkfrom
add-block-selector-docs

Conversation

@Soean

@Soean Soean commented Mar 30, 2023

Copy link
Copy Markdown
Member

What?

Fixes #49469

Adds block selectors docs to the TOC file and adds the generated manifest.

After merging, it should be available via: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-selectors/

@github-actions

Copy link
Copy Markdown

Flaky tests detected in 1dbd073.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4563528141
📝 Reported issues:

@gziolo

gziolo commented Apr 8, 2023

Copy link
Copy Markdown
Member

Good catch! This is a new feature that won’t be available in WordPress core until 6.3 (late August), what would be the best way to highlight it in https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-selectors.md?

Comment thread docs/toc.json
"docs/reference-guides/block-api/block-registration.md": []
},
{
"docs/reference-guides/block-api/block-selectors.md": []

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Is it sorted by name?

@gziolo gziolo added the [Feature] Block API API that allows to express the block paradigm. label Apr 8, 2023
@aaronrobertshaw

Copy link
Copy Markdown
Contributor

Thanks for fixing this up @gziolo 👍

what would be the best way to highlight it in https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-selectors.md?

In some of the components package readmes where there are experimental components, they use a callout alert at the top of the readme. Perhaps we could do something here in block-selectors.md?

Something like adding the following beneath the title:

<div class="callout callout-alert">
	This API was stabilized in Gutenberg 15.5 and is planned for core release
	in WordPress 6.3. To use this prior to WordPress 6.3, you will need to install
	and activate Gutenberg >= 15.5.
</div>
<br />

@gziolo

gziolo commented Apr 12, 2023

Copy link
Copy Markdown
Member

Thanks for fixing this up @gziolo 👍

It’s actually @Soean 😃

In some of the components package readmes where there are experimental components, they use a callout alert at the top of the readme. Perhaps we could do something here in block-selectors.md?

Something like adding the following beneath the title:

<div class="callout callout-alert">
	This API was stabilized in Gutenberg 15.5 and is planned for core release
	in WordPress 6.3. To use this prior to WordPress 6.3, you will need to install
	and activate Gutenberg >= 15.5.
</div>
<br />

That would work until it’s released in WordPress core 👍

It would be also good in general to always include a paragraph next to the page title explaining when the feature becomes available in WordPress core. I didn’t think about it before.

@aaronrobertshaw

Copy link
Copy Markdown
Contributor

It’s actually @Soean 😃

🤦 So it is. Clearly my caffeine levels had dipped too low ☕

That would work until it’s released in WordPress core 👍

I've taken the liberty to push a commit adding a callout that the selectors API won't be released in core until WordPress 6.3.

I hope that's okay @Soean! Feel free to tweak the wording if desired.

@gziolo gziolo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Excellent, that looks great now 🙌🏻

in WordPress 6.3. To use this prior to WordPress 6.3, you will need to
install and activate Gutenberg >= 15.5.
</div>
<br />

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I don't see a line break added in other places, but we can verify once the handbook updates.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I took the <br /> from the components package examples. IIRC, when testing it locally, without the line break the text moved up with no space between it and the callout. That could have been just previewing the markdown though 🤔

@gziolo
gziolo merged commit 4ea1f02 into trunk Apr 13, 2023
@gziolo
gziolo deleted the add-block-selector-docs branch April 13, 2023 07:48
@github-actions github-actions Bot added this to the Gutenberg 15.7 milestone Apr 13, 2023
@gziolo

gziolo commented Apr 13, 2023

Copy link
Copy Markdown
Member

So nice, I like it!

Screenshot 2023-04-13 at 10 44 37

I don't think the <br /> makes any difference here. It probably gets replaced with an empty <p></p> and nothing changes when I remove it in Browser Console.

@gziolo

gziolo commented Apr 13, 2023

Copy link
Copy Markdown
Member

I opened #49792 with improvements for the block editor handbook. I also remove the <br /> there. I also included the Selectors page in the Block API Reference index page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Block API API that allows to express the block paradigm. [Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Dead link in docs: /block-editor/reference-guides/block-api/block-selectors/

3 participants