Skip to content
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

Add "Get started with create-block" doc to the Getting Started section #55373

Merged
merged 3 commits into from
Oct 17, 2023

Conversation

ndiego
Copy link
Member

@ndiego ndiego commented Oct 15, 2023

Fixes #54960

What?

This PR adds a getting started guide for create-block. This package is one of the best tools for getting started with block development. Having a primer on the subject in the Getting Started section will help new developers get oriented.

@ndiego ndiego added the [Type] Developer Documentation Documentation for developers label Oct 15, 2023
@ndiego ndiego self-assigned this Oct 15, 2023
@gziolo
Copy link
Member

gziolo commented Oct 16, 2023

Between this PR and #55372, I'm wondering how much we could remove from README files in @wordpress/create-block and @wordpress/scripts to point folks to these newly created documents instead. Otherwise, we might end up maintaining similar content in two places, which is usually suboptimal in the long term as they tend to diverge.

It surely can be tackled (if not planned already) as a follow-up, I mostly wanted to flag it as a great way to send folks from these packages to higher-level onboarding docs.

@@ -0,0 +1,91 @@
# Get started with create-block

The [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) package is an officially supported tool for scaffolding a WordPress plugin that registers a block. It generates all the necessary code to start a project and integrates a modern JavaScript build setup (using [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts.md)) with no configuration required.
Copy link
Member

Choose a reason for hiding this comment

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

Aside: there is also an integration with wp-env included in Create Block, but it isn't enabled by default. Folks can enable it with the --wp-env CLI param, or through external templates.


These scripts can then be run using the command `npm run {script name}`. The two scripts you will use most often are `start` and `build` since they handle the build step.

When working on your block, use the `npm run start` command. This will start a development server and automatically rebuild the block whenever any code change is detected.
Copy link
Member

Choose a reason for hiding this comment

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

While it works to use npm run start, it's also possible to call npm start for convenience. I don't remember if the included form is being used to align with other npm commands so just sharing as a sidenote.

@gziolo
Copy link
Member

gziolo commented Oct 16, 2023

Love this effort!

@fabiankaegy
Copy link
Member

@gziolo i would hate to see the actual readme files of the packages get removed. These are what shows on NPM and what should in my opinion always be the source of truth for a package.

@gziolo
Copy link
Member

gziolo commented Oct 16, 2023

@gziolo i would hate to see the actual readme files of the packages get removed. These are what shows on NPM and what should in my opinion always be the source of truth for a package.

I didn't say that:

how much we could remove from README files

My comment was about removing similar content not the file from the package and linking to the Block Editor Handbook instead.

@fabiankaegy
Copy link
Member

@gziolo i would hate to see the actual readme files of the packages get removed. These are what shows on NPM and what should in my opinion always be the source of truth for a package.

I didn't say that:

how much we could remove from README files

My comment was about removing similar content not the file from the package and linking to the Block Editor Handbook instead.

🤦

Sorry for the confusion :)

@ndiego
Copy link
Member Author

ndiego commented Oct 16, 2023

Between this PR and #55372, I'm wondering how much we could remove from README files in @wordpress/create-block and @wordpress/scripts to point folks to these newly created documents instead. Otherwise, we might end up maintaining similar content in two places, which is usually suboptimal in the long term as they tend to diverge.

Yeah, I agree. We can look at those next. I think the readme's for the packages could be slimmed down and really just focus on the technical documentation and link to the "Get started..." guides as needed.

@ndiego ndiego changed the title Add Get started with create-block doc. Add "Get started with create-block" doc to the Getting Started section Oct 17, 2023
@ndiego ndiego merged commit a99f326 into trunk Oct 17, 2023
49 checks passed
@ndiego ndiego deleted the docs/add-get-started-with-create-block-doc branch October 17, 2023 19:18
@github-actions github-actions bot added this to the Gutenberg 16.9 milestone Oct 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add a dedicated doc for getting started with create-block (subpage of Developer Environment)
4 participants