VitePress 1.0
blog.vuejs.org
blog.vuejs.org
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.
Is your entire vitepress codebase inside of a vault?
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.
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?
It seems to, but paragraph 2 at the link and the front page subhead at https://vitepress.dev/ shows that its creators think of it as an SSG.
It can also work in concert with a CMS, though: https://vitepress.dev/guide/cms
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.
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.
[1] https://github.com/logdyhq/homepage/blob/main/.github/workfl...
I do this with
for file in .md; do pandoc --quiet --template template.html $file -o "docs/${file%.}.html" done
cd docs/ && ruby -run -ehttpd . -p8000
> edits always instantly reflected
find . -name '*.html' -o -name '*.md' -o -name '\*.sh' | entr ./script.sh
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
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.
[0]: https://nextjs.org/docs/app/building-your-application/config...
Would recommend for any text heavy static site.
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].
[1] https://servicestack.net/posts/new-razor-ssg-docs
[2] https://press-vue.servicestack.net/posts/vite-press-plugin
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>
... 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...
And VuePress might turn off people who are React devs for example.
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.
> producing many copies by repeated direct impression
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.
I would recommend using VitePress, Zola, Jekyll, or some other tool instead if you need an SSG.
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.
Most of downsides I encountered were related to pre-release issues but overall a very pleasant + powerful toolkit
I really enjoy the ability to sprinkle interactivity inside markdown docs, file-based routing, search, etc
It's been surprisingly flexible and configurable to my needs.