vuepress使用指南

vuepress使用指南

使用步骤

1、安装NVM，下载node 16.13.0版本，更高或等低的版本可能会出现奇奇怪怪的bug

nvm安装教程：
Windows设备：在 github 下载安装nvm-windows.exe
安装完成后，在命令行输入nvm -v可以看到nvm的版本，如果看不到，可能是环境变量没有配置好。
输入nvm list available既可以查询到所有可用的node版本。
 linco  nvm list available
| CURRENT | LTS | OLD STABLE | OLD UNSTABLE |
|--------------|--------------|--------------|--------------|
| 19.7.0 | 18.14.2 | 0.12.18 | 0.11.16 |
| 19.6.1 | 18.14.1 | 0.12.17 | 0.11.15 |
| 19.6.0 | 18.14.0 | 0.12.16 | 0.11.14 |
| 19.5.0 | 18.13.0 | 0.12.15 | 0.11.13 |
| 19.4.0 | 18.12.1 | 0.12.14 | 0.11.12 |
| 19.3.0 | 18.12.0 | 0.12.13 | 0.11.11 |
| 19.2.0 | 16.19.1 | 0.12.12 | 0.11.10 |
| 19.1.0 | 16.19.0 | 0.12.11 | 0.11.9 |
| 19.0.1 | 16.18.1 | 0.12.10 | 0.11.8 |
| 19.0.0 | 16.18.0 | 0.12.9 | 0.11.7 |
| 18.11.0 | 16.17.1 | 0.12.8 | 0.11.6 |
| 18.10.0 | 16.17.0 | 0.12.7 | 0.11.5 |
| 18.9.1 | 16.16.0 | 0.12.6 | 0.11.4 |
| 18.9.0 | 16.15.1 | 0.12.5 | 0.11.3 |
| 18.8.0 | 16.15.0 | 0.12.4 | 0.11.2 |
| 18.7.0 | 16.14.2 | 0.12.3 | 0.11.1 |
| 18.6.0 | 16.14.1 | 0.12.2 | 0.11.0 |
| 18.5.0 | 16.14.0 | 0.12.1 | 0.9.12 |
| 18.4.0 | 16.13.2 | 0.12.0 | 0.9.11 |
| 18.3.0 | 16.13.1 | 0.10.48 | 0.9.10 |
输入nvm install <16.18.0>可以安装对应的node版本
nvm list可以查看已经安装完毕的node
nvm use <16.18.0>使用对应版本的node

2、安装好环境后，可以全部或部分安装vuepress

先创建一个文件夹，进入文件夹
使用yarn init -y 创建默认node包
使用yarn add vuepress -D本地保存安装vuepress

3、vuepress的配置

3.1 在package中添加以下指令

{

"scripts": {

"docs:dev": "vuepress dev docs",

"docs:build": "vuepress build docs"

}

}

这是输入yarn docs:dev便会启动一个服务器，可以看到由vuepress渲染后的界面了

3.2 VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：

.

├── docs

│ ├── .vuepress (可选的)

│ │ ├── components (可选的)

│ │ ├── theme (可选的)

│ │ │ └── Layout.vue

│ │ ├── public (可选的)

│ │ ├── styles (可选的)

│ │ │ ├── index.styl

│ │ │ └── palette.styl

│ │ ├── templates (可选的, 谨慎配置)

│ │ │ ├── dev.html

│ │ │ └── ssr.html

│ │ ├── config.js (可选的)

│ │ └── enhanceApp.js (可选的)

│ │

│ ├── README.md

│ ├── guide

│ │ └── README.md

│ └── config.md

│

└── package.json

注意

请留意目录名的大写。

• docs/.vuepress: 用于存放全局的配置、组件、静态资源等。

• docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。

• docs/.vuepress/theme: 用于存放本地主题。

• docs/.vuepress/styles: 用于存放样式相关的文件。

• docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。

• docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。

• docs/.vuepress/public: 静态资源目录,放例如网站icon之类的图像

• docs/.vuepress/templates: 存储 HTML 模板文件。

• docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。

• docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。

• docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。

• docs/.vuepress/enhanceApp.js: 客户端应用的增强。

注意

当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于 默认的模板文件 (opens new window)来修改，否则可能会导致构建出错。

同时阅读:

• 配置

• 主题

• 默认主题配置

默认的页面路由

此处我们把 docs 目录作为 targetDir （参考 命令行接口），下面所有的“文件的相对路径”都是相对于 docs 目录的。在项目根目录下的 package.json 中添加 scripts ：

{

"scripts": {

"dev": "vuepress dev docs",

"build": "vuepress build docs"

}

}

对于上述的目录结构，默认页面路由地址如下：

文件的相对路径	页面路由地址
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

4、配置文件

module.exports= {

title: 'Hello VuePress',

description: 'Just playing around',

base: '/', // 设置站点根路径

dest: './gh-pages',//设置打包到哪个文件夹

markdown: {

lineNumbers: true

},

plugins: [

['@vuepress/search', {

searchMaxSuggestions: 10

}],

// ['vuepress-plugin-autobar'],

// ['permalink-pinyin']//pinyin

],

themeConfig: {

// 添加导航栏

nav: [

{ text: '主页', link: '/' },

{ text: '指南', link: '/linux/' },

{ text: '生活', link: '/myday/' },

{ text: '英语', link: '/life/' },

{ text: '学习', link: '/study/' },

],

// 为以下路由添加左侧边栏

sidebar: 'auto',

sidebarDepth: 2,//左侧导航显示的层级

lastUpdated: 'Last Updated',

}

}

module.exports= {

title: 'Hello VuePress',

description: 'Just playing around',

base: '/', // 设置站点根路径

themeConfig: {

nav: [

{ text: 'Home', link: '/' },

{ text: 'Guide', link: '/hello/' },

{ text: 'External', link: '/js/' },

{ text: 'other', link: '/guide/' }

],

sidebar: {

'/hello/': ['', '一', 'b'],

'/js/': ['', 'abc-1'],

'/guide/': ['', '中文', 'a1']

},//sidebar设置要和路径一样，并且README.md后面是小写的

sidebarDepth: 2,//左侧导航显示的层级

lastUpdated: '最近更新',

}

}

5、上传GitHub pages

gh-pages分支是GitHub提供的特殊分支，在该分支里的文件会所为静态网页被渲染到username.github.io/文件夹名路径下/
使用node安装gh-pages包
使用命令gh-pages -d gh-pages自动创建gh-pages分支并上传