BruceBlog

# VuePress 从 0 开始搭建个人网站

BruceBlog 从无到有的全过程

VuePress 官网传送门 (opens new window)

# 体验 VuePress

  1. 创建并进入新目录
mkdir bruceblog
cd bruceblog
1
2
  1. 初始化 npm
npm init
1
  1. 安装 VuePress
npm install -D vuepress
1
  1. 在根目录下创建 docs 文件夹
mkdir docs
1

  1. 在 docs 目录下新建 README.md 文档，并写入一些内容

  2. 在 package.json 文件添加 scripts

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}
1
2
3
4
5
6
  1. 启动本地服务器
npm run dev
1
  1. 浏览器打开服务器所给地址

# 目录结构

以下为 BruceBlog 部分目录结构，比较重要的是 .vuepress 目录的结构。官方目录结构请移步 → (opens new window)

.
├── docs
│   ├── .vuepress
│   │   ├── public
|   |   |   └── img
│   │   ├── styles
│   │   │   └── index.styl
│   │   ├── nav.js
│   │   ├── sidebar.js
│   │   └── config.js
|   |
│   ├── notes
│   │   ├── vue
|   │   │   ├── images
|   │   │   ├── sidebar.js
|   │   │   ├── vuex.md
|   │   │   ├── vue3.md
|   │   │   └── ...
|   |   |
|   |   ├── react
|   │   │   ├── images
|   │   │   ├── sidebar.js
|   │   │   ├── react-cli.md
|   │   │   └── ...
|   │   │
|   │   ├── ...
|   |   |
│   │   └── README.md
|   |
│   └── README.md
│
├── .gitignore
|
└── package.json

# config.js 文件配置

每个配置的作用都写在注释当中。

官方文档：配置 (opens new window)、插件 (opens new window)、默认主题配置 (opens new window)

module.exports = {
  // 插件：置顶按钮、图片缩放
  plugins: ['@vuepress/back-to-top', '@vuepress/medium-zoom'],
  // 自定义网站 favicon
  head: [['link', { rel: 'icon', href: '/img/logo.png' }]],
  // 根路径，和仓库名一致
  base: '/bruceblog/',
  // 左上角标题
  title: 'BruceBlog',
  // markdown 相关配置
  markdown: {
    // 代码块行号
    lineNumbers: true,
  },
  // 默认主题相关配置
  themeConfig: {
    // 配置左上角的 logo
    logo: '/img/logo.png',
    // 导航栏
    nav: require('./nav.js'),
    // 侧边栏
    sidebar: require('./sidebar.js'),
    // sidebar: 'auto',
    // 标题深度，2 表示提取 h2 和 h3 标题
    sidebarDepth: 2,
    // 启用页面滚动效果
    smoothScroll: true,
    // 最后更新时间
    lastUpdated: 'Last Updated',
    // 默认值是 true 。设置为 false 来禁用所有页面的 下一篇 链接
    nextLinks: true,
    // 默认值是 true 。设置为 false 来禁用所有页面的 上一篇 链接
    prevLinks: true,
    // 导航栏显示 gitee 仓库
    repo: 'https://gitee.com/brucecai55520/bruceblog',
    repoLabel: 'Gitee',
  },
}
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
27
28
29
30
31
32
33
34
35
36
37
38

# 首页

docs/README.md文档：

---
home: true
heroImage: /img/logo.png
heroText: BruceBlog
tagline: 一名前端er的学习笔记
actionText: Get Started →
actionLink: /notes/
features:
  - title: 前端知识
    details: HTML、CSS、JavaScript、Vue、React...
  - title: 计算机基础
    details: 计算机网络、数据结构、操作系统...
  - title: 杂七杂八
    details: 前端面试常见的面试题、资源推荐...
footer: Oh this is BruceBlog
---
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

官方文档 (opens new window)

# 导航栏

这里没有直接把配置写在 config.js 文件中，而是提取成一个模块，便于后续维护，也避免 config.js 文件过于臃肿。

注意事项：

  • 所有路径以 / 开头，/ 代表 docs 目录
  • 若没有指明具体文件，只有文件夹，则默认会寻找该文件夹下的 READMED.md 文档，如 '/notes/' → '/notes/README.md'
// .vuepress/nav.js
module.exports = [
  {
    text: 'Resources',
    link: '/notes/xxx/xxxx',
  },
  {
    text: '前端学习',
    items: [
      { text: 'Vue', link: '/notes/vue/vue基础' },
      { text: 'React', link: '/notes/react/react基础' },
    ],
  },
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14

官方文档 (opens new window)

# 侧边栏

BruceBlog 为不同页面显示不同的侧边栏，并且每个页面的侧边栏封装为一个模块便于后续维护。

以 Vue 页面的侧边栏为例：

// .vuepress/sidebar.js
module.exports = {
  '/notes/vue': require('../notes/vue/sidebar'),
  '/notes/react': require('../notes/react/sidebar'),
}
1
2
3
4
5
// notes/vue/sidebar.js
module.exports = [
  {
    title: 'Vue核心基础',
    path: '/notes/vue/vue核心基础',
  },
  {
    title: 'Vuex',
    path: '/notes/vue/vuex',
  },
  {
    title: 'Vue Router',
    path: '/notes/vue/vue-router',
  },
  {
    title: 'Vue3',
    path: '/notes/vue/vue3',
  },
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

官方文档 (opens new window)

# 修改默认样式

在 .vuepress/styles/index.styl 文件可以方便地添加自定义样式

blockquote {
  border-left: 0.2rem solid #3eaf7c;
  font-weight: 700;
}
1
2
3
4

官方文档 (opens new window)

# Emoji

输入

:tada: :smile:
1

输出

🎉 😄

Emoji 大全 (opens new window)

# 搭建过程踩的坑

  • h1 标题不会生成目录，因此若想标题出现在目录，请用 h2 和 h3 标题
  • 使用 ![]() 插入图片时，要填写标准的相对路径，如 ./images/xxx.png，不要省略前面的 ./，否则图片无法正常显示
  • 在非代码块中（包括行内代码）不要使用紧贴的大括号，两个同向的大括号之间加个空格
// 报错写法
style={{ key: value }}
// 不报错写法
style={ { key: value } }
1
2
3
4
  • 侧边栏对应的文件路径要书写正确，否则侧边栏无法展示
  • 若一个目录有 README.md 和 sidebar.js ，则其子目录文件夹不能再有
  • 总之，如果页面展示出现问题，多看看控制台的报错，一般都会有提示

# 部署

本人选择部署到 Gitee Pages，官方只有部署到 GitHub Pages 的教程 (opens new window)，不过也是大同小异。

  1. 在 docs/.vuepress/config.js 中设置正确的 base。

若发布到 https://<USERNAME>.gitee.io/ ，可省略此步，因为 base 默认为 "/" 。

若发布到 https://<USERNAME>.gitee.io/<REPO>/ ，<REPO> 为仓库名，则将 base 设置为 "/<REPO>/" 。

module.exports = {
  // 仓库名为 bruceblog
  base: '/bruceblog/',
}
1
2
3
4
  1. 在 bruceblog 目录下运行打包命令
npm run build
1
  1. 打包完成后，会生成 dist 文件夹，进入该文件夹
cd docs/.vuepress/dist
1
  1. 初始化 git，并添加暂存区，提交本地库
git init
git add -A
git commit -m 'init bruceblog' -a
1
2
3
  1. 为远程仓库起别名
git remote add origin 远程仓库地址
1
  1. 拉取远程仓库分支，与本地分支合并

本人额外创建了一个分支，master 分支保存原始的 markdown 文档，pages分支则用于上传打包后的文件，并使用 pages 分支部署 Gitee Pages。

git pull origin pages
1
  1. 推送本地分支到远程分支
git push origin master:pages
1
  1. 选择部署分支，并开启 Gitee Pages 服务

至此，BruceBlog 的搭建大功告成！🎉😄

# 更新网站内容

VuePress 每次打包生成的 dist 都不相同，因此尽量有比较大改动时才更新网站，这不像 docsify 那么方便自由

  • 本地拷贝一份 .git 文件夹备用，删除旧的 dist 文件夹
  • 重新打包生成新的 dist 文件夹
  • 把备用 .git 文件夹拷贝到新的 dist 文件夹中
  • 将修改添加暂存区，提交本地库，并推送到远程分支
  • 如此，既能更新远程 pages 分支内容，也能同步 git 的历史操作记录
Last Updated: 12/26/2021, 9:52:48 PM