WP Components: Doc Site with Live Examples

[ItsJonQ]

Hi there! 👋

I've been having lots of chats with @jffng, @griffbrad and @mtias regarding WP Component docs. It seems like one of the bigger missing pieces is a site with live examples.

The Gutenberg Handbook exists, which is a great start! But the lack of live component examples makes it tricky to understand how the UI bits look and feel.

My idea with the dedicated Components doc site with live examples is to create/deploy something useful that folks can use ASAP. My secondary hope is for it to be a doc site that would be easier to maintain and work on.

As an experiment, I threw together a little something at:
https://github.com/ItsJonQ/gutenberg/tree/try/components-doc-site

Specifically, this directory:
https://github.com/ItsJonQ/gutenberg/tree/try/components-doc-site/component-docs

It's an out-of-the-box Create React App project, with a couple of enhancements. Like the Gutenberg handbook, it gets it's content from the README.md files from @wordpress/components.

(More details below)

The generated doc site can be seen at:
https://q-wordpress-component-doc-site-test.netlify.com/

Note: This is all very proof-of-concept! By no means, am I suggesting that any of the decisions (technological, architecture, etc...) are the way to go. The libraries I used to build this were chosen because I wanted to move fast, and they were the ones I was most comfortable with.

Everything is open for discussion. Would love to hear thoughts + feedback!

Auto deploy + Staging previews

My main goal for this was to create a (proof-of-concept) site that could be developed, designed, and updated with minimal effort. From my experience, the service Netlify fits the bill, as it auto deploys on Github updates. Not only that, it auto-generates dedicated staging builds for individual PRs:

This has to be my favourite feature.

This workflow makes it easier for folks, especially non-dev folks, to update README.md content or enhance dev docs UI.

Calypso Live has a very similiar workflow, which is awesome.

Live Previews

At the moment, the only component with live interactive (React) code previews would be the Button component:

https://q-wordpress-component-doc-site-test.netlify.com/button/

(Scroll down a bit)

This works by adding custom <!-- wp:handbook/example --> tags that surround code tags in the README.md docs. When the site renders, it passes the markdown through the Gutenberg's block system, which renders the custom registered live editor/preview blocks, like so:

Nice local dev workflow for docs

For this site, all you need to do is npm install and npm start!

This comes with all the niceties JS folks expect with a Create React App project, like live reload.

Also... to get a Create React App project to understand and work with .md files, I added some Node scripts that read and transform .md -> .json data, which are served via a very simple express server. This allows the React app to make fetch calls to retrieve the data for rendering.

All of this work is bundled with the npm start script. The user doesn't have to do anything extra.

Why Create React App? What about Gatsby?

I've experimented with both! I had initially tried this with Gatsby, but decided against it. The main reason is because I feel like we'd want to integrate this flow into a WordPress powered site (eventually). I don't think a pure static site generator like Gatsby can allow for this. But an App generator, like Create React App, can, since it generates a .js file that can be bootstrapped from a WordPress site.

Thoughts + Feedback please!

Like I mentioned above (apologies for the wall of text), this is an idea and a conversation starter. I would love to improve the WordPress component docs with really slick live examples, not unlike what you might see in libraries like Shopify's Polaris, Material UI, or Segment's Evergreen.

If it makes it easier, I can create a PR from my fork to gutenberg:master.

Thank you so much!

Have a great day

[davewhitley]

Related: #16367 Component library site

[youknowriad]

Hi There! and thanks for opening the issue. This is a goal that was always on our mind for a long time and glad to see that there's some renewed energy to push it forward.

Some Context

That was one of the goals that lead to the creation of the Gutenberg playground Hosted on the github pages of the repository https://wordpress.github.io/gutenberg/

At the moment the playground is just a very simple React App. It's powered by parcel instead of CRA but that's a very small detail. It includes something important that I think we want to keep in that website, a playground to use the block editor without backend (generic).

Our intent has always been to add the components playground (like your site) there, I've started a now probably outdated PR here #14657 to add the README of the components.

This is to say. Yes to this proposal but we should also make sure to be able to load the block editor playground in it somehow. I don't think we care too much if it's a CRA application or a parcel setup, the simplest, the better.

I think one other requirement that would be good to take into consideration is to have it built-in in the repo like now npm run playground:start / npm run playground:build and to load components directly from their source folder to be able to edit them/tweak them live.

Questions about the proposal

Netlify and auto-deploys

Right now, the playground is deployed automatically by travis upon merge to the Github pages. It's nice that the URL/site is tied to the repo but at the same time, with Github pages, we can't deploy a version per branch.

So we need to figure out: Can we mix both: Netlify for PRs and Github Pages for master? Another possibility is to move entirely to Netlify. But there's some questions about their pricing, do they have open source organisation plans...?

I don't see this auto-deploys as the most important thing for this issue but it's definitely a nice to have. We can work on it separately though.

Live previews

I see in your example that there's no import Button from "@wordpress/components". How does it work? All the components are available globally? What If I want to load code from other WordPress modules? I'd personally prefer if the code example is more explicit (includes the import) and avoid magic.

Anyway, that's great and I'm happy to help make this happen.

Do you think you have enough material to start a PR to include in the playground or replace the playground but keep the block editor playground included? How can we move forward?

[ItsJonQ]

@youknowriad

This is to say. Yes to this proposal but we should also make sure to be able to load the block editor playground in it somehow.

Amazing! I'll be sure to include a Playground with my PR for this.

I think one other requirement that would be good to take into consideration is to have it built-in in the repo like now

Will make sure to add this as well. I want to try to make the overall experience as simple, smooth, and slick as possible.

...the simplest, the better.

Amen!

Can we mix both: Netlify for PRs and Github Pages for master?

I believe we can :)

But there's some questions about their pricing, do they have open source organisation plans...?

I'm not sure about that. I know we can use the free setup if the integration is under a single person's Netlify account. I don't know about a free team (Pro plan) plan.

I see in your example that there's no import Button from "@wordpress/components". How does it work? All the components are available globally?

That was my quick work-around for the react-live component used to render the preview/editor. That component has a scope prop, which allows you to pass in dependencies - essentially acting like an import.

Rendering the import statements in the code within react-live would cause issues, since it tries to evaluate it (which doesn't work).

I'd personally prefer if the code example is more explicit (includes the import) and avoid magic.

So would I :). It's definitely possible. @diegohaz was able to achieve this in Reakit with a CodeMirror-based solution. Definitely something we can explore + improve upon!

Do you think you have enough material to start a PR

Most definitely!

How can we move forward?

I'll tidy up my POC and add the Playground. Will look into a solution to include the import statements in the example (without breaking things), haha.

I'll make sure everything is Netlify ready. I'll keep the Playground (the one that deploys to https://wordpress.github.io/gutenberg/) the way it is for now. I don't want to break the features provided by that URL.

Once all this is done, I'll create a PR for review.

We can proceed without Netlify integration (yet) for this repo, as I'm not sure how we'd set that up yet.

Perhaps one of the maintainers can set it up through their Netlify account?

Lemme know if this all sounds good!

Thank you so much!

[youknowriad]

That sounds great for me. I'll ping @pento as he knows more about third-party services integration how this would potentially work.

[pento]

I love this idea, thanks @ItsJonQ!

The Gutenberg Handbook is the correct location for this type of enhancement, hosting official documentation on a 3rd party service isn't an option. That is, integrating this into a WordPress-powered site needs to be a primary goal.

Of course, this doesn't help for PRs. I'm wondering if it might be best to integrate it into WordPress (either within the block editor interface, or as a new wp-admin page), so viewing PR changes is the same process as any other PR: build a local copy, navigate to the appropriate page.

This method would also fit into a Gutenberg PR preview environment: @tellthemachines has recently been experimenting with Tugboat as an option for this.

[youknowriad]

The Gutenberg Handbook is the correct location for this type of enhancement, hosting official documentation on a 3rd party service isn't an option. That is, integrating this into a WordPress-powered site needs to be a primary goal.

I agree with this, that said, having these components in the docs has always been a goal and we were always blocked by the "non-flexibility" of the WordPress Docs site which led to the creation of third party components playgrounds and the difficulty for us to iterate on the components on an isolated container in the repository. I think we need something built-in in the repository in order to work on these components.

So I see this as an opportunity to do half of the process. Build the built-in components playground that can serve for components development/reviews and iteration. Once ready we can start thinking about how best to integrate it with the WordPress handbook (build tools to sync...)

[davewhitley]

If we ever want to see the success of WordPress Components and its adoption, we must have a plan for providing a full-featured, easily accessible documentation site. The Handbook sites are a bottleneck for that to happen.

[karmatosed]

I really love this idea and can absolutely see how important it is. The idea at a contribution day I could just show something, or communicate visually, is incredible.

I have to say I am not sure that the handbook is right spot for this. I say that as someone that has tried to wrestle with the structure and design of that. I feel we may have reached the limits of the handbook structure, it was never intended to be a style guide, or show a design system. A prime example of that is the navigate as for something not fit for this purpose.

Ideally the flow to me should be seamless, PRs should be able to be synced and things demo'ed easily. I would also note something like this should have a search just for it, that can exclude all other noise. Easily finding components to me is key.

Couldn't we link from the handbook but have this as a valuable source?

[chrisvanpatten]

I would strongly encourage everyone here to reach out to the Docs team. Recently, there has been initial progress made toward a consistent local environment for building and managing the handbooks. I have no doubt the docs team would appreciate the help in improving the environment and improving the handbook design and user experience to include more types of content.

[chrisvanpatten]

I'd also remind everyone that many of the limitations in the current handbook are a direct result of the handbook effort being volunteer driven, and additional resources and help would be more than welcome.

[pento]

So I see this as an opportunity to do half of the process.

This has been the path taken historically. Unfortunately, the second half of the process rarely eventuates when it should. Hence the problem we have now: The Block Editor Handbook exists as it is today because the pre-WP 5.0 Gutenberg Handbook needed to land on the devdocs site at the last minute, and it was never revisited.

If we ever want to see the success of WordPress Components and its adoption, we must have a plan for providing a full-featured, easily accessible documentation site. The Handbook sites are a bottleneck for that to happen.

The Handbook sites are an entirely self-inflicted bottleneck. The Block Editor Handbook is a Handbook because it was hacked into place, and never turned into proper documentation. For comparison, the Core Code Reference has a significantly better structure for this kind of documentation.

As @chrisvanpatten mentioned, the Docs team is entirely volunteer driven, there is no-one full time on it. If we want to stop repeating the cycle of documentation being hacked into documentation, I would suggest putting some engineer time into the existing system now, rather than waiting until the last minute, when it will be panic-hacked together.

Ideally the flow to me should be seamless, PRs should be able to be synced and things demo'ed easily. I would also note something like this should have a search just for it, that can exclude all other noise. Easily finding components to me is key.

Putting this in devdocs, and having it easy to use and iterate on are not mutually exclusive. As I mentioned earlier, if this is built to run inside WordPress (really, it just needs to be a blob of JS/HTML that can be rendered in any container), it would work for previewing in PRs, viewing locally, and being synced to devdocs.

Couldn't we link from the handbook but have this as a valuable source?

If all other options are exhausted, and found to be completely non-viable, sure.

[youknowriad]

It's not clear to me what solution you're proposing @pento I think one important requirement that is missing here is that I want to develop and see the changes I'm doing in an agnostic context without even comitting my changes anywhere.

[pento]

The experiment that @ItsJonQ created generates a HTML blob from the Markdown files. That HTML blob can be displayed in pretty much any context, the demo generated docs site is one such context.

Other contexts where that HTML could exist:

• Generated on the fly by your local Gutenberg dev environment as soon as you save a change, visible in a screen in WP Admin (ie, /wp-admin/admin.php?page=gutenberg-docs).
• Generated when a PR is merged to master, and pushed to the WordPress.org devdocs.
• Living inside a Components Playground, allowing people to easily jump from docs, to seeing a component working, to even placing it into a block they're building.

[ItsJonQ]

@chrisvanpatten , @pento , @youknowriad , @drw158 , @karmatosed

Thanks for all the feedback all! It sounds like some folks feel like it would add value!
I'm planning on proceeding with this. However, I'm not sure where.

One idea I had..

If there's some hesitation with it being integrated into this library, or the WP handbook (which I totally understand), I could perhaps build it outside, maybe under my own @itsjonq Github setup... kinda serving as the "Unofficial WordPress Component docs"?

Alternatively, I could proceed with the PR route.

I'm still experimenting and planning out how parts of the site can be constructed (both UI and data -> parse -> render), so things are still in flux.

Let me know what you folks think :)

[youknowriad]

I think the PR route is still valuable. We should also consider reaching out to the docs team in the #docs channel to get some guidance on the other contexts these docs need to be synced to and how best to achieve it.

[griffbrad]

So, the Gutenberg Handbook is already handling content import for us. Every 15 minutes, they’re iterating over the JSON manifest (https://github.com/WordPress/gutenberg/blob/master/docs/manifest.json) and importing the Markdown from github. That importer parses the Markdown server-side and saves the generated HTML in post_content. The Markdown is then saved alongside that post in a meta field called markdown_source.
We should be able to enqueue a JS bundle that feeds the React components the markdown_source string from the WP REST API and renders the page on top of the server-side rendered HTML. This would take the form of an additional WP plugin that could run on the Handbook on .org.

• For the purposes of a proof of concept, I'll include the necessary React components directly in that plugin. Ultimately, in order to share those components between the Handbook, various playgrounds and other documentation sites, they probably make the most sense in an NPM module in the Gutenberg repo. We can keep the discussion about merging those components somewhat separate from the concerns about how we render live component examples on the Handbook.
• We need to test the changes against the .org environment. I've got enough of this running that I can develop the changes, but I don't know what processes are in place for actually testing and deploying changes to WP.org.
• We need to work out the details of the progressive enhancement approach (i.e. do we wrap the server content in a <noscript>, show some kind of loading indicator, etc).

[griffbrad]

Proof of concept for Gutenberg Handbook integration available here:

http://dot-org.bradgriffith.me/handbook/designers-developers/developers/components/button/

Note the live component example under the "Link Button" heading.

To achieve this, I modified the gutenberg theme in the .org repo (https://meta.svn.wordpress.org/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/gutenberg) to do the following:

• Store the full Markdown source in post meta rather than just the URL to the raw content on Github.
• Output that Markdown source following the existing server-side rendered HTML.
• Add wp-scripts.
• Pull a few components from @ItsJonQ directly. Ultimately, these would come from an NPM module, obviously.
• Use those to render the slightly modified Button README you can see here: https://raw.githubusercontent.com/griffbrad/handbook-with-live-examples-proof-of-concept/master/docs/button.md

In that README, note the Gutenbergian inline HTML comments for the component example.

In short, if we can get the necessary React components for doing the progressive enhancement over standard Markdown either merged directly into the Gutenberg repo or otherwise published to NPM, Handbook integration should be a relatively straightforward process at that point.

For those interested, I posted the current proof of concept diff against the gutenberg wordpress.org theme in this gist:

https://gist.github.com/griffbrad/cb2df3eeeee90bc29a37dd7a38fb51c7

[jasmussen]

I really, really dig this. Thanks for starting it.

One of the challenges of the block editor is JavaScript. Even if you're already skilled in JavaScript, there's the React layer on top of that.

While documentation and best practices is a key ingredient in making that easier for people, code examples is another. Actual live examples ups the ante by many many points.

But the most important part, probably, is that this might get people to start using these components as opposed to assuming they have to write their own. Instead of most literally starting from scratch, we can give developers a grabbag of handy LEGO they can piece together.

This in turn carries another benefit that is perhaps even more profound: by getting developers to adopt these components because they are easy, convenient, good looking and useful, means we spread accessibility to each project that includes them. Because of course all these components need to be top-tier accessible.

The feedback loop could be amazing. 👏

[gziolo]

Now that we landed Storybook in #17475, can this be closed? We still need to work towards adding more examples to the Storybook which can be accessed at https://wordpress.github.io/gutenberg/design-system/components/. I don't have strong opinions, we can keep it open but we should clarify what are action items required to consider this issue as done. We can also convert it to the tracking/discussion issue.

[mtias]

Let's close as there's a lot of ongoing work on components and we'd need to revisit how to expose this in the main .org websites separately.