Description
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.