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

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.