VuePress

Contributing Guide

Overview

This repository employs a monorepoopen in new window setup with pnpm workspacesopen in new window, and hosts a number of associated but separated packages.

In the packages directory:

  • bundler-vite: The VuePress bundler package with vite. Use vite to dev and build VuePress app that generated by @vuepress/core.
  • bundler-webpack: The VuePress bundler package with webpack. Use webpack to dev and build VuePress app that generated by @vuepress/core.
  • cli: The VuePress command line interface (CLI) package. It will resolve user config file, and create VuePress app with @vuepress/core, then execute corresponding command.
  • client: The VuePress client package. Provides the client entry, and exports types and composable utils that can be used in client side development.
  • core: The VuePress core. Provides pure Node API to generate VuePress app, including page handling, plugin system and data preparation.
  • markdown: The VuePress markdown package. Use markdown-it as the markdown parser and integrate some plugins to be used in VuePress.
  • shared: Utilities that shared between node side and client side.
  • utils: Utilities that should only be used in node side.

In the ecosystem directory:

  • plugin-${name}: Official plugins.
  • theme-default: The default theme.
  • vuepress: A wrapper of vuepress-vite.
  • vuepress-vite: A wrapper of @vuepress/cli + @vuepress/bundler-vite + @vuepress/theme-default. If users want to use default theme with vite, they can simply install this package.
  • vuepress-webpack: A wrapper of @vuepress/cli + @vuepress/bundler-webpack + @vuepress/theme-default. If users want to use default theme with webpack, they can simply install this package.

Development Setup

Pre-requirement:

Clone the repo, and install dependencies:

pnpm install

Build source code:

pnpm build

Start developing the documentation site:

pnpm docs:dev

Main tools that used in this project:

Scripts

pnpm build

The build script uses tsc and tsup to compile TypeScript source files to JavaScript dist files.

Also, it will copy necessary resources from source directory to dist directory, because some source files (e.g. .vue, .css files) would not be processed by tsc nor tsup, but should keep the same relative path in the dist directory.

You may need to run this script first after your clone this repository, because the dist files are ignored by .gitignore.

pnpm clean

The clean script runs clean script in all packages, cleaning all the dist files and caches. In other words, it will remove all the files that generated by build, copy scripts.

It's used before you want to re-build source files from a clean / initial state.

pnpm docs:*

pnpm docs:build, pnpm docs:dev, pnpm docs:clean

The docs: prefix indicates that these scripts are for documentation, i.e. the docs directory.

VuePress is using itself to build its own documentation site.

You need to run pnpm build to build VuePress source files first, then run these docs: scripts to develop and build our documentation.

pnpm docs:serve

Serve the documentation site locally.

You need to run pnpm docs:build first to generate the documentation dist files, and then run pnpm docs:serve to serve them.

pnpm lint

The lint script uses ESLint to check all source files.

pnpm test

The test script uses Vitest to run unit testings.

Documentation

VuePress documentation is powered by VuePress itself, which is built from the source code of this repository.

All the markdown source files are placed in docs directory. We are maintaining two translations:

  • English (en-US) in / path
  • Chinese (zh-CN) in /zh/ path

We have two different deployments: