Feature consideration: MDX support

[davidmoshal]

would be nice to be able to document components in the book, eg using MDX:

https://mdxjs.com/

Note: not entirely clear to be if this really a feature for vue-book, or for a documentation system like Docute.

Seems to work with Vue:
mdx-js/mdx#238

[asvae]

When it comes to mdxjs, it should be possible to use demos in markdown, as they're just components.

Regarding dosc in vue-book I already did something similar and I stopped moving in that direction because there was pretty much no positive feedback (myself included).

What I did was binding every component to its relations and providing a way to move between component and its children. I also added description to component demo.
In a bit of time I figured, that IDE handles relation management much better, and description in most cases were either in issue, comments or deductible from design itself.

Let's speak of today. What I can potentially do without too much of a stretch is something like this.

<!-- In demo file -->
<VbDocs :component="YourComponent">

And that would display component props (with type and required) and, let's say, methods.
I can also potentially allow to modify some of these props by providing adequate inputs as well as ability to call methods.

So, while this seems like a good idea on the surface, it doesn't allow for jsdoc or any other kind of description. And, actually, is not much different from checking these in IDE. Also we have a product for generating component docs for jsdoc-ed components (https://github.com/vue-styleguidist/vue-styleguidist).

Overall I'm positive as that's not the first time I was asked about component documentation, but I have to find a right spot to strike.

[davidmoshal]

I think there are a couple interconnected issues here, and it's also not clear where this functionality should live (IDE, vuedevtools, vue-book, Docute, other?).

a) ability to document a component through introspection.

• for that I really like the idea of <Introspect :component="YourComponent"/>
• such an introspection component could also be used from Docute, which allows Vue components in Markdown, so you could use it in either/both vue-book and Docute, or other documentation tool supporting embedded vue components, eg vue-press !
• Docute has a plugin, Vuese which is a command line tool to generate documentation for all vue components, but it's currently not working with Typescript yet, but it could be useful to look at it. It also is for a different workflow, ie: creating a standalone site from all vue components in a source directory.

b) ability to call methods

• for me I find that building this into the 'story' component works great, better than Storybook's knobs.
• Also I've used vuedevtools for this.
• so what would be useful would be a 'palette' of vue 'knobs', like range-bound sliders and number steppers. I think there are frameworks that include this implicitly (Swift I think has such a playground, Intellij is a another that has interactive worksheets).

I have to find a right spot to strike.

My 2 cents would be:

1. build an introspection component that could be used anywhere that Vue components could be used (Docute, vue-book, vue-press, etc). ie: pass the component in, and documentation is created by introspection. This maybe is a separate project.

2. a palette of vue components that can be used to tweak values, eg properties and method arguments.

• these could be embedded manually in story components eg <range-slider min="0", max="100" :model="age">, or
• they could appear when hovering over properties in a introspected component.