[DISCUSSION] Vuepress Docs Loader/Generator for Styleguides

[K3TH3R]

Feature request

I don't believe this will end up being a request specifically for VuePress, but I believe this is the most relevant place to begin the discussion so my apologies in advance if I'm in error.

One of the biggest ideas to hit the frontend world over the last several years has been the idea of Design Systems and consequently Styleguides. It's a clear and easy way to communicate pre-existing frontend work to new hires as well as provide them a concrete point of reference as they're onboarding into the development workflow.

Storybook already has Vue integration, but it's not very... Vue-y.

However, VuePress already supports Vue components inside of Markdown files and Vue-Loader has a relatively unknown and rarely used functionality for handling custom blocks. It seems to me like there's a way here to integrate a Styleguide + Docs functionality with Vuepress that is built from an application's components themselves and operates in a very "Vue" way.

What problem does this feature solve?

For application projects, it would allow us to couple our documentation closely to the implementation. I would expect there is still the need for a docs folder for non-component documentation, so this is more of an add-on rather than a requirement.

What does the proposed API look like?

Let's imagine a button component with two color and size styles:

// button.vue
<template>
  <button class="button" :type="type" :size="size">
    <slot></slot>
  </button>
</template>

// omitting script/style for brevity

<docs path="components">
  VueSuperApp has four button variations for you to use when building out our UI.

  <story-template/>
  
  Some more text describing how *super* awesome this button component is and explaining the different styles/sizes. 
  <story title="Primary Button">
    <button type="primary">Primary Button</button>
  </story>
  <story title="Primary Button - Small">
    <button type="primary" size="sm">Small Primary Button</button>
  </story>
  <story title="Secondary Button">
    <button type="secondary">Secondary Button</button>
  </story>
  <story title="Secondary Button - Small">
    <button type="secondary" size="sm">Small Secondary Button</button>
  </story>
</docs>

Like in Storybook, the <story-template/> component would render a string of our component's <template> contents within a code block while the <story> block would insert the Vue component into the Markdown file.

The <docs> tag would simply be a markdown rendering. That "path" attribute would be relative to whatever the chosen docs folder is for the Vuepress instance. In the case of the VuePress default docs folder in the root of the directory, our button component's docs would become /docs/components/button.md.

How should this be implemented in your opinion?

I'm not sure if this is actually something that should be implemented inside of VuePress or whether it belongs in vue-loader or as it's own repo as a plugin for vue-cli. I don't quite understand the interplay between all of the libraries enough to know where this belongs. Wherever it ends up though, it seemed like it would need the most important discussion/consideration from VuePress which is why I decided to submit this here.

In particular, the community would probably want hot-reload for these components in development but they won't exist as actual markdown files inside of the docs folder so there's some juggling there between VuePress/Webpack/Vue-Loader.

Are you willing to work on this yourself?**

I'm willing to help out however I can although my knowledge of Vue ecosystem internals is definitely lacking.

[ulivz]

Thanks for your suggestion, it looks like a preview component to get voice to the refection between the source code and the output?

If yes, there is a WIP lib for it: https://github.com/posva/vuepress-plugin-example-preview

[K3TH3R]

@ulivz I would say that solves about half the request then, yes. The remainder would be providing a mechanism to read the docs tag content from an array of paths, which I imagine would then just be a webpack-loader that a user can configure vue-cli to use? Does that sound right?

[angeliski]

That feature would be great! I some tired in find styleguide for vue but converted to react lib under the hood.
I agree with @K3TH3R , the vuepress-plugin-example-preview is just half problem solved, maybe some other plugin can handler the custom docs block.
But I think is better go step-by-step. I can try help you in that plugin @posva ? Maybe you can draft the expected result and I can try help you in the code. What do you think?

[posva]

that plugin is supposed to display a code sample along the running demo. It's based off what I used for vue-router docs but never got the time to finish it so it can be extensible

[K3TH3R]

@angeliski I've been doing some more research on this idea this morning and have a few things to add to the discussion.

1. The vue-loader docs I linked above already provide an example of creating a custom loader. We can also use the Vue i18n Loader for further reference because they use a custom block for the translations.
2. Using the register components plugin should theoretically allow us to hook into our main app's .vue component library. This would load all of the components in the specified directories globally, but it should automatically connect with the docs webpack-loader with the proper configuration setup in the config.js, something like this:

chainWebpack: config => {
    config.module
      .rule('docs')
      .resourceQuery('/blockType=docs/')
      .use('docs')
      .loader('vuepress-stories-loader'))
      .end()
  }

3. We could use @posva's component as a foundation to build out the story component, which we could implement through Vuepress' enhanceApp.js.

The main problem I am not quite sure how to solve is how to stream the Vue components' docs content into the Vuepress instance. Right now, Vuepress is building/watching based off of the static files in the specified directory (docs by default).

The only thing I can think of is that we scaffold out the components' docs block content into .md files before Vuepress is run? Maybe we can use Webpack's Rule Loader Enforcing to force this Webpack loader to be run before Vuepress? Like how ESLint runs before Javascript is passed to Babel... thoughts?

[angeliski]

@posva I will see what I can do with that plugin

@K3TH3R Really, It's a big problem... Maybe we can put a hook registration in the register components plugin to make something like a "copy/paste" just to webpack find...

@ulivz You see a simple way to do that in the vuepress, using the plugin API?

[elevatebart]

I would say for now checkout f3ltron/vuepress-component-docgen.
I am maintaining vue-styleguidist, which has a syntax similar to what you describe but still need few fixes and mostly has the bad taste of being written in React.

I will be improving docgen soon with multiple new features among which, a live playground for your stories/examples.

[flozero]

Hello just for push it :).

The repo is now vuepress-plugin-docgen

We are now in v1.2 Still in development but it is improving every day 👍

We are working a lot together with @elevatebart and we have created playground version v1 of vuepress-plugin-live. You can combinate with vuepress-plugin-docgen or just choose one of them.
@K3TH3R

I hope you will like and give us a lot feedbacks

[braddialpad]

Hello just for push it :).

The repo is now vuepress-plugin-docgen

We are now in v1.2 Still in development but it is improving every day 👍

We are working a lot together with @elevatebart and we have created playground version v1 of vuepress-plugin-live. You can combinate with vuepress-plugin-docgen or just choose one of them. @K3TH3R

I hope you will like and give us a lot feedbacks

Is this, or anything like this still being worked on? I see the repo has been archived.

[flozero]

Hello @braddialpad the repo is not anymore maintain. The npm package should still be available but no more updates will be achieve. Probably better to check from vitepress now

[elevatebart]

@jsbaguette @braddialpad

I have a working version of vue-live with JSX and everything ready to ship.
I am just blocked by CI right now as travis counts my credits a bit too closely.

Once this shipped I am rebuilding styleguidist on top of vite, no vitepress, no nuxt 3, just the barebones so that anyone can jump on it.

You can still use vue-docgen-cli in the meantime.
It generates (incrementally) the markdown files a nuxt pages or a vitepress would consume.

It works well but needs a bit more setup than a turnkey solution like vue-styleguidist 5.

[braddialpad]

Nice thanks, I think a combination of vue-live and vue-docgen could give me what I'm looking for.