Vuepress

Open-source static site generation, honestly reviewed. No marketing fluff — just what you get when you build with it.

TL;DR

• What it is: MIT-licensed static site generator built by the Vue.js team — Markdown files in, pre-rendered HTML out, with Vue components available anywhere in your content [5].
• Who it’s for: Developers who want to write documentation or a personal blog in Markdown and ship it as a fast static site. Not designed for non-technical users without coding knowledge [2].
• Cost savings: VuePress is free software. Self-hosting on GitHub Pages or a $5/mo VPS replaces SaaS doc tools like Archbee ($50+/mo) or GitBook (gated after the free tier). The trade-off is setup time and developer dependency.
• Key strength: Tight Vue.js integration — you can use Vue components directly inside Markdown files, making it uniquely powerful for Vue project documentation [5][1].
• Key weakness: VuePress v1 is officially in maintenance mode. The Vue.js team recommends VitePress as the replacement. New projects should not start on VuePress v1 [README].

---

What is VuePress

VuePress is a Markdown-centered static site generator created by Evan You, the author of Vue.js. The idea was simple: Vue.js needed documentation, Hexo wasn’t flexible enough, and GitBook was moving toward commercialization. So the Vue team built their own tool and open-sourced it under MIT [5].

The core mechanic is a two-phase rendering pipeline. During development, your site runs as a normal Vue SPA — hot reloading, familiar dev tools, component-driven. At build time, VuePress does server-side rendering, pre-generating HTML for each route, then hydrates as an SPA after load [5]. The result is pages that are indexable by search engines and fast to load on first visit.

What made VuePress interesting at launch in 2018 — earning it #1 Product of the Day on Product Hunt with 526 upvotes — was the Markdown extension system [3]. You get code highlighting, line-level highlighting, internal link resolution, and the ability to embed Vue components inline in .md files. For a developer writing documentation with code samples, these aren’t nice-to-haves — they’re the entire point.

The project sits at 22,802 GitHub stars. But the most important thing in the README is the first sentence: “VuePress v1 is now in maintenance mode.” The Vue.js team has moved their documentation to VitePress, a leaner successor built on Vue 3 and Vite. VuePress v2 exists as a community-supported project. If you start a new project today and choose VuePress v1, you are choosing a dead end [README].

---

Why people choose it

The reviews cluster around three distinct use cases, each with a different profile.

Switching from Nuxt for static content. Samantha Ming’s account [1] is representative of the Vue developer who was using Nuxt for SEO (server-side rendering) but found it over-engineered for what was essentially a content site. Nuxt requires configuring Markdown yourself. VuePress ships with Markdown processing, code highlighting, and a built-in search plugin out of the box. Her conclusion: “I barely had to do any work to get these cool features to work.” The switch removed friction. This use case makes sense — if you’re already in the Vue world and want a content site without the Nuxt overhead, VuePress delivers.

Replacing GitBook for technical documentation. Italo Baeza Cabrera moved his package documentation from GitBook to VuePress and called it a net positive despite some pain [2]. The driving complaints about GitBook: sluggish development reload, limited theme control on free accounts, and feeling like the team was pushing toward a commercial product rather than open-source. VuePress gave back control — local markdown files, Git-tracked content, deployable anywhere. The switch took less than an hour, mostly regex find-and-replace. This pattern appears across Reddit and developer blogs: people choose VuePress when GitBook’s free tier becomes limiting or its commercial trajectory becomes worrying.

Hosting a personal blog for free. Marvin CAI’s walkthrough [4] covers the GitHub Pages + VuePress combination: write posts in Markdown, build to static HTML, push to a public GitHub repo, serve for free. Total hosting cost: $0. For a developer writing occasional technical posts, this is the cheapest reasonable option with a proper SEO-friendly output (unlike Docsify/Docute, which are runtime-rendered and invisible to crawlers) [5].

What these three use cases share: the user is a developer comfortable with YAML config, npm, and a terminal. No review found among the sources describes a non-technical user successfully setting up VuePress without developer assistance. Italo notes explicitly: “People without coding knowledge or that cannot feel at ease puking code instead of a WYSIWYG editor, won’t be using VuePress at all” [2].

---

Features

Core generation:

• Markdown-centered project structure — each .md file becomes a route [5]
• Built-in Markdown extensions: code highlighting, line-level highlighting, custom containers, internal link resolution [1]
• Vue components usable directly inside .md files [5][1]
• Pre-rendered HTML on build + SPA hydration after page load (SEO-friendly) [5]
• Default theme with navigation, sidebar, and search included [1]
• Plugin system for extending behavior [website]
• Community themes available [website]

Built-in search: Samantha Ming calls this out specifically [1] as a feature that seems small but changes everything for a documentation site. The default search is header-based — no external service, no configuration, no API key.

Bundler support: VitePress (the successor) forced migration to Vite. VuePress v2 supports Vite and Webpack. VuePress v1 uses Webpack. For v1, this means slower builds on large sites compared to Vite-based alternatives [website].

What’s not included:

• No WYSIWYG editor — everything is plain files [2]
• No CMS or admin interface — not designed for non-developers
• No built-in deployment tooling — you write a deploy script yourself [4]
• Sidebar navigation is fully manual if your structure isn’t linear [2]

The sidebar point deserves more attention. Italo flags it directly [2]: “Vuepress likes single-level sections, so trying to bury a section inside another is not very good… you are bound to create your own sidebar.” If you have more than a handful of docs pages with a non-trivial structure, expect to spend time wiring sidebar navigation by hand in the config file.

---

Pricing: SaaS vs self-hosted math

VuePress: $0 for the software. You pay for hosting.

• GitHub Pages: free for public repos
• Netlify/Vercel free tier: free for personal projects with reasonable limits
• $5/mo VPS (Hetzner, DigitalOcean): if you need a custom server for other things anyway

Comparable SaaS alternatives:

• GitBook: Free plan limited to 1 public space; Team plan at ~$6.7/user/month (minimum applies); losing content when a project outgrows the free tier is a real scenario [2][5]
• Archbee: Team pricing starts around $50–80/mo; scales with users
• Notion (as a doc tool): Free for personal; Team starts at $10/user/month — not designed as a standalone doc site

The honest math: For a solo developer publishing open-source documentation or a personal site, VuePress on GitHub Pages costs nothing beyond time. For a small team sharing a doc site, you’d deploy once to Netlify and the bill stays $0. The savings versus Archbee or Gitbook’s paid tiers are real — but only if you have a developer on staff to set it up and maintain it.

There’s no per-seat pricing, no usage limits, no vendor who can change pricing on you. MIT license means you can fork it, modify it, and use it commercially without asking anyone [README].

---

Deployment reality check

The deployment path depends on your target.

GitHub Pages (most common for open-source projects): Write a shell script that runs yarn build, copies the output to a dist/ folder, and force-pushes to a gh-pages branch. Marvin CAI’s example [4] is about 15 lines of shell. This is not beginner-friendly — you need to understand git push -f, know what a deploy branch is, and not be terrified when the script rewrites history.

Netlify or Vercel: Connect your repo, set the build command to vuepress build docs and the output directory to docs/.vuepress/dist. Both platforms autodetect this. Arguably easier than GitHub Pages. Free tier covers most personal/documentation use cases.

Self-hosted VPS: Nginx or Caddy serving static files. You build locally or in CI, upload the output, point your DNS at the server. Standard static site hosting — nothing VuePress-specific here.

What can go wrong:

• The base config option must match your GitHub Pages subdirectory or assets break silently [4]
• v1’s Webpack-based build is slow on large sites — 100+ pages starts to feel it
• Plugin compatibility between v1 and v2 is not guaranteed; tutorials are often version-ambiguous, causing confusion
• The sidebar doesn’t auto-generate from your file structure — manual config or a plugin [2]

Realistic time for a developer setting up their first VuePress project: 1–2 hours to a working site on GitHub Pages. For a non-developer: not a realistic solo task.

---

Pros and cons

Pros

• Genuinely MIT-licensed. Fork it, embed it, use it commercially. No fair-code restrictions, no vendor lock [README].
• Vue everywhere. Components work inside Markdown. If you’re already writing Vue, this is the most natural documentation tool available [1][5].
• Zero hosting cost path. GitHub Pages + VuePress = a real, SEO-indexed, fast documentation site for $0/mo [4].
• Built-in search and Markdown extensions. Both work without configuration or external services [1].
• Pre-rendered HTML. Unlike Docsify/Docute (runtime rendering), VuePress output is fully crawlable — content exists in the HTML, not assembled by JavaScript [5].
• Backed by the Vue.js team’s own use. This was the actual tool used to build Vue.js documentation. It solves real problems [5].
• Plugin system. The community has built plugins for blogging, Google Analytics, Algolia search, PWA, and more [website][4].
• 46 Product Hunt reviews at 5/5 average — unusually high quality signal from its 2018 launch [3].

Cons

• VuePress v1 is in maintenance mode. This is the single most important fact about the project right now. No new features. Bug fixes only. The Vue.js team has moved on. Starting a new project on v1 today means you’re building on a foundation the maintainers have already left [README].
• Not for non-technical users. No GUI, no visual editor, no drag-and-drop anything. Writing config in YAML/JavaScript is a prerequisite [2]. The target user is a developer.
• Manual sidebar configuration. If your docs aren’t a single linear flow, expect non-trivial sidebar wiring [2].
• Webpack-based builds are slow. v1’s Webpack pipeline is significantly slower than VitePress’s Vite-based equivalent on large content sets.
• Ecosystem fragmentation. There are now three projects: v1 (maintenance), v2 (community), and VitePress (official). Documentation and tutorials online often don’t specify which version they target. This creates confusion and wasted debugging time.
• WYSIWYG-free. Non-developers can’t contribute content without learning Markdown and Git [2].
• No content management. No draft workflow, no web-based editing, no collaborator experience beyond what Git provides natively.

---

Who should use this / who shouldn’t

Use VuePress if:

• You’re maintaining an existing VuePress v1 site and don’t want the migration cost right now.
• You’re a Vue developer building documentation for an open-source project and want Vue components in your docs.
• You want $0 hosting and have 1–2 hours to configure deployment.
• You value MIT licensing and no vendor dependency.
• You’re comfortable in a terminal and with Markdown.

Skip it (migrate to VitePress instead) if:

• You’re starting a new documentation site today. VitePress is faster, officially maintained, and where new investment is going [README][5].
• You’re already on VuePress v1 and your site is growing — now is the time to migrate before technical debt compounds.

Skip it (use VuePress v2 instead) if:

• You need Vue 3 compatibility or a more active plugin ecosystem than v1 offers.
• VitePress’s opinionated defaults are too restrictive (it doesn’t support plugins the same way v1 does) [5].

Skip it entirely (pick something else) if:

• You’re a non-technical founder who wants to write content without touching a terminal. Look at Notion-based sites, Outline, or BookStack.
• Your team needs a collaborative editing experience — VuePress has none.
• You’re comparing this to Archbee or Confluence for team knowledge management. VuePress is a documentation publishing tool, not a wiki.

---

Alternatives worth considering

• VitePress — the official successor, maintained by the Vue.js core team. Built on Vue 3 and Vite. Faster builds, same MIT license, better long-term trajectory. If you can use VitePress, use VitePress [README][5].
• Docusaurus — React equivalent maintained by Meta. Stronger plugin ecosystem, better i18n, more community documentation. Choose it if you’re not in the Vue ecosystem [5].
• Hexo — the static site generator VuePress was partially created to replace. Still active, large plugin library, but theming is string-based and not Vue-native [5].
• GitBook — the hosted doc tool most developers have tried. Free tier works for simple cases; commercial pivot frustrates open-source maintainers [2][5].
• Docsify / Docute — Vue-powered, zero-build, fully runtime. Simpler to set up than VuePress but not SEO-friendly because content is rendered client-side [5].
• Outline — self-hosted team wiki. Better fit for non-technical teams who need to collaborate and edit content, not just publish it.

---

Bottom line

VuePress solved a real problem in 2018: Vue.js needed documentation tooling, and the existing options (GitBook, Hexo, Docsify) each had the wrong trade-off. The result was a tool that gave Vue developers Markdown-first authoring with Vue components embedded, SEO-ready output, and $0 hosting via GitHub Pages. For that specific use case, it still works.

The problem is that “still works” is not the same as “the right choice.” VuePress v1 is in maintenance mode by its own authors’ declaration. VitePress exists, is faster, is actively maintained by the same team, and does nearly everything v1 does with less weight. The honest recommendation for anyone starting fresh is: use VitePress, not VuePress. If you’re inheriting a VuePress v1 codebase, plan your migration now while it’s elective rather than emergency work.

If the migration or initial setup is the blocker, that’s the kind of one-time technical task that upready.dev handles for clients — deploy it, hand it over, done.

---

Sources

1. Samantha Ming — “Building my New Site with VuePress”. https://www.samanthaming.com/blog/building-my-new-site-with-vuepress/
2. Italo Baeza Cabrera, Medium — “How Vuepress helped my documentation” (May 11, 2020). https://darkghosthunter.medium.com/how-vuepress-helped-my-documentation-4c66f1affb4e
3. hunted.space — “VuePress — A static site generator by Vue.js | Product Hunt Launch Dashboard”. https://www.hunted.space/dashboard/vue-js-2/launches/vuepress
4. Marvin CAI, Medium — “Host Blog with Vuepress and Github pages” (Mar 28, 2020). https://medium.com/@marvin5064/host-blog-with-vuepress-and-github-pages-7000581de789
5. VuePress v2 Official Docs — “Introduction | VuePress”. https://vuejs.press/guide/introduction.html

Primary sources:

• GitHub repository and README: https://github.com/vuejs/vuepress (22,802 stars, MIT license — v1 maintenance mode)
• Official website: https://vuepress.vuejs.org
• VitePress (official successor): https://vitepress.vuejs.org