Replies: 29 comments 35 replies
-
/cc @bencodezen @meteorlxy @ulivz @kiaking @posva @brc-dd @billyyyyy3320 @georges-gomes |
Beta Was this translation helpful? Give feedback.
-
I have a feature request on integrating VitePress into an existing (Vue) Vite project with access to all its (generated) resources. I'm new to the while Vue/Vite ecosystem and maybe it's just a configuration issue. I currently have two projects (a language learning tool and a style guide) where VitePress serves as the internal documentation hob for all participants and is installed side-by-side as a dev dependency within each main project. However, having to run I'd love VitePress to run on the same port as the main project and use and access the same assets, resources, The main project/application is unaware of VitePress and utilises it's own "index.html" app environment. In both cases VitePress runs within the main project as a companion and is not supposed to ever become it's own SSG'd website, but a sophisticated documentation tool to possibly showcase and host some of the main project's code, components and resources were it lives in. This is particular true for the Style Guide project. It appears to be impossible to "reach up" from the docs contents and theme files inside the We're mainly on Windows and unfortunately junctions (hardlinks) do not always work well with Node's path resolver. |
Beta Was this translation helpful? Give feedback.
-
I'm all aboard the VuePress train (vs Nuxt et al) for a bunch of reasons that probably don't make sense to list here, but I'm still on VuePress 1.0, so moving to Vue 3 will be a change for me no matter what. I'm using Vite with Nuxt on other projects, but don't have enough hands-on in V*Press to know how it would affect configuration / plugins etc., so happy to run with the consensus. Regarding the direction of V*Press, my main issues with 1.0 are some folder / theme decisions which I feel are too inflexible.
The way I see VuePress is a lovely engine for converting markdown files to data, and letting me do whatever the hell I want to do with it, vs something like Nuxt which is much more prescriptive in where it wants you to put things and how the lifecycle works. My personal site is a completely custom theme and it's been (mainly!) a joy to develop! I will happily tell everyone I meet that VuePress is just super flexible and a perfect go-to for getting any hierarchy of information online, so – side point – I feel the VuePress mindset leaning towards documentation is a little perplexing. However, my experience to build a custom site from scratch in v1.0 is that you effectively need to build an "internal theme" in the Additionally, VuePress can only be hosted as a hidden sibling folder in Is there something specific that would mean such changes would be unworkable? |
Beta Was this translation helpful? Give feedback.
-
I also believe that consolidating the global effort into a VuePress 3 would make sense but I can understand the migration efforts for VuePress uses to be a bit overwhelming. As discussed with @yyx990803, I can try to label issues and PRs to the right categories for this goal. What labels to you want to use ?
What are your thoughts ? Too granular, not granular enough ? |
Beta Was this translation helpful? Give feedback.
-
Separately, this is what I would like to see in this major release: SEOSEO is a major feature today in the selection of solution for content, even when it's documentation. To have proper SEO, VitePress needs:
One can argue that "Clean URLs" are not SEO specific but at least it needs to work with Sitemaps and canonical URLs where everything generates the same URL for Search engines. Otherwise search engines will mark this content as duplicate if there is a mismatch anywhere. At least Google does. Note: I'm willing to contribute all PRs on this topic. |
Beta Was this translation helpful? Give feedback.
-
Overall, I'm a fan of "consolidating the ecosystem". I have no loyalty to a particular bundler... I've always hated configuring webpack, and I'm sure I'd hate configuring vite just as much 🤷 So, for me, I've always been much more concerned with the final resulting static website, and really don't care what build system was being used. But, I never had cause to adjust the bundler configuration in general... which brings me to I guess my main concern about plugins.
The Plugin ecosystem of VuePress has turned out to be very important to our team to customize the default theme so that we can change how our site works without having to re-write things from the ground up. I'm fairly naive when it comes to the impacts of writing webpack/vite plugins; however, to my mind "Writing a VuePress plugin" was much more approachable than "Writing a Webpack plugin". In fact, I wouldn't have thought those two things were associated at all. But, I bring it up as there was a comment above by @posva:
Again, I'm naive of the differences and impacts, or experience, of writing
VuePress' Default Theme was imperative in getting our design system documentation site out and deployed quickly. However, having a default theme isn't good enough on its own. VuePress also enabled users to extend the default theme to make minor, or even major, changes to fit their needs. But, they didn't have to write a custom theme from the ground up. In particular, the default theme uses |
Beta Was this translation helpful? Give feedback.
-
I love vitepress and have done some plugins (in the most basic way possíbel) like:
It is hard to reuse the algolia config data and the slot. Those should be more flexíble, maybe having a type inside a search config field where the default is algolia. For the slot I'm using alias to replace the default component with mine... But looks more like an workaround. Another great use is to center ALL my repo docs at works. And It is beautiful... |
Beta Was this translation helpful? Give feedback.
-
Reading this thread, I think there aren't much negative opinion about making VitePress VuePress 3 👀 But either if that comes true or not, I would like to discuss about how we roll out "Alpha" release of VitePress Next. My suggestionShip it as VitePress 1.0.0-alpha.1 with If we tries to ship VuePress 3.0.0-alpha.1, it has to be By keeping VitePress name until 1.0.0 release, we could make VitePress 1.0.0-alpha to be the latest publishable code. I think it make sense since VitePress is still 0.x version so alpha being the latest should be natural. And once we see the actual date of 1.0.0 release, we can firmly decide whether it's going to be shipped as VuePress 3, or VitePress 1. What do you shink of this approach 👀 ? /cc @yyx990803 @bencodezen @meteorlxy @ulivz @posva @brc-dd @billyyyyy3320 @georges-gomes |
Beta Was this translation helpful? Give feedback.
-
From last year to now, I have probably studied and used vuepress-next (vuepress2) for more than a year. Although it is not a stable and official version, I have already used it in all my personal projects and company open source projects also use. Concern: "plugin system":
Concern: "missing features":
|
Beta Was this translation helpful? Give feedback.
-
Will VitePress support authentication? |
Beta Was this translation helpful? Give feedback.
-
Ola, I am a little late to this party, but I hope my input could still be of some use. I run a documentation website on Vuepress-next (https://krdocs.swatdo.ge/), I had to hack in a lot of features, some of which id love to see factored in to vuepress 3. (I personally do not think it is worth it to continue work on vuepress 2)
When it comes to plugins, I personally do not mind how it is done. As long as it is easy to pick up, enough examples are given and the documentation for them is good, thats what vue is all about afterall :) |
Beta Was this translation helpful? Give feedback.
-
I think this makes the most sense. I'd hate to see both projects competing for development time and community focus. I have a thought/question about their parallel development: Since VuePress 2 uses Vite, would it be possible to write some essential VuePress 2 plugins as Vite plugins, allowing them to more easily be ported over to VitePress/VuePress 3? Or would the different APIs make it hard to manage? |
Beta Was this translation helpful? Give feedback.
-
Just some feedback from a VuePressNext user. I am a SAP Cloud Solution Architect mainly using VuePressNext for my docu site A year ago i migrated my MKDocs template using VuePressNext mainly for beeing able to
The current situation is that everything works fine, but i am not able to use Vite for compilation. So i gave VitePress a try and figured out, that some of the Vite issues are solved here.Currently most missing things that would block me from migration are:
As always, i tried to use as much as possible markdown-it plugins, Using something like
but they are not working as expected and there is no error. DeepLink SupportI also started an unanswered question/discussion in vuepressnext Concerning my custom component API Explorer, i am needing support for DeepLinks, but VuePress is filtering out router params and i can not add/overwrite route to be able to use addtional params for a page, that can handled by my component. It would be great, if VitePress with his own router solution would make such usecases possible. HighlightingWhile working with above API Explorer, where i needed to remotely read markdown and rendering it on client side, i figured out the pros and cons of highlighters. There were issues using prism or shiki to run it on client side. Also, if remote code uses {{}} or maybe JSON instead json, they fail for unknown languages or stop rendering without errors. The only error tolerant solution seems to be hightlight.js. Sadly this will then render a complete different theme. But this is only my specific issue needing to render also markdown on clientside. Main issue is renderingMy main problem is, that i get everything running on preview, but compiling crashes with vite.
Final thoughtsI like the new fresh design and performance of vite, but it is hard (or currently impossible) to get everything running in vite. There is maybe no need for all plugins, but media-zoom should be part of the core and also CodeGroups. If you need a documentation template, you should not be forced to develop own controls for basic tasks. Thanks for the great products that make life easier for a developer! Regards |
Beta Was this translation helpful? Give feedback.
-
Hi! Noticing this thread is both kinda long and now a bit quiet, and that the v1.0.0-alpha project is closed (and there isn't a new project yet). Relevant dates: Two suggestions:
|
Beta Was this translation helpful? Give feedback.
-
Hi, I am currently running an info portal around our SAP BTP SaaS offering UDINA BTP using VuePress2. Main reason for VuePress2 was the available color mode toggle and i also had not to migrate former vue code. With the latest v2.0.0-beta.53 i was finally able to switch to vite and like the performance boost, which is noticeable if your site starts growing. Personally, i like the idea of using standards as much as possible. Also, i do not need webpack support anymore since all my custom components and also web components are running. For missing gaps, i prefer markdown-it plugins and (if not available) develop custom vue3 components leveraging SAP UI5 Web Components. My site is locally running parallel on VitePress 1.0.0-alpha30 and i miss the following topics. Missing Features (ordered by priority)
For my custom components i need to find a way to inject darkmode switcher to be in sync with UI5 web components used theme, but i think i can handle this. Final thoughtsTo let this project become more agile while shrinking down support effort, dropping webpack would be ideal. For users it is anyhow irrelevant which tool is internally used and for devs, vite brings a lot of benefits. Best regards |
Beta Was this translation helpful? Give feedback.
-
回您说的这句话“我最初给 VitePress 取了一个不同的名字,因为我希望能够探索不同的架构而不用担心向后兼容” 。我从哲学角度来看,旧的不去新的不来, |
Beta Was this translation helpful? Give feedback.
-
Making VitePress as VuePress3 is a great idea, and I hope the plugins Api become more stable than last, it makes the plugin ecosystem release more power, and easy to upgrade to new version. |
Beta Was this translation helpful? Give feedback.
-
VitePress should add to important todos: Internationalization Then final statement should be made, because 2 same systems is confusing specially for new project. Which one should I use? |
Beta Was this translation helpful? Give feedback.
-
Shall we improve vitepress to support dynamic content? so it will be a general framework instead of SSG only. In real life a lot of website are static and dynamic hybrid. There should be a good tool for both static and dynamic content. |
Beta Was this translation helpful? Give feedback.
-
I would add also the ability to use foot notes like [^note1] etc |
Beta Was this translation helpful? Give feedback.
-
It'd be good to have built-in support for the _redirects file supported by Netlify/Cloudflare pages to test the redirections locally? |
Beta Was this translation helpful? Give feedback.
-
If someone wanted to add plugins, let's say for their own projects, would it be different from Vuepress 2? Or do we have to change theme for ourselves? |
Beta Was this translation helpful? Give feedback.
-
I wish VitePress could evolve into a renderer-agnostic SSG. I like the site layout that VitePress generates but I work with React-based apps and would love a SSG that is built on vite + react for my documentation needs. The current VitePress implementation could become an opinionated VuePress 3 but having a generic SSG built on vite and a renderer of choice (via plugins) would definitely be beneficial for broader use cases. |
Beta Was this translation helpful? Give feedback.
-
Would be better to go with VitePress 3 and make those breaking changes. It would also be good to align with Vue major version so that those who are |
Beta Was this translation helpful? Give feedback.
-
Something that I would really like to see and haven't seen being mentioned would be a Vitepress Nuxt module. This would somehow hook vitepress internal logic with nuxt and give hopefully the best of both worlds (Nuxt features and ecosystem + vitepress clean SSG and awesome md + vue support) (I know Nuxt content exists, but it's fundamentally different from how vitepress works. This would also only work with the Nuxt vite builder) We have a lot to gain by unifying the ecosystem. |
Beta Was this translation helpful? Give feedback.
-
@Hebilicious Do you have any feeling for how that would be different from https://content.nuxtjs.org/? I haven't used it yet, but am porting a VitePress site to Nuxt as I need a more code-focused project structure. |
Beta Was this translation helpful? Give feedback.
-
But VuePress2 is fantastic! |
Beta Was this translation helpful? Give feedback.
-
But VuePress2 is fantastic! |
Beta Was this translation helpful? Give feedback.
-
I'm planning to push VitePress to stable status, likely in the first half of 2022. This thread will list the planned TODOs for feedback. The plan is tentative so feel free to suggest things that you think is important / missing.
VitePress 1.0 or VuePress 3?
I initially gave VitePress a different name because I wanted to be able to explore a different architecture without worrying about backwards compat. After shipping the vuejs.org with VitePress, I believe VitePress is flexible enough to be a full replacement of current VuePress while offering better DX and better performance.
The two projects are similar in that both are Vue-powered SSGs and share the same set of markdown extensions, but are also fundamentally different. VitePress tries to stay as minimal as possible and delegate customization to either Vue (via custom themes) or Vite (VitePress supports all Vite config options and plugins). There is no VitePress-specific plugin system. For a normal user that is using the default theme and doesn't need heavy customization, it can serve almost as a drop-in placement with minor changes. But it will be very different if you are building a completely custom site.
The VuePress team worked on VuePress 2, which also uses Vue 3 and supports Vite. However, I see two problems with this:
I think we should ship VitePress stable as VuePress 3, but I am open to potential questions and concerns.
Other Important TODOs
type: 'module'
and pure-ESM dep supportvitepress build
fails withERR_REQUIRE_ESM
#476New default theme
We are planning to complete rework the default theme. The theme will have a similar style with the new vuejs.org theme, but still visually distinct enough. @kiaking has already been working on the new design. The new default theme will also try to address current open issues that are related to the default theme, e.g. built-in simple search.
Rewrite docs. Current docs is rough and incomplete. We need examples of vite configuration, a custom theme tutorial, etc.
E2E tests
More feature alignment with VuePress 1/2, where applicable. E.g. permalink customization etc. Feel free to suggest features that you found important in VuePress but missing in VitePress.
Beta Was this translation helpful? Give feedback.
All reactions