[HN Gopher] VitePress 1.0
___________________________________________________________________
VitePress 1.0
Author : cielpy
Score : 101 points
Date : 2024-03-21 15:58 UTC (7 hours ago)
(HTM) web link (blog.vuejs.org)
(TXT) w3m dump (blog.vuejs.org)
| Brajeshwar wrote:
| 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.
|
| Thank you VitePress.
| codybontecou wrote:
| How are you managing your vault alongside your codebase?
|
| Is your entire vitepress codebase inside of a vault?
| Brajeshwar wrote:
| .gitignore > .obsidian
|
| 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.
| bbx wrote:
| 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?
| CharlesW wrote:
| > _I thought the name hinted at the fact that this was a
| WordPress replacement, not a static site generator..._
|
| 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
| evantbyrne wrote:
| 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.
| NathanKP wrote:
| 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.
| minimaxir wrote:
| Hugo's builds are fast because it caches: does VitePress cache?
| NathanKP wrote:
| There is that, but even without cache the Go code for Hugo is
| blazing fast compared with the the JS bundler for VitePress,
| sadly
| Menu_Overview wrote:
| Vite Pres has client-side routing, right? Like, it works
| without JS, but if JS is enabled, it runs as a SPA.
| NathanKP wrote:
| 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.
| synergy20 wrote:
| this is where it differs from those SSG I guess, used
| vitepress a while ago, will reuse it later
| piterrro wrote:
| 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.
|
| [1]
| https://github.com/logdyhq/homepage/blob/main/.github/workfl...
|
| [2] https://logdy.dev
| pwenzel wrote:
| 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.
| NathanKP wrote:
| 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.
| piterrro wrote:
| 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.
|
| [1] https://github.com/logdyhq/homepage
| TikolaNesla wrote:
| If you like Vue, you'll love VitePress
| afavour wrote:
| 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.
| addicted wrote:
| Maybe because Vite has a broader audience than Vue.
|
| And VuePress might turn off people who are React devs for
| example.
| ayhanfuat wrote:
| There is a discussion related to naming on GitHub:
| https://github.com/vuejs/vitepress/discussions/548
|
| 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.
| amiantos wrote:
| Seems weird to me to name this project after WordPress when
| it's not really an equivalent to WordPress at all.
| Menu_Overview wrote:
| I think the etymology for both of these kinda comes from
| "letterpress".
|
| > producing many copies by repeated direct impression
| lloydatkinson wrote:
| 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.
| waitwhatwhoa wrote:
| 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.
|
| [1] https://docusaurus.io/
|
| [2] https://starlight.astro.build/
| esher wrote:
| How does it compare to Nuxt Content? https://content.nuxt.com
| codybontecou wrote:
| 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.
| BD103 wrote:
| 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.
| Menu_Overview wrote:
| 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.
| cynicalsecurity wrote:
| 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.
| DrBazza wrote:
| 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.
| mythz wrote:
| 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].
|
| [1] https://servicestack.net/posts/new-razor-ssg-docs
|
| [2] https://press-vue.servicestack.net/posts/vite-press-plugin
| Kinrany wrote:
| Wouldn't it be faster to do the same but keep vitepress?
| mythz wrote:
| Wouldn't what be faster?
| Kinrany wrote:
| Instead of porting to static .NET pages + progressively
| enhanced Vue, keep vitepress for static pages and replace
| dynamic parts with progressively enhanced Vue?
| mythz wrote:
| 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.
| synergy20 wrote:
| 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?
| codybontecou wrote:
| I built my blog around Vitepress: https://www.codybontecou.com/
|
| It's been surprisingly flexible and configurable to my needs.
| MoOmer wrote:
| 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.
| codybontecou wrote:
| Haha, I appreciate the heads-up. It's not a bug. That user
| just decided to comment there for some reason.
| DrBazza wrote:
| Does a static site generator really need to produce a site with
| Javascript? Seems a bit self defeating.
| lloydatkinson wrote:
| Fortunately there are other options if you wish to still use
| JS/TS for the build while delivering zero JS to the client.
| Astro, Fresh.
| rgbrgb wrote:
| > 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.
|
| [0]: https://nextjs.org/docs/app/building-your-
| application/config...
| malkosta wrote:
| > 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.
|
| > edits always instantly reflected find . -name
| '*.html' -o -name '*.md' -o -name '\*.sh' | entr ./script.sh
|
| > Built-in Markdown Extensions
|
| 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
| simonbutt wrote:
| 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.
|
| Would recommend for any text heavy static site.
| AltruisticGapHN wrote:
| Do you get the awesome search by default?
| ashishb wrote:
| How does this compare to Hugo?
| valgaze wrote:
| I used an early RC to build docs for a chat library:
| https://speedybot.js.org
|
| 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
| satvikpendem wrote:
| Do I have to use Vue in order to use VitePress? I'm looking for a
| React solution, perhaps Astro fits?
___________________________________________________________________
(page generated 2024-03-21 23:02 UTC)