VuePress搭建

VuePress搭建

初始化

  1. 创建并进入一个新目录

    1
    mkdir @docs && cd @docs

  2. 使用你喜欢的包管理器进行初始化

    1
    yarn init # npm init

  3. 将 VuePress 安装为本地依赖

    我们已经不再推荐全局安装 VuePress

    1
    yarn add -D vuepress # npm install -D vuepress

  4. 创建你的第一篇文档

    1
    mkdir docs && echo '# Hello VuePress' > docs/README.md

  5. 在 package.json 中添加一些 scripts(opens new window)

    这一步骤是可选的，但我们推荐你完成它。在下文中，我们会默认这些 scripts 已经被添加。

    1
    2
    3
    4
    5
    6
    {
      "scripts": {
        "docs:dev": "vuepress dev docs",
        "docs:build": "vuepress build docs"
      }
    }

  6. 在本地启动服务器

    1
    yarn docs:dev # npm run docs:dev

    VuePress 会在 http://localhost:8080 (opens new window)启动一个热重载的开发服务器。

目录对应规则

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.
├── 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: 静态资源目录。
  • 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: 客户端应用的增强。
文件的相对路径 页面路由地址
/README.md /
/guide/README.md /guide/
/config.md /config.html

首页

https://www.vuepress.cn/theme/default-theme-config.html#%E9%A6%96%E9%A1%B5

根目下的README.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

添加关于页面

根目录下。about->README.md

导航栏

https://www.vuepress.cn/theme/default-theme-config.html#%E5%AF%BC%E8%88%AA%E6%A0%8F

.vuepress/config.js

部署到gitee

pack.json

1
2
3
4
5
"scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "deploy": "bash deploy.sh"
  },

deploy.h （可以不用，这个作用是打包，和推送到远程分支）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@gitee.com:getp/docs.git master:gh-pages

cd -
TIP

image-20220916161648066

打包时发生错误，解决方案：

image-20220916202446069

image-20220916202413842

最后解决方案，把这个变量给删除了

image-20220916203753623

安装pwa插件

https://www.vuepress.cn/plugin/official/plugin-pwa.html#%E5%AE%89%E8%A3%85

安装

1
2
yarn add -D @vuepress/plugin-pwa
# OR npm install -D @vuepress/plugin-pwa

使用

1
2
3
module.exports = {
  plugins: ['@vuepress/pwa']
}

vssue评论

https://vssue.js.org/zh/guide/getting-started.html#%E9%80%89%E6%8B%A9%E4%BD%A0%E8%A6%81%E4%BD%BF%E7%94%A8%E7%9A%84%E4%BB%A3%E7%A0%81%E6%89%98%E7%AE%A1%E5%B9%B3%E5%8F%B0

创建一个新的第三方应用

image-20220916214221105

点击创建应用

image-20220916214449341

获取 Client ID 和 Secret

image-20220916214558758

安装

通过 NPM 安装 @vssue/vuepress-plugin-vssue 和你需要使用的 API 包 ：(我这里用的是gitee，所以安装gitee相关的包)

1
2
npm install @vssue/vuepress-plugin-vssue
npm i @vssue/api-gitee-v5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// .vuepress/config.js

module.exports = {
  plugins: {
    '@vssue/vuepress-plugin-vssue': {
      // 设置 `platform` 而不是 `api`
      platform: 'gitee',

      // 其他的 Vssue 配置
      owner: 'getp',
      repo: 'docs',
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
      autoCreateIssue: true
    },
  },
};

image-20220916215712962

图片有错误，owner应该应gitee账户

使用 Vssue 组件

1
<Vssue :title="$title" />

image-20220916220007486

全局引入

image-20220916222025593

image-20220916222806002

image-20220916223133063

back-to-top

安装

1
2
yarn add -D @vuepress/plugin-back-to-top
# OR npm install -D @vuepress/plugin-back-to-top

使用

1
2
3
module.exports = {
  plugins: ['@vuepress/back-to-top']
}

image-20220916224647940

VuePress
#VuePress #知识库
VuePress搭建
http://example.com/2022/08/28/06.扩展/02.博客/03.VuePress搭建/
作者
Deng ErPu
发布于
2022年8月28日
许可协议