vitepress

vitepress copied to clipboard

As I commented here https://github.com/vuejs/vitepress/issues/638#issuecomment-1156004999

This PR externalizes the markdown-it component plugin.

The @mdit-vue/plugin-component package is extracted from vuepress-next, with full tests and some minor bug fixes (like #638).

Another fix is that allowing @click on native HTML tags, e.g. <button @click="onClick">, which will fail in current vitepress.

I'm planning to extract more markdown plugins as possible, so that we can share them among similar projects, like vite-plugin-vue-markdown or so.

@kiaking @brc-dd

cc @antfu (just noticed that you also forked the plugin yesterday 🤣 )

This is a cool idea and I like the direction. But, if we're going to externalize I think it's better to discuss this before actually using it in VitePress.

For example, it might be better to have it under @vue/ organization. And probably generalize it so that users can actually use it for more general use.

Downside of externalizing the package is that it gets harder to tweak the code in dev. For example, if we have issues in VitePress that require to modify the package, we need to link it locally, publish the package first, etc... It's way easier to maintain if the code is directly under the VitePress project.

So for example if vite-plugin-vue-markdown will not use it for some reason, and if it's not that attractive to be used on other projects, it only leaves the downside of having more complexity, which I would like to avoid.

Let's discuss this with Vue team and see what would be the best fit.

Overall to be clear, I'm not against the approach and I think it's really good idea to have generic Vue Markdown parsing plugin. But If we were to have one, and for VitePress to depend on it, I would like it to be more well thought 👍

What about using MDC syntax introduced in Nuxt content?

• https://content.nuxtjs.org/guide/writing/mdc
• https://github.com/nuxt/content/tree/main/src/runtime/markdown-parser

What about using MDC syntax introduced in Nuxt content?

I would say not for now. Because VitePress is all about simplicity. If you want more powerful features, you should use just Nuxt Content instead.

But, it would be cool if users can opt-in MDC somehow. Like having vitepress-mdc package or something.

For example, it might be better to have it under @vue/ organization. And probably generalize it so that users can actually use it for more general use.

IMO, it might be more "markdown-it scoped" than "vue scoped". As for now I don't think it's properly to put it under @vue orgs 🤔

Downside of externalizing the package is that it gets harder to tweak the code in dev .... it only leaves the downside of having more complexity

We are not going to externalize all markdown plugins. Some plugins are coupled with specific tool, which are rarely useful in other projects. The externalized plugins should be solid and decoupled enough, and could be useful as a standalone markdown-it plugin (even without vitepress).

@kiaking So should we move our discussion to Discord or keep it here?

So should we move our discussion to Discord or keep it here?

Yeah to get the general concensus let's do it briefly on Discord. At the moment this this is more of a poltical issues like where the package should belong, who should be mainteiners, publish access, and so on. Probably bringing this up in online MTG once should conclude the dicission 👍

I would also concern a bit about externalizing it - since it's only a one-file module and not really complex to maintain within this repo. While externalizing it will debugging harder and releasing cycles longer.

If we are talking about reusability and testing, I would suggest we keep them under this repo as monorepo so we could have their separate tests and publish them for other plugins to reuse.

... since it's only a one-file module ...

In fact, it need to be a little more complex. We also need to fork and modify the built-in html_re, html_inline_rule to implement the markdown spec more perfectly. I believe that current vitepress and vite-plugin-vue-markdown could not pass the test cases.

... keep them under this repo as monorepo ...

It could be a choice, but IMO it's not only a vitepress thing.

As for debugging and releasing, in fact, those plugins are just like other 3rd-party plugins we are using, they are solid and decoupled, and we don't need to worry about them. For those deeply customized plugins that need to be debugged, we should still keep them internal.

If the intention is to separate the markdown logic into external packages, I hope you consider adding my suggestions about hoistng multiple

Vitepress is basically a preprocessor for Vite, and transparent MD parse to SFC is a core principle of Vitepress. Hence it should support the full possibilities of Vue/Vite, including extending SFC syntax into other types of markups, like route blocks, graphql, mermaid markup, music markup, etc.

@kaceo It's already supported for sure.

https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc#customblocks