The docs mode controversary

[gossi]

Hello,

I'm a lover of the idea for docs mode/addon-docs and I truly in favor of its apperance.

What I wanted to do: Write one markdown file, use perhaps a loader to transform and then have this file represented as a docs viewMode story.

While working with it - I found some controversary with it, that I think makes it hard to understand and to work with it. Second is, I don't use react, which I think is important for what's to come.

First: Story vs Stories

CSF: 1 file = 1 stories
MDX: 1 file = 1 story

I made it on purpose to name it like that, because this is how stor(y|ies) are shown in the navigation. You write a stories js/ts file, which has a parent node for the title of the default export and children nodes for each exported named story. Whereas an MDX file is one file, that is represented as one node in the navigation.

With CSF it is impossible to re-create a one-node per file documentation. Stories of API instead is capable of doing so (yet, not opting into docs viewMode here). MDX is ok to create a one-node story.
Now, we have docs viewMode and story viewMode - yet it depends on the API you are about to use what you get, not flexible to describe this in either way.

Second: Styling

MDX is rendered by storybook and stories are rendered/hoisted into the framework of your choice, which also applies styling of that (also docs render respective stories in the little iframe here). However, that means the docs page itself has its own CSS and not the CSS of the iframe container. I assume a lot of people use storybook to exactly render their styles. That said, there is a switch of styles between canvas and docs mode (and docs mode is not the foundation of my library I storybooking here). So it's glitching between the two - I find that greatly irritating.

Third: React only

I tried to re-create a docs viewMode representation for ember (my framework here) and hoist the markdown I wrote into the iframe of my framework and display that inside docs. Was kinda impossible, as there is already the buy-in into react, which makes it super hard (if possible at all? - I don't know storybook enough for this).

Going low-level here (using a webpack loader) I created proxy markdown files that my loader parses (and reads the linked markdown files in there) to create a stories file in CSF and then hoist those contents into my framework container. That works but feels so damn wrong to do. I still wish my original idea will be possible at sometime.

--

Summary: Stor(y|ies) are a hard to understand the concept(s). There is a docs viewMode that is coupled to a certain API that has a buy-in to a specific framework and prohibits styling from your framework of choice (now that I wrote it down like that, it sounds really bad - truly not my intention here. Please consider it objective).

As @shilman and me already had a discussion about this on discord, I'm truly aware that the overall architecture will not change but I hope my concerns I explored can be taken care of and I am happy to help with this from ember side of things.

PS. the references of what I did:

• Storybook config: https://github.com/gossi/hokulea/blob/master/explorer/.storybook/main.js
• Webpack loader: https://github.com/gossi/hokulea/blob/master/explorer/.storybook/doc-loader.js
• Sample proxy story: https://raw.githubusercontent.com/gossi/hokulea/master/explorer/stories/getting-started.md
• Output: https://hokulea.netlify.app (Documentation part)

[shilman]

What do you propose?

[gossi]

Thinking about this for five minutes, this is what I've come up with:

First: Make story or stories explicit

The default export can describe if a single story or multiples are used. Whether to show stories or just one story. Some API ideas:

// idea 1: everything on default - it's implicit docs mode by the presence of `template`
export default {
  title: 'hello world',
  template: () => {...},
  story: {...}
}

// idea 2: explicit 
export const mainStory = () => {...}

export default {
  title: 'hello world',
  main: mainStory
}

Second: Explicit viewMode

That goes by story. Per default, a story is shown on canvas (as is right now) but can opt in to various modes:

export const mainStory = () => {...}

mainStory.story {
  viewMode: 'docs'
}

// viewMode can be 'docs' or 'canvas' (default) - but allows more options for the future

Third: Generic Markdown stories

Provide a loader or equivalent technology - for each framework how to load markdown stories. Maybe configurable as I did (links above). So you can describe the markdown dialects or extensions as you are pleased to do so. Then it's up to the framework to provide a little glue code to take the rendered markdown and hoist it into the iframe for each respective framework. I don't think this is too much code here, just the wrapper for each framework.

Note: That alone would enable me as a documentor to write stories more flexible and be explicit in what I want, independent of available solutions (like mdx).

Fourth: Auto generated docs

This is a really tricky one. E.g. docs-addon has these nice blocks, that would need to be recreated for each framework and each need to handle it separately. This is an absolute maintenance overhead, not a way to go.

I only have a little idea here: The generated html from the react part of auto-docs can be used with the same mechanism as I stated above for generic markdown stories to hoist this into the the iframe of the respective framework (must be a configurable opt-in).

The wrapper would then be: Hello, here is some html, please show it in your framework and by that has a clear purpose.

[gossi]

I also learned by accident, that multiple default exports can have the same title. With that in mind one file = one story works again, when the default export has the title for the group they are in and the named export the node for it.

I perhaps constrained myself with it, thinking each story is its own module and by that isolated from the rest. However, they don't have the - let's call it "docs" - icon in the navigation.

That's fine, but overall there is a lot confusion and also I am missing clarity on this. I am pretty sure this clarity will also make it even better for development.

[shilman]

Sorry for the slow reply. Here are my thoughts on the above:

1) Story or stories explicit

Possible duplicate to #8255

2) Explicit viewMode

Fixed in #10292 (I think) and available in https://github.com/storybookjs/storybook/releases/tag/v6.0.0-alpha.44

3) Generic markdown stories

What do you think about MDJS?

This was proposed in #9289, and MDJS came out of that discussion. I'm not interested in adding support to addon-docs, which is already complex enough as is.

4) Auto-generated docs

Addon-docs supports Auto-generated Docs with DocsPage. I'm not interested in allowing users to write Doc Blocks in any non-react framework. Again, too much flexibility for not enough benefit. If you want to write an ember-specific documentation addon, I invite you to do so!

[gossi]

1. Yes, exactly this.
2. Thanks, will try
3. Markdown:

Well markdown != markdown. There is pure markdown that practically nobody uses and then there are various flavors for added syntaxes and then there are extensions for common markdown parser to add even more syntax (I'm a fan here ✌️). One such extension is syntax support for various frameworks.

From what I did for hokulea and my current idea to support ember here, is to provide a gmd extension, which parses markdown with support for ember syntax, but also supports a .gmd.js file in the root of your project that you can use to configure the markdown parser, to exactly support the case of preset flavor + additional syntaxes (would use markdown-it-compiler under the hood).

I also like the approach from mdjs here but I doubt it cannot be used with ember here.

4. Auto-docs:

This is kinda to figure out what works for ember here at the moment. I need to learn more where storybook "ends" and "addon-docs" starts. Perhaps an ember-specific doc addon is a thing but this is what I'm trying to figure out at the moment. Maybe it's what I mentioned under (3).

[shilman]

I need to learn more where storybook "ends" and "addon-docs" starts.

For the most part, addon-docs is just a normal addon like any other. The only difference is that most addons are rendered in the "manager" (Storybook UI) and docs is rendered in the "preview" (user components iframe).

If it helps (or you're just curious), you can read more about the rationale for that in this design document.

The key piece of Storybook code is here:

https://github.com/storybookjs/storybook/blob/next/lib/core/src/client/preview/StoryRenderer.tsx#L280-L302

Everything else is implemented by addon-docs. This "core" code is specific to addon-docs, but other addons can mimic the same API to hook into Storybook (overriding docs.container/docs.page story parameters). I might also be convinced to generalize this API somehow if it's needed and the proposal doesn't complexify things.

Perhaps an ember-specific doc addon is a thing but this is what I'm trying to figure out at the moment.

It sounds like it to me. I'd recommend building what you want, shipping it, and getting feedback from the community. I'm happy to answer questions about addon-docs to help make this easier.

[stale]

Hi everyone! Seems like there hasn't been much going on in this issue lately. If there are still questions, comments, or bugs, please feel free to continue the discussion. Unfortunately, we don't have time to get to every issue. We are always open to contributions so please send us a pull request if you would like to help. Inactive issues will be closed after 30 days. Thanks!

[stale]

Hey there, it's me again! I am going close this issue to help our maintainers focus on the current development roadmap instead. If the issue mentioned is still a concern, please open a new ticket and mention this old one. Cheers and thanks for using Storybook!