vuepress快速上手

这是我参与「第五届青训营」伴学笔记创作活动的第 12 天

生成简单的文档网站

mkdir 文件名
cd 文件名
npm init，示例如下：

// package.json
{
  "name": "chrome_plugins_doc",
  "version": "1.0.0",
  "description": "This is the instruction document of chrome plugins",
  "main": "index.js",
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
  "keywords": [
    "chrome",
    "plugins",
    "instruction"
  ],
  "author": "Karl_fang",
  "license": "ISC",
  "devDependencies": {
    "vuepress": "^1.9.7"
  }
}

npm install -g vuepress，mac用sudo npm install -g vuepress

自己的mac电脑使用(sudo) npm install -g vuepress一直报错就报错了，报错信息如下：

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/.temp'
     at Object.mkdirSync (node:fs:1334:3)
     at Object.mkdirsSync (/usr/local/lib/node_modules/vuepress/node_modules/fs-extra/lib/mkdirs/mkdirs-sync.js:31:9)
     at createTemp (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/node/createTemp.js:31:8)
     at App.resolveConfigAndInitialize (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/node/App.js:79:37)
     at processTicksAndRejections (node:internal/process/task_queues:96:5)
     at async App.process (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/node/App.js:103:5)
     at async dev (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/index.js:17:3)

然后用npm install -D vuepress就可以了，也不知道为啥

创建docs文件夹
在docs文件下创建.vuepress文件夹，并在此文件夹里创建config.js文件

目录结构如下所示：
vuepress-demo
├── package.json
├── package-lock.json
├── node_modules
└── docs
    ├── .vuepress
    │   └── config.js # 配置
    ├── README.md # 首页文件

配置config.js文件，如下：

module.exports = {
  title: 'Chrome插件文档说明',
  description: '我的的文档',
}

执行npm run dev后就能得到一个简单的网页，成功后终端会显示如下：

success [09:57:25] Build 57053e finished in 89 ms! (http://localhost:8080/)

如果出现404页面那么可能是config.js这个配置文件有问题

推荐目录结构

.
├── 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 项目初始化时，根目录下自动生成的配置文件,定义了项目的基本配置信息及需要依赖的各个模块、指定运行脚本命令的npm命令行缩写等

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: 静态资源目录。
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: 客户端应用的增强。

配置网页的图标

module.exports = {
  ...
  head: [
    [
      'link', { rel: 'icon', href: '/images/common/logo.png' }
    ]
  ],
  ...
}

::: tip 图片放在public文件夹下，这里的/images/common/logo.png，实际路径为/public/images/common/logo.png :::

侧边栏标题添加图标

module.exports = {
  ...
  themeConfig: {
    ...
    logo: '/images/common/logo.png', 
    ...
  }
  ...
}

::: tip 图片存放的位置同上面说的，要放在public文件夹下 :::

更好的手册

其实大部分都可以在vuepress官方文档中找到，本文档只不过把在本项目中使用的相应内容筛选出来，但是也加了文档中所没有写出的部署遇到的问题。

vuepress快速上手（一） ｜ 青训营笔记