VueJS Styleguides

example_syntax.vue

The basic idea is to add one more template tag to Vue-Loader's interpreter:

<styleguide lang="markdown">
  This area would allow virtually any kind of markdown text, comments, etc. 
</styleguide>

<template>
  // ...
</template>

<script>
  // ...
</script>

<style>
  // ...
</style>

styleguide.md

Styleguides are becoming an important way for communicating between and onboarding new developers, designers, and other team members to projects. It seems to me that Vue-Loader has most of the core functionality in place to allow us to create styleguides quite easily from existing component trees with only a few minor tweaks. Below are a few of the most obvious ideas to me based on existing styleguide patterns/ideas.

1. Ideally, the structure of the final styleguide should reflect the structure of the application. For example, support for the File-Type First or Feature First/Pods or Domain structures should be supported. This way, if you're working on a small VueJS application you could have a relatively flat component tree styleguide while if you're doing a Pods or Domain-style large application structure the styleguide would allow users to drill down into sub-views/component trees and get a quick idea for the piece of the "tree" that they are working on currently.
2. On top of the additional syntax wrapper shown above (<styleguide>), it also seems like there should be some sort of basic templating system that allows us to construct more complex documentation. For example, KSS could be used within the <style> section while JSDoc (or even Flow documentation support) could be supported within the <script> tags. With a basic templating syntax you could insert SASS/JS Documentation into a specific area of the component's style, ala:

<styleguide>
  Some general text about this component

  Some text about the component's styles
  {{ style_doc }}

  Some text about the component's javascript
  {{ js_doc }}
</styleguide>

This idea could potentially be eliminated by the styleguide generator's templates as well, where instead of forcing the user to manually insert the above documentation, it just generates an extra tab per documentation format found (ie. Component / Styles / Script tabs that toggles between the documentation for each aspect of the component).

3. This would have to be a separate "task" that vue-loader could be configured to run when and if needed as it would be a lot of complex string processing that would slow down general day-to-day development work.

4. In the case of "global" styles like color variables, fonts, type styles, etc. that aren't necessarily inside an existing component and might be @import'd in multiple locations, this could be resolved with users just creating .vue files within those directories that use the KSS syntax (if that's their choice). Potentially, it could be as simple as just:

 /app
  /styles
    /colors.scss
    /type.scss
    /type.vue
    /grid.scss
    /global.scss

  // type.vue
  <styleguide src="./type.scss" src-type="kss" lang="markdown">
    Some text describing this grouping of styles (ie. typography)
  </styleguide>

Then the KSS interpreter is run on the type.scss file and inserted below the text within the <styleguide> tag.

5. Based on the structure discussion in point 1, I think the easiest rule would be that if a folder doesn't hold any *.vue files, it wouldn't exist in the styleguide (ie. "pure" js folders that contain only javascript). However, with the format of point 4, potentially the "pure" js folders could also contain documentation on those elements by simply adding desired vue component files:

 /core
  /actions.js
  /actions.vue
  /store.js
  /mutations.js

  // actions.vue
  <styleguide src="./actions.js" src-type="jsdoc" lang="markdown">
    Some text describing the actions and functionality
  </styleguide>

And then the JSDoc (again, if that's their choice) inserted below the above text

Ad.1: Although auto-generating an app's documentation is neat, it might be more in line with Vue's declarative nature to leave the eventual organization of documentation up to the developer. In this case the root component's <styleguide> tag would seem like a good place to do it. That way, an app can either document itself, like you say, in a way that gives insight into the structure of the application, or developers can create a separate entry-point that documents the available components in a way that might be more suitable to, say, designers working on the project. (what is the colour palate, what does a button look like, etc.)

To avoid some of the pitfalls that make other style-guide systems fall apart for large applications (i.e. rendering everything at once) it might be good to think about how to declare and display structure and/or table of contents.

Styleguidist does it with a config file (example from semantic-react), but again, l think there is an opportunity here to make it more declarative.

Quick brainfart: Like the <template> tag often gets augmented by methods, computed, etc. in the <script> tag, so the <styleguide> could be augmented by "menu options" (or namespace) (or package) as well. This way the components can declare / override where they sit in the hierarchy. That might broaden the scope out of vue-loader territory though. Also, I realize this goes against my point above of centralizing the style guide structure :)

After looking at some of the semantic-react components, I definitely agree that providing a declarative way for team members to organize and structure large documentation sounds like a must. I'm also starting to think that the potential complexity means this should be it's own library, especially considering the need to provide a "starter" styleguide and customization options for companies to have their own internally branded styleguides.

I'm going to do some more thinking on this, but I really like having a declarative syntax for namespaces, TOC, etc. within the <styleguide> tag syntax to keep it familiar. The main thing I think I'm struggling with right now is how deeply nested we would expect those namespaces to be (or whether there should even be a limit) AND what the format would be for generating those hierarchies, which is why I was originally looking towards the auto-generating documentation because it would at the very least reflect the existing structure of the application.