VuePress
Vue.js-based SSG specialized for documentation. Over 22k GitHub stars, optimized for technical documentation sites.
トレンド・動向
Established as documentation site standard in Vue.js community. Further acceleration achieved with VitePress successor.
## Static Site Generator
VuePress
## Overview
VuePress is a documentation-focused static site generator built with Vue.js. With over 22k GitHub stars, it is optimized for building technical documentation sites. Established as the documentation site standard in the Vue.js community, VuePress has achieved further acceleration and feature enhancements with the introduction of VitePress.
## Details
VuePress was developed in 2018 by Evan You, the creator of Vue.js. It generates beautiful SPAs from Markdown files and provides rich functionality needed for technical documentation creation. Each page is pre-rendered as server-side rendered static HTML and operates as an SPA after page load.
Since 2023, the Vue.js team has focused on developing VitePress as the successor to VuePress, with the stable release of VitePress 1.0. VitePress, based on Vue 3 and Vite, provides faster development experience and production performance. Existing VuePress projects are recommended to gradually migrate to VitePress.
Key features of VuePress include the ability to use Vue.js components directly within Markdown, a rich plugin ecosystem, search functionality, multi-language support, and PWA support. Configuration files are centrally managed in `.vuepress/config.js`, providing an intuitive structure for developers.
## Pros and Cons
### Pros
- **Complete Vue.js Integration**: Natural use of Vue.js components within Markdown
- **Documentation-Focused Design**: All features needed for technical documentation are included
- **Rich Plugin Ecosystem**: Comprehensive official plugins for search, PWA, Google Analytics, etc.
- **Hot Reload Support**: Smooth writing experience with automatic reloading during development
- **SEO Optimization**: Generates SEO-excellent sites through pre-rendering
- **Simple Configuration**: Build professional sites with minimal configuration
### Cons
- **Development Halt and VitePress Migration**: New development is consolidated into VitePress
- **Build Time for Large Sites**: Tends to have longer build times with many pages
- **Vue.js Dependency**: Requires Vue.js knowledge, incurring learning costs
- **Plugin Configuration Complexity**: Advanced customization requires detailed configuration knowledge
- **Bundle Size**: Large JavaScript file size during initial load due to SPA nature
## Reference Pages
- [VuePress Official Site](https://vuepress.vuejs.org/)
- [VuePress GitHub Repository](https://github.com/vuejs/vuepress)
- [Migration Guide to VitePress](https://vitepress.dev/guide/migration-from-vuepress)
- [VuePress Plugin List](https://vuepress.vuejs.org/plugin/)
- [VuePress Theme List](https://vuepress.vuejs.org/theme/)
## Code Examples
### Project Initialization and Installation
```bash
# Initialize VuePress project
mkdir my-docs
cd my-docs
npm init -y
# Install VuePress as dev dependency
npm install -D vuepress
# Add scripts to package.json
```
```json
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
```
### Basic Site Configuration
```javascript
// .vuepress/config.js
module.exports = {
title: 'My Documentation',
description: 'Documentation for Vue.js project',
// Theme configuration
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'API', link: '/api/' }
],
sidebar: {
'/guide/': [
'',
'getting-started',
'configuration'
]
},
// GitHub repository settings
repo: 'username/repo',
editLinks: true,
editLinkText: 'Edit this page'
},
// Plugin configuration
plugins: [
'@vuepress/back-to-top',
'@vuepress/medium-zoom',
['@vuepress/search', {
searchMaxSuggestions: 10
}]
]
}
```
### Markdown Extensions
```markdown
<!-- Custom containers -->
::: tip Tip
This is a helpful tip.
:::
::: warning Warning
This is an important warning.
:::
::: danger Danger
This is a warning about dangerous operations.
:::
<!-- Code block highlighting -->
```javascript{1,3-5}
export default {
data() {
return {
message: 'Hello VuePress!'
}
}
}
```
<!-- Using Vue components -->
<Badge text="v1.0.0" type="tip"/>
<Badge text="Deprecated" type="warn"/>
```
### Custom Theme Creation
```javascript
// .vuepress/theme/index.js
module.exports = {
extend: '@vuepress/theme-default',
// Layout override
Layout: require.resolve('./layouts/Layout.vue'),
// Global components
plugins: [
[
'@vuepress/register-components',
{
componentsDir: './components'
}
]
]
}
```
### Plugin Development and Customization
```javascript
// .vuepress/config.js
module.exports = {
plugins: [
// Custom plugin
[
(options, ctx) => ({
name: 'my-plugin',
enhanceAppFiles: resolve(__dirname, 'enhanceApp.js'),
globalUIComponents: ['MyGlobalComponent']
})
],
// PWA configuration
[
'@vuepress/pwa',
{
serviceWorker: true,
updatePopup: {
message: "New content is available.",
buttonText: "Refresh"
}
}
]
]
}
```
### Build and Deploy
```bash
# Start development server
npm run docs:dev
# Production build
npm run docs:build
# GitHub Pages deployment script
#!/usr/bin/env sh
set -e
npm run docs:build
cd docs/.vuepress/dist
git init
git add -A
git commit -m 'deploy'
git push -f [email protected]:username/repo.git master:gh-pages
```