Update platform docs intro #61341

stokesman · 2024-05-03T01:35:05Z

What?

Updates the intro.md with some critical things that were missing for a workable build to be produced when following the guide. Among those:

Recommends the React variant as part of npm create vite@latest as without this JSX won’t work by default and react dependencies won’t be installed. The React variant also installs some other nice defaults like eslint with react related plugins.
~~Details that @wordpress/block-library expects IS_GUTENBERG_PLUGIN and how to provide it as without this a runtime error makes for a broken app.~~
Adds a missing style import @wordpress/block-editor/build-style/content.css
Specifies the styles prop of BlockCanvas with imported content styles as without this various things won’t be styled in the canvas.

Less important changes:

Adds ?raw param to style imports to avoid Vite ever trying to process them.
Instructs that registerCoreBlocks() be put in src/main.jsx so it won’t execute during HMR and cause errors (they are non-fatal but they sure clutter up the console).
Specifies to update src/App.jsx instead of index.jsx because it’s what’ll exist when using the React variant and it also means the createRoot/render bits can be removed from the code sample.

Along with that there were a some minor edits to either fix typos or try to make it read a little better.

Why?

To hopefully approach the expectation that following this guide will produce a working example in 10 minutes. From the docs homepage:

You’ll probably go well over 10 minutes if you have to discover how to fix all the gotchas you'll hit by following the guide as is.

How?

I think this is mostly covered in What. I may add some review comments.

Testing Instructions

cd platform-docs
npm install
npm run start

Ensure it all looks good.

github-actions · 2024-05-03T01:35:18Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @aks30498.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: aks30498.

Co-authored-by: stokesman <presstoke@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: michalczaplinski <czapla@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

michalczaplinski · 2024-12-05T17:34:24Z

👋 @stokesman I've closed my PR (#60087) in favor of yours here as your PR is more comprehensive.

Since #61486 has been merged, it's probably unnecessary to include the point about process.env.IS_GUTENBERG_PLUGIN. I haven't tested it to confirm, though.

youknowriad · 2024-12-05T17:57:51Z

platform-docs/docs/intro.md

+if (
+  ! registeredBlockTypes.length ||
+  ! registeredBlockTypes.some((blockType) => blockType.name.startsWith('core/'))
+) registerCoreBlocks();


Is there a simpler way to do this. We're trying to teach people how to build a block editor, we should try to keep things as simple as possible. For instance is there something like ! isHMR && registerCoreBlocks() instead of using the block package.

I didn’t see a simple way to branch for HMR but could have missed something. Reregistering the blocks was not any fatal issue but it polluted the console quite a bit. Now that I’ve tested with the latest @wordpress packages I’m not seeing console messages output for blocks and I don’t know why. Still, there is one that gets output for the core/footnote format. The simplest way I thought of to avoid this is instructing that the registerCoreBlocks call be made in src/main.jsx.

youknowriad · 2024-12-05T18:00:38Z

platform-docs/docs/intro.md

+  ${ blocksCommonStyles }
+  ${ blocksStyles }
+  ${ blocksEditorStyles }
+`;


While we should do this for "content styles", some of these styles shouldn't be injected into the iframe and others should be injected inside and outside the iframe:

components (in both places because of placeholders and buttons)

block-editor/style style shouldn't be loaded in the iframe IMO (if something is not working we should fix it in gutenberg), instead it should be loaded in the app directly (so direct import here)

Yes, I’d meant to revisit this and get it right.

(if something is not working we should fix it in gutenberg)

Agreed. I can’t quite recall what style issues I’d noted. Perhaps the default block appender was not getting styled but since #66630 that doesn’t appear to be an issue.

youknowriad · 2024-12-05T18:01:30Z

platform-docs/docs/intro.md

-      onInput={setBlocks}
-    >
+    <>
+      <style>{ styles }</style>


Let's avoid this and just do importfor the two stylesheets that need to load here. We should clarify what things are "content" styles and what things are "UI styles". I think we should add a paragraph to explain this.

Okay. This style tag is gone. This reason it was this way was because I’d added the ?raw param to the their import path to tell Vite not to process them and due to that Vite won’t automatically inject them. I can’t remember if there was any issue with Vite processing them or if I just thought it was better dev performance. Now instead of doing an import for those files I’ve instructed that they be added to index.html (the vite-ignore attribute will also keep them from being processed).

I know it’s not quite as simple that way but I think it may help express the difference with these UI styles versus the content styles. I also added a note hoping to help explain it, not sure if it suffices.

youknowriad

Thanks for working on this, especially the content styles part.

stokesman · 2024-12-10T23:59:55Z

platform-docs/docs/intro.md

 import blockEditorContentStyles from "@wordpress/block-editor/build-style/content.css?raw";
-
-// Default styles that are needed for the core blocks.
-import blocksCommonStyles from "@wordpress/block-library/build-style/common.css?raw";


I realized this one was extra, it is @import‘d in the block library’s style (the one on the next line).

youknowriad · 2024-12-11T07:19:22Z

platform-docs/docs/intro.md

+      */ }
+      <BlockCanvas
+        height="500px"
+        styles={ [


Do you think there's any performance value in putting a stable array here (maybe define this array outside the component)

youknowriad

So I didn't actually try the code, but this looks good to me.

youknowriad · 2024-12-11T07:20:42Z

I think this closes #67048

…61341) Unlinked contributors: aks30498. Co-authored-by: youknowriad <youknowriad@git.wordpress.org> Co-authored-by: michalczaplinski <czapla@git.wordpress.org> Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>

Update platform docs intro so following it actually works

d19f572

stokesman marked this pull request as draft May 3, 2024 01:41

michalczaplinski mentioned this pull request May 13, 2024

Platform Docs: Update intro.md #60087

Closed

youknowriad reviewed Dec 5, 2024

View reviewed changes

stokesman added 2 commits December 9, 2024 17:40

Remove outdated part about IS_GUTENBERG_PLUGIN env variable

39868a5

Revise instructions

8e07f04

stokesman marked this pull request as ready for review December 10, 2024 23:50

stokesman added Framework Issues related to broader framework topics, especially as it relates to javascript [Type] Developer Documentation Documentation for developers labels Dec 10, 2024

stokesman commented Dec 10, 2024

View reviewed changes

youknowriad reviewed Dec 11, 2024

View reviewed changes

youknowriad approved these changes Dec 11, 2024

View reviewed changes

Make styles array stable

c354415

stokesman merged commit 1a8771b into trunk Dec 11, 2024
61 of 62 checks passed

stokesman deleted the update/platform-docs-intro-for-reality branch December 11, 2024 16:05

stokesman changed the title ~~Update platform docs intro so following it actually works~~ Update platform docs intro Dec 11, 2024

github-actions bot added this to the Gutenberg 20.0 milestone Dec 11, 2024

stokesman mentioned this pull request Dec 11, 2024

Gutenberg Framework: Clarify and simplify how to load content styles #67048

Closed

6 tasks

ronakganatra9 mentioned this pull request Dec 18, 2024

Storybook block editor component css issue ( in BlockCanvas ) #68092

Open

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update platform docs intro #61341

Update platform docs intro #61341

stokesman commented May 3, 2024 •

edited by youknowriad

Loading

github-actions bot commented May 3, 2024 •

edited

Loading

michalczaplinski commented Dec 5, 2024

youknowriad Dec 5, 2024

stokesman Dec 10, 2024

youknowriad Dec 5, 2024

stokesman Dec 10, 2024

youknowriad Dec 5, 2024

stokesman Dec 10, 2024

youknowriad left a comment

stokesman Dec 10, 2024

youknowriad Dec 11, 2024

youknowriad left a comment

youknowriad commented Dec 11, 2024

Update platform docs intro #61341

Update platform docs intro #61341

Conversation

stokesman commented May 3, 2024 • edited by youknowriad Loading

What?

Why?

How?

Testing Instructions

github-actions bot commented May 3, 2024 • edited Loading

Unlinked Accounts

michalczaplinski commented Dec 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

youknowriad commented Dec 11, 2024

stokesman commented May 3, 2024 •

edited by youknowriad

Loading

github-actions bot commented May 3, 2024 •

edited

Loading