VuePress 是一个静态网站生成器,它基于 Vue.js 和 Markdown 来创建文档网站。VuePress 能够快速创建高质量的文档网站,具有易用性和可定制性。VuePress 采用了现代化的技术栈,包括 webpack、Vue.js、markdown-it 等等,这些技术使得 VuePress 具备自定义主题和插件、支持代码语法高亮、提供搜索和分页等功能。VuePress 还能够对网站进行优化,例如 gzip 压缩、预渲染和缓存等操作,从而提升网站的性能和访问速度。VuePress 的使用非常简单,只需要编写 Markdown 文件即可,同时还可以通过配置文件进行个性化设置。
VuePress 是一种基于 Vue.js 的静态网站生成器,它专注于文档编写和网站构建。与其他静态网站生成器相比,VuePress 有以下异同:
使用 Vue.js:VuePress 使用 Vue.js 框架来构建页面,这使得在开发自定义主题或插件时非常方便,因为大多数 Vue.js 开发人员都会熟悉它。
集成 Markdown:VuePress 支持使用 Markdown 编写文档,并且内置了一个 Markdown 解析器,可以轻松地将 Markdown 文档转换为 HTML 页面。
自定义主题和插件:VuePress 允许用户轻松地创建自定义主题和插件,以满足不同的需求。
独立部署:VuePress 生成的静态文件可以独立部署到任何静态文件托管服务上,例如 GitHub Pages、Netlify 等。
内置搜索:VuePress 内置搜索功能,为用户提供快速查找文档的能力。
静态资源管理:VuePress 可以很好地处理静态资源,例如图片、CSS 和 JavaScript 文件等。
node -v
npm -v
npm install -g vuepress
mkdir my-docs && cd my-docs
vuepress create docs
cd docs
npm run dev
http://localhost:8080/
,您应该能够看到一个初始的VuePress页面。现在您已经成功地安装并运行了VuePress。接下来,您可以根据需要编辑和自定义VuePress主题、页面和文档。
首先需要安装VuePress。可以使用npm或yarn进行安装。例如,使用npm安装:
npm install -g vuepress
在命令行中使用以下命令创建一个新的VuePress项目:
vuepress create my-site
这将在当前目录下创建一个名为my-site
的新目录,并包含VuePress的默认文件和目录结构。
VuePress提供了默认主题,但也支持自定义主题。在my-site
目录中,可以创建一个名为.vuepress
的新目录,并在其中创建一个名为theme
的新目录。在theme
目录中,创建一个名为Layout.vue
的文件,用于覆盖默认主题的布局。
接下来,可以从VuePress默认主题的GitHub仓库中下载CSS和其他必要文件,并将它们放置在my-site/.vuepress/theme
目录中。然后,将my-site/.vuepress/config.js
文件中的theme
选项设置为自定义主题目录的路径:
module.exports = {
theme: './theme/'
}
配置文件config.js
中包含VuePress的所有配置选项。可以根据需要修改这些选项。例如,可以更改网站的标题和描述:
module.exports = {
title: 'My Site',
description: 'This is my site'
}
还可以添加自定义页面、插件等。修改完配置文件后,需要重新启动VuePress以使更改生效。
config.js的详细解析:
title
: 网站的名称,将会显示在浏览器的标签栏中。
description
: 网站的描述信息,会在生成的 HTML 页面中添加一个 meta 标签。
base
: 站点的基础路径,如 /blog/
。如果你的站点部署在非根目录下,则需要设置该选项。
head
: 该选项接收一个数组,里面可以添加一些额外的 标签,如
、
等。
themeConfig
: 主题配置,包括导航栏、侧边栏、页面滚动等选项。
plugins
: 插件配置,可以通过此选项引入一些插件来扩展 VuePress 的功能。
markdown
: Markdown 配置,可以定义 Markdown 渲染时的默认配置,如代码块的语言、是否启用行号等。
locales
: 多语言支持,可以为你的网站提供多语言翻译功能。
extraWatchFiles
: 监听文件变化,可以自动刷新页面。
demo:
module.exports = {
title: 'My VuePress Site', // 网站标题
description: 'A brief description of my site', // 网站描述
themeConfig: {
nav: [
{ text: 'Home', link: '/' }, // 导航栏链接
{ text: 'Guide', link: '/guide/' }, // 导航栏链接
{ text: 'External', link: 'https://google.com' } // 外部链接
],
sidebar: {
'/': [
'', // 首页
'about', // 关于页面
'contact' // 联系页面
],
'/guide/': [
'', // 指南首页
'getting-started', // 入门指南
'advanced' // 高级使用方法
]
}
}
}
这个 demo 中,title
和 description
字段分别设置了网站的标题和描述。themeConfig
对象中,nav
属性用于配置网站导航栏,其中包含一个内部链接和一个外部链接。sidebar
属性用于配置侧边栏,其中 /
表示配置网站根目录下的侧边栏,/guide/
表示配置 /guide
目录下的侧边栏。每个侧边栏都是一个数组,包含了当前目录下的所有 Markdown 文件。
通过脚本配置,本地配置直接运行将文档发布到github
package.json里配置
{
"name": "vuepressdemo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs",
"test": "echo \"Error: no test specified\" && exit 1",
"deploy": "bash deploy.sh"
},
"keywords": [],
"author": "fcli",
"license": "ISC",
"devDependencies": {
}
}
添加deploy.sh
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
# echo 'www.fcli.xyz' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果你想要部署到 https://USERNAME.github.io
git push -f https://github.com/bogart001/bogart001.github.io.git master
# 如果发布到 https://USERNAME.github.io/ REPO=github上的项目
# git push -f [email protected]:USERNAME/.git master:gh-pages
cd -