feat(website): investigate how to integrate Storybook to the podman desktop website about podman-desktop

[axel7083]

We can go for the second option then, we can always go back to another solution anyway - if you both agree @benoitf @deboer-tim let's give a try to the integration.

[axel7083]

Let's explore some scenarios

📝 Integration through @docusaurus/plugin-content-docs

By full integration, I mean trying to include the storybooks inside the docusaurus style (sidebar etc.).

Looking at the storybook-static (build folder), we can see they produced a index.json file, here is a snippet

{
	"v": 5,
	"entries": {
		"example-button--docs": {
			"id": "example-button--docs",
			"title": "Example/Button",
			"name": "Docs",
			"importPath": "./src/stories/Button.stories.svelte",
			"type": "docs",
			"tags": [
				"dev",
				"test",
				"autodocs"
			],
			"storiesImports": []
		},
    ...
}

When serving the storybook-static folder we can understand how the site is structured

They are using an iframe, with a dedicated iframe.html located in the static folder. My first thought was to integrate this iframe in docusaurus using mdx file, and generate the sidebar using the index.json.

The result are... limited...

Controlling the height of the iframe is very very difficult, and I was not able to do it. See my branch to give it a try feature/storybook-docusaurus-integration

The sidebar are nicely generated, but the iframe is impossible to properly configured...

We could work around by having some js resizing the iframe, but that's not ideal.

🦖 Custom react page using Docusaurus components

The idea of using a custom react page is properly the best, as we can reuse Docusaurus components. Here is what I was able to do:

custom-page.mp4

It look nice, but it is a bit complicated.

Generating the sidebar

I reuse code from the first Integration where I created a custom docusaurus plugin to generate the sidebar. Then what I did was creating a custom page in website/src/pages/storybook/index.ts where I create a similar layout than the documentation using docusaurus components (E.g. DocSidebar``, Layout` etc.)

To get the iframe of storybook, I added simply <iframe...> in my JSX component.

Dark Theme

This allows me to get access to hook like useColorMode telling me which mode (dark | light) is currently being used by docusaurus.

Providing the dark theme to the iframe was a bit fun to do, storybook also uses the iframe, so it uses iframe.postMessage to communicate theme update, I simply use the same channel than they do to communicates the dark mode.

Why is it easier to create a custom page: we do not have to generate fake markdown containing the iframe to display the right content, moreover we are not limited by mdx to add custom code to manage the iframe height.

branch with sources of this test: https://github.com/axel7083/podman-desktop/tree/feature/storybook-docusaurus-integration-v2

🖖storybook as subpath of Docusaurus website

If we want to have Storybook as a standalone website, with its full capabilities, it is very hard to have it works under a subpath.
Let's say we would to have it under https://podman-desktop.io/storybook this is annoying, because it has very poor support for it, which mean requires a lot of sed to replace href. See storybookjs/storybook#1291

[deboer-tim]

1. 'Integration through @docusaurus/plugin-content-docs' seems like a dead end to me - it doesn't feel very embedded to me and not clear we'd ever get it to feel like it's not just an iframe pasted in there.
2. 'Custom react page using Docusaurus components' looks integrated the best and feels like it could even fit in within the Extension docs, e.g. at some point you could have Extensions > Developing, Extensions > API Reference, and Extensions > UI Components in the same place and it wouldn't feel like you're jumping around.
3. 'storybook as subpath of Docusaurus website' also sounds like a dead end, and if it was a non-integrated subpath you could just as easily do storybook.podman-desktop.io instead.

So to me 2 seems like the winner and (at least from the video) that the basic things are already working fine. If that was too much work or delayed, then neither of the other paths sound better than using storybook.podman-desktop.io (or ui-components.podman-desktop.io or something) in the meantime.

[axel7083]

So to me 2 seems like the winner and (at least from the video) that the basic things are already working fine. If that was too much work or delayed, then neither of the other paths sound better than using storybook.podman-desktop.io (or ui-components.podman-desktop.io or something) in the meantime.

I like the solution of having storybook.podman-desktop.io, could we configure it in a manner where it would redirect to a static folder (which is not at the root directory?) ?

[benoitf]

the main problem with two websites is how do you go from one to the other one as from user POV you should think you're on the same website and can navigate easily from one chapter to another

it's like when website is one site and docs another one. We tried to have only one navigation pattern to make it more user friendly to the user.

[benoitf]

yes for now it looks like option 2. aka Custom react page using Docusaurus components is the best compromise and the best overall experience of the user navigating the website.

[axel7083]

Closing as was only investigation next steps will be handled by #7438