search

adamziel / playground-docs-workflow

Experimenting with maintaining WordPress docs using WordPress Playground
https://adamziel.github.io/playground-docs-workflow/
11 stars 2 forks source link

Documentation for using wp-now with Playground #31

Closed flexseth closed 3 months ago

flexseth commented 4 months ago

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

ironnysh commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

Coolio. Will do it tomorrow :-)

flexseth commented 4 months ago

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

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:

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 commented 4 months ago

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

ironnysh commented 4 months ago

@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 commented 4 months ago

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

Resolved by

flexseth commented 4 months ago

@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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

@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 commented 4 months ago

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 commented 3 months ago

Can close this one 🥳

flexseth commented 3 months ago

Can close this one 🥳

done and done :)