feat(demo): built-in markdown plugin provides support for showcasing demo capabilities.

[hairyf]

Is your feature request related to a problem? Please describe.

vitepress is currently not capable enough for developing component libraries. While it is fast, it lacks something. We may be able to incorporate support for component capabilities similar to dumi to help developers quickly develop Vue component libraries docs.

<demo src="../demo.vue" title="Demo block" desc="use demo" />

Alternatively, use the desc defined in the container to write Markdown syntax.

::: demo src="../demo.vue" title="Demo block"

This is a `description` that can be written using Markdown.

:::

Describe the solution you'd like

To address this, I have created the markdown-it-vitepress-demo plugin. I'm not sure if it can be helpful.

Describe alternatives you've considered

No response

Additional context

• https://github.com/vuejs/vitepress/issues/987
• https://github.com/vuejs/vitepress/issues/1349

Validations

• [X] Follow our Code of Conduct
• [X] Read the docs.
• [X] Read the Contributing Guidelines.
• [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

Hey, is there a deployed site where we can see that plugin in action?

[hairyf]

of course, I can provide a simple demo implementation:

https://markdown-it-vitepress-demo.vercel.app/demos.html

The implementation can be found within the markdown-it-vitepress-demo docs, and you can view the source code here:

• https://github.com/hairyf/markdown-it-vitepress-demo/tree/main/docs
• https://github.com/hairyf/markdown-it-vitepress-demo/blob/main/docs/.vitepress/theme/components/CustomDemoContainer.vue

[dwgray]

This seems like an essential feature for building documentation sites for vue.js libraries. Is there an alternative solution that I'm missing, or are folks just working around this for now? It seems like @hairyf 's plugin is a good start, but it hasn't been touched for a year and doesn't have the markers of an extensively used project. I'd be happy to help with a solution for this if someone can point me in the right direction (or would be even happier if there is an existing alternative that I'm missing).

My definition of 'this': I'm contributing to a vue.js 3x library - bootstrap-vue-next that is a rewrite of a vue.js 2x library bootstrap-vue. We're generally trying to use the newest toolset, so long before I had any involvement in this project, the owners opted for vitepress over vuepress. In the old project, when documenting usage of one of the components, all that was required was a straightforward implementations of the sample code set off in an ```html block (obviously, there is a lot going on under the hood, but there isn't anything else required in the md file - most specifically there isn't any duplication of the sample code or scaffolding).

Example on GitHub

Snapshot:

What we're doing in vitepress is quite a bit uglier - not only is the sample manually duplicated, but there is a significant amount of scaffolding code that's repeated for each sample + the <script> part of the running sample has to be included in the script for the main file, which means variables have to be unique for each sample within a file.

Example on Github

Snapshot:

and the following is included in the main script block

import { BFormCheckbox} from 'bootstrap-vue-next'
const status = ref(false);

Thanks in advance for any direction you can give me on this. Again, I'd be happy to help with a solution for this if someone can point me in the right direction.

[hairyf]

@dwgray If you don't mind, you can use markdown-it-vitepress-demo to create a demo, which is still valid in the latest version of vite

I used it in the docs for vue3-pixi project and it runs well

[dwgray]

Thanks, @hairyf. I'll take a closer look now that I know that you're actively using it in your vue3-pixi.