Next steps for VitePress

[yyx990803]

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:

• It still carries the baggage of VuePress' current plugin system, which seems unnecessary when you can use Vite plugins.
• The complexity of supporting both webpack and vite isn't desirable in the long run.

I think we should ship VitePress stable as VuePress 3, but I am open to potential questions and concerns.

• Pros: Less confusion in the long run. There will be just one officially maintained SSG with better DX, better performance, and customization that fully aligns with standard Vite-based Vue apps.
• Cons: Potential confusion in the short run, since there are probably a lot of tutorials / integrations targeting VuePress 1. Still I think with the recent Vue 3 switch, users won't be surprised with a major upgrade for VuePress.

Other Important TODOs

• type: 'module' and pure-ESM dep support

  • vitepress build fails with ERR_REQUIRE_ESM #476
  • fix: ERR_REQUIRE_ESM error when project type is set to module #512

• New 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.

[yyx990803]

/cc @bencodezen @meteorlxy @ulivz @kiaking @posva @brc-dd @billyyyyy3320 @georges-gomes

[bencodezen]

Thanks for the write-up!

Given my own bandwidth for projects at the moment, I agree with the suggestion to ship VitePress as VuePress 3 in order to consolidate the ecosystem. From there, I think we can update the docs to help people be successful even though there are some mental models to change from the original VuePress. 👍

[brc-dd]

Perhaps we should first ask VuePress users (through Discord, Reddit, Twitter, Dev, etc.) and see if the most used/requested features of VuePress (v1 and v2) can be ported to VitePress efficiently?

[posva]

I also think the upgrade to only support Vite makes sense and having other breaking changes happening at the same time makes sense. I imagine some of the existing vitepress plugins are really used and would need to be migrated to vite plugins.

[WebMechanic]

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 yarn dev and yarn docs:dev launches separate servers that don't like each other despite virtually living in the same DocumentRoot.

I'd love VitePress to run on the same port as the main project and use and access the same assets, resources, /public folder etc. that are already available and primarily generated there (i.e Sass output).

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 .vitepress and ./docs folders and seamlessly import() assets generated by that main project. They use separate "public" folders and running on different ports on localhost w/o SSL causes CORS errors when I cross-link to assets served from the actual /public folder.

We're mainly on Windows and unfortunately junctions (hardlinks) do not always work well with Node's path resolver.

[davestewart]

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.

Apologies if this is not the right direction for "feel free to suggest things that you think is important"; I haven't been keeping up with the day-to-day development over the last year, and I'm happy to start a separate discussion if that would be more appropriate.

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.vuepress folder, as proper themes can only be loaded from a dependency. This feels too tightly coupled, and I would like this to change so you can do a small amount of config in the .vuepress folder (like site title and theme folder) but the theme can be a separate folder in your site.

Additionally, VuePress can only be hosted as a hidden sibling folder in content/.vuepress, which makes it impossible to silo changes to your site engine separately to content and is invisible when saving from applications like PhotoShop (save dialogs appear to have separate settings from the Finder, so you need to know the keyboard shortcut to toggle files). Making this more flexible has been discussed various times and rejected. Ideally in config you could point to content, .vuepress, theme, dest etc as completely independent paths, and .vuepress would not be hidden or even required to have a fixed name.

Is there something specific that would mean such changes would be unworkable?

[georges-gomes]

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 ?
My proposal here

• VP3 - core/enhancement > Enhancement required for VuePress 3
• VP3 - core/bug > Bug fix required for VuePress 3
• VP3 - default theme > Enhancement or bug require in default theme for VuePress 3

What are your thoughts ? Too granular, not granular enough ?
Once we agree on the semantic, I can start scanning the issues and PRs and apply the appropriate label.

[georges-gomes]

Separately, this is what I would like to see in this major release:

SEO

SEO is a major feature today in the selection of solution for content, even when it's documentation.
The ability to be indexed and ranked properly is on the top of the list.

To have proper SEO, VitePress needs:

• Sitemap (Sitemap generation #520).
• Specific header meta per pages (API to change head content #551) / Having proper per page, meta data greatly improved SEO and overall quality of the link when shared on social media platforms.
• Default canonical url / VitePress supports canonical URLs today but you have to set it up "manually" on every page through front-matter. It's actually a best practice to always have a canonical URL in your page because this avoid any duplicate related to anchors in URL or trailing slash (This obviously makes more sense with feat(cleanUrls): CleanUrls feature - No .html in navigation bar #488). VitePress needs default canonical url so we don't need to add it to every page and potentially make mistakes. Astro has it build in elegantly. This can probably be solved together with the previous point.
• Clean URLs (feat(cleanUrls): CleanUrls feature - No .html in navigation bar #488) / Consistency in URL is important. Most SSG solution don't use .html extension in URLs. This makes the migration from one solution to another risky because of URLs changes. I can see people turning down VitePress because of urls ending with .html.
• Potentially MPA mode stable...

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.

[brianmercer]

Agreed on these.

Can sitemap or the others be done with a vite plugin?

Would clean urls require replacing the vitepress client-side router?

[georges-gomes]

Hi Brian,

#488 is implementing the cleanUrl without replacing the router.
I also implemented #588 for custom headers (it also solves canonical URL with a bit of code)

I haven't looked at sitemaps yet.

[chris-dura]

Perhaps we should first ask VuePress users (through Discord, Reddit, Twitter, Dev, etc.) and see if the most used/requested features of VuePress (v1 and v2) can be ported to VitePress efficiently?

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.

1. Concern: "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:

I imagine some of the existing vitepress plugins are really used and would need to be migrated to vite plugins.

Again, I'm naive of the differences and impacts, or experience, of writing vuepress plugin vs webpack plugin vs vitepress plugin vs vite plugin. But, on its face, the implication that "I have to learn to write a bundler (vite) plugin in order to modify the vitepress default theme" is a minor concern... but maybe only because I have zero experience writing vite plugins... and I've never wanted to learn to write "plugins for bundlers" at all... ever. :) But, perhaps I just don't have enough knowledge around writing vite plugins to see how that maps to my current experience of writing VuePress plugins to do VuePress things.

2. Concern: Multi-Level Extending/Customizing the Default Theme

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 alias so that users can completely replace default theme components with their own, or the default theme also use slots to allow for injection of custom components. Without these capabilities, a user (who did not/could not write their own theme from the ground up) would be have to find a community theme to fit their needs. I know if that was the case for our team, we very likely would have gone with a different ecosystem entirely, for example GatsbyJS, since there are more themes to choose from.

[WebMechanic]

the default theme uses alias so that users can completely replace default theme components with their own

haven't seen this alias thing, could you please point me to the ressource where this is explained? Thanks!

[davestewart]

I think it's explained here: https://vuepress.vuejs.org/theme/inheritance.html#override-components

I'm not sure how long this has been a thing, as I suggested similar but it wasn't a goer. Maybe I missed it (likely) or maybe thinking moved on?

FWIW, I think it's easy to build a VuePress theme from scratch, and (at the time) I wasted weeks trying to tweak the built in components when it was easier just to eject or build your own from scratch. The hard bit if starting from scratch was wrapping your head round the core architecture / concepts, but clearly good docs was and will be the solution there.

[chris-dura]

3. Concern: Markdown content in Vue Component (slot)

Saw a random comment in the vitepress discord that maybe has been resolved, but adds another concern. The comment implied vitepress doesn't come with using "Markdown in Vue Component" as a default capability... and I think being able to do this is also a MUST HAVE?

// path/to/some/markdown/README.md

# Title

Some markdown content, above a custom vue component.

<MyComponent>

This (slotted) content _must_ be able to use *markdown syntax*.

</MyComponent>

## Some other title

- more
- content

[emersonbottero]

I love vitepress and have done some plugins (in the most basic way possíbel) like:

• dark theme
• mermaidjs (since this one uses the mermaid api It Works with images... 🤩)
• offline search with lunr,

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...
The only problem is that I can't override the link to edit in Github, since the pipeline clones a Lot of repo those would change.
Maybe a function method to set the github link would do the trick.

[iceener]

Can you describe a bit more how to use vitepress-plugin-search? I was able to make Search Bar visible but indexing doesn't work. Is there any additional configuration needed?

[mrienstra]

@iceener, try Discord, or start a new issue or discussion. If you find the documentation lacking, consider opening a PR to improve it when you find the information you seek.
... Oh, sorry, I just realized you're asking here because your question is about @emersonbottero's https://github.com/emersonbottero/vitepress-plugin-search. Maybe open an issue over there?

[emersonbottero]

See the read me or clone the repo..
There's a demo inside it

[kiaking]

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 suggestion

Ship it as VitePress 1.0.0-alpha.1 with --tag latest by merging the code into main branch. The idea is to get community PRs targeted to upstream main branch, rather than VitePress next development continues on next branch.

If we tries to ship VuePress 3.0.0-alpha.1, it has to be --tag next until it's finally ready, which means less people gonna use it until it's stable. Looking into the list of todos toward 1.0.0 release, I'm assuming it needs a bit more time.

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

[brc-dd]

Fine by me. However, I suggest adding a note on the VuePress repo asking users to check out VitePress (just that VitePress is an alternative, also built by the Vue.js team; no need to mention if this will be VuePress' v3). This way, we can have some more traffic here, and once we are stable enough, we can decide what to do next.

PS: Just saw that it is already there on GitHub. Earlier I was checking on NPM.

[Zhengqbbb]

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":

• It has to be said that the vuepress plugin system provides strong scalability. But writing a plugin at the same time is very painful at the beginning. You need to read the source code of the same type of plugin and read the documentation to learn, but this is also the first npm package I released.
• But if you were to ask me which plugin I would choose to learn to write, I would of course prefer to learn the vite plugin. After all, I can use it anywhere other than vitepress.

Tip: It is very important to inform the official plugin demo , at least it saves me more than the documentation: https://vuepress.vuejs.org/plugin/#examples

Concern: "missing features":

1. sitemap without a doubt!

   • Support custom header meta per pages. Vuepress only supports defining title and description in Frontmatter.

2. Basic interactive capabilities for page switching (should be included in the default theme)

• 3. generate code copy button

[Zhengqbbb]

So is the docs so weak that you missed them even you've used for more than a year? 😢

What am I doing！！！yeah I do miss it, I can't even believe my eyes when I open it 😱😱😱😱😭

[posva]

I would also say no to any page transition by default. Users can add them if they want to but since they don't add any meaning to the interaction (user navigating through documentation pages) I would even consider this kind of transition a bad practice. The only exception could be "directional" navigations like going forward or backward.

[Zhengqbbb]

I would also say no to any page transition by default. Users can add them if they want to but since they don't add any meaning to the interaction (user navigating through documentation pages) I would even consider this kind of transition a bad practice. The only exception could be "directional" navigations like going forward or backward.

Yeah, I'm currently aware of this.

[stafyniaksacha]

FWIW, in our accessibility team's opinion, these page transitions are "terrible" for accessibility, and we spend time making sure we remove them. Transitions like these can cause things like vertigo in people with vestibular disorders.

Does it apply to “light” fade transition (0.1 / 0.2 ms) ?

[chris-dura]

@stafyniaksacha -- It is notoriously hard to come up with a "baseline" for problematic motion because some settings will be fine for one person, but trigger another person. However, (and don't take my word for it in all cases) in general, gentle "fade transitions" are overall pretty safe when NOT coupled with actual motion (eg, translation and sliding). But again, it's hard to say what will and won't trigger someone with a vestibular disorder, so it is ALWAYS best practice to use the prefers-reduced-motion media query to make adjustments when the user has explicitly indicated they prefer reduced/no motion!

[hyp530]

Will VitePress support authentication?
In my case, I run a backend Golang Gin server and a MongoDB.
That would be great if VitePress could have built-in features to enable data communication with a backend server, particulary for authentication purposes.

[kiaking]

I would say no, at least for now. VitePress is a static site generator, so all content would be generated on build time so authentication doesn't really fit well.

If you're creating SPA, you should use Vite directly, and if you need even more power like SSR or advanced features, frameworks like Nuxt might be the best fit.

[aaronransley]

I was curious about this strategy as well, since I have a use case where VitePress is perfect with the exception that I need to lazy-load sensitive documentation data after authentication + authorization routines have a chance to run.

Has anyone managed to fork / patch VitePress to support this setup? Would I be better off simply recreating styling / site structure using Vite / Vue / Nuxt directly?

[SwatDoge]

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)

1. Support for large, merged documentation. This website gets intensively used, and nothing is as fast as looking something up with CTRL + F. Having one big document with (a large part) of all content significantly slows down the website. It would be really great to have optimisations specifically for this, for instance not loading elements that are out of view.
2. A good set of plug-and-play out-of-the-box features. I originally picked Vuepress 2 because it had built in dark mode, I am glad to see this return to Vitepress, and hope there will be more accessability features. It saves a lot of time.
3. Icons. Colors and icons are great for recognizing where to go, I'd love to see an option or plugin for icons in nav- and sidebars.
4. Make adding custom languages to scripting windows more intuitive, it took me very long to figure out personally, as it was not part of the vuepress development experience.

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 :)

[WebMechanic]

"not loading elements that are out of view" and using "CTRL + F" are mutualy exclusive: the browser can't find content that isn't loaded/present.
That's a similar issue to Twitter's timeline, which is throwing away content that's scrolled far out of view. It can no longer be found with Ctrl+F.

Icons are a matter of taste and some dispise them, and w/o associated text they're also bad for accessibility.
Anything cosmetic like that belongs exclusively to the Theme's custom stylesheet.
I certainly wouldn't want to have any icon pack preinstalled as it's 100% not the one I'd like to use. Not sure if @antfu 's icon plugin could be a solution.

[elliottregan]

I think we should ship VitePress stable as VuePress 3

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?

[hschaefer123]

Just some feedback from a VuePressNext user.

I am a SAP Cloud Solution Architect mainly using VuePressNext for my docu site
https://btp.udina.de/

A year ago i migrated my MKDocs template using VuePressNext mainly for beeing able to

• replace python by javascript
• easily be able to integrate additional functionality using Vue3 Components
• integrate/use SAP UI5 Web Components with Vue3

The current situation is that everything works fine, but i am not able to use Vite for compilation.
I like the Vite startup time and would like to switch over.

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:

• Image medium-zoom
• CustomContainer
• CodeGroup

As always, i tried to use as much as possible markdown-it plugins,
but i am currently not able to get them running inside vitepress?!?

Using something like
config.ts

markdown: {
      config: (md) => {
        // use more markdown-it plugins!
          md.use(require("markdown-it-implicit-figures"), {
            figcaption: true,
          }),
          md.use(require("markdown-it-plantuml"), {});
...

but they are not working as expected and there is no error.

DeepLink Support

I also started an unanswered question/discussion in vuepressnext
vuepress/core#1010

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.
It must not be VueRouter, but addtional uri params or routes should not be replaced by core.

Highlighting

While 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 rendering

My main problem is, that i get everything running on preview, but compiling crashes with vite.
Using SAP UI5 Web Componente with <ClientOnly/> always getting

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'C:\VSC\@udina\udina.docvp\node_modules\@ui5\webcomponents\dist\Title' imported from C:\VSC\@udina\udina.docvp\docs\.vitepress\.temp\development_ui5wc.md.js

Final thoughts

I 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
Holger

[mrienstra]

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:
Feb 21: this thread began.
June 1: "v1.0.0-alpha" project closed.
June 5: most recent "Maintainer" comment or reply on this thread.

Two suggestions:

1. Start a new project for the roadmap from alpha to beta (or stable?).
2. Start a new discussion to continue the conversation started here, pin it and unpin this one.

[brc-dd]

Start a new project for the roadmap from alpha to beta (or stable?).

We already have one, but its not public.

PS: don't ping people unnecessarily. If they haven't unsubscribed from this thread, they would've got the notification.

[Goozoon]

and in Code section last 'thing' is 4month ago
Hope it will be still alive

[brc-dd]

@Goozoon can you please clarify what exactly are you referring to?

[Goozoon]

partly my fault
but when you open main page - https://github.com/vuejs/vitepress
all you see on the right side is

[Releases 55]
v1.0.0-alpha.4 Latest on 22 Jun

But there is also Alpha 25 release when you open - https://github.com/vuejs/vitepress/releases

[hschaefer123]

Hi,
first of all, thanks for offering this great SSR!

I am currently running an info portal around our SAP BTP SaaS offering UDINA BTP using VuePress2.
The site was migrated from MKDocs to get rid of python and beeing able to easily integrate custom vue3 components.

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)

1. MustHave Mostly miss the medium-zoom plugin. This feature is heavily used on my site to watch diagrams in fullsize
2. It is not possible to add Custom Container eg. theorem and then just styling them with custom css. Vuepress generated class names for unknown types like .custom-container.theorem that could easily be styled.
3. I like the configuration less search besides algoilia docsearch, but if understood right, this can be used free and should be a problem for me
4. My header title "Business Technology Platform" is too long for sidebar and will be wrapped, what looks ugly, but i can live with shortened UDINA BTP. Maybe addressed in upcomming theme.
5. Readability of custom container color theme is currently problematic for light and dark. Maybe this will be addressed with the new theme.

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 thoughts

To 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
Holger

[evanlong0803]

回您说的这句话“我最初给 VitePress 取了一个不同的名字，因为我希望能够探索不同的架构而不用担心向后兼容” 。我从哲学角度来看，旧的不去新的不来，VitePress 挺好

[taozuhong]

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.

[volarname]

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?

[Goozoon]

Internationalization is almost done - #1339

Naming is a nightmare, indeed: vue 1, 2, 3, Vite 1, 2, 3, vupress, next, vitepress...

[xu4wang]

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.

[hschaefer123]

I would join this idea, because my VuePress2 site uses markdown for the static docs and also dynamically reads markdown from remote sites to generate html to offer the same ux look. But this also introduces problems with unvalid (from vue perspective) remote markdown, where syntaxhighlighting only works with highlight.js (more error tollerant).

A second need would also be better router support. I was not able to use/enhance the router the default way for my custom components offering deep links. As i saw, VP skipped router by implementing own routing. That will maybe also lead into issues.

But generally a good idea, that would fullfill my needs.

Regards
Holger

[damianof]

I would add also the ability to use foot notes like [^note1] etc

[santiagoarizti]

you can already do this by installing markdown-it-footnote and adding it via .vitepress/config.ts with:

import MarkdownItFootnote from 'markdown-it-footnote';
export default defineConfig({
    //...
    markdown: {
        config(md) {
            md.use(MarkdownItFootnote);
        }
    }
});

[damianof]

Thank you!

[seanogdev]

It'd be good to have built-in support for the _redirects file supported by Netlify/Cloudflare pages to test the redirections locally?

[9x9x9x]

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?

[sagargurtu]

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.

[davestewart]

I like this.

My preference would be something a little more like Nuxt's Content which basically gives you an engine for transforming content and querying for structure / navigation / etc, then theme, layout and components are and additional layer / dependency on top.

[codler]

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 Using Vue in Markdown know easier what Vue version are running behind.

[Hebilicious]

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've glanced at the codebase, and this seems doable. The client part would require more work, but the node part should be almost identical.
If that's something that many people want, I'd be happy to start working on it!

(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.
Many of the comments here are asking for features like authentication or more advanced features, a vitepress nuxt module would enable all these advanced use cases.

[tommie]

@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.

[Hebilicious]

@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.

Would need to dive more into it to compare both, but from the top of my head :

• Nuxt content use MDC, vitepress use something more flexible where you can mix and match Vue code within the MD files (is create a ref etc). Afaik you can't do that in Nuxt content (you would need to create a component)

• Nuxt content does some kind of querying and can retrieve remote data, which is more advanced but leads to a less snappy website than vitepress (would need to benchmark that, just a gut feeling at this point)

[kaikaibenkai]

But VuePress2 is fantastic!
Is it possible to publish them simultaneously?

[kaikaibenkai]

But VuePress2 is fantastic!
Is it possible to publish them simultaneously?

[caojiantao]

Then, several years have passed, and the permalink feature still hasn't been supported. 😔