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

Documentation for using wp-now with Playground #31

Closed
flexseth opened this issue Apr 3, 2024 · 14 comments
Closed

Documentation for using wp-now with Playground #31

flexseth opened this issue Apr 3, 2024 · 14 comments

Comments

@flexseth
Copy link

flexseth commented Apr 3, 2024

Error code

command not found: wp-now

Exists when

User has not installed wp-now package
https://www.npmjs.com/package/@wp-now/wp-now

If wp-now is not installed on a users machine, many of the commands will not work.

The need

Blueprints or instructions that use the wp-now package should help users navigate how to install and use the package with Playground.

Docs to include

  • Requirements & known limitations
  • wp-now vs. VS Code extension
  • Installing via npx
  • Installing in a single directory vs. globally on your machine
  • Using blueprints with wp-now
  • etc
@ironnysh
Copy link

ironnysh commented Apr 6, 2024

That's already available on NPM/GitHub, so just need to import the README to the docs directory. Or am I missing something? :-)

And slightly off-topic: the image in the README is broken on NPM.

@adamziel
Copy link
Owner

That's already available on NPM/GitHub, so just need to import the README to the docs directory. Or am I missing something? :-)

You're exactly right! :-)

@ironnysh
Copy link

Coolio. Will do it tomorrow :-)

@flexseth
Copy link
Author

flexseth commented Apr 15, 2024

About wp-now

wp-now streamlines the process of setting up a local WordPress environment.
See the NPM package on wp-now.

Requirements

wp-now includes an entire WordPress environment, so you don't need to install WordPress separately. It runs on PHP WASM (Web Assembly) - @ironnysh - please provide link for more context

Node.js is required to run wp-now. You can download it from the Node.js website.
Node is required because the Playground using NPM behind the scenes to install packages.


Boot modes

theme
plugin
wp-content
"blueprint mode" - on the roadmap
(@ironnysh - I've documented wp-content mode here a little bit)

Limitations

When booting in wp-content mode without a theme, you will receive an error that there is no theme present.
Solution: Add an empty themes directory

shell step in wp-now with wp-cli

The shell step currently won't work in wp-now because it doesn't support the shell command.
This is a known limitation that we are working towards making work!

Other known limitations

Please check the Playground Tools GitHub repo for issues related to wp-now

Also see the Known Limitations sections on the wp-now documentation for more info


How to boot up Playground in easy mode

wp-content mode

  • Loads up everything in the wp-content directory
  • Themes, Plugins, and Uploads

A great option if you want to create a new theme for a website, or work with existing website content.
TODO: Show steps to boot in wp-content mode - @ironnysh :)

Or want to work with an existing website to test out a plugin or theme.

How to boot up Playground in wp-content mode

Content needed for wp-content mode
WordPress installation should include the following:

  • All uploaded media to this website
  • The current theme being used
  • All plugins being used

Security warnings

Sometimes when you use NPM packages from an external source, the project you are using needs to update them.

See the Security Warnings page for more information on how to audit and fix security issues in wp-now.

You can report these types of errors if you aren't able to get them fixed.
Here is a sample error report on the playground-tools repo

wp-now: Error starting: getaddrinfo ENOTFOUND

@flexseth
Copy link
Author

@ironnysh Included a bunch of notes. They're kinda organized. :)

@ironnysh
Copy link

@flexseth, thanks for the list :-)

I went over everything here, as well as the published docs (specifically, the Contributing chapter), and I have some suggestions.

If it’s okay with you (and @adamziel, of course :-) ), I’d like to propose this as a working plan, which I’d be happy to take on.

Reorganize the chapters

  1. Add a new chapter: Local Playground, which will include:
    • The wp-now README (note: the wp-now docs are outdated, and need to be revised before importing to Docusaurus. See details below, under "wp-now Docs").
    • The VS Code extension doc.
    • Restructure the current Usage in Node.js chapter into a page, focusing only on the @php-wasm/node package (i.e., import the README to the docs).

Revise the Contributing chapter

All the subsections in the Contributing chapter need a rewrite.

wp-now Docs

Using Blueprints

  1. Let’s add 1-2 simpler Blueprint examples.
  2. Shelf the Defining Custom URLs until wp-now adds support for custom domains or SSL.

Known issues
Some were resolved for sure. Others, maybe:

Misc

@flexseth
Copy link
Author

And slightly off-topic: the image in the README is broken on NPM.

Resolved by

@flexseth
Copy link
Author

@ironnysh - working on some more page updates.

Also linked an issue that I think could help with organizing some of the content for the pages, once it's all there

@flexseth
Copy link
Author

All issues and known limitations of wp-now as of the date of this comment

Should take care of that part of the doc update

@ironnysh
Copy link

organizing some of the content

@flexseth, are we talking about the documentation site? In any case, #126 should probably be a discussion and not an issue.

issues and known limitations

Probably shouldn't be combined in a single public-facing page in the docs.

Since all the content I mentioned is live, I'd like to work on this “textual refactor” ASAP.
@adamziel, would one PR for all of these be okay with you? I can also separate them by chapters/pages.

@adamziel
Copy link
Owner

adamziel commented Apr 19, 2024

@ironnysh That plan looks absolutely amazing! One PR for all of these is amazing, too. Let's make these updates in mdx and Docusaurus at https://github.com/WordPress/wordpress-playground/ as they could already benefit the readers and getting playground-docs-workflow repo ready to use will take a bit more time.

@ironnysh
Copy link

Let's make these updates in mdx and Docusaurus at https://github.com/WordPress/wordpress-playground/

Right :-) Also adding Improve the description of SetSiteOptionsStep #1291 to the list.

@ironnysh
Copy link

ironnysh commented May 1, 2024

Can close this one 🥳

ironnysh added a commit to WordPress/wordpress-playground that referenced this issue May 1, 2024
## What is this PR doing?

1. Reorganizing the **Contributing** chapter of the docs, and updating
the content. See [this
issue](adamziel/playground-docs-workflow#31 (comment))

2. Adding references to [the Developer
docs](https://developer.wordpress.org/) in relevant Blueprints steps.
See #1291.

~### To-Do:~

- [x] Update [wp-now](https://www.npmjs.com/package/@wp-now/wp-now)
README.

**Done** in [Update wp-now documentation
#251](WordPress/playground-tools#251).

## Testing Instructions
1. Build the site (standard `npm run build` to update the steps in
`packages/playground/blueprints/src/lib/steps/`)
2. Run `npm run dev:docs`.
3. Review the changes.

@adamziel
@flexseth
Copy link
Author

flexseth commented May 5, 2024

Can close this one 🥳

done and done :)

@flexseth flexseth closed this as completed May 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants