Separate pages & URLs for all nav items to allow richer documentation of components

[arielsalminen]

“One component per page” functionality is now supported in Vue Styleguidist and I want to bring it into Vue Design System rather soon as well. It does require a couple of things:

• Updating Vue Styleguidist NPM dependency
• Changing the formatting of the Vue Styleguidist config (mostly template option)
• Edits to the way sidenav highlights items (has to support highlighting of sub items as well)
• Edits to the overall styles of docs (they need to better support separate pages)
• Reordering sections/components.
• Richer example content that better supports separate pages and one component per page. Could include things like:
  • Best practices
  • Content guidelines
  • Usage do’s & don’ts

Looking for input from the community at the moment. Seem my second comment below.

[arielsalminen]

I’m interested to hear people’s opinions about this before working on it further:

Would you prefer that every component is in a separate URL, or the current model where different sections live in separate URLs?

Example of how it works currently can be seen on the website (sections have separate URLs): http://vueds.com/example/

The problem with the current model is that it can get a bit heavy when the system gets bigger and when there are more components. The other side is that it doesn’t allow a lot of documentation per component.

I guess the best solution would be to have this as an option, but Styleguidist doesn’t currently support that so it’d have to be a fork (for the time being at least). That’s something I’d want to avoid as it will make the process of updating things much harder.

[arielsalminen]

Related pull/branch is here: https://github.com/viljamis/vue-design-system/pull/64 , but there’s nothing there yet

[tuuukka]

+1 to supporting components to have separate URLs. When the design system grows bigger, listing the detailed view of all components makes the style guide slow to load and harder to browse. It's also quite useful to be able to link a specific component to team members.

On the flip side easy discovery and glanceability is also quite important in the component listing. Maybe the ideal scenario would be to have control over the level of detail exposed in the listing. For small design systems displaying the full component documentation directly in the listing view might make sense. For larger systems you might however only show the key details and expose the full documentation only when drilling down into the individual component view.

[arielsalminen]

Related discussion/issue in Vue Styleguidist: https://github.com/vue-styleguidist/vue-styleguidist/issues/113

[arielsalminen]

Related issue in React Styleguidist: https://github.com/styleguidist/react-styleguidist/issues/892

[arielsalminen]

@tuuukka It looks like this is most likely going to be behind an option at some point, so you can decide how much separation is needed. There’s a related pull request in React Styleguidist, thanks to @rafaesc: https://github.com/styleguidist/react-styleguidist/pull/941

[rafaesc]

A new PR related with this issue

https://github.com/styleguidist/react-styleguidist/pull/993

[arielsalminen]

@rafaesc Looks very useful!

[arielsalminen]

Part of https://github.com/viljamis/vue-design-system/pull/82

[arielsalminen]

Released in https://github.com/viljamis/vue-design-system/releases/tag/3.0.0