Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

[DISCUSSION] Vuepress Docs Loader/Generator for Styleguides #1084

Copy link
Copy link
Open
@K3TH3R

Description

@K3TH3R
Issue body actions

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Morty Proxy This is a proxified and sanitized view of the page, visit original site.