About 12-18 months ago, I was looking for a Documentation tool. My requirement was something I could wrap on top and not worry about neither the frontmatter, nor worry about inline anything. I stumbled on VitePress and dovetails like a glove. I have been using it since as the default starter for anything documentation that I do. I'm open to migrating to something else "better" if the other team members want to. But this is my personal start and works well so far.
This is the Obsidian of Documentation. In fact, I use Obsidian to edit locally and VitePress spits out the HTML for Preview and so for the Production Deployment.
Obsidian already ignores all of your dotfiles, thus a clean interface. I don't see the "node_modules" folder these days, it is just there and I ignore.
For similar Vault Preferences, in-fact, my setting is to symlink the Vault's `.obsidian` to an `.obsidian` somewhere commonplace. I do this for such documentation/website that is also crunched by some other tools -- Jekyll, VitePress, etc.
It's been exciting to see Docusaurus [1], VitePress, and Starlight [2] all under very active development, with the first two being React- and Vue-based respectively, and Starlight being built in the Astro Islands "bring your own UI framework" model. Docusaurus ended up feeling a bit too heavyweight and opinionated for my uses, and I've been happy with Starlight so far, with the developer/author experience being very similar to what I've seen during experimentation with VitePress.
I thought the name hinted at the fact that this was a WordPress replacement, not a static site generator (which there are plenty off).
I used to build lots of WordPress themes years ago. I've seen a lot of static site generators popping out every couple of months, or API-driven frontend frameworks linked to a headless CMS. I've (successfully) used a few of them. But what about "all-in-one" dynamic website engines? Are there new interesting ones out there that I have missed?
Give Wagtail a try if you are a fan of Python/Django/Postgres. It is a very good CMS while also properly integrating with the underlying framework.
Payload CMS is a far less mature option but it looks promising and could be a decent choice for teams that prefer JavaScript/Mongo. I have no direct experience with this one so can't say if it is good in practice.
I've been using VitePress for a while now. I'm building everything on https://containersonaws.com/pattern/ via VitePress and an entirely custom theme. It feels great to be able to design the website using proper Vue components, compared to the quasi-template language of something like Hugo. And the page load and navigation performance has been quite nice in my opinion.
The only downside that I will mention is that builds are quite slow. I'm not sure how this will scale out as I get more pages. My Hugo website can build 100's of pages in under a second, while VitePress is taking 30-40 seconds to build around 100 pages.
Personally, I don't care about the build times as they happen in a GH workflow [1] and the compiled sources get updated to Cloudflare Pages that's how [2] gets deployed.
Yep that's right. Every page has it's own statically rendered bundle. But if you have JS on then it can fetch a chunk and rerender the page client side as a SPA.
How does VitePress compare to Jekyll in terms of developer-friendliness and page build times? I still use Jekyll for small projects because it is well-documented and just works.
I have not used Jekyll, but I think it's important to note that VitePress is Vue specific. It's designed to be used with Vue components, and it's designed to produce a single page app where navigation happens client side (though there is still a statically rendered version of each page, so it works without JS). Most other static site renderers do exclusively static rendering, without the automatic progressive enhancement to SPA. And VitePress has such intelligent client side enhancement that it even does things like preload pages in the background as soon as the link appears on screen. It adds up to a very fast and light feeling experience.
I love VitePress, it's simple, extensible, and just works. For a basic documentation/blog page it's enough. I was able to build Logdy's website, documentation and blog with it. You can check the source code of the website here[1]. The only thing I'm missing is a full compilation to a static html.
> In a nutshell, VitePress takes your source content written in Markdown, applies a theme to it, and generates static HTML pages that can be easily deployed anywhere.
I do this with
for file in .md; do pandoc --quiet --template template.html $file -o "docs/${file%.}.html" done
> instant server start
cd docs/ && ruby -run -ehttpd . -p8000
There is also python and many other builtin alternatives for most systems.
It supports anything Pandoc supports...which is pretty much anything I need.
Yes...I know it doesn't have many fancy features...but it has the best feature that none of those SSGs have: I don't need to read ANY docs even if I spend 1 years without touching it. Here is the result: https://alexandremcosta.github.io
> Unlike many traditional SSGs where each navigation results in a full page reload, a website generated by VitePress serves static HTML on the initial visit, but becomes a Single Page Application (SPA) for subsequent navigation within the site. This model, in our opinion, provides an optimal balance for performance:
If I understand correctly, this is the same approach next.js takes for rendering. Seems like the advantage is that the directory structure and markdown support are there from initialization rather than needing to be configured [0]. Also I'm guessing the vue dev audience likes to stay out of next-land.
A couple weeks ago I rebuilt the https://hiresynth.ai landing page and docs using vitepress and was super impressed with the speed of implementation and how pretty it was by default.
VitePress has a great development experience but we ended up running into several issues with our large (500+ pages) docs site with several broken pages with broken rendering, duplicate & missing content, etc. that took too long to identity and resolve that we ended up porting it to a .NET Razor SSG website [1] adopting a simpler "pure" .html static SSG pages with progressively enhanced Vue components for any markdown pages requiring interactivity.
VitePress is a great choice if you just need a pure docs site, but if you prefer not to have your entire Website built with it, we're maintaining a "Vite Press Plugin" that can be used to add Blogs and other markdown powered features to Vue and React Vite Apps. It includes GitHub Actions to publish to a repo's GitHub Pages branch so the resulting static website can be hosted Free on GitHub Pages CDN as done for the Vite Press Plugin's introductory Blog Post [2].
Instead of porting to static .NET pages + progressively enhanced Vue, keep vitepress for static pages and replace dynamic parts with progressively enhanced Vue?
The issues with VitePress is what caused us to port our docs elsewhere. We had several broken pages with repeated and missing content which we spent a long time trying to workaround their SSR/SPA hydration issues by running custom js to try manually detect and resolve issues, but that started to become unwieldy having to maintain these hacks for several pages that we made the switch to abandon it and move to a cleaner C# Razor SSG .html pages that's progressively enhanced with Vue Components. We no longer have any rendering issues and now have full control over the entire SSG output that we're able to resolve any issues that we do run into.
Has anyone found a good way to password protect a sub-folder/page of a vitepress docs site?
We’re currently using cloudflare for the purpose, but it breaks the JS on vitepress, which means things like the mermaid or plug-in and sidebar can’t load.
We’re use the MPA (multi page app) setting. SPA would mean everything is still actually bundled and sent to the user anyway.
Beyond that, haven’t had any issues with VitePress. Great product.
my 2 cents: if you intend to secure the content then it cannot be delivered to the client, as in: you need to have a password/token protected endpoint.
If it's just for the visuals then I guess you can prepare a Vue module that will prompt for a password before showing the content, then wrap a content within it.
<PasswordProtected :password="'foobar'">
This content will be displayed only after providing a password
</PasswordProtected>
> if you intend to secure the content then it cannot be delivered to the client
... In plaintext. You could maybe wrap a kdf and a webcrypto thing in a Vue component - decrypting on the client by deriving a key from a user supplied password.
It would almost certainly be a worse solution than basic auth on a normal web server...
Not the most important thing in the world but I'm surprised this is named VitePress when it uses Vue and is apparently replacing a project named VuePress. Surely the latter is the more appropriate name? I could make a static site generator with React or Svelte or whatever that also uses Vite.
Given that version 1 landed as "VitePress" they probably decided to keep the name.
> 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.
> ...
> 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.
Unfortunately the Vue ecosystem has gone through several poor names for its libraries. One example is its state management library, Vuex. When it came to a new major release which would normally be a major version bump semantically, right?
What happened instead was… they essentially forked Vuex, renamed it Pinia (thus no longer even being at first glance related to Vue, or the Flux pattern it sort of uses).
The reasoning was illogical, something about worried people would be confused with its new API. Well I’ll take that to the next level and point out they didn’t simply fork and rename Vue when they released a new major version.
This led to very poor discoverability for sometime, I don’t know if that’s still the case as I decided to use React not longer after this because of all the nonsense in Vue.
Nuxt Content is a lot less opinionated. You'll have to build out most yourself. There are themes (https://github.com/atinux/content-wind), but last I checked, it wasn't simple to configure.
Agreed. I built my personal website with Nuxt Content, but I'm not satisfied with it. It forces you to do a lot of things yourself and is definitely targeted towards dynamic websites. Since I am building for Github Pages, I found it quite unintuitive.
I would recommend using VitePress, Zola, Jekyll, or some other tool instead if you need an SSG.
VitePress is geared more for documentation websites, while Nuxt Content is more for regular websites.
Of course, VitePress can be used for all sorta of stuff. My old website used to be based on it. If you click through the sites using VitePress you can see the similarities and what you get for free with the default theme.
I can not use those SSGs as I want to keep some of my pages private, so I can login and edit and read myself(currently using wordpress for that with plugin). I wish some of SSG can do the simple CMS functions, but none that I found, can vitepress do that, i.e. having basic CMS support?
Hey, neat - clicked around a little bit! Bug report: the contact page had some comments related to an article that definitely weren't related to the contact page.
Good, but no one really cares of fast loading of pages. Either 0.1 or 1 sec, or even 2-3 sec. Most important is if the website contains useful information.
You care if you're on mobile on a slow device with a poor network, a megabyte of slow loading javascript isn't great. That's about 50% of the planet by all accounts.
This is the Obsidian of Documentation. In fact, I use Obsidian to edit locally and VitePress spits out the HTML for Preview and so for the Production Deployment.
Thank you VitePress.