Skip to content
Get packs

Guide · Open source

How to use VuePress: install, run and what to use instead

Updated · written with AI from the project's own documentation and checked against our catalogue data

VuePress is an open-source tool that turns Markdown files into a static website, using Vue for the page templates. This guide explains what it is, how to get a local checkout running with Yarn, and whether it is the right choice today. By the end you will know the basic setup steps and which newer option the project's README recommends for new work.

VuePressvuejs/vuepress · ★ 22.7k · MIT

Quick start

  1. 1Decide if VuePress fits. Confirm you already have a VuePress v1 site or a Vue-based team. For new projects, review VitePress or VuePress v2+ first.
  2. 2Install Node.js and Yarn. The README lists Node.js and Yarn as prerequisites for the clone-and-build method.
  3. 3Get a local checkout. Clone the repository to your machine so you can build it from source.
  4. 4Install dependencies. Run yarn install in the checkout to install all dependencies.
  5. 5Start the dev server. Run yarn dev to serve VuePress' own documentation using VuePress.
  6. 6Run tests. Run yarn test to confirm your changes pass the test suite before contributing.

What VuePress does and who it is for

VuePress takes Markdown files and builds them into a static site, with Vue handling the page templates. The project describes itself as a minimalistic Vue-powered static site generator and aims it mainly at documentation sites and blogs.

It suits developers who already have a VuePress v1 documentation site to maintain, and teams already comfortable with Vue who want a simple Markdown-to-site tool.

Check the status before you start

The README states that VuePress v1 is now in maintenance mode. For new projects, the README points to two newer options: VitePress, which is supported by the Vue.js official team and built on Vue 3 and Vite, and VuePress v2+, which is community supported and can use Vite, Webpack or other bundlers.

The README does not indicate ongoing feature work on v1, so a new project should usually start with one of these newer tools.

  • New project: consider VitePress or VuePress v2+
  • Existing VuePress v1 site: keep it running with the steps below

Prerequisites: Node.js and Yarn

The install method described in the source is cloning the repository and building it locally. The listed prerequisites are Node.js and Yarn. The README does not give required version numbers, so check the project's own documentation for those.

  • Node.js
  • Yarn

Install dependencies and run the docs locally

From a local checkout of the repository, install all dependencies with Yarn. To serve VuePress' own documentation using VuePress itself, run the dev command. The README notes that you can also open the project in Gitpod, a free online IDE for GitHub, if you have no local checkout.

yarn install # install all dependencies yarn dev # serves VuePress' own docs with itself

Run the tests and contribute

To check that a change passes the test suite, run the test command. The README asks contributors to read the Contributing Guide and to contact the RFC process before making substantial changes. Beginner-friendly issues are labelled good first issue.

  • Read the Contributing Guide in .github/CONTRIBUTING.md
  • Check the RFCs for substantial changes
  • Browse issues labelled good first issue
yarn test # make sure your code change pass the test

Find examples and documentation

The full documentation lives at the official VuePress site. The README also links to Awesome VuePress, a curated list of VuePress-related projects, and to vuepress.tools, a showcase site.

  • Official docs: https://vuepress.vuejs.org/
  • Awesome VuePress: https://github.com/vuepressjs/awesome-vuepress

What people use it for

  • Maintaining an existing VuePress v1 documentation site
  • Building a simple Markdown-based documentation site for a Vue-literate team
  • Running a blog built from Markdown files with Vue templates
  • Exploring how VuePress' own documentation is built by serving it locally

Frequently asked questions

Is VuePress free to use?

VuePress is released under the MIT licence, as stated in the README and the repository's LICENSE file. The licence permits use, and the source is public on GitHub.

What do I need to install VuePress?

The source lists Node.js and Yarn as prerequisites. The install method described is cloning the repository and running yarn install from a local checkout.

Is VuePress still maintained?

The README says VuePress v1 is now in maintenance mode. It recommends VitePress, supported by the Vue team, or VuePress v2+, which is community supported, for new work.

What are good alternatives to VuePress?

The README points to VitePress and VuePress v2+. Other comparable projects mentioned in our analysis are Docusaurus and Hugo, which are different tools with their own setup.

Should I use VuePress or VitePress for a new site?

The README positions VitePress as the officially supported Vue-based option built on Vue 3 and Vite. For a new project, it is the safer starting point than v1.

Can I use VuePress without writing code?

VuePress requires working with Node-based tooling, so it is not a no-code website builder. Non-developers will likely find it difficult to set up and maintain.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

VuePress is a reasonable choice if you already run a VuePress v1 documentation site or your team knows Vue and wants a simple Markdown-to-site tool. If you are starting a new project, need a no-code builder, or want active feature development, pick VitePress or VuePress v2+ instead.

Install options & downloads