What is vitepress?
VitePress is a static site generator powered by Vite and Vue. It is designed to be simple and performant, making it ideal for documentation sites and blogs.
What are vitepress's main functionalities?
Creating a Basic Site
This feature allows you to set up a basic VitePress site. The provided code snippet shows how to add scripts to your `package.json` to start the development server, build the site, and serve the built site.
```json
{
"scripts": {
"dev": "vitepress dev",
"build": "vitepress build",
"serve": "vitepress serve"
}
}
```
Markdown Support
VitePress supports Markdown out of the box, allowing you to write your content in a simple and readable format. The code snippet demonstrates a basic Markdown file with headings and paragraphs.
```markdown
# Hello VitePress
This is a paragraph in VitePress.
## Subheading
More content here.
```
Customizing the Theme
You can customize the theme of your VitePress site by extending the default theme. The code snippet shows how to replace the default layout with a custom Vue component.
```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
export default {
...DefaultTheme,
Layout: MyLayout
}
```
Other packages similar to vitepress
docusaurus
Docusaurus is a static site generator focused on documentation websites. It offers a rich set of features like versioning, search, and theming. Compared to VitePress, Docusaurus is more feature-rich but also more complex to set up.
vuepress
VuePress is another static site generator powered by Vue. It is similar to VitePress but uses Webpack instead of Vite. VuePress is more mature and has a larger community, but VitePress offers faster build times due to Vite.
gatsby
Gatsby is a React-based static site generator. It is highly flexible and can be used for a wide range of websites, not just documentation. Gatsby has a large ecosystem of plugins but can be more complex to configure compared to VitePress.
(WIP) VitePress 📝💨
VuePress' little brother, built on top of vite
Note this is early WIP! Currently the focus is on making Vite stable and feature complete first. It is not recommended to use this for anything serious yet.
npm install -D vitepress
echo '# Hello VitePress' > index.md
npx vitepress
npx vitepress build
Customization
Configuration can be done via .vitepress/config.js
(see src/node/config.ts
)
You can develop your custom theme by adding the following files:
.vitepress/theme/Layout.vue
<template>
<h1>Custom Layout!</h1>
<Content/><!-- make sure to include markdown outlet -->
</template>
.vitepress/theme/index.js
import Layout from './Layout.vue'
export default {
Layout,
NotFound: () => 'custom 404',
enhanceApp({ app, router, siteData }) {
}
}
Unlike VuePress, the only file with a fixed location in a theme is index.js
- everything else is imported and exported there like in a normal application.
Motivation
I love VuePress, but being built on top of webpack, the time it takes to spin up the dev server for a simple doc site with a few pages is just becoming unbearable. Even HMR updates can take up to seconds to reflect in the browser!
As a reference, the Composition API RFC repo is just two pages, but it takes 4 seconds to spin up the server, and almost 2 seconds for any edit to reflect in the browser.
Fundamentally, this is because VuePress is a webpack app under the hood. Even with just two pages, it's a full on webpack project (including all the theme source files) being compiled. It gets even worse when the project has many pages - every page must first be fully compiled before the server can even display anything!
Incidentally, vite solves these problems really well: nearly instant server start, on-demand compilation that only compiles the page being served, and lightning fast HMR. Plus, there are a few additional design issues I have noted in VuePress over time, but never had the time to fix due to the amount of refactoring it would require.
Now, with vite
and Vue 3, it is time to rethink what a "Vue-powered static site generator" can really be.
Improvements over VuePress
Other Differences
-
More opinionated and less configurable: VitePress aims to scale back the complexity in the current VuePress and restart from its minimalist roots.
-
Future oriented: VitePress only targets browsers that support native ES module imports. It encourages the use of native JavaScript without transpilation, and CSS variables for theming.
Will this become the next VuePress in the future?
Maybe! It's currently under a different name so that we don't over commit to the compatibility with the current VuePress ecosystem (mostly themes and plugins). We'll see how close we can get without compromising the design goals listed above. But the overall idea is that VitePress will have a drastically more minimal theming API (preferring JavaScript APIs instead of file layout conventions) and likely no plugins (all customization is done in themes).
Want to contribute?
Check out our contributing guide for more information!
License
MIT